diff options
Diffstat (limited to 'gnu/usr.bin')
26 files changed, 0 insertions, 46736 deletions
diff --git a/gnu/usr.bin/texinfo/README-alpha b/gnu/usr.bin/texinfo/README-alpha deleted file mode 100644 index 2661145da82..00000000000 --- a/gnu/usr.bin/texinfo/README-alpha +++ /dev/null @@ -1,11 +0,0 @@ -Please report bugs in this alpha distribution to - texinfo-pretest@cs.umb.edu -rather than bug-texinfo@prep. Thanks. - -You can get on texinfo-pretest, if you're not already, -by sending a message whose body is - subscribe you@your.preferred.email.address - -to texinfo-pretest-request@cs.umb.edu. -And you can get off the list by sending an unsubscribe message. -(I use majordomo to maintain the list.) diff --git a/gnu/usr.bin/texinfo/THANKS b/gnu/usr.bin/texinfo/THANKS deleted file mode 100644 index daa1cfe7098..00000000000 --- a/gnu/usr.bin/texinfo/THANKS +++ /dev/null @@ -1,9 +0,0 @@ -Thanks to these contributors and many more ... - -Dave Love -Donald Knuth -Erick Branderhorst -Karl Eichwalder -Laurent Bourbeau -Stephen Gildea -William Bader diff --git a/gnu/usr.bin/texinfo/config.h.in b/gnu/usr.bin/texinfo/config.h.in deleted file mode 100644 index f814b6573c5..00000000000 --- a/gnu/usr.bin/texinfo/config.h.in +++ /dev/null @@ -1,257 +0,0 @@ -/* config.h.in. Generated automatically from configure.in by autoheader. */ -/* acconfig.h - This file is in the public domain. - - Descriptive text for the C preprocessor macros that - the distributed Autoconf macros can define. - No software package will use all of them; autoheader copies the ones - your configure.in uses into your configuration header file templates. - - The entries are in sort -df order: alphabetical, case insensitive, - ignoring punctuation (such as underscores). Although this order - can split up related entries, it makes it easier to check whether - a given entry is in the file. - - Leave the following blank line there!! Autoheader needs it. */ - - - -/* Define if using alloca.c. */ -#undef C_ALLOCA - -/* Define to empty if the keyword does not work. */ -#undef const - -/* Define to one of _getb67, GETB67, getb67 for Cray-2 and Cray-YMP systems. - This function is required for alloca.c support on those systems. */ -#undef CRAY_STACKSEG_END - -/* Define if you have alloca, as a function or macro. */ -#undef HAVE_ALLOCA - -/* Define if you have <alloca.h> and it should be used (not on Ultrix). */ -#undef HAVE_ALLOCA_H - -/* Define if you don't have vprintf but do have _doprnt. */ -#undef HAVE_DOPRNT - -/* Define if you have a working `mmap' system call. */ -#undef HAVE_MMAP - -/* Define if you have the vprintf function. */ -#undef HAVE_VPRINTF - -/* Define as __inline if that's what the C compiler calls it. */ -#undef inline - -/* Define if on MINIX. */ -#undef _MINIX - -/* Define to `long' if <sys/types.h> doesn't define. */ -#undef off_t - -/* Define if the system does not provide POSIX.1 features except - with this defined. */ -#undef _POSIX_1_SOURCE - -/* Define if you need to in order for stat and other things to work. */ -#undef _POSIX_SOURCE - -/* Define as the return type of signal handlers (int or void). */ -#undef RETSIGTYPE - -/* Define if the setvbuf function takes the buffering type as its second - argument and the buffer pointer as the third, as on System V - before release 3. */ -#undef SETVBUF_REVERSED - -/* Define to `unsigned' if <sys/types.h> doesn't define. */ -#undef size_t - -/* If using the C implementation of alloca, define if you know the - direction of stack growth for your system; otherwise it will be - automatically deduced at run-time. - STACK_DIRECTION > 0 => grows toward higher addresses - STACK_DIRECTION < 0 => grows toward lower addresses - STACK_DIRECTION = 0 => direction of growth unknown - */ -#undef STACK_DIRECTION - -/* Define if you have the ANSI C header files. */ -#undef STDC_HEADERS - -/* Define if your <sys/time.h> declares struct tm. */ -#undef TM_IN_SYS_TIME - -/* Define to 1 if NLS is requested. */ -#undef ENABLE_NLS - -/* Define as 1 if you have catgets and don't want to use GNU gettext. */ -#undef HAVE_CATGETS - -/* Define as 1 if you have gettext and don't want to use GNU gettext. */ -#undef HAVE_GETTEXT - -/* Define if your locale.h file contains LC_MESSAGES. */ -#undef HAVE_LC_MESSAGES - -/* Define as 1 if you have the stpcpy function. */ -#undef HAVE_STPCPY - -/* Define to the name of the distribution. */ -#undef PACKAGE - -/* Define to the version of the distribution. */ -#undef VERSION - -/* Define if you have the __argz_count function. */ -#undef HAVE___ARGZ_COUNT - -/* Define if you have the __argz_next function. */ -#undef HAVE___ARGZ_NEXT - -/* Define if you have the __argz_stringify function. */ -#undef HAVE___ARGZ_STRINGIFY - -/* Define if you have the bzero function. */ -#undef HAVE_BZERO - -/* Define if you have the dcgettext function. */ -#undef HAVE_DCGETTEXT - -/* Define if you have the getcwd function. */ -#undef HAVE_GETCWD - -/* Define if you have the getpagesize function. */ -#undef HAVE_GETPAGESIZE - -/* Define if you have the memcpy function. */ -#undef HAVE_MEMCPY - -/* Define if you have the memmove function. */ -#undef HAVE_MEMMOVE - -/* Define if you have the memset function. */ -#undef HAVE_MEMSET - -/* Define if you have the munmap function. */ -#undef HAVE_MUNMAP - -/* Define if you have the putenv function. */ -#undef HAVE_PUTENV - -/* Define if you have the setenv function. */ -#undef HAVE_SETENV - -/* Define if you have the setlocale function. */ -#undef HAVE_SETLOCALE - -/* Define if you have the setvbuf function. */ -#undef HAVE_SETVBUF - -/* Define if you have the sigprocmask function. */ -#undef HAVE_SIGPROCMASK - -/* Define if you have the sigsetmask function. */ -#undef HAVE_SIGSETMASK - -/* Define if you have the stpcpy function. */ -#undef HAVE_STPCPY - -/* Define if you have the strcasecmp function. */ -#undef HAVE_STRCASECMP - -/* Define if you have the strchr function. */ -#undef HAVE_STRCHR - -/* Define if you have the strdup function. */ -#undef HAVE_STRDUP - -/* Define if you have the strerror function. */ -#undef HAVE_STRERROR - -/* Define if you have the <argz.h> header file. */ -#undef HAVE_ARGZ_H - -/* Define if you have the <fcntl.h> header file. */ -#undef HAVE_FCNTL_H - -/* Define if you have the <limits.h> header file. */ -#undef HAVE_LIMITS_H - -/* Define if you have the <locale.h> header file. */ -#undef HAVE_LOCALE_H - -/* Define if you have the <malloc.h> header file. */ -#undef HAVE_MALLOC_H - -/* Define if you have the <ncurses/termcap.h> header file. */ -#undef HAVE_NCURSES_TERMCAP_H - -/* Define if you have the <nl_types.h> header file. */ -#undef HAVE_NL_TYPES_H - -/* Define if you have the <pwd.h> header file. */ -#undef HAVE_PWD_H - -/* Define if you have the <string.h> header file. */ -#undef HAVE_STRING_H - -/* Define if you have the <strings.h> header file. */ -#undef HAVE_STRINGS_H - -/* Define if you have the <sys/fcntl.h> header file. */ -#undef HAVE_SYS_FCNTL_H - -/* Define if you have the <sys/file.h> header file. */ -#undef HAVE_SYS_FILE_H - -/* Define if you have the <sys/param.h> header file. */ -#undef HAVE_SYS_PARAM_H - -/* Define if you have the <sys/ptem.h> header file. */ -#undef HAVE_SYS_PTEM_H - -/* Define if you have the <sys/time.h> header file. */ -#undef HAVE_SYS_TIME_H - -/* Define if you have the <sys/ttold.h> header file. */ -#undef HAVE_SYS_TTOLD_H - -/* Define if you have the <sys/wait.h> header file. */ -#undef HAVE_SYS_WAIT_H - -/* Define if you have the <termcap.h> header file. */ -#undef HAVE_TERMCAP_H - -/* Define if you have the <termio.h> header file. */ -#undef HAVE_TERMIO_H - -/* Define if you have the <termios.h> header file. */ -#undef HAVE_TERMIOS_H - -/* Define if you have the <unistd.h> header file. */ -#undef HAVE_UNISTD_H - -/* Define if you have the <values.h> header file. */ -#undef HAVE_VALUES_H - -/* Define if you have the bsd library (-lbsd). */ -#undef HAVE_LIBBSD - -/* Define if you have the i library (-li). */ -#undef HAVE_LIBI - -/* Define if you have the z library (-lz). */ -#undef HAVE_LIBZ - -/* For gettext (NLS) */ -#include <libintl.h> -#define _(String) gettext (String) -#define N_(String) (String) - - -/* Leave that blank line there!! Autoheader needs it. - If you're adding to this file, keep in mind: - The entries are in sort -df order: alphabetical, case insensitive, - ignoring punctuation (such as underscores). */ diff --git a/gnu/usr.bin/texinfo/dir b/gnu/usr.bin/texinfo/dir deleted file mode 100644 index 1bb59fa1f9a..00000000000 --- a/gnu/usr.bin/texinfo/dir +++ /dev/null @@ -1,16 +0,0 @@ -$Id: dir,v 1.3 2002/06/10 13:51:01 espie Exp $ -This is the file .../info/dir, which contains the topmost node of the -Info hierarchy. The first time you invoke Info you start off -looking at that node, which is (dir)Top. - -File: dir Node: Top This is the top of the INFO tree - - This (the Directory node) gives a menu of major topics. - Typing "q" exits, "?" lists all Info commands, "d" returns here, - "h" gives a primer for first-timers, - "mEmacs<Return>" visits the Emacs topic, etc. - - In Emacs, you can click mouse button 2 on a menu item or cross reference - to select it. - -* Menu: diff --git a/gnu/usr.bin/texinfo/doc/texinfo.texi b/gnu/usr.bin/texinfo/doc/texinfo.texi deleted file mode 100644 index 5ffef5da409..00000000000 --- a/gnu/usr.bin/texinfo/doc/texinfo.texi +++ /dev/null @@ -1,17289 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.texi,v 1.3 2002/06/10 13:51:02 espie Exp $ -@c %**start of header - -@c All text is ignored before the setfilename. -@setfilename texinfo -@settitle Texinfo @value{edition} - -@set edition 2.24 -@set update-month July 1997 -@set update-date 25 @value{update-month} - -@c Define a new index for options. -@defcodeindex op -@c Put everything except function (command, in this case) names in one -@c index (arbitrarily chosen to be the concept index). -@syncodeindex op cp -@syncodeindex vr cp -@syncodeindex pg cp - -@footnotestyle separate -@paragraphindent 2 -@finalout -@comment %**end of header - -@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a -@c prefix arg). This updates the node pointers, which texinfmt.el needs. - -@dircategory Texinfo documentation system -@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Updating info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. -* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. -* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. -@end direntry - -@c Set smallbook if printing in smallbook format so the example of the -@c smallbook font is actually written using smallbook; in bigbook, a kludge -@c is used for TeX output. Do this through the -t option to texi2dvi, -@c so this same source can be used for other paper sizes as well. -@c smallbook -@c set smallbook -@c @@clear smallbook - -@c Currently undocumented command, 5 December 1993: -@c -@c nwnode (Same as node, but no warnings; for `makeinfo'.) - -@ifinfo -This file documents Texinfo, a documentation system that can produce -both on-line information and a printed manual from a single source file. - -Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97 Free Software Foundation, Inc. - -This is the second edition of the Texinfo documentation,@* -and is consistent with version 2 of @file{texinfo.tex}. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@end ifinfo - -@setchapternewpage odd - -@shorttitlepage Texinfo - -@titlepage -@c use the new format for titles -@title Texinfo -@subtitle The GNU Documentation Format -@subtitle Edition @value{edition}, for Texinfo Version Three -@subtitle @value{update-month} - -@author Robert J.@: Chassell -@author Richard M.@: Stallman - -@c Include the Distribution inside the titlepage so -@c that headings are turned off. - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97 -Free Software Foundation, Inc. - -@sp 2 -This is the second edition of the Texinfo documentation,@* -and is consistent with version 2 of @file{texinfo.tex}. -@sp 2 - -Published by the Free Software Foundation @* -59 Temple Place Suite 330 @* -Boston, MA 02111-1307 @* -USA @* -Printed copies are available for $15 each.@* -ISBN 1-882114-64-7 -@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 -@c ISBN 1-882114-64-7 is for edition 2.23 of 1 October 1996. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - -@ifinfo -@node Top, Copying, (dir), (dir) -@top Texinfo - -Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output.@refill - -The first part of this master menu lists the major nodes in this Info -document, including the @@-command and concept indices. The rest of -the menu lists all the lower level nodes in the document.@refill - -This is Edition @value{edition} of the Texinfo documentation, -@w{@value{update-date},} for Texinfo Version Three. -@end ifinfo - -@c Here is a spare copy of the chapter menu entry descriptions, -@c in case they are accidently deleted -@ignore -Your rights. -Texinfo in brief. -How to use Texinfo mode. -What is at the beginning of a Texinfo file? -What is at the end of a Texinfo file? -How to create chapters, sections, subsections, - appendices, and other parts. -How to provide structure for a document. -How to write nodes. -How to write menus. -How to write cross references. -How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -How to write quotations, examples, etc. -How to write lists and tables. -How to create indices. -How to insert @@-signs, braces, etc. -How to indicate results of evaluation, - expansion of macros, errors, etc. -How to force and prevent line and page breaks. -How to describe functions and the like in a uniform manner. -How to write footnotes. -How to specify text for either @TeX{} or Info. -How to print hardcopy. -How to create an Info file. -How to install an Info file -A list of all the Texinfo @@-commands. -Hints on how to write a Texinfo document. -A sample Texinfo file to look at. -Tell readers they have the right to copy - and distribute. -How to incorporate other Texinfo files. -How to write page headings and footings. -How to find formatting mistakes. -All about paragraph refilling. -A description of @@-Command syntax. -Texinfo second edition features. -A menu containing commands and variables. -A menu covering many topics. -@end ignore - -@menu -* Copying:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: How to use Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* Structuring:: How to create chapters, sections, subsections, - appendices, and other parts. -* Nodes:: How to write nodes. -* Menus:: How to write menus. -* Cross References:: How to write cross references. -* Marking Text:: How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: How to write quotations, examples, etc. -* Lists and Tables:: How to write lists and tables. -* Indices:: How to create indices. -* Insertions:: How to insert @@-signs, braces, etc. -* Breaks:: How to force and prevent line and page breaks. -* Definition Commands:: How to describe functions and the like - in a uniform manner. -* Footnotes:: How to write footnotes. -* Conditionals:: How to specify text for either @TeX{} or Info. -* Macros:: Defining new Texinfo commands. -* Format/Print Hardcopy:: How to convert a Texinfo file to a file - for printing and how to print that file. -* Create an Info File:: Convert a Texinfo file into an Info file. -* Install an Info File:: Make an Info file accessible to users. -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo File:: A sample Texinfo file to look at. -* Sample Permissions:: Tell readers they have the right to copy - and distribute. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* Refilling Paragraphs:: All about paragraph refilling. -* Command Syntax:: A description of @@-Command syntax. -* Obtaining TeX:: How to Obtain @TeX{}. -* Command and Variable Index:: A menu containing commands and variables. -* Concept Index:: A menu covering many topics. - -@detailmenu - - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Using Texinfo:: Create a conventional printed book - or an Info file. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: - -Using Texinfo Mode - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - -Updating Nodes and Menus - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - -Beginning a Texinfo File - -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -The Texinfo File Header - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. - -The Title and Copyright Pages - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright & Permissions:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. - -The `Top' Node and Master Menu - -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. - -Chapter Structuring - -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. - -Nodes - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. - -The @code{@@node} Command - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. -* Top Node Summary:: Write a brief description for readers. - -Menus - -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. - -Cross References - -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. - -@code{@@xref} - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. - -Marking Words and Phrases - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - -Indicating Definitions, Commands, etc. - -* Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -* url:: How to indicate a world wide web reference. -* email:: How to indicate an electronic mail address. - -Emphasizing Text - -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -* Customized Highlighting:: How to define highlighting commands. - -Quotations and Examples - -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. - -Lists and Tables - -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. - -Making a Two-column Table - -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. - -Multi-column Tables - -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. - -Creating Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - -Combining Indices - -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - -Special Insertions - -* Braces Atsigns:: How to insert braces, @samp{@@}. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* pounds:: How to insert the pounds currency symbol. -* minus:: How to insert a minus sign. -* math:: How to format a mathematical expression. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -* Images:: How to include graphics. - -Inserting @@ and Braces - -* Inserting An Atsign:: How to insert @samp{@@}. -* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. - -Inserting Space - -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* dmn:: How to format a dimension. - -Inserting Ellipsis, Dots, and Bullets - -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. - -Inserting @TeX{} and the Copyright Symbol - -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright}@{@}. - -Glyphs for Examples - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - -Glyphs Summary - -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: - -Making and Preventing Breaks - -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: - -The Definition Commands - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. - -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - -Conditionally Visible Text - -* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. -* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. -* Raw Formatter Commands:: Using raw @TeX{} or HTML commands. -* set clear value:: Designating which text to format (for - all output formats); and how to set a - flag to a string that you can insert. - -@code{@@set}, @code{@@clear}, and @code{@@value} - -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. - -Macros: Defining New Texinfo Commands - -* Defining Macros:: Both defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. - -Format and Print Hardcopy - -* Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format in a shell. -* Format with texi2dvi:: A simpler way to use the shell. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What you need to do to use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. - -Creating an Info File - -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - -Installing an Info File - -* Directory file:: The top level menu for all Info files. -* New Info File:: Listing a new info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: @code{install-info} options. - -Sample Permissions - -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. - -Include Files - -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. - -Page Headings - -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. - -Formatting Mistakes - -* makeinfo Preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with @TeX{} formatting. -* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. - -Finding Badly Referenced Nodes - -* Using Info-validate:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. - -How to Obtain @TeX{} - -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@end detailmenu -@end menu - -@node Copying, Overview, Top, Top -@comment node-name, next, previous, up -@unnumbered Texinfo Copying Conditions -@cindex Copying conditions -@cindex Conditions for copying Texinfo - -The programs currently being distributed that relate to Texinfo include -portions of GNU Emacs, plus other separate programs (including -@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). -These programs are @dfn{free}; this means that everyone is free to use -them and free to redistribute them on a free basis. The Texinfo-related -programs are not in the public domain; they are copyrighted and there -are restrictions on their distribution, but these restrictions are -designed to permit everything that a good cooperating citizen would want -to do. What is not allowed is to try to prevent others from further -sharing any version of these programs that they might get from -you.@refill - - Specifically, we want to make sure that you have the right to give -away copies of the programs that relate to Texinfo, that you receive -source code or else can get it if you want it, that you can change these -programs or use pieces of them in new free programs, and that you know -you can do these things.@refill - - To make sure that everyone has such rights, we have to forbid you to -deprive anyone else of these rights. For example, if you distribute -copies of the Texinfo related programs, you must give the recipients all -the rights that you have. You must make sure that they, too, receive or -can get the source code. And you must tell them their rights.@refill - - Also, for our own protection, we must make certain that everyone finds -out that there is no warranty for the programs that relate to Texinfo. -If these programs are modified by someone else and passed on, we want -their recipients to know that what they have is not what we distributed, -so that any problems introduced by others will not reflect on our -reputation.@refill - - The precise conditions of the licenses for the programs currently -being distributed that relate to Texinfo are found in the General Public -Licenses that accompany them.@refill - -@node Overview, Texinfo Mode, Copying, Top -@comment node-name, next, previous, up -@chapter Overview of Texinfo -@cindex Overview of Texinfo -@cindex Texinfo overview - -@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is -pronounced like ``speck'', not ``hex''. This odd pronunciation is -derived from, but is not the same as, the pronunciation of @TeX{}. In -the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' -rather than the English letter ``ex''. Pronounce @TeX{} as if the -@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo -as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' -and write the other letters in lower case.} -is a documentation system that uses a single source file to produce both -on-line information and printed output. This means that instead of -writing two different documents, one for the on-line help or other on-line -information and the other for a typeset manual or other printed work, you -need write only one document. When the work is revised, you need revise -only one document. (You can read the on-line information, known as an -@dfn{Info file}, with an Info documentation-reading program.)@refill - -@menu -* Using Texinfo:: Create a conventional printed book - or an Info file. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: -@end menu - -@node Using Texinfo, Info Files, Overview, Overview -@ifinfo -@heading Using Texinfo -@end ifinfo - -Using Texinfo, you can create a printed document with the normal -features of a book, including chapters, sections, cross references, -and indices. From the same Texinfo source file, you can create a -menu-driven, on-line Info file with nodes, menus, cross references, -and indices. You can, if you wish, make the chapters and sections of -the printed document correspond to the nodes of the on-line -information; and you use the same cross references and indices for -both the Info file and the printed work. @cite{The GNU -Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill - -To make a printed document, you process a Texinfo source file with the -@TeX{} typesetting program. This creates a DVI file that you can -typeset and print as a book or report. (Note that the Texinfo language -is completely different from @TeX{}'s usual language, plain @TeX{}.) If -you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you -can use the @code{texi2roff} program instead.@refill - -To make an Info file, you process a Texinfo source file with the -@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; -this creates an Info file that you can install on-line.@refill - -@TeX{} and @code{texi2roff} work with many types of printers; similarly, -Info works with almost every type of computer terminal. This power -makes Texinfo a general purpose system, but brings with it a constraint, -which is that a Texinfo file may contain only the customary -``typewriter'' characters (letters, numbers, spaces, and punctuation -marks) but no special graphics.@refill - -A Texinfo file is a plain @sc{ascii} file containing text and -@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the -typesetting and formatting programs what to do. You may edit a -Texinfo file with any text editor; but it is especially convenient to -use GNU Emacs since that editor has a special mode, called Texinfo -mode, that provides various Texinfo-related features. (@xref{Texinfo -Mode}.)@refill - -Before writing a Texinfo source file, you should become familiar with -the Info documentation reading program and learn about nodes, -menus, cross references, and the rest. (@inforef{Top, info, info}, -for more information.)@refill - -You can use Texinfo to create both on-line help and printed manuals; -moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the format in which documentation for GNU utilities and libraries is -written.@refill - -@node Info Files, Printed Books, Using Texinfo, Overview -@comment node-name, next, previous, up -@section Info files -@cindex Info files - -An Info file is a Texinfo file formatted so that the Info documentation -reading program can operate on it. (@code{makeinfo} -and @code{texinfo-format-buffer} are two commands that convert a Texinfo file -into an Info file.)@refill - -Info files are divided into pieces called @dfn{nodes}, each of which -contains the discussion of one topic. Each node has a name, and -contains both text for the user to read and pointers to other nodes, -which are identified by their names. The Info program displays one node -at a time, and provides commands with which the user can move to other -related nodes.@refill - -@ifinfo -@inforef{Top, info, info}, for more information about using Info.@refill -@end ifinfo - -Each node of an Info file may have any number of child nodes that -describe subtopics of the node's topic. The names of child -nodes are listed in a @dfn{menu} within the parent node; this -allows you to use certain Info commands to move to one of the child -nodes. Generally, an Info file is organized like a book. If a node -is at the logical level of a chapter, its child nodes are at the level -of sections; likewise, the child nodes of sections are at the level -of subsections.@refill - -All the children of any one parent are linked together in a -bidirectional chain of `Next' and `Previous' pointers. The `Next' -pointer provides a link to the next section, and the `Previous' pointer -provides a link to the previous section. This means that all the nodes -that are at the level of sections within a chapter are linked together. -Normally the order in this chain is the same as the order of the -children in the parent's menu. Each child node records the parent node -name as its `Up' pointer. The last child has no `Next' pointer, and the -first child has the parent both as its `Previous' and as its `Up' -pointer.@footnote{In some documents, the first child has no `Previous' -pointer. Occasionally, the last child has the node name of the next -following higher level node as its `Next' pointer.}@refill - -The book-like structuring of an Info file into nodes that correspond -to chapters, sections, and the like is a matter of convention, not a -requirement. The `Up', `Previous', and `Next' pointers of a node can -point to any other nodes, and a menu can contain any other nodes. -Thus, the node structure can be any directed graph. But it is usually -more comprehensible to follow a structure that corresponds to the -structure of chapters and sections in a printed book or report.@refill - -In addition to menus and to `Next', `Previous', and `Up' pointers, Info -provides pointers of another kind, called references, that can be -sprinkled throughout the text. This is usually the best way to -represent links that do not fit a hierarchical structure.@refill - -Usually, you will design a document so that its nodes match the -structure of chapters and sections in the printed output. But -occasionally there are times when this is not right for the material -being discussed. Therefore, Texinfo uses separate commands to specify -the node structure for the Info file and the section structure for the -printed output.@refill - -Generally, you enter an Info file through a node that by convention is -named `Top'. This node normally contains just a brief summary of the -file's purpose, and a large menu through which the rest of the file is -reached. From this node, you can either traverse the file -systematically by going from node to node, or you can go to a specific -node listed in the main menu, or you can search the index menus and then -go directly to the node that has the information you want. Alternatively, -with the standalone Info program, you can specify specific menu items on -the command line (@pxref{Top,,, info, Info}). - -If you want to read through an Info file in sequence, as if it were a -printed manual, you can hit @key{SPC} repeatedly, or you get the whole -file with the advanced Info command @kbd{g *}. (@inforef{Expert, -Advanced Info commands, info}.)@refill - -@c !!! dir file may be located in one of many places: -@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/info -@c /usr/local/lib/info -The @file{dir} file in the @file{info} directory serves as the -departure point for the whole Info system. From it, you can reach the -`Top' nodes of each of the documents in a complete Info system.@refill - -@node Printed Books, Formatting Commands, Info Files, Overview -@comment node-name, next, previous, up -@section Printed Books -@cindex Printed book and manual characteristics -@cindex Manual characteristics, printed -@cindex Book characteristics, printed -@cindex Texinfo printed book characteristics -@cindex Characteristics, printed books or manuals - -@cindex Knuth, Donald -A Texinfo file can be formatted and typeset as a printed book or manual. -To do this, you need @TeX{}, a powerful, sophisticated typesetting -program written by Donald Knuth.@footnote{You can also use the -@code{texi2roff} program if you do not have @TeX{}; since Texinfo is -designed for use with @TeX{}, @code{texi2roff} is not described here. -@code{texi2roff} is not part of the standard GNU distribution.} - -A Texinfo-based book is similar to any other typeset, printed work: it -can have a title page, copyright page, table of contents, and preface, -as well as chapters, numbered or unnumbered sections and subsections, -page headers, cross references, footnotes, and indices.@refill - -You can use Texinfo to write a book without ever having the intention -of converting it into on-line information. You can use Texinfo for -writing a printed novel, and even to write a printed memo, although -this latter application is not recommended since electronic mail is so -much easier.@refill - -@TeX{} is a general purpose typesetting program. Texinfo provides a -file called @file{texinfo.tex} that contains information (definitions or -@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. -(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands -to @TeX{} commands, which @TeX{} can then process to create the typeset -document.) @file{texinfo.tex} contains the specifications for printing -a document.@refill - -Most often, documents are printed on 8.5 inch by 11 inch -pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you -can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by -235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper -(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}. -Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill - -By changing the parameters in @file{texinfo.tex}, you can change the -size of the printed document. In addition, you can change the style in -which the printed document is formatted; for example, you can change the -sizes and fonts used, the amount of indentation for each paragraph, the -degree to which words are hyphenated, and the like. By changing the -specifications, you can make a book look dignified, old and serious, or -light-hearted, young and cheery.@refill - -@TeX{} is freely distributable. It is written in a superset of Pascal -called WEB and can be compiled either in Pascal or (by using a -conversion program that comes with the @TeX{} distribution) in C. -(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information -about @TeX{}.)@refill - -@TeX{} is very powerful and has a great many features. Because a -Texinfo file must be able to present information both on a -character-only terminal in Info form and in a typeset book, the -formatting commands that Texinfo supports are necessarily -limited.@refill - -@xref{Obtaining TeX, , How to Obtain @TeX{}}. - - -@node Formatting Commands, Conventions, Printed Books, Overview -@comment node-name, next, previous, up -@section @@-commands -@cindex @@-commands -@cindex Formatting commands - -In a Texinfo file, the commands that tell @TeX{} how to typeset the -printed manual and tell @code{makeinfo} and -@code{texinfo-format-buffer} how to create an Info file are preceded -by @samp{@@}; they are called @dfn{@@-commands}. For example, -@code{@@node} is the command to indicate a node and @code{@@chapter} -is the command to indicate the start of a chapter.@refill - -@quotation -@strong{Please note:} All the @@-commands, with the exception of the -@code{@@TeX@{@}} command, must be written entirely in lower -case.@refill -@end quotation - -The Texinfo @@-commands are a strictly limited set of constructs. The -strict limits make it possible for Texinfo files to be understood both -by @TeX{} and by the code that converts them into Info files. You can -display Info files on any terminal that displays alphabetic and -numeric characters. Similarly, you can print the output generated by -@TeX{} on a wide variety of printers.@refill - -Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does -not refer to a disputation between two people; it refers to the -information presented to the command. According to the @cite{Oxford -English Dictionary}, the word derives from the Latin for @dfn{to make -clear, prove}; thus it came to mean `the evidence offered as proof', -which is to say, `the information offered', which led to its -mathematical meaning. In its other thread of derivation, the word -came to mean `to assert in a manner against which others may make -counter assertions', which led to the meaning of `argument' as a -disputation.} they take, you need to write @@-commands on lines of -their own or as part of sentences:@refill - -@itemize @bullet -@item -Write a command such as @code{@@noindent} at the beginning of a line as -the only text on the line. (@code{@@noindent} prevents the beginning of -the next line from being indented as the beginning of a -paragraph.)@refill - -@item -Write a command such as @code{@@chapter} at the beginning of a line -followed by the command's arguments, in this case the chapter title, on -the rest of the line. (@code{@@chapter} creates chapter titles.)@refill - -@item -Write a command such as @code{@@dots@{@}} wherever you wish but usually -within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill - -@item -Write a command such as @code{@@code@{@var{sample-code}@}} wherever you -wish (but usually within a sentence) with its argument, -@var{sample-code} in this example, between the braces. (@code{@@code} -marks text as being code.)@refill - -@item -Write a command such as @code{@@example} at the beginning of a line of -its own; write the body-text on following lines; and write the matching -@code{@@end} command, @code{@@end example} in this case, at the -beginning of a line of its own after the body-text. (@code{@@example} -@dots{} @code{@@end example} indents and typesets body-text as an -example.)@refill -@end itemize - -@noindent -@cindex Braces, when to use -As a general rule, a command requires braces if it mingles among other -text; but it does not need braces if it starts a line of its own. The -non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; -they do not need braces.@refill - -As you gain experience with Texinfo, you will rapidly learn how to -write the different commands: the different ways to write commands -make it easier to write and read Texinfo files than if all commands -followed exactly the same syntax. (For details about @@-command -syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill - -@node Conventions, Comments, Formatting Commands, Overview -@comment node-name, next, previous, up -@section General Syntactic Conventions -@cindex General syntactic conventions -@cindex Syntactic conventions -@cindex Conventions, syntactic - -All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and -@samp{@}} can appear in a Texinfo file and stand for themselves. -@samp{@@} is the escape character which introduces commands. -@samp{@{} and @samp{@}} should be used only to surround arguments to -certain commands. To put one of these special characters into the -document, put an @samp{@@} character in front of it, like this: -@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill - -@ifinfo -It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: ` ` and ' ' (but without a space between the -two single-quote characters). This convention should be followed in -Texinfo files. @TeX{} converts doubled single-quote characters to -left- and right-hand doubled quotation marks and Info converts doubled -single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill -@end ifinfo -@iftex -It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This -convention should be followed in Texinfo files. @TeX{} converts -doubled single-quote characters to left- and right-hand doubled -quotation marks, ``like this'', and Info converts doubled single-quote -characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and -@w{@tt{ '' }} to @w{@tt{ " }}.@refill -@end iftex - -Use three hyphens in a row, @samp{---}, for a dash---like this. In -@TeX{}, a single or double hyphen produces a printed dash that is -shorter than the usual typeset dash. Info reduces three hyphens to two -for display on the screen. - -To prevent a paragraph from being indented in the printed manual, put -the command @code{@@noindent} on a line by itself before the -paragraph.@refill - -If you mark off a region of the Texinfo file with the @code{@@iftex} -and @w{@code{@@end iftex}} commands, that region will appear only in -the printed copy; in that region, you can use certain commands -borrowed from plain @TeX{} that you cannot use in Info. Likewise, if -you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo} -commands, that region will appear only in the Info file; in that -region, you can use Info commands that you cannot use in @TeX{}. -Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, -@code{@@ifnothtml @dots{} @@end ifnothtml}, -@code{@@ifnotinfo @dots{} @@end ifnotinfo}, -@code{@@ifnottex @dots{} @@end ifnottex}, -@xref{Conditionals}. - -@cindex Tabs; don't use! -@quotation -@strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses -variable-width fonts, which means that it cannot predefine a tab to work -in all circumstances. Consequently, @TeX{} treats tabs like single -spaces, and that is not what they look like. Furthermore, -@code{makeinfo} does nothing special with tabs, and thus a tab character -in your input file may appear differently in the output. - -@noindent -To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple -spaces when you press the @key{TAB} key.@refill - -@noindent -Also, you can run @code{untabify} in Emacs to convert tabs in a region -to multiple spaces.@refill - -@noindent -Don't use tabs. -@end quotation - -@node Comments, Minimum, Conventions, Overview -@comment node-name, next, previous, up -@section Comments - -You can write comments in a Texinfo file that will not appear in -either the Info file or the printed manual by using the -@code{@@comment} command (which may be abbreviated to @code{@@c}). -Such comments are for the person who reads the Texinfo file. All the -text on a line that follows either @code{@@comment} or @code{@@c} is a -comment; the rest of the line does not appear in either the Info file -or the printed manual. (Often, you can write the @code{@@comment} or -@code{@@c} in the middle of a line, and only the text that follows after -the @code{@@comment} or @code{@@c} command does not appear; but some -commands, such as @code{@@settitle} and @code{@@setfilename}, work on a -whole line. You cannot use @code{@@comment} or @code{@@c} in a line -beginning with such a command.)@refill -@cindex Comments -@findex comment -@findex c @r{(comment)} - -You can write long stretches of text that will not appear in either -the Info file or the printed manual by using the @code{@@ignore} and -@code{@@end ignore} commands. Write each of these commands on a line -of its own, starting each command at the beginning of the line. Text -between these two commands does not appear in the processed output. -You can use @code{@@ignore} and @code{@@end ignore} for writing -comments. Often, @code{@@ignore} and @code{@@end ignore} is used -to enclose a part of the copying permissions that applies to the -Texinfo source file of a document, but not to the Info or printed -version of the document.@refill -@cindex Ignored text -@cindex Unprocessed text -@findex ignore -@c !!! Perhaps include this comment about ignore and ifset: -@ignore -Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or -@code{@@ifclear} conditions is ignored in the sense that it will not -contribute to the formatted output. However, TeX and makeinfo must -still parse the ignored text, in order to understand when to -@emph{stop} ignoring text from the source file; that means that you -will still get error messages if you have invalid Texinfo markup -within ignored text. -@end ignore - -@node Minimum, Six Parts, Comments, Overview -@comment node-name, next, previous, up -@section What a Texinfo File Must Have -@cindex Minimal Texinfo file (requirements) -@cindex Must have in Texinfo file -@cindex Required in Texinfo file -@cindex Texinfo file minimum - -By convention, the names of Texinfo files end with one of the -extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer -extension is preferred since it describes more clearly to a human -reader the nature of the file. The shorter extensions are for -operating systems that cannot handle long file names.@refill - -In order to be made into a printed manual and an Info file, a Texinfo -file @strong{must} begin with lines like this:@refill - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -@noindent -The contents of the file follow this beginning, and then you @strong{must} end -a Texinfo file with a line like this:@refill - -@example -@@bye -@end example - -@findex input @r{(@TeX{} command)} -@noindent -The @samp{\input texinfo} line tells @TeX{} to use the -@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo -@@-commands into @TeX{} typesetting commands. (Note the use of the -backslash, @samp{\}; this is correct for @TeX{}.) The -@samp{@@setfilename} line provides a name for the Info file and tells -@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a -title for the page headers (or footers) of the printed manual.@refill - -The @code{@@bye} line at the end of the file on a line of its own tells -the formatters that the file is ended and to stop formatting.@refill - -Usually, you will not use quite such a spare format, but will include -mode setting and start-of-header and end-of-header lines at the -beginning of a Texinfo file, like this:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@@c %**end of header -@end group -@end example - -@noindent -In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into -Texinfo mode when you edit the file. - -The @code{@@c} lines which surround the @samp{@@setfilename} and -@samp{@@settitle} lines are optional, but you need them in order to -run @TeX{} or Info on just part of the file. (@xref{Start of Header}, -for more information.)@refill - -Furthermore, you will usually provide a Texinfo file with a title -page, indices, and the like. But the minimum, which can be useful -for short documents, is just the three lines at the beginning and the -one line at the end.@refill - -@node Six Parts, Short Sample, Minimum, Overview -@comment node-name, next, previous, up -@section Six Parts of a Texinfo File - -Generally, a Texinfo file contains more than the minimal -beginning and end---it usually contains six parts:@refill - -@table @r -@item 1. Header -The @dfn{Header} names the file, tells @TeX{} which definitions' file to -use, and performs other ``housekeeping'' tasks.@refill - -@item 2. Summary Description and Copyright -The @dfn{Summary Description and Copyright} segment describes the document -and contains the copyright notice and copying permissions for the Info -file. The segment must be enclosed between @code{@@ifinfo} and -@code{@@end ifinfo} commands so that the formatters place it only in the Info -file.@refill - -@item 3. Title and Copyright -The @dfn{Title and Copyright} segment contains the title and copyright pages -and copying permissions for the printed manual. The segment must be -enclosed between @code{@@titlepage} and @code{@@end titlepage} commands. -The title and copyright page appear only in the printed @w{manual}.@refill - -@item 4. `Top' Node and Master Menu -The @dfn{Master Menu} contains a complete menu of all the nodes in the whole -Info file. It appears only in the Info file, in the `Top' node.@refill - -@item 5. Body -The @dfn{Body} of the document may be structured like a traditional book or -encyclopedia or it may be free form.@refill - -@item 6. End -The @dfn{End} contains commands for printing indices and generating -the table of contents, and the @code{@@bye} command on a line of its -own.@refill -@end table - -@node Short Sample, Acknowledgements, Six Parts, Overview -@comment node-name, next, previous, up -@section A Short Sample Texinfo File -@cindex Sample Texinfo file - -Here is a complete but very short Texinfo file, in six parts. The first -three parts of the file, from @samp{\input texinfo} through to -@samp{@@end titlepage}, look more intimidating than they are. Most of -the material is standard boilerplate; when you write a manual, simply -insert the names for your own manual in this segment. (@xref{Beginning a -File}.)@refill - -@noindent -In the following, the sample text is @emph{indented}; comments on it are -not. The complete file, without any comments, is shown in -@ref{Sample Texinfo File}. - -@subheading Part 1: Header - -@noindent -The header does not appear in either the Info file or the -printed output. It sets various parameters, including the -name of the Info file and the title used in the header. - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header - -@@setchapternewpage odd -@end group -@end example - -@subheading Part 2: Summary Description and Copyright - -@noindent -The summary description and copyright segment does not -appear in the printed document. - -@example -@group -@@ifinfo -This is a short example of a complete Texinfo file. - -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end ifinfo -@end group -@end example - -@subheading Part 3: Titlepage and Copyright - -@noindent -The titlepage segment does not appear in the Info file. - -@example -@group -@@titlepage -@@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} -@end group - -@group -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage -@end group -@end example - -@subheading Part 4: `Top' Node and Master Menu - -@noindent -The `Top' node contains the master menu for the Info file. -Since a printed manual uses a table of contents rather than -a menu, the master menu appears only in the Info file. - -@example -@group -@@node Top, First Chapter, , (dir) -@@comment node-name, next, previous, up -@end group -@end example - -@example -@group -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Concept Index:: This index has two entries. -@@end menu -@end group -@end example - -@subheading Part 5: The Body of the Document - -@noindent -The body segment contains all the text of the document, but not the -indices or table of contents. This example illustrates a node and a -chapter containing an enumerated list.@refill - -@example -@group -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Sample index entry -@end group - -@group -This is the contents of the first chapter. -@@cindex Another sample index entry -@end group - -@group -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate -@end group - -@group -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. -@end group -@end example - -@subheading Part 6: The End of the Document - -@noindent -The end segment contains commands both for generating an index in a node -and unnumbered chapter of its own and for generating the table of -contents; and it contains the @code{@@bye} command that marks the end of -the document.@refill - -@example -@group -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index -@end group - -@group -@@printindex cp - -@@contents -@@bye -@end group -@end example - -@subheading The Results - -Here is what the contents of the first chapter of the sample look like: - -@sp 1 -@need 700 -@quotation -This is the contents of the first chapter. - -Here is a numbered list. - -@enumerate -@item -This is the first item. - -@item -This is the second item. -@end enumerate - -The @code{makeinfo} and @code{texinfo-format-buffer} -commands transform a Texinfo file such as this into -an Info file; and @TeX{} typesets it for a printed -manual. -@end quotation - -@node Acknowledgements, , Short Sample, Overview -@comment node-name, next, previous, up -@section Acknowledgements - -@cindex Stallman, Richard M. -@cindex Chassell, Robert J. -@cindex Berry, Karl -Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@: -Chassell} revised and extended it, starting with Edition 1.1. Karl -Berry made updates for the Texinfo 3.8 and subsequent releases, starting -with Edition 2.22. - -@cindex Pinard, Fran@,{c}ois -@cindex Zuhn, David D. -@cindex Weisshaus, Melissa -Our thanks go out to all who helped improve this work, particularly to -Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and -reported mistakes and obscurities; our special thanks go to Melissa -Weisshaus for her frequent and often tedious reviews of nearly similar -editions. Our mistakes are our own. - -Please send suggestions and corrections to: - -@example -@group -@r{Internet address:} - bug-texinfo@@prep.ai.mit.edu -@end group -@end example - -@noindent -Please include the manual's edition number and update date in your messages. - -@node Texinfo Mode, Beginning a File, Overview, Top -@comment node-name, next, previous, up -@chapter Using Texinfo Mode -@cindex Texinfo mode -@cindex Mode, using Texinfo -@cindex GNU Emacs -@cindex Emacs - -You may edit a Texinfo file with any text editor you choose. A Texinfo -file is no different from any other @sc{ascii} file. However, GNU Emacs -comes with a special mode, called Texinfo -mode, that provides Emacs commands and tools to help ease your work.@refill - -This chapter describes features of GNU Emacs' Texinfo mode but not any -features of the Texinfo formatting language. If you are reading this -manual straight through from the beginning, you may want to skim through -this chapter briefly and come back to it after reading succeeding -chapters which describe the Texinfo formatting language in -detail.@refill - -@menu -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. -@end menu - -@node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode -@ifinfo -@heading Texinfo Mode Overview -@end ifinfo - -Texinfo mode provides special features for working with Texinfo -files:@refill - -@itemize @bullet -@item -Insert frequently used @@-commands. @refill - -@item -Automatically create @code{@@node} lines. - -@item -Show the structure of a Texinfo source file.@refill - -@item -Automatically create or update the `Next', -`Previous', and `Up' pointers of a node. - -@item -Automatically create or update menus.@refill - -@item -Automatically create a master menu.@refill - -@item -Format a part or all of a file for Info.@refill - -@item -Typeset and print part or all of a file.@refill -@end itemize - -Perhaps the two most helpful features are those for inserting frequently -used @@-commands and for creating node pointers and menus.@refill - -@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode -@section The Usual GNU Emacs Editing Commands - -In most cases, the usual Text mode commands work the same in Texinfo -mode as they do in Text mode. Texinfo mode adds new editing commands -and tools to GNU Emacs' general purpose editing features. The major -difference concerns filling. In Texinfo mode, the paragraph -separation variable and syntax table are redefined so that Texinfo -commands that should be on lines of their own are not inadvertently -included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) -command will refill a paragraph but not mix an indexing command on a -line adjacent to it into the paragraph.@refill - -In addition, Texinfo mode sets the @code{page-delimiter} variable to -the value of @code{texinfo-chapter-level-regexp}; by default, this is -a regular expression matching the commands for chapters and their -equivalents, such as appendices. With this value for the page -delimiter, you can jump from chapter title to chapter title with the -@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} -(@code{backward-page}) commands and narrow to a chapter with the -@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, -The GNU Emacs Manual}, for details about the page commands.)@refill - -You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the three extensions -@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is -preferred, since it is explicit, but a shorter extension may be -necessary for operating systems that limit the length of file names. -GNU Emacs automatically enters Texinfo mode when you visit a file with -a @file{.texinfo} or @file{.texi} -extension. Also, Emacs switches to Texinfo mode -when you visit a -file that has @samp{-*-texinfo-*-} in its first line. If ever you are -in another mode and wish to switch to Texinfo mode, type @code{M-x -texinfo-mode}.@refill - -Like all other Emacs features, you can customize or enhance Texinfo -mode as you wish. In particular, the keybindings are very easy to -change. The keybindings described here are the default or standard -ones.@refill - -@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode -@comment node-name, next, previous, up -@section Inserting Frequently Used Commands -@cindex Inserting frequently used commands -@cindex Frequently used commands, inserting -@cindex Commands, inserting them - -Texinfo mode provides commands to insert various frequently used -@@-commands into the buffer. You can use these commands to save -keystrokes.@refill - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command:@refill - -@table @kbd -@item C-c C-c c -@itemx M-x texinfo-insert-@@code -@findex texinfo-insert-@@code -Insert @code{@@code@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c d -@itemx M-x texinfo-insert-@@dfn -@findex texinfo-insert-@@dfn -Insert @code{@@dfn@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c e -@itemx M-x texinfo-insert-@@end -@findex texinfo-insert-@@end -Insert @code{@@end} and attempt to insert the correct following word, -such as @samp{example} or @samp{table}. (This command does not handle -nested lists correctly, but inserts the word appropriate to the -immediately preceding list.)@refill - -@item C-c C-c i -@itemx M-x texinfo-insert-@@item -@findex texinfo-insert-@@item -Insert @code{@@item} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c k -@itemx M-x texinfo-insert-@@kbd -@findex texinfo-insert-@@kbd -Insert @code{@@kbd@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c n -@itemx M-x texinfo-insert-@@node -@findex texinfo-insert-@@node -Insert @code{@@node} and a comment line -listing the sequence for the `Next', -`Previous', and `Up' nodes. -Leave point after the @code{@@node}.@refill - -@item C-c C-c o -@itemx M-x texinfo-insert-@@noindent -@findex texinfo-insert-@@noindent -Insert @code{@@noindent} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c s -@itemx M-x texinfo-insert-@@samp -@findex texinfo-insert-@@samp -Insert @code{@@samp@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c t -@itemx M-x texinfo-insert-@@table -@findex texinfo-insert-@@table -Insert @code{@@table} followed by a @key{SPC} -and leave the cursor after the @key{SPC}.@refill - -@item C-c C-c v -@itemx M-x texinfo-insert-@@var -@findex texinfo-insert-@@var -Insert @code{@@var@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c x -@itemx M-x texinfo-insert-@@example -@findex texinfo-insert-@@example -Insert @code{@@example} and put the -cursor at the beginning of the next line.@refill - -@c M-@{ was the binding for texinfo-insert-braces; -@c in Emacs 19, backward-paragraph will take this binding. -@item C-c C-c @{ -@itemx M-x texinfo-insert-braces -@findex texinfo-insert-braces -Insert @code{@{@}} and put the cursor between the braces.@refill - -@item C-c C-c @} -@itemx C-c C-c ] -@itemx M-x up-list -@findex up-list -Move from between a pair of braces forward past the closing brace. -Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which -is, however, more mnemonic; hence the two keybindings. (Also, you can -move out from between braces by typing @kbd{C-f}.)@refill -@end table - -To put a command such as @w{@code{@@code@{@dots{}@}}} around an -@emph{existing} word, position the cursor in front of the word and type -@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. -The value of the prefix argument tells Emacs how many words following -point to include between braces---@samp{1} for one word, @samp{2} for -two words, and so on. Use a negative argument to enclose the previous -word or words. If you do not specify a prefix argument, Emacs inserts -the @@-command string and positions the cursor between the braces. This -feature works only for those @@-commands that operate on a word or words -within one line, such as @code{@@kbd} and @code{@@var}.@refill - -This set of insert commands was created after analyzing the frequency -with which different @@-commands are used in the @cite{GNU Emacs -Manual} and the @cite{GDB Manual}. If you wish to add your own insert -commands, you can bind a keyboard macro to a key, use abbreviations, -or extend the code in @file{texinfo.el}.@refill - -@findex texinfo-start-menu-description -@cindex Menu description, start -@cindex Description for menu, start -@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert -command that works differently from the other insert commands. It -inserts a node's section or chapter title in the space for the -description in a menu entry line. (A menu entry has three parts, the -entry name, the node name, and the description. Only the node name is -required, but a description helps explain what the node is about. -@xref{Menu Parts, , The Parts of a Menu}.)@refill - -To use @code{texinfo-start-menu-description}, position point in a menu -entry line and type @kbd{C-c C-c C-d}. The command looks for and copies -the title that goes with the node name, and inserts the title as a -description; it positions point at beginning of the inserted text so you -can edit it. The function does not insert the title if the menu entry -line already contains a description.@refill - -This command is only an aid to writing descriptions; it does not do the -whole job. You must edit the inserted text since a title tends to use -the same words as a node name but a useful description uses different -words.@refill - -@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode -@comment node-name, next, previous, up -@section Showing the Section Structure of a File -@cindex Showing the section structure of a file -@cindex Section structure of a file, showing it -@cindex Structure of a file, showing it -@cindex Outline of file structure, showing it -@cindex Contents-like outline of file structure -@cindex File section structure, showing it -@cindex Texinfo file section structure, showing it - -You can show the section structure of a Texinfo file by using the -@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command -shows the section structure of a Texinfo file by listing the lines -that begin with the @@-commands for @code{@@chapter}, -@code{@@section}, and the like. It constructs what amounts -to a table of contents. These lines are displayed in another buffer -called the @samp{*Occur*} buffer. In that buffer, you can position -the cursor over one of the lines and use the @kbd{C-c C-c} command -(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot -in the Texinfo file.@refill - -@table @kbd -@item C-c C-s -@itemx M-x texinfo-show-structure -@findex texinfo-show-structure -Show the @code{@@chapter}, @code{@@section}, and such lines of a -Texinfo file.@refill - -@item C-c C-c -@itemx M-x occur-mode-goto-occurrence -@findex occur-mode-goto-occurrence -Go to the line in the Texinfo file corresponding to the line under the -cursor in the @file{*Occur*} buffer.@refill -@end table - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the -@@-commands for @code{@@chapter}, @code{@@section}, and the like, -but also the @code{@@node} lines. (This is how the -@code{texinfo-show-structure} command worked without an argument in -the first version of Texinfo. It was changed because @code{@@node} -lines clutter up the @samp{*Occur*} buffer and are usually not -needed.) You can use @code{texinfo-show-structure} with a prefix -argument to check whether the `Next', `Previous', and `Up' pointers of -an @code{@@node} line are correct.@refill - -Often, when you are working on a manual, you will be interested only -in the structure of the current chapter. In this case, you can mark -off the region of the buffer that you are interested in by using the -@kbd{C-x n n} (@code{narrow-to-region}) command and -@code{texinfo-show-structure} will work on only that region. To see -the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). -(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more -information about the narrowing commands.)@refill - -@vindex page-delimiter -@cindex Page delimiter in Texinfo mode -In addition to providing the @code{texinfo-show-structure} command, -Texinfo mode sets the value of the page delimiter variable to match -the chapter-level @@-commands. This enables you to use the @kbd{C-x -]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) -commands to move forward and backward by chapter, and to use the -@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter. -@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information -about the page commands.@refill - -@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode -@comment node-name, next, previous, up -@section Updating Nodes and Menus -@cindex Updating nodes and menus -@cindex Create nodes, menus automatically -@cindex Insert nodes, menus automatically -@cindex Automatically insert nodes, menus - -Texinfo mode provides commands for automatically creating or updating -menus and node pointers. The commands are called ``update'' commands -because their most frequent use is for updating a Texinfo file after -you have worked on it; but you can use them to insert the `Next', -`Previous', and `Up' pointers into an @code{@@node} line that has none and to -create menus in a file that has none.@refill - -If you do not use the updating commands, you need to write menus and -node pointers by hand, which is a tedious task.@refill - -@menu -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. -@end menu - -@node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus -@ifinfo -@subheading The Updating Commands -@end ifinfo - -You can use the updating commands@refill - -@itemize @bullet -@item -to insert or update the `Next', `Previous', and `Up' pointers of a -node,@refill - -@item -to insert or update the menu for a section, and@refill - -@item -to create a master menu for a Texinfo source file.@refill -@end itemize - -You can also use the commands to update all the nodes and menus in a -region or in a whole Texinfo file.@refill - -The updating commands work only with conventional Texinfo files, which -are structured hierarchically like books. In such files, a structuring -command line must follow closely after each @code{@@node} line, except -for the `Top' @code{@@node} line. (A @dfn{structuring command line} is -a line beginning with @code{@@chapter}, @code{@@section}, or other -similar command.) - -You can write the structuring command line on the line that follows -immediately after an @code{@@node} line or else on the line that -follows after a single @code{@@comment} line or a single -@code{@@ifinfo} line. You cannot interpose more than one line between -the @code{@@node} line and the structuring command line; and you may -interpose only an @code{@@comment} line or an @code{@@ifinfo} line. - -Commands which work on a whole buffer require that the `Top' node be -followed by a node with an @code{@@chapter} or equivalent-level command. -Note that the menu updating commands will not create a main or master -menu for a Texinfo file that has only @code{@@chapter}-level nodes! The -menu updating commands only create menus @emph{within} nodes for lower level -nodes. To create a menu of chapters, you must provide a `Top' -node.@refill - -The menu updating commands remove menu entries that refer to other Info -files since they do not refer to nodes within the current buffer. This -is a deficiency. Rather than use menu entries, you can use cross -references to refer to other Info files. None of the updating commands -affect cross references.@refill - -Texinfo mode has five updating commands that are used most often: two -are for updating the node pointers or menu of a single node (or a -region); two are for updating every node pointer and menu in a file; -and one, the @code{texinfo-master-menu} command, is for creating a -master menu for a complete file, and optionally, for updating every -node and menu in the whole Texinfo file.@refill - -The @code{texinfo-master-menu} command is the primary command:@refill - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -@findex texinfo-master-menu -Create or update a master menu that includes all the other menus -(incorporating the descriptions from pre-existing menus, if -any).@refill - -With an argument (prefix argument, @kbd{C-u,} if interactive), first create or -update all the nodes and all the regular menus in the buffer before -constructing the master menu. (@xref{The Top Node, , The Top Node and -Master Menu}, for more about a master menu.)@refill - -For @code{texinfo-master-menu} to work, the Texinfo file must have a -`Top' node and at least one subsequent node.@refill - -After extensively editing a Texinfo file, you can type the following: - -@example -C-u M-x texinfo-master-menu -@exdent or -C-u C-c C-u m -@end example - -@noindent -This updates all the nodes and menus completely and all at once.@refill -@end table - -The other major updating commands do smaller jobs and are designed for -the person who updates nodes and menus as he or she writes a Texinfo -file.@refill - -@need 1000 -The commands are:@refill - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -@findex texinfo-update-node -Insert the `Next', `Previous', and `Up' pointers for the node that point is -within (i.e., for the @code{@@node} line preceding point). If the -@code{@@node} line has pre-existing `Next', `Previous', or `Up' -pointers in it, the old pointers are removed and new ones inserted. -With an argument (prefix argument, @kbd{C-u}, if interactive), this command -updates all @code{@@node} lines in the region (which is the text -between point and mark).@refill - -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -@findex texinfo-make-menu -Create or update the menu in the node that point is within. -With an argument (@kbd{C-u} as prefix argument, if -interactive), the command makes or updates menus for the -nodes which are either within or a part of the -region.@refill - -Whenever @code{texinfo-make-menu} updates an existing menu, the -descriptions from that menu are incorporated into the new menu. This -is done by copying descriptions from the existing menu to the entries -in the new menu that have the same node names. If the node names are -different, the descriptions are not copied to the new menu.@refill - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -@findex texinfo-every-node-update -Insert or update the `Next', `Previous', and `Up' pointers for every -node in the buffer.@refill - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -@findex texinfo-all-menus-update -Create or update all the menus in the buffer. With an argument -(@kbd{C-u} as prefix argument, if interactive), first insert -or update all the node -pointers before working on the menus.@refill - -If a master menu exists, the @code{texinfo-all-menus-update} command -updates it; but the command does not create a new master menu if none -already exists. (Use the @code{texinfo-master-menu} command for -that.)@refill - -When working on a document that does not merit a master menu, you can -type the following: - -@example -C-u C-c C-u C-a -@exdent or -C-u M-x texinfo-all-menus-update -@end example - -@noindent -This updates all the nodes and menus.@refill -@end table - -The @code{texinfo-column-for-description} variable specifies the -column to which menu descriptions are indented. By default, the value -is 32 although it is often useful to reduce it to as low as 24. You -can set the variable with the @kbd{M-x edit-options} command -(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs -Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, -, Examining and Setting Variables, emacs, The GNU Emacs -Manual}).@refill - -Also, the @code{texinfo-indent-menu-description} command may be used to -indent existing menu descriptions to a specified column. Finally, if -you wish, you can use the @code{texinfo-insert-node-lines} command to -insert missing @code{@@node} lines into a file. (@xref{Other Updating -Commands}, for more information.)@refill - -@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus -@comment node-name, next, previous, up -@subsection Updating Requirements -@cindex Updating requirements -@cindex Requirements for updating commands - -To use the updating commands, you must organize the Texinfo file -hierarchically with chapters, sections, subsections, and the like. -When you construct the hierarchy of the manual, do not `jump down' -more than one level at a time: you can follow the `Top' node with a -chapter, but not with a section; you can follow a chapter with a -section, but not with a subsection. However, you may `jump up' any -number of levels at one time---for example, from a subsection to a -chapter.@refill - -Each @code{@@node} line, with the exception of the line for the `Top' -node, must be followed by a line with a structuring command such as -@code{@@chapter}, @code{@@section}, or -@code{@@unnumberedsubsec}.@refill - -Each @code{@@node} line/structuring-command line combination -must look either like this:@refill - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@comment node-name, next, previous, up -@@section Comments -@end group -@end example - -or like this (without the @code{@@comment} line): - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@section Comments -@end group -@end example - -@noindent -In this example, `Comments' is the name of both the node and the -section. The next node is called `Minimum' and the previous node is -called `Conventions'. The `Comments' section is within the `Overview' -node, which is specified by the `Up' pointer. (Instead of an -@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill - -If a file has a `Top' node, it must be called @samp{top} or @samp{Top} -and be the first node in the file.@refill - -The menu updating commands create a menu of sections within a chapter, -a menu of subsections within a section, and so on. This means that -you must have a `Top' node if you want a menu of chapters.@refill - -Incidentally, the @code{makeinfo} command will create an Info file for -a hierarchically organized Texinfo file that lacks `Next', `Previous' -and `Up' pointers. Thus, if you can be sure that your Texinfo file -will be formatted with @code{makeinfo}, you have no need for the -`update node' commands. (@xref{Create an Info File, , Creating an -Info File}, for more information about @code{makeinfo}.) However, -both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands -require that you insert menus in the file.@refill - -@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus -@comment node-name, next, previous, up -@subsection Other Updating Commands - -In addition to the five major updating commands, Texinfo mode -possesses several less frequently used updating commands:@refill - -@table @kbd -@item M-x texinfo-insert-node-lines -@findex texinfo-insert-node-lines -Insert @code{@@node} lines before the @code{@@chapter}, -@code{@@section}, and other sectioning commands wherever they are -missing throughout a region in a Texinfo file.@refill - -With an argument (@kbd{C-u} as prefix argument, if interactive), the -@code{texinfo-insert-node-lines} command not only inserts -@code{@@node} lines but also inserts the chapter or section titles as -the names of the corresponding nodes. In addition, it inserts the -titles as node names in pre-existing @code{@@node} lines that lack -names. Since node names should be more concise than section or -chapter titles, you must manually edit node names so inserted.@refill - -For example, the following marks a whole buffer as a region and inserts -@code{@@node} lines and titles throughout:@refill - -@example -C-x h C-u M-x texinfo-insert-node-lines -@end example - -(Note that this command inserts titles as node names in @code{@@node} -lines; the @code{texinfo-start-menu-description} command -(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles -as descriptions in menu entries, a different action. However, in both -cases, you need to edit the inserted text.)@refill - -@item M-x texinfo-multiple-files-update -@findex texinfo-multiple-files-update @r{(in brief)} -Update nodes and menus in a document built from several separate files. -With @kbd{C-u} as a prefix argument, create and insert a master menu in -the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first -update all the menus and all the `Next', `Previous', and `Up' pointers -of all the included files before creating and inserting a master menu in -the outer file. The @code{texinfo-multiple-files-update} command is -described in the appendix on @code{@@include} files. -@ifinfo -@xref{texinfo-multiple-files-update}.@refill -@end ifinfo -@iftex -@xref{texinfo-multiple-files-update, , -@code{texinfo-multiple-files-update}}.@refill -@end iftex - -@item M-x texinfo-indent-menu-description -@findex texinfo-indent-menu-description -Indent every description in the menu following point to the specified -column. You can use this command to give yourself more space for -descriptions. With an argument (@kbd{C-u} as prefix argument, if -interactive), the @code{texinfo-indent-menu-description} command indents -every description in every menu in the region. However, this command -does not indent the second and subsequent lines of a multi-line -description.@refill - -@item M-x texinfo-sequential-node-update -@findex texinfo-sequential-node-update -Insert the names of the nodes immediately following and preceding the -current node as the `Next' or `Previous' pointers regardless of those -nodes' hierarchical level. This means that the `Next' node of a -subsection may well be the next chapter. Sequentially ordered nodes are -useful for novels and other documents that you read through -sequentially. (However, in Info, the @kbd{g *} command lets -you look through the file sequentially, so sequentially ordered nodes -are not strictly necessary.) With an argument (prefix argument, if -interactive), the @code{texinfo-sequential-node-update} command -sequentially updates all the nodes in the region.@refill -@end table - -@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode -@comment node-name, next, previous, up -@section Formatting for Info -@cindex Formatting for Info -@cindex Running an Info formatter -@cindex Info formatting - -Texinfo mode provides several commands for formatting part or all of a -Texinfo file for Info. Often, when you are writing a document, you -want to format only part of a file---that is, a region.@refill - -You can use either the @code{texinfo-format-region} or the -@code{makeinfo-region} command to format a region:@refill - -@table @kbd -@findex texinfo-format-region -@item C-c C-e C-r -@itemx M-x texinfo-format-region -@itemx C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@end table - -You can use either the @code{texinfo-format-buffer} or the -@code{makeinfo-buffer} command to format a whole buffer:@refill - -@table @kbd -@findex texinfo-format-buffer -@item C-c C-e C-b -@itemx M-x texinfo-format-buffer -@itemx C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@end table - -@need 1000 -For example, after writing a Texinfo file, you can type the following: - -@example -C-u C-c C-u m -@exdent or -C-u M-x texinfo-master-menu -@end example - -@noindent -This updates all the nodes and menus. Then type the following to create -an Info file: - -@example -C-c C-m C-b -@exdent or -M-x makeinfo-buffer -@end example - -For @TeX{} or the Info formatting commands to work, the file @emph{must} -include a line that has @code{@@setfilename} in its header.@refill - -@xref{Create an Info File}, for details about Info formatting.@refill - -@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode -@comment node-name, next, previous, up -@section Formatting and Printing -@cindex Formatting for printing -@cindex Printing a region or buffer -@cindex Region formatting and printing -@cindex Buffer formatting and printing -@cindex Part of file formatting and printing - -Typesetting and printing a Texinfo file is a multi-step process in which -you first create a file for printing (called a DVI file), and then -print the file. Optionally, you may also create indices. To do this, -you must run the @code{texindex} command after first running the -@code{tex} typesetting command; and then you must run the @code{tex} -command again. Or else run the @code{texi2dvi} command which -automatically creates indices as needed.@refill - -Often, when you are writing a document, you want to typeset and print -only part of a file to see what it will look like. You can use the -@code{texinfo-tex-region} and related commands for this purpose. Use -the @code{texinfo-tex-buffer} command to format all of a -buffer.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -@findex texinfo-tex-buffer -Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the -buffer, this command automatically creates or updates indices as -needed.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -@findex texinfo-tex-region -Run @TeX{} on the region.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Run @code{texindex} to sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does -not run @code{texindex} automatically; it only runs the @code{tex} -typesetting command. You must run the @code{texinfo-tex-region} command -a second time after sorting the raw index files with the @code{texindex} -command. (Usually, you do not format an index when you format a region, -only when you format a buffer. Now that the @code{texi2dvi} command -exists, there is little or no need for this command.)@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -@findex texinfo-tex-print -Print the file (or the part of the file) previously formatted with -@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill -@end table - -For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the -file @emph{must} start with a @samp{\input texinfo} line and must -include an @code{@@settitle} line. The file must end with @code{@@bye} -on a line by itself. (When you use @code{texinfo-tex-region}, you must -surround the @code{@@settitle} line with start-of-header and -end-of-header lines.)@refill - -@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related -commands, such as @code{tex-show-print-queue}.@refill - -@node Texinfo Mode Summary, , Printing, Texinfo Mode -@comment node-name, next, previous, up -@section Texinfo Mode Summary - -In Texinfo mode, each set of commands has default keybindings that -begin with the same keys. All the commands that are custom-created -for Texinfo mode begin with @kbd{C-c}. The keys are somewhat -mnemonic.@refill - -@subheading Insert Commands - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command to be inserted. (It might make more -sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but -@kbd{C-c C-c} is quick to type.)@refill - -@example -C-c C-c c @r{Insert} @samp{@@code}. -C-c C-c d @r{Insert} @samp{@@dfn}. -C-c C-c e @r{Insert} @samp{@@end}. -C-c C-c i @r{Insert} @samp{@@item}. -C-c C-c n @r{Insert} @samp{@@node}. -C-c C-c s @r{Insert} @samp{@@samp}. -C-c C-c v @r{Insert} @samp{@@var}. -C-c C-c @{ @r{Insert braces.} -C-c C-c ] -C-c C-c @} @r{Move out of enclosing braces.} - -@group -C-c C-c C-d @r{Insert a node's section title} - @r{in the space for the description} - @r{in a menu entry line.} -@end group -@end example - -@subheading Show Structure - -The @code{texinfo-show-structure} command is often used within a -narrowed region.@refill - -@example -C-c C-s @r{List all the headings.} -@end example - -@subheading The Master Update Command - -The @code{texinfo-master-menu} command creates a master menu; and can -be used to update every node and menu in a file as well.@refill - -@example -@group -C-c C-u m -M-x texinfo-master-menu - @r{Create or update a master menu.} -@end group - -@group -C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} - @r{create or update all nodes and regular} - @r{menus, and then create a master menu.} -@end group -@end example - -@subheading Update Pointers - -The update pointer commands are invoked by typing @kbd{C-c C-u} and -then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for -@code{texinfo-every-node-update}.@refill - -@example -C-c C-u C-n @r{Update a node.} -C-c C-u C-e @r{Update every node in the buffer.} -@end example - -@subheading Update Menus - -Invoke the update menu commands by typing @kbd{C-c C-u} -and then either @kbd{C-m} for @code{texinfo-make-menu} or -@kbd{C-a} for @code{texinfo-all-menus-update}. To update -both nodes and menus at the same time, precede @kbd{C-c C-u -C-a} with @kbd{C-u}.@refill - -@example -C-c C-u C-m @r{Make or update a menu.} - -@group -C-c C-u C-a @r{Make or update all} - @r{menus in a buffer.} -@end group - -@group -C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} - @r{first create or update all nodes and} - @r{then create or update all menus.} -@end group -@end example - -@subheading Format for Info - -The Info formatting commands that are written in Emacs Lisp are -invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region -or @kbd{C-b} for the whole buffer.@refill - -The Info formatting commands that are written in C and based on the -@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then -either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill - -@need 800 -@noindent -Use the @code{texinfo-format@dots{}} commands: - -@example -@group -C-c C-e C-r @r{Format the region.} -C-c C-e C-b @r{Format the buffer.} -@end group -@end example - -@need 750 -@noindent -Use @code{makeinfo}: - -@example -C-c C-m C-r @r{Format the region.} -C-c C-m C-b @r{Format the buffer.} -C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} -C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} -@end example - -@subheading Typeset and Print - -The @TeX{} typesetting and printing commands are invoked by typing -@kbd{C-c C-t} and then another control command: @kbd{C-r} for -@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, -and so on.@refill - -@example -C-c C-t C-r @r{Run @TeX{} on the region.} -C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} -C-c C-t C-i @r{Run} @code{texindex}. -C-c C-t C-p @r{Print the DVI file.} -C-c C-t C-q @r{Show the print queue.} -C-c C-t C-d @r{Delete a job from the print queue.} -C-c C-t C-k @r{Kill the current @TeX{} formatting job.} -C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} -C-c C-t C-l @r{Recenter the output buffer.} -@end example - -@subheading Other Updating Commands - -The `other updating commands' do not have standard keybindings because -they are rarely used. - -@example -@group -M-x texinfo-insert-node-lines - @r{Insert missing @code{@@node} lines in region.} - @r{With @kbd{C-u} as a prefix argument,} - @r{use section titles as node names.} -@end group - -@group -M-x texinfo-multiple-files-update - @r{Update a multi-file document.} - @r{With @kbd{C-u 2} as a prefix argument,} - @r{create or update all nodes and menus} - @r{in all included files first.} -@end group - -@group -M-x texinfo-indent-menu-description - @r{Indent descriptions.} -@end group - -@group -M-x texinfo-sequential-node-update - @r{Insert node pointers in strict sequence.} -@end group -@end example - -@node Beginning a File, Ending a File, Texinfo Mode, Top -@comment node-name, next, previous, up -@chapter Beginning a Texinfo File -@cindex Beginning a Texinfo file -@cindex Texinfo file beginning -@cindex File beginning - -Certain pieces of information must be provided at the beginning of a -Texinfo file, such as the name of the file and the title of the -document.@refill - -@menu -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. -@end menu - -@node Four Parts, Sample Beginning, Beginning a File, Beginning a File -@ifinfo -@heading Four Parts Begin a File -@end ifinfo - -Generally, the beginning of a Texinfo file has four parts:@refill - -@enumerate -@item -The header, delimited by special comment lines, that includes the -commands for naming the Texinfo file and telling @TeX{} what -definitions file to use when processing the Texinfo file.@refill - -@item -A short statement of what the file is about, with a copyright notice -and copying permissions. This is enclosed in @code{@@ifinfo} and -@code{@@end ifinfo} commands so that the formatters place it only -in the Info file.@refill - -@item -A title page and copyright page, with a copyright notice and copying -permissions. This is enclosed between @code{@@titlepage} and -@code{@@end titlepage} commands. The title and copyright page appear -only in the printed @w{manual}.@refill - -@item -The `Top' node that contains a menu for the whole Info file. The -contents of this node appear only in the Info file.@refill -@end enumerate - -Also, optionally, you may include the copying conditions for a program -and a warranty disclaimer. The copying section will be followed by an -introduction or else by the first chapter of the manual.@refill - -Since the copyright notice and copying permissions for the Texinfo -document (in contrast to the copying permissions for a program) are in -parts that appear only in the Info file or only in the printed manual, -this information must be given twice.@refill - -@node Sample Beginning, Header, Four Parts, Beginning a File -@comment node-name, next, previous, up -@section Sample Texinfo File Beginning - -The following sample shows what is needed.@refill - -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{name-of-info-file} -@@settitle @var{name-of-manual} -@@setchapternewpage odd -@@c %**end of header - -@@ifinfo -This file documents @dots{} - -Copyright @var{year} @var{copyright-owner} - -@group -Permission is granted to @dots{} -@@end ifinfo -@end group - -@group -@@c This title page illustrates only one of the -@@c two methods of forming a title page. -@end group - -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@end group - -@group -@@c The following two commands -@@c start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} @var{year} @var{copyright-owner} -@end group - -Published by @dots{} - -Permission is granted to @dots{} -@@end titlepage - -@@node Top, Overview, , (dir) - -@@ifinfo -This document describes @dots{} - -This document applies to version @dots{} -of the program named @dots{} -@@end ifinfo - -@group -@@menu -* Copying:: Your rights and freedoms. -* First Chapter:: Getting started @dots{} -* Second Chapter:: @dots{} - @dots{} - @dots{} -@@end menu -@end group - -@group -@@node First Chapter, Second Chapter, top, top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Index entry for First Chapter -@end group -@end example - -@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File -@comment node-name, next, previous, up -@section The Texinfo File Header -@cindex Header for Texinfo files -@cindex Texinfo file header - -Texinfo files start with at least three lines that provide Info and -@TeX{} with necessary information. These are the @code{\input -texinfo} line, the @code{@@settitle} line, and the -@code{@@setfilename} line. If you want to run @TeX{} on just a part -of the Texinfo File, you must write the @code{@@settitle} -and @code{@@setfilename} lines between start-of-header and end-of-header -lines.@refill - -Thus, the beginning of a Texinfo file looks like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@setfilename sample.info -@@settitle Sample Document -@end group -@end example - -@noindent -or else like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header -@end group -@end example - -@menu -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. -@end menu - -@node First Line, Start of Header, Header, Header -@comment node-name, next, previous, up -@subsection The First Line of a Texinfo File -@cindex First line of a Texinfo file -@cindex Beginning line of a Texinfo file -@cindex Header of a Texinfo file - -Every Texinfo file that is to be the top-level input to @TeX{} must begin -with a line that looks like this:@refill - -@example -\input texinfo @@c -*-texinfo-*- -@end example - -@noindent -This line serves two functions: - -@enumerate -@item -When the file is processed by @TeX{}, the @samp{\input texinfo} command -tells @TeX{} to load the macros needed for processing a Texinfo file. -These are in a file called @file{texinfo.tex}, which is usually located -in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash, -@samp{\}, to mark the beginning of a command, just as Texinfo uses -@samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\} -to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which -is why it appears at the beginning of the file.@refill - -@item -When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode -specification tells Emacs to use Texinfo mode.@refill -@end enumerate - -@node Start of Header, setfilename, First Line, Header -@comment node-name, next, previous, up -@subsection Start of Header -@cindex Start of header line - -Write a start-of-header line on the second line of a Texinfo file. -Follow the start-of-header line with @code{@@setfilename} and -@code{@@settitle} lines and, optionally, with other command lines, such -as @code{@@smallbook} or @code{@@footnotestyle}; and then by an -end-of-header line (@pxref{End of Header}).@refill - -With these lines, you can format part of a Texinfo file for Info or -typeset part for printing.@refill - -A start-of-header line looks like this:@refill - -@example -@@c %**start of header -@end example - -The odd string of characters, @samp{%**}, is to ensure that no other -comment is accidentally taken for a start-of-header line.@refill - -@node setfilename, settitle, Start of Header, Header -@comment node-name, next, previous, up -@subsection @code{@@setfilename} -@cindex Info file requires @code{@@setfilename} -@findex setfilename - -In order to serve as the primary input file for either @code{makeinfo} -or @TeX{}, a Texinfo file must contain a line that looks like this: - -@example -@@setfilename @var{info-file-name} -@end example - -Write the @code{@@setfilename} command at the beginning of a line and -follow it on the same line by the Info file name. Do not write anything -else on the line; anything on the line after the command is considered -part of the file name, including what would otherwise be a -comment. - -The @code{@@setfilename} line specifies the name of the Info file to be -generated. This name should be different from the name of the Texinfo -file. There are two conventions for choosing the name: you can either -remove the @samp{.texi} extension from the input file name, or replace -it with the @samp{.info} extension. - -Some operating systems cannot handle long file names. You can run into -a problem even when the file name you specify is itself short enough. -This occurs because the Info formatters split a long Info file into -short indirect subfiles, and name them by appending @samp{-1}, -@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original -file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.) -The subfile name @file{texinfo.info-10}, for example, is too long for -some systems; so the Info file name for this document is @file{texinfo} -rather than @file{texinfo.info}. - -@cindex Ignored before @code{@@setfilename} -The Info formatting commands ignore everything written before the -@code{@@setfilename} line, which is why the very first line of -the file (the @code{\input} line) does not show up in the output. - -@pindex texinfo.cnf -The @code{@@setfilename} line produces no output when you typeset a -manual with @TeX{}, but it nevertheless is essential: it opens the -index, cross-reference, and other auxiliary files used by Texinfo, and -also reads @file{texinfo.cnf} if that file is present on your system -(@pxref{Preparing for TeX,, Preparing to Use @TeX{}}). - - -@node settitle, setchapternewpage, setfilename, Header -@comment node-name, next, previous, up -@subsection @code{@@settitle} -@findex settitle - -In order to be made into a printed manual, a Texinfo file must contain -a line that looks like this:@refill - -@example -@@settitle @var{title} -@end example - -Write the @code{@@settitle} command at the beginning of a line and -follow it on the same line by the title. This tells @TeX{} the title -to use in a header or footer. Do not write anything else on the line; -anything on the line after the command is considered part of the -title, including a comment.@refill - -Conventionally, when @TeX{} formats a Texinfo file for double-sided -output, the title is printed in the left-hand (even-numbered) page -headings and the current chapter title is printed in the right-hand -(odd-numbered) page headings. (@TeX{} learns the title of each chapter -from each @code{@@chapter} command.) Page footers are not -printed.@refill - -Even if you are printing in a single-sided style, @TeX{} looks for an -@code{@@settitle} command line, in case you include the manual title -in the heading. @refill - -The @code{@@settitle} command should precede everything that generates -actual output in @TeX{}.@refill - -Although the title in the @code{@@settitle} command is usually the -same as the title on the title page, it does not affect the title as -it appears on the title page. Thus, the two do not need not match -exactly; and the title in the @code{@@settitle} command can be a -shortened or expanded version of the title as it appears on the title -page. (@xref{titlepage, , @code{@@titlepage}}.)@refill - -@TeX{} prints page headings only for that text that comes after the -@code{@@end titlepage} command in the Texinfo file, or that comes -after an @code{@@headings} command that turns on headings. -(@xref{headings on off, , The @code{@@headings} Command}, for more -information.)@refill - -You may, if you wish, create your own, customized headings and -footings. @xref{Headings, , Page Headings}, for a detailed discussion -of this process.@refill - -@node setchapternewpage, paragraphindent, settitle, Header -@comment node-name, next, previous, up -@subsection @code{@@setchapternewpage} -@cindex Starting chapters -@cindex Pages, starting odd -@findex setchapternewpage - -In a book or a manual, text is usually printed on both sides of the -paper, chapters start on right-hand pages, and right-hand pages have -odd numbers. But in short reports, text often is printed only on one -side of the paper. Also in short reports, chapters sometimes do not -start on new pages, but are printed on the same page as the end of the -preceding chapter, after a small amount of vertical whitespace.@refill - -You can use the @code{@@setchapternewpage} command with various -arguments to specify how @TeX{} should start chapters and whether it -should typeset pages for printing on one or both sides of the paper -(single-sided or double-sided printing).@refill - -Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument.@refill - -For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page:@refill - -@example -@@setchapternewpage odd -@end example - -You can specify one of three alternatives with the -@code{@@setchapternewpage} command:@refill - -@table @asis -@ignore -@item No @code{@@setchapternewpage} command -If the Texinfo file does not contain an @code{@@setchapternewpage} -command before the @code{@@titlepage} command, @TeX{} automatically -begins chapters on new pages and prints headings in the standard -format for single-sided printing. This is the conventional format for -single-sided printing.@refill - -The result is exactly the same as when you write -@code{@@setchapternewpage on}.@refill -@end ignore -@item @code{@@setchapternewpage off} -Cause @TeX{} to typeset a new chapter on the same page as the last -chapter, after skipping some vertical whitespace. Also, cause @TeX{} to -format page headers for single-sided printing. (You can override the -headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to typeset page -headers for single-sided printing. This is the form most often -used for short reports.@refill - -This alternative is the default.@refill - -@item @code{@@setchapternewpage odd} -Cause @TeX{} to start new chapters on new, odd-numbered pages -(right-handed pages) and to typeset for double-sided printing. This is -the form most often used for books and manuals.@refill -@end table - -@noindent -Texinfo does not have an @code{@@setchapternewpage even} command.@refill - -@noindent -(You can countermand or modify an @code{@@setchapternewpage} command -with an @code{@@headings} command. @xref{headings on off, , The -@code{@@headings} Command}.)@refill - -At the beginning of a manual or book, pages are not numbered---for -example, the title and copyright pages of a book are not numbered. -By convention, table of contents pages are numbered with roman -numerals and not in sequence with the rest of the document.@refill - -Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it.@refill - -Usually, you do not write an @code{@@setchapternewpage} command for -single-sided printing, but accept the default which is to typeset for -single-sided printing and to start new chapters on new pages. Usually, -you write an @code{@@setchapternewpage odd} command for double-sided -printing.@refill - -@node paragraphindent, End of Header, setchapternewpage, Header -@comment node-name, next, previous, up -@subsection Paragraph Indenting -@cindex Indenting paragraphs -@cindex Paragraph indentation -@findex paragraphindent - -The Info formatting commands may insert spaces at the beginning of the -first line of each paragraph, thereby indenting that paragraph. You -can use the @code{@@paragraphindent} command to specify the -indentation. Write an @code{@@paragraphindent} command at the -beginning of a line followed by either @samp{asis} or a number. The -template is:@refill - -@example -@@paragraphindent @var{indent} -@end example - -The Info formatting commands indent according to the value of -@var{indent}:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, the Info formatting -commands do not change the existing indentation.@refill - -@item -If the value of @var{indent} is zero, the Info formatting commands delete -existing indentation.@refill - -@item -If the value of @var{indent} is greater than zero, the Info formatting -commands indent the paragraph by that number of spaces.@refill -@end itemize - -The default value of @var{indent} is @samp{asis}.@refill - -Write the @code{@@paragraphindent} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you write -the command between the start-of-header and end-of-header lines, the -region formatting commands indent paragraphs as specified.)@refill - -A peculiarity of the @code{texinfo-format-buffer} and -@code{texinfo-format-region} commands is that they do not indent (nor -fill) paragraphs that contain @code{@@w} or @code{@@*} commands. -@xref{Refilling Paragraphs}, for a detailed description of what goes -on.@refill - -@node End of Header, , paragraphindent, Header -@comment node-name, next, previous, up -@subsection End of Header -@cindex End of header line - -Follow the header lines with an @w{end-of-header} line. -An end-of-header line looks like this:@refill - -@example -@@c %**end of header -@end example - -If you include the @code{@@setchapternewpage} command between the -start-of-header and end-of-header lines, @TeX{} will typeset a region as -that command specifies. Similarly, if you include an @code{@@smallbook} -command between the start-of-header and end-of-header lines, @TeX{} will -typeset a region in the ``small'' book format.@refill - -@ifinfo -The reason for the odd string of characters (@samp{%**}) is so that the -@code{texinfo-tex-region} command does not accidentally find -something that it should not when it is looking for the header.@refill - -The start-of-header line and the end-of-header line are Texinfo mode -variables that you can change.@refill -@end ifinfo - -@iftex -@xref{Start of Header}. -@end iftex - -@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File -@comment node-name, next, previous, up -@section Summary and Copying Permissions for Info - -The title page and the copyright page appear only in the printed copy of -the manual; therefore, the same information must be inserted in a -section that appears only in the Info file. This section usually -contains a brief description of the contents of the Info file, a -copyright notice, and copying permissions.@refill - -The copyright notice should read:@refill - -@example -Copyright @var{year} @var{copyright-owner} -@end example - -@noindent -and be put on a line by itself.@refill - -Standard text for the copyright permissions is contained in an appendix -to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying -Permissions}, for the complete text.@refill - -The permissions text appears in an Info file @emph{before} the first -node. This mean that a reader does @emph{not} see this text when -reading the file using Info, except when using the advanced Info command -@kbd{g *}. - -@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File -@comment node-name, next, previous, up -@section The Title and Copyright Pages - -A manual's name and author are usually printed on a title page. -Sometimes copyright information is printed on the title page as well; -more often, copyright information is printed on the back of the title -page. - -The title and copyright pages appear in the printed manual, but not in the -Info file. Because of this, it is possible to use several slightly -obscure @TeX{} typesetting commands that cannot be used in an Info file. -In addition, this part of the beginning of a Texinfo file contains the text -of the copying permissions that will appear in the printed manual.@refill - -@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the -standard text for the copyright permissions.@refill - -@menu -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright & Permissions:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. -@end menu - -@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@titlepage} -@cindex Title page -@findex titlepage - -Start the material for the title page and following copyright page -with @code{@@titlepage} on a line by itself and end it with -@code{@@end titlepage} on a line by itself.@refill - -The @code{@@end titlepage} command starts a new page and turns on page -numbering. (@xref{Headings, , Page Headings}, for details about how to -generate page headings.) All the material that you want to -appear on unnumbered pages should be put between the -@code{@@titlepage} and @code{@@end titlepage} commands. By using the -@code{@@page} command you can force a page break within the region -delineated by the @code{@@titlepage} and @code{@@end titlepage} -commands and thereby create more than one unnumbered page. This is -how the copyright page is produced. (The @code{@@titlepage} command -might perhaps have been better named the -@code{@@titleandadditionalpages} command, but that would have been -rather long!)@refill - -@c !!! append refill to footnote when makeinfo can handle it. -When you write a manual about a computer program, you should write the -version of the program to which the manual applies on the title -page. If the manual changes more frequently than the program or is -independent of it, you should also include an edition -number@footnote{We have found that it is helpful to refer to versions -of manuals as `editions' and versions of programs as `versions'; -otherwise, we find we are liable to confuse each other in conversation -by referring to both the documentation and the software with the same -words.} for the manual. This helps readers keep track of which manual -is for which version of the program. (The `Top' node -should also contain this information; see @ref{makeinfo top, , -@code{@@top}}.)@refill - -Texinfo provides two main methods for creating a title page. One method -uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands -to generate a title page in which the words on the page are -centered.@refill - -The second method uses the @code{@@title}, @code{@@subtitle}, and -@code{@@author} commands to create a title page with black rules under -the title and author lines and the subtitle text set flush to the -right hand side of the page. With this method, you do not specify any -of the actual formatting of the title page. You specify the text -you want, and Texinfo does the formatting. You may use either -method.@refill - -@findex shorttitlepage -For extremely simple applications, Texinfo also provides a command -@code{@@shorttitlepage} which takes a single argument as the title. -The argument is typeset on a page by itself and followed by a blank -page. - - -@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} -@findex titlefont -@findex center -@findex sp @r{(titlepage line spacing)} - -You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} -commands to create a title page for a printed document. (This is the -first of the two methods for creating a title page in Texinfo.)@refill - -Use the @code{@@titlefont} command to select a large font suitable for -the title itself.@refill - -@need 700 -For example: - -@example -@@titlefont@{Texinfo@} -@end example - -Use the @code{@@center} command at the beginning of a line to center -the remaining text on that line. Thus,@refill - -@example -@@center @@titlefont@{Texinfo@} -@end example - -@noindent -centers the title, which in this example is ``Texinfo'' printed -in the title font.@refill - -Use the @code{@@sp} command to insert vertical space. For example:@refill - -@example -@@sp 2 -@end example - -@noindent -This inserts two blank lines on the printed page. (@xref{sp, , -@code{@@sp}}, for more information about the @code{@@sp} -command.)@refill - -A template for this method looks like this:@refill - -@example -@group -@@titlepage -@@sp 10 -@@center @@titlefont@{@var{name-of-manual-when-printed}@} -@@sp 2 -@@center @var{subtitle-if-any} -@@sp 2 -@@center @var{author} -@dots{} -@@end titlepage -@end group -@end example - -The spacing of the example fits an 8 1/2 by 11 inch manual.@refill - -@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} -@findex title -@findex subtitle -@findex author - -You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} -commands to create a title page in which the vertical and horizontal -spacing is done for you automatically. This contrasts with the method -described in -the previous section, in which the @code{@@sp} command is needed to -adjust vertical spacing.@refill - -Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} -commands at the beginning of a line followed by the title, subtitle, -or author.@refill - -The @code{@@title} command produces a line in which the title is set -flush to the left-hand side of the page in a larger than normal font. -The title is underlined with a black rule.@refill - -The @code{@@subtitle} command sets subtitles in a normal-sized font -flush to the right-hand side of the page.@refill - -The @code{@@author} command sets the names of the author or authors in -a middle-sized font flush to the left-hand side of the page on a line -near the bottom of the title page. The names are underlined with a -black rule that is thinner than the rule that underlines the title. -(The black rule only occurs if the @code{@@author} command line is -followed by an @code{@@page} command line.)@refill - -There are two ways to use the @code{@@author} command: you can write -the name or names on the remaining part of the line that starts with -an @code{@@author} command:@refill - -@example -@@author by Jane Smith and John Doe -@end example - -@noindent -or you can write the names one above each other by using two (or more) -@code{@@author} commands:@refill - -@example -@group -@@author Jane Smith -@@author John Doe -@end group -@end example - -@noindent -(Only the bottom name is underlined with a black rule.)@refill - -@need 950 -A template for this method looks like this:@refill - -@example -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@@page -@dots{} -@@end titlepage -@end group -@end example - -@ifinfo -@noindent -Contrast this form with the form of a title page written using the -@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill - -@example -@@titlepage -@@sp 10 -@@center @@titlefont@{Name of Manual When Printed@} -@@sp 2 -@@center Subtitle, If Any -@@sp 1 -@@center Second subtitle -@@sp 2 -@@center Author -@@page -@dots{} -@@end titlepage -@end example -@end ifinfo - -@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection Copyright Page and Permissions -@cindex Copyright page -@cindex Printed permissions -@cindex Permissions, printed - -By international treaty, the copyright notice for a book should be -either on the title page or on the back of the title page. The -copyright notice should include the year followed by the name of the -organization or person who owns the copyright.@refill - -When the copyright notice is on the back of the title page, that page -is customarily not numbered. Therefore, in Texinfo, the information -on the copyright page should be within @code{@@titlepage} and -@code{@@end titlepage} commands.@refill - -@findex vskip -@findex filll -@cindex Vertical whitespace (@samp{vskip}) -Use the @code{@@page} command to cause a page break. To push the -copyright notice and the other text on the copyright page towards the -bottom of the page, you can write a somewhat mysterious line after the -@code{@@page} command that reads like this:@refill - -@example -@@vskip 0pt plus 1filll -@end example - -@noindent -This is a @TeX{} command that is not supported by the Info formatting -commands. The @code{@@vskip} command inserts whitespace. The -@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace, -and as much optional whitespace as needed to push the -following text to the bottom of the page. Note the use of three -@samp{l}s in the word @samp{filll}; this is the correct usage in -@TeX{}.@refill - -@findex copyright -In a printed manual, the @code{@@copyright@{@}} command generates a -@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The -copyright notice itself has the following legally defined sequence:@refill - -@example -Copyright @copyright{} @var{year} @var{copyright-owner} -@end example - -It is customary to put information on how to get a manual after the -copyright notice, followed by the copying permissions for the -manual.@refill - -Note that permissions must be given here as well as in the summary -segment within @code{@@ifinfo} and @code{@@end ifinfo} that -immediately follows the header since this text appears only in the -printed manual and the @samp{ifinfo} text appears only in the Info -file.@refill - -@xref{Sample Permissions}, for the standard text.@refill - -@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection Heading Generation -@findex end titlepage -@cindex Headings, page, begin to appear -@cindex Titlepage end starts headings -@cindex End titlepage starts headings - -An @code{@@end titlepage} command on a line by itself not only marks -the end of the title and copyright pages, but also causes @TeX{} to start -generating page headings and page numbers. - -To repeat what is said elsewhere, Texinfo has two standard page heading -formats, one for documents which are printed on one side of each sheet of paper -(single-sided printing), and the other for documents which are printed on both -sides of each sheet (double-sided printing). -(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.) -You can specify these formats in different ways:@refill - -@itemize @bullet -@item -The conventional way is to write an @code{@@setchapternewpage} command -before the title page commands, and then have the @code{@@end -titlepage} command start generating page headings in the manner desired. -(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill - -@item -Alternatively, you can use the @code{@@headings} command to prevent page -headings from being generated or to start them for either single or -double-sided printing. (Write an @code{@@headings} command immediately -after the @code{@@end titlepage} command. @xref{headings on off, , The -@code{@@headings} Command}, for more information.)@refill - -@item -Or, you may specify your own page heading and footing format. -@xref{Headings, , Page Headings}, for detailed -information about page headings and footings.@refill -@end itemize - -Most documents are formatted with the standard single-sided or -double-sided format, using @code{@@setchapternewpage odd} for -double-sided printing and no @code{@@setchapternewpage} command for -single-sided printing.@refill - -@node headings on off, , end titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection The @code{@@headings} Command -@findex headings - -The @code{@@headings} command is rarely used. It specifies what kind of -page headings and footings to print on each page. Usually, this is -controlled by the @code{@@setchapternewpage} command. You need the -@code{@@headings} command only if the @code{@@setchapternewpage} command -does not do what you want, or if you want to turn off pre-defined page -headings prior to defining your own. Write an @code{@@headings} command -immediately after the @code{@@end titlepage} command.@refill - -You can use @code{@@headings} as follows:@refill - -@table @code -@item @@headings off -Turn off printing of page headings.@refill - -@item @@headings single -Turn on page headings appropriate for single-sided printing. -@refill - -@item @@headings double -Turn on page headings appropriate for double-sided printing. The two -commands, @code{@@headings on} and @code{@@headings double}, are -synonymous.@refill - -@item @@headings singleafter -@itemx @@headings doubleafter -Turn on @code{single} or @code{double} headings, respectively, after the -current page is output. - -@item @@headings on -Turn on page headings: @code{single} if @samp{@@setchapternewpage -on}, @code{double} otherwise. -@end table - -For example, suppose you write @code{@@setchapternewpage off} before the -@code{@@titlepage} command to tell @TeX{} to start a new chapter on the -same page as the end of the last chapter. This command also causes -@TeX{} to typeset page headers for single-sided printing. To cause -@TeX{} to typeset for double sided printing, write @code{@@headings -double} after the @code{@@end titlepage} command. - -You can stop @TeX{} from generating any page headings at all by -writing @code{@@headings off} on a line of its own immediately after the -line containing the @code{@@end titlepage} command, like this:@refill - -@example -@@end titlepage -@@headings off -@end example - -@noindent -The @code{@@headings off} command overrides the @code{@@end titlepage} -command, which would otherwise cause @TeX{} to print page -headings.@refill - -You can also specify your own style of page heading and footing. -@xref{Headings, , Page Headings}, for more information.@refill - -@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File -@comment node-name, next, previous, up -@section The `Top' Node and Master Menu -@cindex @samp{@r{Top}} node -@cindex Master menu -@cindex Node, `Top' - -The `Top' node is the node from which you enter an Info file.@refill - -A `Top' node should contain a brief description of the Info file and an -extensive, master menu for the whole Info file. -This helps the reader understand what the Info file is -about. Also, you should write the version number of the program to -which the Info file applies; or, at least, the edition number.@refill - -The contents of the `Top' node should appear only in the Info file; none -of it should appear in printed output, so enclose it between -@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not -print either an @code{@@node} line or a menu; they appear only in Info; -strictly speaking, you are not required to enclose these parts between -@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so. -@xref{Conditionals, , Conditionally Visible Text}.)@refill - -@menu -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. -@end menu - -@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node -@ifinfo -@subheading `Top' Node Title -@end ifinfo - -Sometimes, you will want to place an @code{@@top} sectioning command -line containing the title of the document immediately after the -@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top} -Sectioning Command}, for more information).@refill - -For example, the beginning of the Top node of this manual contains an -@code{@@top} sectioning command, a short description, and edition and -version information. It looks like this:@refill - -@example -@group -@dots{} -@@end titlepage - -@@ifinfo -@@node Top, Copying, , (dir) -@@top Texinfo - -Texinfo is a documentation system@dots{} -@end group - -@group -This is edition@dots{} -@dots{} -@@end ifinfo -@end group - -@group -@@menu -* Copying:: Texinfo is freely - redistributable. -* Overview:: What is Texinfo? -@dots{} -@end group -@@end menu -@end example - -In a `Top' node, the `Previous', and `Up' nodes usually refer to the top -level directory of the whole Info system, which is called @samp{(dir)}. -The `Next' node refers to the first node that follows the main or master -menu, which is usually the copying permissions, introduction, or first -chapter.@refill - -@node Master Menu Parts, , Title of Top Node, The Top Node -@subsection Parts of a Master Menu -@cindex Master menu parts -@cindex Parts of a master menu - -A @dfn{master menu} is a detailed main menu listing all the nodes in a -file. - -A master menu is enclosed in @code{@@menu} and @code{@@end menu} -commands and does not appear in the printed document.@refill - -Generally, a master menu is divided into parts.@refill - -@itemize @bullet -@item -The first part contains the major nodes in the Texinfo file: the nodes -for the chapters, chapter-like sections, and the appendices.@refill - -@item -The second part contains nodes for the indices.@refill - -@item -The third and subsequent parts contain a listing of the other, lower -level nodes, often ordered by chapter. This way, rather than go -through an intermediary menu, an inquirer can go directly to a -particular node when searching for specific information. These menu -items are not required; add them if you think they are a -convenience. If you do use them, put @code{@@detailmenu} before the -first one, and @code{@@end detailmenu} after the last; otherwise, -@code{makeinfo} will get confused. -@end itemize - -Each section in the menu can be introduced by a descriptive line. So -long as the line does not begin with an asterisk, it will not be -treated as a menu entry. (@xref{Writing a Menu}, for more -information.)@refill - -For example, the master menu for this manual looks like the following -(but has many more entries):@refill - -@example -@group -@@menu -* Copying:: Texinfo is freely - redistributable. -* Overview:: What is Texinfo? -* Texinfo Mode:: Special features in GNU Emacs. -@dots{} -@dots{} -@end group -@group -* Command and Variable Index:: - An entry for each @@-command. -* Concept Index:: An entry for each concept. -@end group - -@group -@@detailmenu - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Info Files:: What is an Info file? -* Printed Manuals:: Characteristics of - a printed manual. -@dots{} -@dots{} -@end group - -@group -Using Texinfo Mode - -* Info on a Region:: Formatting part of a file - for Info. -@dots{} -@dots{} -@@end detailmenu -@@end menu -@end group -@end example - -@node Software Copying Permissions, , The Top Node, Beginning a File -@comment node-name, next, previous, up -@section Software Copying Permissions -@cindex Software copying permissions -@cindex Copying software -@cindex Distribution -@cindex License agreement - -If the Texinfo file has a section containing the ``General Public -License'' and the distribution information and a warranty disclaimer -for the software that is documented, this section usually follows the -`Top' node. The General Public License is very important to Project -GNU software. It ensures that you and others will continue to have a -right to use and share the software.@refill - -The copying and distribution information and the disclaimer are -followed by an introduction or else by the first chapter of the -manual.@refill - -@cindex Introduction, as part of file -Although an introduction is not a required part of a Texinfo file, it -is very helpful. Ideally, it should state clearly and concisely what -the file is about and who would be interested in reading it. In -general, an introduction would follow the licensing and distribution -information, although sometimes people put it earlier in the document. -Usually, an introduction is put in an @code{@@unnumbered} section. -(@xref{unnumbered & appendix, , The @code{@@unnumbered} and -@code{@@appendix} Commands}.)@refill - -@node Ending a File, Structuring, Beginning a File, Top -@comment node-name, next, previous, up -@chapter Ending a Texinfo File -@cindex Ending a Texinfo file -@cindex Texinfo file ending -@cindex File ending -@findex bye - -The end of a Texinfo file should include the commands that create -indices and generate detailed and summary tables of contents. -And it must include the @code{@@bye} command that marks the last line -processed by @TeX{}.@refill - -@need 700 -For example: - -@example -@@node Concept Index, , Variables Index, Top -@@c node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp - -@@contents -@@bye -@end example - -@menu -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. -@end menu - -@node Printing Indices & Menus, Contents, Ending a File, Ending a File -@comment node-name, next, previous, up -@section Index Menus and Printing an Index -@findex printindex -@cindex Printing an index -@cindex Indices, printing and menus -@cindex Generating menus with indices -@cindex Menus generated with indices - -To print an index means to include it as part of a manual or Info -file. This does not happen automatically just because you use -@code{@@cindex} or other index-entry generating commands in the -Texinfo file; those just cause the raw data for the index to be -accumulated. To generate an index, you must include the -@code{@@printindex} command at the place in the document where you -want the index to appear. Also, as part of the process of creating a -printed manual, you must run a program called @code{texindex} -(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted -index file. The sorted index file is what is actually used to -print the index.@refill - -Texinfo offers six different types of predefined index: the concept -index, the function index, the variables index, the keystroke index, the -program index, and the data type index (@pxref{Predefined Indices}). Each -index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr}, -@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them -into separate sections (@pxref{Combining Indices}); or you may define -your own indices (@pxref{New Indices, , Defining New Indices}).@refill - -The @code{@@printindex} command takes a two-letter index name, reads -the corresponding sorted index file and formats it appropriately into -an index.@refill - -@ignore -The two-letter index names are: - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table -@end ignore -The @code{@@printindex} command does not generate a chapter heading -for the index. Consequently, you should precede the -@code{@@printindex} command with a suitable section or chapter command -(usually @code{@@unnumbered}) to supply the chapter heading and put -the index into the table of contents. Precede the @code{@@unnumbered} -command with an @code{@@node} line.@refill - -@need 1200 -For example: - -@smallexample -@group -@@node Variable Index, Concept Index, Function Index, Top -@@comment node-name, next, previous, up -@@unnumbered Variable Index - -@@printindex vr -@end group - -@group -@@node Concept Index, , Variable Index, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp -@end group - -@group -@@summarycontents -@@contents -@@bye -@end group -@end smallexample - -@noindent -(Readers often prefer that the concept index come last in a book, -since that makes it easiest to find.)@refill - -@ignore -@c TeX can do sorting, just not conveniently enough to handle sorting -@c Texinfo indexes. --karl, 5may97. -In @TeX{}, the @code{@@printindex} command needs a sorted index file -to work from. @TeX{} does not know how to do sorting; this is a -deficiency. @TeX{} writes output files of raw index data; use the -@code{texindex} program to convert these files to sorted index files. -(@xref{Format/Print Hardcopy}, for more information.)@refill -@end ignore - - -@node Contents, File End, Printing Indices & Menus, Ending a File -@comment node-name, next, previous, up -@section Generating a Table of Contents -@cindex Table of contents -@cindex Contents, Table of -@findex contents -@findex summarycontents -@findex shortcontents - -The @code{@@chapter}, @code{@@section}, and other structuring commands -supply the information to make up a table of contents, but they do not -cause an actual table to appear in the manual. To do this, you must -use the @code{@@contents} and @code{@@summarycontents} -commands:@refill - -@table @code -@item @@contents -Generate a table of contents in a printed manual, including all -chapters, sections, subsections, etc., as well as appendices and -unnumbered chapters. (Headings generated by the @code{@@heading} -series of commands do not appear in the table of contents.) The -@code{@@contents} command should be written on a line by -itself.@refill - -@item @@shortcontents -@itemx @@summarycontents -(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the -two commands are exactly the same.)@refill - -Generate a short or summary table of contents that lists only the -chapters (and appendices and unnumbered chapters). Omit sections, subsections -and subsubsections. Only a long manual needs a short table -of contents in addition to the full table of contents.@refill - -Write the @code{@@shortcontents} command on a line by itself right -@emph{before} the @code{@@contents} command.@refill -@end table - -The table of contents commands automatically generate a chapter-like -heading at the top of the first table of contents page. Write the table -of contents commands at the very end of a Texinfo file, just before the -@code{@@bye} command, following any index sections---anything in the -Texinfo file after the table of contents commands will be omitted from -the table of contents.@refill - -When you print a manual with a table of contents, the table of -contents are printed last and numbered with roman numerals. You need -to place those pages in their proper place, after the title page, -yourself. (This is the only collating you need to do for a printed -manual. The table of contents is printed last because it is generated -after the rest of the manual is typeset.)@refill - -@need 700 -Here is an example of where to write table of contents commands:@refill - -@example -@group -@var{indices}@dots{} -@@shortcontents -@@contents -@@bye -@end group -@end example - -Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the @code{@@contents} and -@code{@@shortcontents} commands.@refill - -@node File End, , Contents, Ending a File -@comment node-name, next, previous, up -@section @code{@@bye} File Ending -@findex bye - -An @code{@@bye} command terminates @TeX{} or Info formatting. None of -the formatting commands see any of the file following @code{@@bye}. -The @code{@@bye} command should be on a line by itself.@refill - -If you wish, you may follow the @code{@@bye} line with notes. These notes -will not be formatted and will not appear in either Info or a printed -manual; it is as if text after @code{@@bye} were within @code{@@ignore} -@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line -with a local variables list. @xref{Compile-Command, , Using Local -Variables and the Compile Command}, for more information.@refill - -@node Structuring, Nodes, Ending a File, Top -@comment node-name, next, previous, up -@chapter Chapter Structuring -@cindex Chapter structuring -@cindex Structuring of chapters - -The @dfn{chapter structuring} commands divide a document into a hierarchy of -chapters, sections, subsections, and subsubsections. These commands -generate large headings; they also provide information for the table -of contents of a printed manual (@pxref{Contents, , Generating a Table -of Contents}).@refill - -The chapter structuring commands do not create an Info node structure, -so normally you should put an @code{@@node} command immediately before -each chapter structuring command (@pxref{Nodes}). The only time you -are likely to use the chapter structuring commands without using the -node structuring commands is if you are writing a document that -contains no cross references and will never be transformed into Info -format.@refill - -It is unlikely that you will ever write a Texinfo file that is -intended only as an Info file and not as a printable document. If you -do, you might still use chapter structuring commands to create a -heading at the top of each node---but you don't need to.@refill - -@menu -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. -@end menu - -@node Tree Structuring, Structuring Command Types, Structuring, Structuring -@comment node-name, next, previous, up -@section Tree Structure of Sections -@cindex Tree structuring - -A Texinfo file is usually structured like a book with chapters, -sections, subsections, and the like. This structure can be visualized -as a tree (or rather as an upside-down tree) with the root at the top -and the levels corresponding to chapters, sections, subsection, and -subsubsections.@refill - -Here is a diagram that shows a Texinfo file with three chapters, -each of which has two sections.@refill - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | - Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - -@end group -@end example - -In a Texinfo file that has this structure, the beginning of Chapter 2 -looks like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@chapter Chapter 2 -@end group -@end example - -The chapter structuring commands are described in the sections that -follow; the @code{@@node} and @code{@@menu} commands are described in -following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill - -@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring -@comment node-name, next, previous, up -@section Types of Structuring Commands - -The chapter structuring commands fall into four groups or series, each -of which contains structuring commands corresponding to the -hierarchical levels of chapters, sections, subsections, and -subsubsections.@refill - -The four groups are the @code{@@chapter} series, the -@code{@@unnumbered} series, the @code{@@appendix} series, and the -@code{@@heading} series.@refill - -Each command produces titles that have a different appearance on the -printed page or Info file; only some of the commands produce -titles that are listed in the table of contents of a printed book or -manual.@refill - -@itemize @bullet -@item -The @code{@@chapter} and @code{@@appendix} series of commands produce -numbered or lettered entries both in the body of a printed work and in -its table of contents.@refill - -@item -The @code{@@unnumbered} series of commands produce unnumbered entries -both in the body of a printed work and in its table of contents. The -@code{@@top} command, which has a special use, is a member of this -series (@pxref{makeinfo top, , @code{@@top}}).@refill - -@item -The @code{@@heading} series of commands produce unnumbered headings -that do not appear in a table of contents. The heading commands never -start a new page.@refill - -@item -The @code{@@majorheading} command produces results similar to using -the @code{@@chapheading} command but generates a larger vertical -whitespace before the heading.@refill - -@item -When an @code{@@setchapternewpage} command says to do so, the -@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands -start new pages in the printed manual; the @code{@@heading} commands -do not.@refill -@end itemize - -@need 1000 -Here are the four groups of chapter structuring commands:@refill - -@c Slightly different formatting for regular sized books and smallbooks. -@ifset smallbook -@sp 1 -@tex -{\let\rm=\indrm \let\tt=\indtt -\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil\cr - -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifset -@ifclear smallbook -@sp 1 -@tex -\vbox{ -\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil& \hskip.5em #\hfil\cr - -& & & \cr -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifclear -@ifinfo -@example -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end example -@end ifinfo - -@c Cannot line up columns properly inside of an example because of roman -@c proportional fonts. -@ignore -@ifset smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ifset -@ifclear smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ignore - -@node makeinfo top, chapter, Structuring Command Types, Structuring -@comment node-name, next, previous, up -@section @code{@@top} - -The @code{@@top} command is a special sectioning command that you use -only after an @samp{@@node Top} line at the beginning of a Texinfo file. -The @code{@@top} command tells the @code{makeinfo} formatter -which node is the `Top' -node. It has the same typesetting effect as @code{@@unnumbered} -(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). -For detailed information, see -@ref{makeinfo top command, , The @code{@@top} Command}.@refill - -@node chapter, unnumbered & appendix, makeinfo top, Structuring -@comment node-name, next, previous, up -@section @code{@@chapter} -@findex chapter - -@code{@@chapter} identifies a chapter in the document. Write the -command at the beginning of a line and follow it on the same line by -the title of the chapter.@refill - -For example, this chapter in this manual is entitled ``Chapter -Structuring''; the @code{@@chapter} line looks like this:@refill - -@example -@@chapter Chapter Structuring -@end example - -In @TeX{}, the @code{@@chapter} command creates a chapter in the -document, specifying the chapter title. The chapter is numbered -automatically.@refill - -In Info, the @code{@@chapter} command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath. Thus, -in Info, the above example produces the following output:@refill - -@example -Chapter Structuring -******************* -@end example - -@findex centerchap -Texinfo also provides a command @code{@@centerchap}, which is analogous -to @code{@@unnumbered}, but centers its argument in the printed output. -This kind of stylistic choice is not usually offered by Texinfo. -@c but the Hacker's Dictionary wanted it ... - - -@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumbered}, @code{@@appendix} -@findex unnumbered -@findex appendix - -Use the @code{@@unnumbered} command to create a chapter that appears -in a printed manual without chapter numbers of any kind. Use the -@code{@@appendix} command to create an appendix in a printed manual -that is labelled by letter instead of by number.@refill - -For Info file output, the @code{@@unnumbered} and @code{@@appendix} -commands are equivalent to @code{@@chapter}: the title is printed on a -line by itself with a line of asterisks underneath. (@xref{chapter, , -@code{@@chapter}}.)@refill - -To create an appendix or an unnumbered chapter, write an -@code{@@appendix} or @code{@@unnumbered} command at the beginning of a -line and follow it on the same line by the title, as you would if you -were creating a chapter.@refill - - -@node majorheading & chapheading, section, unnumbered & appendix, Structuring -@section @code{@@majorheading}, @code{@@chapheading} -@findex majorheading -@findex chapheading - -The @code{@@majorheading} and @code{@@chapheading} commands put -chapter-like headings in the body of a document.@refill - -However, neither command causes @TeX{} to produce a numbered heading -or an entry in the table of contents; and neither command causes -@TeX{} to start a new page in a printed manual.@refill - -In @TeX{}, an @code{@@majorheading} command generates a larger vertical -whitespace before the heading than an @code{@@chapheading} command but -is otherwise the same.@refill - -In Info, -the @code{@@majorheading} and -@code{@@chapheading} commands are equivalent to -@code{@@chapter}: the title is printed on a line by itself with a line -of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill - -@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring -@comment node-name, next, previous, up -@section @code{@@section} -@findex section - -In a printed manual, an @code{@@section} command identifies a -numbered section within a chapter. The section title appears in the -table of contents. In Info, an @code{@@section} command provides a -title for a segment of text, underlined with @samp{=}.@refill - -This section is headed with an @code{@@section} command and looks like -this in the Texinfo file:@refill - -@example -@@section @@code@{@@@@section@} -@end example - -To create a section, write the @code{@@section} command at the -beginning of a line and follow it on the same line by the section -title.@refill - -Thus, - -@example -@@section This is a section -@end example - -@noindent -produces - -@example -@group -This is a section -================= -@end group -@end example - -@noindent -in Info. - -@node unnumberedsec appendixsec heading, subsection, section, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} -@findex unnumberedsec -@findex appendixsec -@findex heading - -The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} -commands are, respectively, the unnumbered, appendix-like, and -heading-like equivalents of the @code{@@section} command. -(@xref{section, , @code{@@section}}.)@refill - -@table @code -@item @@unnumberedsec -The @code{@@unnumberedsec} command may be used within an -unnumbered chapter or within a regular chapter or appendix to -provide an unnumbered section.@refill - -@item @@appendixsec -@itemx @@appendixsection -@code{@@appendixsection} is a longer spelling of the -@code{@@appendixsec} command; the two are synonymous.@refill -@findex appendixsection - -Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} -command is used only within appendices.@refill - -@item @@heading -You may use the @code{@@heading} command anywhere you wish for a -section-style heading that will not appear in the table of contents.@refill -@end table - -@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring -@comment node-name, next, previous, up -@section The @code{@@subsection} Command -@findex subsection - -Subsections are to sections as sections are to chapters. -(@xref{section, , @code{@@section}}.) In Info, subsection titles are -underlined with @samp{-}. For example,@refill - -@example -@@subsection This is a subsection -@end example - -@noindent -produces - -@example -@group -This is a subsection --------------------- -@end group -@end example - -In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep.@refill - -@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring -@comment node-name, next, previous, up -@section The @code{@@subsection}-like Commands -@cindex Subsection-like commands -@findex unnumberedsubsec -@findex appendixsubsec -@findex subheading - -The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and -@code{@@subheading} commands are, respectively, the unnumbered, -appendix-like, and heading-like equivalents of the @code{@@subsection} -command. (@xref{subsection, , @code{@@subsection}}.)@refill - -In Info, the @code{@@subsection}-like commands generate a title -underlined with hyphens. In a printed manual, an @code{@@subheading} -command produces a heading like that of a subsection except that it is -not numbered and does not appear in the table of contents. Similarly, -an @code{@@unnumberedsubsec} command produces an unnumbered heading like -that of a subsection and an @code{@@appendixsubsec} command produces a -subsection-like heading labelled with a letter and numbers; both of -these commands produce headings that appear in the table of -contents.@refill - -@node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring -@comment node-name, next, previous, up -@section The `subsub' Commands -@cindex Subsub commands -@findex subsubsection -@findex unnumberedsubsubsec -@findex appendixsubsubsec -@findex subsubheading - -The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are:@refill - -@table @code -@item @@subsubsection -Subsubsections are to subsections as subsections are to sections. -(@xref{subsection, , @code{@@subsection}}.) In a printed manual, -subsubsection titles appear in the table of contents and are numbered -four levels deep.@refill - -@item @@unnumberedsubsubsec -Unnumbered subsubsection titles appear in the table of contents of a -printed manual, but lack numbers. Otherwise, unnumbered -subsubsections are the same as subsubsections. In Info, unnumbered -subsubsections look exactly like ordinary subsubsections.@refill - -@item @@appendixsubsubsec -Conventionally, appendix commands are used only for appendices and are -lettered and numbered appropriately in a printed manual. They also -appear in the table of contents. In Info, appendix subsubsections look -exactly like ordinary subsubsections.@refill - -@item @@subsubheading -The @code{@@subsubheading} command may be used anywhere that you need -a small heading that will not appear in the table of contents. In -Info, subsubheadings look exactly like ordinary subsubsection -headings.@refill -@end table - -In Info, `subsub' titles are underlined with periods. -For example,@refill - -@example -@@subsubsection This is a subsubsection -@end example - -@noindent -produces - -@example -@group -This is a subsubsection -....................... -@end group -@end example - -@node Raise/lower sections, , subsubsection, Structuring -@comment node-name, next, previous, up -@section @code{@@raisesections} and @code{@@lowersections} -@findex raisesections -@findex lowersections -@cindex Raising and lowering sections -@cindex Sections, raising and lowering - -The @code{@@raisesections} and @code{@@lowersections} commands raise and -lower the hierarchical level of chapters, sections, subsections and the -like. The @code{@@raisesections} command changes sections to chapters, -subsections to sections, and so on. The @code{@@lowersections} command -changes chapters to sections, sections to subsections, and so on. - -@cindex Include files, and section levels -An @code{@@lowersections} command is useful if you wish to include text -that is written as an outer or standalone Texinfo file in another -Texinfo file as an inner, included file. If you write the command at -the beginning of the file, all your @code{@@chapter} commands are -formatted as if they were @code{@@section} commands, all your -@code{@@section} command are formatted as if they were -@code{@@subsection} commands, and so on. - -@need 1000 -@code{@@raisesections} raises a command one level in the chapter -structuring hierarchy:@refill - -@example -@group - @r{Change} @r{To} - -@@subsection @@section, -@@section @@chapter, -@@heading @@chapheading, - @r{etc.} -@end group -@end example - -@need 1000 -@code{@@lowersections} lowers a command one level in the chapter -structuring hierarchy:@refill - -@example -@group - @r{Change} @r{To} - -@@chapter @@section, -@@subsection @@subsubsection, -@@heading @@subheading, - @r{etc.} -@end group -@end example - -An @code{@@raisesections} or @code{@@lowersections} command changes only -those structuring commands that follow the command in the Texinfo file. -Write an @code{@@raisesections} or @code{@@lowersections} command on a -line of its own. - -An @code{@@lowersections} command cancels an @code{@@raisesections} -command, and vice versa. Typically, the commands are used like this: - -@example -@@lowersections -@@include somefile.texi -@@raisesections -@end example - -Without the @code{@@raisesections}, all the subsequent sections in your -document will be lowered. - -Repeated use of the commands continue to raise or lower the hierarchical -level a step at a time. - -An attempt to raise above `chapters' reproduces chapter commands; an -attempt to lower below `subsubsections' reproduces subsubsection -commands. - -@node Nodes, Menus, Structuring, Top -@comment node-name, next, previous, up -@chapter Nodes - -@dfn{Nodes} are the primary segments of a Texinfo file. They do not -themselves impose a hierarchic or any other kind of structure on a file. -Nodes contain @dfn{node pointers} that name other nodes, and can contain -@dfn{menus} which are lists of nodes. In Info, the movement commands -can carry you to a pointed-to node or to a node listed in a menu. Node -pointers and menus provide structure for Info files just as chapters, -sections, subsections, and the like, provide structure for printed -books.@refill - -@menu -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. -@end menu - -@node Two Paths, Node Menu Illustration, Nodes, Nodes -@ifinfo -@heading Two Paths -@end ifinfo - -The node and menu commands and the chapter structuring commands are -independent of each other: - -@itemize @bullet -@item -In Info, node and menu commands provide structure. The chapter -structuring commands generate headings with different kinds of -underlining---asterisks for chapters, hyphens for sections, and so on; -they do nothing else.@refill - -@item -In @TeX{}, the chapter structuring commands generate chapter and section -numbers and tables of contents. The node and menu commands provide -information for cross references; they do nothing else.@refill -@end itemize - -You can use node pointers and menus to structure an Info file any way -you want; and you can write a Texinfo file so that its Info output has a -different structure than its printed output. However, most Texinfo -files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is not -convenient to do otherwise.@refill - -Generally, printed output is structured in a tree-like hierarchy in -which the chapters are the major limbs from which the sections branch -out. Similarly, node pointers and menus are organized to create a -matching structure in the Info output.@refill - -@node Node Menu Illustration, node, Two Paths, Nodes -@comment node-name, next, previous, up -@section Node and Menu Illustration - -Here is a copy of the diagram shown earlier that illustrates a Texinfo -file with three chapters, each of which contains two sections.@refill - -Note that the ``root'' is at the top of the diagram and the ``leaves'' -are at the bottom. This is how such a diagram is drawn conventionally; -it illustrates an upside-down tree. For this reason, the root node is -called the `Top' node, and `Up' node pointers carry you closer to the -root.@refill - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | - Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - -@end group -@end example - -Write the beginning of the node for Chapter 2 like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@comment node-name, next, previous, up -@end group -@end example - -@noindent -This @code{@@node} line says that the name of this node is ``Chapter 2'', the -name of the `Next' node is ``Chapter 3'', the name of the `Previous' -node is ``Chapter 1'', and the name of the `Up' node is ``Top''. - -@quotation -@strong{Please Note:} `Next' refers to the next node at the same -hierarchical level in the manual, not necessarily to the next node -within the Texinfo file. In the Texinfo file, the subsequent node may -be at a lower level---a section-level node may follow a chapter-level -node, and a subsection-level node may follow a section-level node. -`Next' and `Previous' refer to nodes at the @emph{same} hierarchical -level. (The `Top' node contains the exception to this rule. Since the -`Top' node is the only node at that level, `Next' refers to the first -following node, which is almost always a chapter or chapter-level -node.)@refill -@end quotation - -To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter -2. (@xref{Menus}.) You would write the menu just -before the beginning of Section 2.1, like this:@refill - -@example -@group - @@menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: - @@end menu -@end group -@end example - -Write the node for Sect. 2.1 like this:@refill - -@example -@group - @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 - @@comment node-name, next, previous, up -@end group -@end example - -In Info format, the `Next' and `Previous' pointers of a node usually -lead to other nodes at the same level---from chapter to chapter or from -section to section (sometimes, as shown, the `Previous' pointer points -up); an `Up' pointer usually leads to a node at the level above (closer -to the `Top' node); and a `Menu' leads to nodes at a level below (closer -to `leaves'). (A cross reference can point to a node at any level; -see @ref{Cross References}.)@refill - -Usually, an @code{@@node} command and a chapter structuring command are -used in sequence, along with indexing commands. (You may follow the -@code{@@node} line with a comment line that reminds you which pointer is -which.)@refill - -Here is the beginning of the chapter in this manual called ``Ending a -Texinfo File''. This shows an @code{@@node} line followed by a comment -line, an @code{@@chapter} line, and then by indexing lines.@refill - -@example -@group -@@node Ending a File, Structuring, Beginning a File, Top -@@comment node-name, next, previous, up -@@chapter Ending a Texinfo File -@@cindex Ending a Texinfo file -@@cindex Texinfo file ending -@@cindex File ending -@end group -@end example - -@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes -@comment node-name, next, previous, up -@section The @code{@@node} Command - -@cindex Node, defined -A @dfn{node} is a segment of text that begins at an @code{@@node} -command and continues until the next @code{@@node} command. The -definition of node is different from that for chapter or section. A -chapter may contain sections and a section may contain subsections; -but a node cannot contain subnodes; the text of a node continues only -until the next @code{@@node} command in the file. A node usually -contains only one chapter structuring command, the one that follows -the @code{@@node} line. On the other hand, in printed output nodes -are used only for cross references, so a chapter or section may -contain any number of nodes. Indeed, a chapter usually contains -several nodes, one for each section, subsection, and -subsubsection.@refill - -To create a node, write an @code{@@node} command at the beginning of a -line, and follow it with four arguments, separated by commas, on the -rest of the same line. These arguments are the name of the node, and -the names of the `Next', `Previous', and `Up' pointers, in that order. -You may insert spaces before each pointer if you wish; the spaces are -ignored. You must write the name of the node, and the names of the -`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, -the formatters fail. (@inforef{Top, info, info}, for more information -about nodes in Info.)@refill - -Usually, you write one of the chapter-structuring command lines -immediately after an @code{@@node} line---for example, an -@code{@@section} or @code{@@subsection} line. (@xref{Structuring -Command Types, , Types of Structuring Commands}.)@refill - -@quotation -@strong{Please note:} The GNU Emacs Texinfo mode updating commands work -only with Texinfo files in which @code{@@node} lines are followed by chapter -structuring lines. @xref{Updating Requirements}.@refill -@end quotation - -@TeX{} uses @code{@@node} lines to identify the names to use for cross -references. For this reason, you must write @code{@@node} lines in a -Texinfo file that you intend to format for printing, even if you do not -intend to format it for Info. (Cross references, such as the one at the -end of this sentence, are made with @code{@@xref} and its related -commands; see @ref{Cross References}.)@refill - -@menu -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. -* Top Node Summary:: Write a brief description for readers. -@end menu - -@node Node Names, Writing a Node, node, node -@ifinfo -@subheading Choosing Node and Pointer Names -@end ifinfo - -The name of a node identifies the node. The pointers enable -you to reach other nodes and consist of the names of those nodes.@refill - -Normally, a node's `Up' pointer contains the name of the node whose menu -mentions that node. The node's `Next' pointer contains the name of the -node that follows that node in that menu and its `Previous' pointer -contains the name of the node that precedes it in that menu. When a -node's `Previous' node is the same as its `Up' node, both node pointers -name the same node.@refill - -Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the @file{dir} file, which -contains the main menu for all of Info.@refill - -The `Top' node itself contains the main or master menu for the manual. -Also, it is helpful to include a brief description of the manual in the -`Top' node. @xref{First Node}, for information on how to write the -first node of a Texinfo file.@refill - -@node Writing a Node, Node Line Tips, Node Names, node -@comment node-name, next, previous, up -@subsection How to Write an @code{@@node} Line -@cindex Writing an @code{@@node} line -@cindex @code{@@node} line writing -@cindex Node line writing - -The easiest way to write an @code{@@node} line is to write @code{@@node} -at the beginning of a line and then the name of the node, like -this:@refill - -@example -@@node @var{node-name} -@end example - -If you are using GNU Emacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or you -can leave the pointers out of the Texinfo file and let @code{makeinfo} -insert node pointers into the Info file it creates. (@xref{Texinfo -Mode}, and @ref{makeinfo Pointer Creation}.)@refill - -Alternatively, you can insert the `Next', `Previous', and `Up' -pointers yourself. If you do this, you may find it helpful to use the -Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts -@samp{@@node} and a comment line listing the names of the pointers in -their proper order. The comment line helps you keep track of which -arguments are for which pointers. This comment line is especially useful -if you are not familiar with Texinfo.@refill - -The template for a node line with `Next', `Previous', and `Up' pointers -looks like this:@refill - -@example -@@node @var{node-name}, @var{next}, @var{previous}, @var{up} -@end example - -If you wish, you can ignore @code{@@node} lines altogether in your first -draft and then use the @code{texinfo-insert-node-lines} command to -create @code{@@node} lines for you. However, we do not -recommend this practice. It is better to name the node itself -at the same time that you -write a segment so you can easily make cross references. A large number -of cross references are an especially important feature of a good Info -file.@refill - -After you have inserted an @code{@@node} line, you should immediately -write an @@-command for the chapter or section and insert its name. -Next (and this is important!), put in several index entries. Usually, -you will find at least two and often as many as four or five ways of -referring to the node in the index. Use them all. This will make it -much easier for people to find the node.@refill - -@node Node Line Tips, Node Line Requirements, Writing a Node, node -@comment node-name, next, previous, up -@subsection @code{@@node} Line Tips - -Here are three suggestions: - -@itemize @bullet -@item -Try to pick node names that are informative but short.@refill - -In the Info file, the file name, node name, and pointer names are all -inserted on one line, which may run into the right edge of the window. -(This does not cause a problem with Info, but is ugly.)@refill - -@item -Try to pick node names that differ from each other near the beginnings -of their names. This way, it is easy to use automatic name completion in -Info.@refill - -@item -By convention, node names are capitalized just as they would be for -section or chapter titles---initial and significant words are -capitalized; others are not.@refill -@end itemize - -@node Node Line Requirements, First Node, Node Line Tips, node -@comment node-name, next, previous, up -@subsection @code{@@node} Line Requirements - -@cindex Node line requirements -Here are several requirements for @code{@@node} lines: - -@itemize @bullet -@cindex Unique nodename requirement -@cindex Nodename must be unique -@item -All the node names for a single Info file must be unique.@refill - -Duplicates confuse the Info movement commands. This means, for -example, that if you end every chapter with a summary, you must name -each summary node differently. You cannot just call each one -``Summary''. You may, however, duplicate the titles of chapters, sections, -and the like. Thus you can end each chapter in a book with a section -called ``Summary'', so long as the node names for those sections are all -different.@refill - -@item -A pointer name must be the name of a node.@refill - -The node to which a pointer points may come before or after the -node containing the pointer.@refill - -@cindex @@-command in nodename -@cindex Nodename, cannot contain -@item -You cannot use any of the Texinfo @@-commands in a node name; -@w{@@-commands} confuse Info.@refill - -@need 750 -Thus, the beginning of the section called @code{@@chapter} looks like -this:@refill - -@smallexample -@group -@@node chapter, unnumbered & appendix, makeinfo top, Structuring -@@comment node-name, next, previous, up -@@section @@code@{@@@@chapter@} -@@findex chapter -@end group -@end smallexample - -@cindex Comma in nodename -@cindex Apostrophe in nodename -@item -You cannot use commas or apostrophes within a node name; these -confuse @TeX{} or the Info formatters.@refill - -@need 700 -For example, the following is a section title: - -@smallexample -@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} -@end smallexample - -@noindent -The corresponding node name is: - -@smallexample -unnumberedsec appendixsec heading -@end smallexample - -@cindex Case in nodename -@item -Case is significant. -@end itemize - - -@node First Node, makeinfo top command, Node Line Requirements, node -@comment node-name, next, previous, up -@subsection The First Node -@cindex Top node is first -@cindex First node - -The first node of a Texinfo file is the @dfn{Top} node, except in an -included file (@pxref{Include Files}). The Top node contains the main -or master menu for the document, and a short summary of the document -(@pxref{Top Node Summary}). - -@cindex Up node of Top node -@cindex (dir) as Up node of Top node -The Top node (which must be named @samp{top} or @samp{Top}) should have -as its `Up' node the name of a node in another file, where there is a -menu that leads to this file. Specify the file name in parentheses. If -the file is to be installed directly in the Info directory file, use -@samp{(dir)} as the parent of the Top node; this is short for -@samp{(dir)top}, and specifies the Top node in the @file{dir} file, -which contains the main menu for the Info system as a whole. For -example, the @code{@@node Top} line of this manual looks like this: - -@example -@@node Top, Copying, , (dir) -@end example - -@noindent -(You can use the Texinfo updating commands or the @code{makeinfo} -utility to insert these pointers automatically.) - -@cindex Previous node of Top node -Do not define the `Previous' node of the Top node to be @samp{(dir)}, as -it causes confusing behavior for users: if you are in the Top node and -hits @key{DEL} to go backwards, you wind up in the middle of the -some other entry in the @file{dir} file, which has nothing to do with -what you were reading. - -@xref{Install an Info File}, for more information about installing -an Info file in the @file{info} directory. - - -@node makeinfo top command, Top Node Summary, First Node, node -@comment node-name, next, previous, up -@subsection The @code{@@top} Sectioning Command -@findex top @r{(@@-command)} - -A special sectioning command, @code{@@top}, has been created for use -with the @code{@@node Top} line. The @code{@@top} sectioning command tells -@code{makeinfo} that it marks the `Top' node in the file. It provides -the information that @code{makeinfo} needs to insert node -pointers automatically. Write the @code{@@top} command at the -beginning of the line immediately following the @code{@@node Top} -line. Write the title on the remaining part of the same line as the -@code{@@top} command.@refill - -In Info, the @code{@@top} sectioning command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath.@refill - -In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -sectioning command is merely a synonym for @code{@@unnumbered}. -Neither of these formatters require an @code{@@top} command, and do -nothing special with it. You can use @code{@@chapter} or -@code{@@unnumbered} after the @code{@@node Top} line when you use -these formatters. Also, you can use @code{@@chapter} or -@code{@@unnumbered} when you use the Texinfo updating commands to -create or update pointers and menus.@refill - - -@node Top Node Summary, , makeinfo top command, node -@subsection The `Top' Node Summary -@cindex @samp{@r{Top}} node summary - -You can help readers by writing a summary in the `Top' node, after the -@code{@@top} line, before the main or master menu. The summary should -briefly describe the document. In Info, this summary will appear just -before the master menu. In a printed manual, this summary will appear -on a page of its own.@refill - -If you do not want the summary to appear on a page of its own in a -printed manual, you can enclose the whole of the `Top' node, including -the @code{@@node Top} line and the @code{@@top} sectioning command line -or other sectioning command line between @code{@@ifinfo} and @code{@@end -ifinfo}. This prevents any of the text from appearing in the printed -output. (@pxref{Conditionals, , Conditionally Visible Text}). You can -repeat the brief description from the `Top' node within @code{@@iftex} -@dots{} @code{@@end iftex} at the beginning of the first chapter, for -those who read the printed manual. This saves paper and may look -neater.@refill - -You should write the version number of the program to which the manual -applies in the summary. This helps the reader keep track of which -manual is for which version of the program. If the manual changes more -frequently than the program or is independent of it, you should also -include an edition number for the manual. (The title page should also -contain this information: see @ref{titlepage, , -@code{@@titlepage}}.)@refill - -@node makeinfo Pointer Creation, , node, Nodes -@section Creating Pointers with @code{makeinfo} -@cindex Creating pointers with @code{makeinfo} -@cindex Pointer creation with @code{makeinfo} -@cindex Automatic pointer creation with @code{makeinfo} - -The @code{makeinfo} program has a feature for automatically creating -node pointers for a hierarchically organized file that lacks -them.@refill - -When you take advantage of this feature, you do not need to write the -`Next', `Previous', and `Up' pointers after the name of a node. -However, you must write a sectioning command, such as @code{@@chapter} -or @code{@@section}, on the line immediately following each truncated -@code{@@node} line. You cannot write a comment line after a node -line; the section line must follow it immediately.@refill - -In addition, you must follow the `Top' @code{@@node} line with a line beginning -with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo -top, , @code{@@top}}. - -Finally, you must write the name of each node (except for the `Top' -node) in a menu that is one or more hierarchical levels above the -node's hierarchical level.@refill - -This node pointer insertion feature in @code{makeinfo} is an -alternative to the menu and pointer creation and update commands in -Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially -helpful to people who do not use GNU Emacs for writing Texinfo -documents.@refill - -@node Menus, Cross References, Nodes, Top -@comment node-name, next, previous, up -@chapter Menus -@cindex Menus -@findex menu - -@dfn{Menus} contain pointers to subordinate -nodes.@footnote{Menus can carry you to any node, regardless -of the hierarchical structure; even to nodes in a different -Info file. However, the GNU Emacs Texinfo mode updating -commands work only to create menus of subordinate nodes. -Conventionally, cross references are used to refer to other -nodes.} In Info, you use menus to go to such nodes. Menus -have no effect in printed manuals and do not appear in -them.@refill - -By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it.@refill - -@ifinfo -A node that has a menu should @emph{not} contain much text. If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines.@refill -@end ifinfo -@iftex -@emph{A node that has a menu should not contain much text.} If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines. Otherwise, a reader with a terminal -that displays only a few lines may miss the menu and its associated -text. As a practical matter, you should locate a menu within 20 lines -of the beginning of the node.@refill -@end iftex - -@menu -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. -@end menu - -@node Menu Location, Writing a Menu, Menus, Menus -@ifinfo -@heading Menus Need Short Nodes -@end ifinfo -@cindex Menu location -@cindex Location of menus -@cindex Nodes for menus are short -@cindex Short nodes for menus - -@ifinfo -A reader can easily see a menu that is close to the beginning of the -node. The node should be short. As a practical matter, you should -locate a menu within 20 lines of the beginning of the node. -Otherwise, a reader with a terminal that displays only a few lines may -miss the menu and its associated text.@refill -@end ifinfo - -The short text before a menu may look awkward in a printed manual. To -avoid this, you can write a menu near the beginning of its node and -follow the menu by an @code{@@node} line, and then an @code{@@heading} -line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, -the menu, @code{@@node} line, and title appear only in the Info file, -not the printed document.@refill - -For example, the preceding two paragraphs follow an Info-only menu, -@code{@@node} line, and heading, and look like this:@refill - -@example -@group -@@menu -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part entries. -* Other Info Files:: How to refer to a different - Info file. -@@end menu - -@@node Menu Location, Writing a Menu, , Menus -@@ifinfo -@@heading Menus Need Short Nodes -@@end ifinfo -@end group -@end example - -The Texinfo file for this document contains more than a dozen -examples of this procedure. One is at the beginning of this chapter; -another is at the beginning of the ``Cross References'' chapter.@refill - -@node Writing a Menu, Menu Parts, Menu Location, Menus -@section Writing a Menu -@cindex Writing a menu -@cindex Menu writing - -A menu consists of an @code{@@menu} command on a line by -itself followed by menu entry lines or menu comment lines -and then by an @code{@@end menu} command on a line by -itself.@refill - -A menu looks like this:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -In a menu, every line that begins with an @w{@samp{* }} is a -@dfn{menu entry}. (Note the space after the asterisk.) A -line that does not start with an @w{@samp{* }} may also -appear in a menu. Such a line is not a menu entry but is a -menu comment line that appears in the Info file. In -the example above, the line @samp{Larger Units of Text} is a -menu comment line; the two lines starting with @w{@samp{* }} -are menu entries. - -@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus -@section The Parts of a Menu -@cindex Parts of a menu -@cindex Menu parts -@cindex @code{@@menu} parts - -A menu entry has three parts, only the second of which is required: - -@enumerate -@item -The menu entry name (optional). - -@item -The name of the node (required). - -@item -A description of the item (optional). -@end enumerate - -The template for a menu entry looks like this:@refill - -@example -* @var{menu-entry-name}: @var{node-name}. @var{description} -@end example - -Follow the menu entry name with a single colon and follow the node name -with tab, comma, period, or newline.@refill - -In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) -command. The menu entry name is what the user types after the @kbd{m} -command.@refill - -The third part of a menu entry is a descriptive phrase or sentence. -Menu entry names and node names are often short; the description -explains to the reader what the node is about. A useful description -complements the node name rather than repeats it. The description, -which is optional, can spread over two or more lines; if it does, some -authors prefer to indent the second line while others prefer to align it -with the first (and all others). It's up to you. - - -@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus -@comment node-name, next, previous, up -@section Less Cluttered Menu Entry -@cindex Two part menu entry -@cindex Double-colon menu entries -@cindex Menu entries with two colons -@cindex Less cluttered menu entry -@cindex Uncluttered menu entry - -When the menu entry name and node name are the same, you can write -the name immediately after the asterisk and space at the beginning of -the line and follow the name with two colons.@refill - -@need 800 -For example, write - -@example -* Name:: @var{description} -@end example - -@need 800 -@noindent -instead of - -@example -* Name: Name. @var{description} -@end example - -You should use the node name for the menu entry name whenever possible, -since it reduces visual clutter in the menu.@refill - -@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus -@comment node-name, next, previous, up -@section A Menu Example -@cindex Menu example -@cindex Example menu - -A menu looks like this in Texinfo:@refill - -@example -@group -@@menu -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: - -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@end group -@end example - -@need 700 -Here is an example as you might see it in a Texinfo file:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@end group -@end example - -In this example, the menu has two entries. @samp{Files} is both a menu -entry name and the name of the node referred to by that name. -@samp{Multiples} is the menu entry name; it refers to the node named -@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it -appears in the menu, but is not an entry.@refill - -Since no file name is specified with either @samp{Files} or -@samp{Buffers}, they must be the names of nodes in the same Info file -(@pxref{Other Info Files, , Referring to Other Info Files}).@refill - -@node Other Info Files, , Menu Example, Menus -@comment node-name, next, previous, up -@section Referring to Other Info Files -@cindex Referring to other Info files -@cindex Nodes in other Info files -@cindex Other Info files' nodes -@cindex Going to other Info files' nodes -@cindex Info; other files' nodes - -You can create a menu entry that enables a reader in Info to go to a -node in another Info file by writing the file name in parentheses just -before the node name. In this case, you should use the three-part menu -entry format, which saves the reader from having to type the file -name.@refill - -@need 800 -The format looks like this:@refill - -@example -@group -@@menu -* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} -* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} -@@end menu -@end group -@end example - -For example, to refer directly to the @samp{Outlining} and -@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a -menu like this:@refill - -@example -@group -@@menu -* Outlining: (emacs)Outline Mode. The major mode for - editing outlines. -* Rebinding: (emacs)Rebinding. How to redefine the - meaning of a key. -@@end menu -@end group -@end example - -If you do not list the node name, but only name the file, then Info -presumes that you are referring to the `Top' node.@refill - -The @file{dir} file that contains the main menu for Info has menu -entries that list only file names. These take you directly to the `Top' -nodes of each Info document. (@xref{Install an Info File}.)@refill - -@need 700 -For example: - -@example -@group -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -@end group -@end example - -@noindent -(The @file{dir} top level directory for the Info system is an Info file, -not a Texinfo file, but a menu entry looks the same in both types of -file.)@refill - -Note that the GNU Emacs Texinfo mode menu updating commands only work -with nodes within the current buffer, so you cannot use them to create -menus that refer to other files. You must write such menus by hand.@refill - -@node Cross References, Marking Text, Menus, Top -@comment node-name, next, previous, up -@chapter Cross References -@cindex Making cross references -@cindex Cross references -@cindex References - -@dfn{Cross references} are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes are the -places to which cross references can refer.@refill - -@menu -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. -@end menu - -@node References, Cross Reference Commands, Cross References, Cross References -@ifinfo -@heading What References Are For -@end ifinfo - -Often, but not always, a printed document should be designed so that -it can be read sequentially. People tire of flipping back and forth -to find information that should be presented to them as they need -it.@refill - -However, in any document, some information will be too detailed for -the current context, or incidental to it; use cross references to -provide access to such information. Also, an on-line help system or a -reference manual is not like a novel; few read such documents in -sequence from beginning to end. Instead, people look up what they -need. For this reason, such creations should contain many cross -references to help readers find other information that they may not -have read.@refill - -In a printed manual, a cross reference results in a page reference, -unless it is to another manual altogether, in which case the cross -reference names that manual.@refill - -In Info, a cross reference results in an entry that you can follow using -the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info -commands, info}.)@refill - -The various cross reference commands use nodes to define cross -reference locations. This is evident in Info, in which a cross -reference takes you to the specified node. @TeX{} also uses nodes to -define cross reference locations, but the action is less obvious. When -@TeX{} generates a DVI file, it records nodes' page numbers and -uses the page numbers in making references. Thus, if you are writing -a manual that will only be printed, and will not be used on-line, you -must nonetheless write @code{@@node} lines to name the places to which -you make cross references.@refill - -@need 800 -@node Cross Reference Commands, Cross Reference Parts, References, Cross References -@comment node-name, next, previous, up -@section Different Cross Reference Commands -@cindex Different cross reference commands - -There are four different cross reference commands:@refill - -@table @code -@item @@xref -Used to start a sentence in the printed manual saying @w{`See @dots{}'} -or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}. - -@item @@ref -Used within or, more often, at the end of a sentence; same as -@code{@@xref} for Info; produces just the reference in the printed -manual without a preceding `See'.@refill - -@item @@pxref -Used within parentheses to make a reference that suits both an Info -file and a printed book. Starts with a lower case `see' within the -printed manual. (@samp{p} is for `parenthesis'.)@refill - -@item @@inforef -Used to make a reference to an Info file for which there is no printed -manual.@refill -@end table - -@noindent -(The @code{@@cite} command is used to make references to books and -manuals for which there is no corresponding Info file and, therefore, -no node to which to point. @xref{cite, , @code{@@cite}}.)@refill - -@node Cross Reference Parts, xref, Cross Reference Commands, Cross References -@comment node-name, next, previous, up -@section Parts of a Cross Reference -@cindex Cross reference parts -@cindex Parts of a cross reference - -A cross reference command requires only one argument, which is the -name of the node to which it refers. But a cross reference command -may contain up to four additional arguments. By using these -arguments, you can provide a cross reference name for Info, a topic -description or section title for the printed output, the name of a -different Info file, and the name of a different printed -manual.@refill - -Here is a simple cross reference example:@refill - -@example -@@xref@{Node name@}. -@end example - -@noindent -which produces - -@example -*Note Node name::. -@end example - -@noindent -and - -@quotation -See Section @var{nnn} [Node name], page @var{ppp}. -@end quotation - -@need 700 -Here is an example of a full five-part cross reference:@refill - -@example -@group -@@xref@{Node name, Cross Reference Name, Particular Topic, -info-file-name, A Printed Manual@}, for details. -@end group -@end example - -@noindent -which produces - -@example -*Note Cross Reference Name: (info-file-name)Node name, -for details. -@end example - -@noindent -in Info and - -@quotation -See section ``Particular Topic'' in @i{A Printed Manual}, for details. -@end quotation - -@noindent -in a printed book. - -The five possible arguments for a cross reference are:@refill - -@enumerate -@item -The node name (required). This is the node to which the -cross reference takes you. In a printed document, the location of the -node provides the page reference only for references within the same -document.@refill - -@item -The cross reference name for the Info reference, if it is to be different -from the node name. If you include this argument, it becomes -the first part of the cross reference. It is usually omitted.@refill - -@item -A topic description or section name. Often, this is the title of the -section. This is used as the name of the reference in the printed -manual. If omitted, the node name is used.@refill - -@item -The name of the Info file in which the reference is located, if it is -different from the current file. You need not include any @samp{.info} -suffix on the file name, since Info readers try appending it -automatically. - -@item -The name of a printed manual from a different Texinfo file.@refill -@end enumerate - -The template for a full five argument cross reference looks like -this:@refill - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -Cross references with one, two, three, four, and five arguments are -described separately following the description of @code{@@xref}.@refill - -Write a node name in a cross reference in exactly the same way as in -the @code{@@node} line, including the same capitalization; otherwise, the -formatters may not find the reference.@refill - -You can write cross reference commands within a paragraph, but note -how Info and @TeX{} format the output of each of the various commands: -write @code{@@xref} at the beginning of a sentence; write -@code{@@pxref} only within parentheses, and so on.@refill - -@node xref, Top Node Naming, Cross Reference Parts, Cross References -@comment node-name, next, previous, up -@section @code{@@xref} -@findex xref -@cindex Cross references using @code{@@xref} -@cindex References using @code{@@xref} - -The @code{@@xref} command generates a cross reference for the -beginning of a sentence. The Info formatting commands convert it into -an Info cross reference, which the Info @samp{f} command can use to -bring you directly to another node. The @TeX{} typesetting commands -convert it into a page reference, or a reference to another book or -manual.@refill - -@menu -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. -@end menu - -@node Reference Syntax, One Argument, xref, xref -@ifinfo -@subheading What a Reference Looks Like and Requires -@end ifinfo - -Most often, an Info cross reference looks like this:@refill - -@example -*Note @var{node-name}::. -@end example - -@noindent -or like this - -@example -*Note @var{cross-reference-name}: @var{node-name}. -@end example - -@noindent -In @TeX{}, a cross reference looks like this: - -@example -See Section @var{section-number} [@var{node-name}], page @var{page}. -@end example - -@noindent -or like this - -@example -See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end example - -The @code{@@xref} command does not generate a period or comma to end -the cross reference in either the Info file or the printed output. -You must write that period or comma yourself; otherwise, Info will not -recognize the end of the reference. (The @code{@@pxref} command works -differently. @xref{pxref, , @code{@@pxref}}.)@refill - -@quotation -@strong{Please note:} A period or comma @strong{must} follow the closing -brace of an @code{@@xref}. It is required to terminate the cross -reference. This period or comma will appear in the output, both in -the Info file and in the printed manual.@refill -@end quotation - -@code{@@xref} must refer to an Info node by name. Use @code{@@node} -to define the node (@pxref{Writing a Node}).@refill - -@code{@@xref} is followed by several arguments inside braces, separated by -commas. Whitespace before and after these commas is ignored.@refill - -A cross reference requires only the name of a node; but it may contain -up to four additional arguments. Each of these variations produces a -cross reference that looks somewhat different.@refill - -@quotation -@strong{Please note:} Commas separate arguments in a cross reference; -avoid including them in the title or other part lest the formatters -mistake them for separators.@refill -@end quotation - -@node One Argument, Two Arguments, Reference Syntax, xref -@subsection @code{@@xref} with One Argument - -The simplest form of @code{@@xref} takes one argument, the name of -another node in the same Info file. The Info formatters produce -output that the Info readers can use to jump to the reference; @TeX{} -produces output that specifies the page and section number for you.@refill - -@need 700 -@noindent -For example, - -@example -@@xref@{Tropical Storms@}. -@end example - -@noindent -produces - -@example -*Note Tropical Storms::. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Tropical Storms@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Tropical Storms::, for more info. -@end example - -@quotation -See Section 3.1 [Tropical Storms], page 24, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Two Arguments, Three Arguments, One Argument, xref -@subsection @code{@@xref} with Two Arguments - -With two arguments, the second is used as the name of the Info cross -reference, while the first is still the name of the node to which the -cross reference points.@refill - -@need 750 -@noindent -The template is like this: - -@example -@@xref@{@var{node-name}, @var{cross-reference-name}@}. -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning@}. -@end example - -@noindent -produces: - -@example -*Note Lightning: Electrical Effects. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Electrical Effects, Lightning@}, for more info. -@end example - -@noindent -which produces -@example -*Note Lightning: Electrical Effects, for more info. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Three Arguments, Four and Five Arguments, Two Arguments, xref -@subsection @code{@@xref} with Three Arguments - -A third argument replaces the node name in the @TeX{} output. The third -argument should be the name of the section in the printed output, or -else state the topic discussed by that section. Often, you will want to -use initial upper case letters so it will be easier to read when the -reference is printed. Use a third argument when the node name is -unsuitable because of syntax or meaning.@refill - -Remember to avoid placing a comma within the title or topic section of -a cross reference, or within any other section. The formatters divide -cross references into arguments according to the commas; a comma -within a title or other section will divide it into two arguments. In -a reference, you need to write a title such as ``Clouds, Mist, and -Fog'' without the commas.@refill - -Also, remember to write a comma or period after the closing brace of a -@code{@@xref} to terminate the cross reference. In the following -examples, a clause follows a terminating comma.@refill - - -@need 750 -@noindent -The template is like this: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -If a third argument is given and the second one is empty, then the -third argument serves both. (Note how two commas, side by side, mark -the empty second argument.)@refill - -@example -@group -@@xref@{Electrical Effects, , Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Thunder and Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -As a practical matter, it is often best to write cross references with -just the first argument if the node name and the section title are the -same, and with the first and third arguments if the node name and title -are different.@refill - -Here are several examples from @cite{The GNU Awk User's Guide}:@refill - -@smallexample -@@xref@{Sample Program@}. -@@xref@{Glossary@}. -@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. -@@xref@{Close Output, , Closing Output Files and Pipes@}, - for more information. -@@xref@{Regexp, , Regular Expressions as Patterns@}. -@end smallexample - -@node Four and Five Arguments, , Three Arguments, xref -@subsection @code{@@xref} with Four and Five Arguments - -In a cross reference, a fourth argument specifies the name of another -Info file, different from the file in which the reference appears, and -a fifth argument specifies its title as a printed manual.@refill - -Remember that a comma or period must follow the closing brace of an -@code{@@xref} command to terminate the cross reference. In the -following examples, a clause follows a terminating comma.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning, Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -*Note Lightning: (weather)Electrical Effects, for details. -@end example - -@noindent -The name of the Info file is enclosed in parentheses and precedes -the name of the node. - -@noindent -In a printed manual, the reference looks like this:@refill - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -@noindent -The title of the printed manual is typeset in italics; and the -reference lacks a page number since @TeX{} cannot know to which page a -reference refers when that reference is to another manual.@refill - -Often, you will leave out the second argument when you use the long -version of @code{@@xref}. In this case, the third argument, the topic -description, will be used as the cross reference name in Info.@refill - -@noindent -The template looks like this: - -@example -@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, -@var{printed-manual-title}@}, for details. -@end example - -@noindent -which produces - -@example -*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. -@end example - -@noindent -and - -@quotation -See section @var{title-or-topic} in @var{printed-manual-title}, for details. -@end quotation - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, , Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -@group -*Note Thunder and Lightning: (weather)Electrical Effects, -for details. -@end group -@end example - -@noindent -and - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -On rare occasions, you may want to refer to another Info file that -is within a single printed manual---when multiple Texinfo files are -incorporated into the same @TeX{} run but make separate Info files. -In this case, you need to specify only the fourth argument, and not -the fifth.@refill - -@node Top Node Naming, ref, xref, Cross References -@section Naming a `Top' Node -@cindex Naming a `Top' Node in references -@cindex @samp{@r{Top}} node naming for references - -In a cross reference, you must always name a node. This means that in -order to refer to a whole manual, you must identify the `Top' node by -writing it as the first argument to the @code{@@xref} command. (This -is different from the way you write a menu entry; see @ref{Other Info -Files, , Referring to Other Info Files}.) At the same time, to -provide a meaningful section topic or title in the printed cross -reference (instead of the word `Top'), you must write an appropriate -entry for the third argument to the @code{@@xref} command. -@refill - -@noindent -Thus, to make a cross reference to @cite{The GNU Make Manual}, -write:@refill - -@example -@@xref@{Top, , Overview, make, The GNU Make Manual@}. -@end example - -@noindent -which produces - -@example -*Note Overview: (make)Top. -@end example - -@noindent -and - -@quotation -See section ``Overview'' in @i{The GNU Make Manual}. -@end quotation - -@noindent -In this example, @samp{Top} is the name of the first node, and -@samp{Overview} is the name of the first section of the manual.@refill -@node ref, pxref, Top Node Naming, Cross References -@comment node-name, next, previous, up -@section @code{@@ref} -@cindex Cross references using @code{@@ref} -@cindex References using @code{@@ref} -@findex ref - -@code{@@ref} is nearly the same as @code{@@xref} except that it does -not generate a `See' in the printed output, just the reference itself. -This makes it useful as the last part of a sentence.@refill - -@need 700 -@noindent -For example, - -@example -For more information, see @@ref@{Hurricanes@}. -@end example - -@noindent -produces - -@example -For more information, see *Note Hurricanes. -@end example - -@noindent -and - -@quotation -For more information, see Section 8.2 [Hurricanes], page 123. -@end quotation - -The @code{@@ref} command sometimes leads writers to express themselves -in a manner that is suitable for a printed manual but looks awkward -in the Info format. Bear in mind that your audience will be using -both the printed and the Info format.@refill - -@need 800 -@noindent -For example, - -@example -@group -Sea surges are described in @@ref@{Hurricanes@}. -@end group -@end example - -@need 800 -@noindent -produces - -@quotation -Sea surges are described in Section 6.7 [Hurricanes], page 72. -@end quotation - -@need 800 -@noindent -in a printed document, and the following in Info: - -@example -Sea surges are described in *Note Hurricanes::. -@end example - -@quotation -@strong{Caution:} You @emph{must} write a period or comma immediately -after an @code{@@ref} command with two or more arguments. Otherwise, -Info will not find the end of the cross reference entry and its -attempt to follow the cross reference will fail. As a general rule, -you should write a period or comma after every @code{@@ref} command. -This looks best in both the printed and the Info output.@refill -@end quotation - -@node pxref, inforef, ref, Cross References -@comment node-name, next, previous, up -@section @code{@@pxref} -@cindex Cross references using @code{@@pxref} -@cindex References using @code{@@pxref} -@findex pxref - -The parenthetical reference command, @code{@@pxref}, is nearly the -same as @code{@@xref}, but you use it @emph{only} inside parentheses -and you do @emph{not} type a comma or period after the command's -closing brace. The command differs from @code{@@xref} in two -ways:@refill - -@enumerate -@item -@TeX{} typesets the reference for the printed manual with a lower case -`see' rather than an upper case `See'.@refill - -@item -The Info formatting commands automatically end the reference with a -closing colon or period.@refill -@end enumerate - -Because one type of formatting automatically inserts closing -punctuation and the other does not, you should use @code{@@pxref} -@emph{only} inside parentheses as part of another sentence. Also, you -yourself should not insert punctuation after the reference, as you do -with @code{@@xref}.@refill - -@code{@@pxref} is designed so that the output looks right and works -right between parentheses both in printed output and in an Info file. -In a printed manual, a closing comma or period should not follow a -cross reference within parentheses; such punctuation is wrong. But in -an Info file, suitable closing punctuation must follow the cross -reference so Info can recognize its end. @code{@@pxref} spares you -the need to use complicated methods to put a terminator into one form -of the output and not the other.@refill - -@noindent -With one argument, a parenthetical cross reference looks like -this:@refill - -@example -@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} -@end example - -@need 800 -@noindent -which produces - -@example -@group -@dots{} storms cause flooding (*Note Hurricanes::) @dots{} -@end group -@end example - -@noindent -and - -@quotation -@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} -@end quotation - -With two arguments, a parenthetical cross reference has this -template:@refill - -@example -@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} -@end example - -@noindent -which produces - -@example -@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{} -@end example - -@noindent -and - -@need 1500 -@quotation -@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} -@end quotation - -@code{@@pxref} can be used with up to five arguments just like -@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill - -@quotation -@strong{Please note:} Use @code{@@pxref} only as a parenthetical -reference. Do not try to use @code{@@pxref} as a clause in a sentence. -It will look bad in either the Info file, the printed output, or -both.@refill - -Also, parenthetical cross references look best at the ends of sentences. -Although you may write them in the middle of a sentence, that location -breaks up the flow of text.@refill -@end quotation - -@node inforef, uref, pxref, Cross References -@section @code{@@inforef} -@cindex Cross references using @code{@@inforef} -@cindex References using @code{@@inforef} -@findex inforef - -@code{@@inforef} is used for cross references to Info files for which -there are no printed manuals. Even in a printed manual, -@code{@@inforef} generates a reference directing the user to look in -an Info file.@refill - -The command takes either two or three arguments, in the following -order:@refill - -@enumerate -@item -The node name. - -@item -The cross reference name (optional). - -@item -The Info file name. -@end enumerate - -@noindent -Separate the arguments with commas, as with @code{@@xref}. Also, you -must terminate the reference with a comma or period after the -@samp{@}}, as you do with @code{@@xref}.@refill - -@noindent -The template is: - -@example -@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, -@end example - -@need 800 -@noindent -Thus, - -@example -@group -@@inforef@{Expert, Advanced Info commands, info@}, -for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -@group -*Note Advanced Info commands: (info)Expert, -for more information. -@end group -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation - -@need 800 -@noindent -Similarly, - -@example -@group -@@inforef@{Expert, , info@}, for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -*Note (info)Expert::, for more information. -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation - -The converse of @code{@@inforef} is @code{@@cite}, which is used to -refer to printed works for which no Info form exists. @xref{cite, , -@code{@@cite}}.@refill - - -@node uref, , inforef, Cross References -@section @code{@@uref@{@var{url}[, @var{displayed-text}]@}} -@findex uref -@cindex Uniform resource locator, referring to -@cindex URL, referring to - -@code{@@uref} produces a reference to a uniform resource locator (URL). -It takes one mandatory argument, the URL, and one optional argument, the -text to display (the default is the URL itself). In HTML output, -@code{@@uref} produces a link you can follow. For example: - -@example -The official GNU ftp site is -@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@} -@end example - -@noindent produces (in text): -@display -The official GNU ftp site is -@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu} -@end display - -@noindent whereas -@example -The official -@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu, - GNU ftp site@} holds programs and texts. -@end example - -@noindent produces (in text): -@display -The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds -programs and texts. -@end display - -@noindent and (in HTML): -@example -The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp -site</A> holds programs and texts. -@end example - -To merely indicate a URL, use @code{@@url} (@pxref{url, @code{@@url}}). - - -@node Marking Text, Quotations and Examples, Cross References, Top -@comment node-name, next, previous, up -@chapter Marking Words and Phrases -@cindex Paragraph, marking text within -@cindex Marking words and phrases -@cindex Words and phrases, marking them -@cindex Marking text within a paragraph - -In Texinfo, you can mark words and phrases in a variety of ways. -The Texinfo formatters use this information to determine how to -highlight the text. -You can specify, for example, whether a word or phrase is a -defining occurrence, a metasyntactic variable, or a symbol used in a -program. Also, you can emphasize text.@refill - -@menu -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. -@end menu - -@node Indicating, Emphasis, Marking Text, Marking Text -@comment node-name, next, previous, up -@section Indicating Definitions, Commands, etc. -@cindex Highlighting text -@cindex Indicating commands, definitions, etc. - -Texinfo has commands for indicating just what kind of object a piece of -text refers to. For example, metasyntactic variables are marked by -@code{@@var}, and code by @code{@@code}. Since the pieces of text are -labelled by commands that tell what kind of object they are, it is easy -to change the way the Texinfo formatters prepare such text. (Texinfo is -an @emph{intentional} formatting language rather than a @emph{typesetting} -formatting language.)@refill - -For example, in a printed manual, -code is usually illustrated in a typewriter font; -@code{@@code} tells @TeX{} to typeset this text in this font. But it -would be easy to change the way @TeX{} highlights code to use another -font, and this change would not effect how keystroke examples are -highlighted. If straight typesetting commands were used in the body -of the file and you wanted to make a change, you would need to check -every single occurrence to make sure that you were changing code and -not something else that should not be changed.@refill - -@menu -* Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -* url:: How to indicate a world wide web reference. -* email:: How to indicate an electronic mail address. -@end menu - -@node Useful Highlighting, code, Indicating, Indicating -@ifinfo -@subheading Highlighting Commands are Useful -@end ifinfo - -The highlighting commands can be used to generate useful information -from the file, such as lists of functions or file names. It is -possible, for example, to write a program in Emacs Lisp (or a keyboard -macro) to insert an index entry after every paragraph that contains -words or phrases marked by a specified command. You could do this to -construct an index of functions if you had not already made the -entries.@refill - -The commands serve a variety of purposes:@refill - -@table @code -@item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input.@refill - -@item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard.@refill - -@item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable.@refill - -@item @@url@{@var{uniform-resource-locator}@} -Indicate a uniform resource locator for the World Wide Web. - -@item @@file@{@var{file-name}@} -Indicate the name of a file.@refill - -@item @@email@{@var{email-address}[, @var{displayed-text}]@} -Indicate an electronic mail address. - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term.@refill - -@item @@cite@{@var{reference}@} -Indicate the name of a book.@refill - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Use for an @sc{ascii} control character.@refill -@end ignore -@end table - -@node code, kbd, Useful Highlighting, Indicating -@comment node-name, next, previous, up -@subsection @code{@@code}@{@var{sample-code}@} -@findex code - -Use the @code{@@code} command to indicate text that is a piece of a -program and which consists of entire syntactic tokens. Enclose the -text in braces.@refill - -Thus, you should use @code{@@code} for an expression in a program, for -the name of a variable or function used in a program, or for a -keyword. Also, you should use @code{@@code} for the name of a -program, such as @code{diff}, that is a name used in the machine. (You -should write the name of a program in the ordinary text font if you -regard it as a new English word, such as `Emacs' or `Bison'.)@refill - -Use @code{@@code} for environment variables such as @code{TEXINPUTS}, -and other variables.@refill - -Use @code{@@code} for command names in command languages that -resemble programming languages, such as Texinfo or the shell. -For example, @code{@@code} and @code{@@samp} are produced by writing -@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo -source, respectively.@refill - -Note, however, that you should not use @code{@@code} for shell options -such as @samp{-c} when such options stand alone. (Use @code{@@samp}.) -Also, an entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format.@refill - -It is incorrect to alter the case of a word inside an @code{@@code} -command when it appears at the beginning of a sentence. Most computer -languages are case sensitive. In C, for example, @code{Printf} is -different from the identifier @code{printf}, and most likely is a -misspelling of it. Even in languages which are not case sensitive, it -is confusing to a human reader to see identifiers spelled in different -ways. Pick one spelling and always use that. If you do not want to -start a sentence with a command written all in lower case, you should -rearrange the sentence.@refill - -Do not use the @code{@@code} command for a string of characters shorter -than a syntactic token. If you are writing about @samp{TEXINPU}, which -is just a part of the name for the @code{TEXINPUTS} environment -variable, you should use @code{@@samp}.@refill - -In particular, you should not use the @code{@@code} command when writing -about the characters used in a token; do not, for example, use -@code{@@code} when you are explaining what letters or printable symbols -can be used in the names of functions. (Use @code{@@samp}.) Also, you -should not use @code{@@code} to mark text that is considered input to -programs unless the input is written in a language that is like a -programming language. For example, you should not use @code{@@code} for -the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although -you may use @code{@@code} for the names of the Emacs Lisp functions that -the keystroke commands invoke.@refill - -In the printed manual, @code{@@code} causes @TeX{} to typeset the -argument in a typewriter face. In the Info file, it causes the Info -formatting commands to use single quotation marks around the text. - -@need 700 -For example, - -@example -Use @@code@{diff@} to compare two files. -@end example - -@noindent -produces this in the printed manual:@refill - -@quotation -Use @code{diff} to compare two files. -@end quotation -@iftex - -@noindent -and this in the Info file:@refill - -@example -Use `diff' to compare two files. -@end example -@end iftex - - -@node kbd, key, code, Indicating -@subsection @code{@@kbd}@{@var{keyboard-characters}@} -@findex kbd -@cindex keyboard input - -Use the @code{@@kbd} command for characters of input to be typed by -users. For example, to refer to the characters @kbd{M-a}, -write@refill - -@example -@@kbd@{M-a@} -@end example - -@noindent -and to refer to the characters @kbd{M-x shell}, write@refill - -@example -@@kbd@{M-x shell@} -@end example - -@cindex user input -@cindex slanted typewriter font, for @code{@@kbd} -The @code{@@kbd} command has the same effect as @code{@@code} in Info, -but by default produces a different font (slanted typewriter instead of -normal typewriter) in the printed manual, so users can distinguish the -characters they are supposed to type from those the computer outputs. - -@findex kbdinputstyle -Since the usage of @code{@@kbd} varies from manual to manual, you can -control the font switching with the @code{@@kbdinputstyle} command. -This command has no effect on Info output. Write this command at the -beginning of a line with a single word as an argument, one of the -following: -@vindex distinct@r{, arg to @@kbdinputstyle} -@vindex example@r{, arg to @@kbdinputstyle} -@vindex code@r{, arg to @@kbdinputstyle} -@table @samp -@item code -Always use the same font for @code{@@kbd} as @code{@@code}. -@item example -Use the distinguishing font for @code{@@kbd} only in @code{@@example} -and similar environments. -@item example -(the default) Always use the distinguishing font for @code{@@kbd}. -@end table - -You can embed another @@-command inside the braces of an @code{@@kbd} -command. Here, for example, is the way to describe a command that -would be described more verbosely as ``press an @samp{r} and then -press the @key{RET} key'':@refill - -@example -@@kbd@{r @@key@{RET@}@} -@end example - -@noindent -This produces: @kbd{r @key{RET}} - -You also use the @code{@@kbd} command if you are spelling out the letters -you type; for example:@refill - -@example -To give the @@code@{logout@} command, -type the characters @@kbd@{l o g o u t @@key@{RET@}@}. -@end example - -@noindent -This produces: - -@quotation -To give the @code{logout} command, -type the characters @kbd{l o g o u t @key{RET}}. -@end quotation - -(Also, this example shows that you can add spaces for clarity. If you -really want to mention a space character as one of the characters of -input, write @kbd{@@key@{SPC@}} for it.)@refill - - -@node key, samp, kbd, Indicating -@comment node-name, next, previous, up -@subsection @code{@@key}@{@var{key-name}@} -@findex key - -Use the @code{@@key} command for the conventional name for a key on a -keyboard, as in:@refill - -@example -@@key@{RET@} -@end example - -You can use the @code{@@key} command within the argument of an -@code{@@kbd} command when the sequence of characters to be typed -includes one or more keys that are described by name.@refill - -@need 700 -For example, to produce @kbd{C-x @key{ESC}} you would type:@refill - -@example -@@kbd@{C-x @@key@{ESC@}@} -@end example - -Here is a list of the recommended names for keys: -@cindex Recommended names for keys -@cindex Keys, recommended names -@cindex Names recommended for keys -@cindex Abbreviations for keys - -@quotation -@table @t -@item SPC -Space -@item RET -Return -@item LFD -Linefeed (however, since most keyboards nowadays do not have a Linefeed key, -it might be better to call this character @kbd{C-j}. -@item TAB -Tab -@item BS -Backspace -@item ESC -Escape -@item DEL -Delete -@item SHIFT -Shift -@item CTRL -Control -@item META -Meta -@end table -@end quotation - -@cindex META key -There are subtleties to handling words like `meta' or `ctrl' that are -names of modifier keys. When mentioning a character in which the -modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command -alone; do not use the @code{@@key} command; but when you are referring -to the modifier key in isolation, use the @code{@@key} command. For -example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and -@samp{@@key@{META@}} to produce @key{META}. - -@c I don't think this is a good explanation. -@c I think it will puzzle readers more than it clarifies matters. -- rms. -@c In other words, use @code{@@kbd} for what you do, and use @code{@@key} -@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to -@c the beginning of the sentence. The @code{@@key@{META@}} key is often in -@c the lower left of the keyboard.''@refill - -@node samp, var, key, Indicating -@comment node-name, next, previous, up -@subsection @code{@@samp}@{@var{text}@} -@findex samp - -Use the @code{@@samp} command to indicate text that is a literal example -or `sample' of a sequence of characters in a file, string, pattern, etc. -Enclose the text in braces. The argument appears within single -quotation marks in both the Info file and the printed manual; in -addition, it is printed in a fixed-width font.@refill - -@example -To match @@samp@{foo@} at the end of the line, -use the regexp @@samp@{foo$@}. -@end example - -@noindent -produces - -@quotation -To match @samp{foo} at the end of the line, use the regexp -@samp{foo$}.@refill -@end quotation - -Any time you are referring to single characters, you should use -@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. -Use @code{@@samp} for the names of command-line options (except in an -@code{@@table}, where @code{@@code} seems to read more easily). Also, -you may use @code{@@samp} for entire statements in C and for entire -shell commands---in this case, @code{@@samp} often looks better than -@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is -not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill - -Only include punctuation marks within braces if they are part of the -string you are specifying. Write punctuation marks outside the braces -if those punctuation marks are part of the English text that surrounds -the string. In the following sentence, for example, the commas and -period are outside of the braces:@refill - -@example -@group -In English, the vowels are @@samp@{a@}, @@samp@{e@}, -@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes -@@samp@{y@}. -@end group -@end example - -@noindent -This produces: - -@quotation -In English, the vowels are @samp{a}, @samp{e}, -@samp{i}, @samp{o}, @samp{u}, and sometimes -@samp{y}. -@end quotation - -@node var, file, samp, Indicating -@comment node-name, next, previous, up -@subsection @code{@@var}@{@var{metasyntactic-variable}@} -@findex var - -Use the @code{@@var} command to indicate metasyntactic variables. A -@dfn{metasyntactic variable} is something that stands for another piece of -text. For example, you should use a metasyntactic variable in the -documentation of a function to describe the arguments that are passed -to that function.@refill - -Do not use @code{@@var} for the names of particular variables in -programming languages. These are specific names from a program, so -@code{@@code} is correct for them. For example, the Emacs Lisp variable -@code{texinfo-tex-command} is not a metasyntactic variable; it is -properly formatted using @code{@@code}.@refill - -The effect of @code{@@var} in the Info file is to change the case of -the argument to all upper case; in the printed manual, to italicize it. - -@need 700 -For example, - -@example -To delete file @@var@{filename@}, -type @@code@{rm @@var@{filename@}@}. -@end example - -@noindent -produces - -@quotation -To delete file @var{filename}, type @code{rm @var{filename}}. -@end quotation - -@noindent -(Note that @code{@@var} may appear inside @code{@@code}, -@code{@@samp}, @code{@@file}, etc.)@refill - -Write a metasyntactic variable all in lower case without spaces, and -use hyphens to make it more readable. Thus, the Texinfo source for -the illustration of how to begin a Texinfo manual looks like -this:@refill - -@example -@group -\input texinfo -@@@@setfilename @@var@{info-file-name@} -@@@@settitle @@var@{name-of-manual@} -@end group -@end example - -@noindent -This produces: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -In some documentation styles, metasyntactic variables are shown with -angle brackets, for example:@refill - -@example -@dots{}, type rm <filename> -@end example - -@noindent -However, that is not the style that Texinfo uses. (You can, of -course, modify the sources to @TeX{} and the Info formatting commands -to output the @code{<@dots{}>} format if you wish.)@refill - -@node file, dfn, var, Indicating -@comment node-name, next, previous, up -@subsection @code{@@file}@{@var{file-name}@} -@findex file - -Use the @code{@@file} command to indicate text that is the name of a -file, buffer, or directory, or is the name of a node in Info. You can -also use the command for file name suffixes. Do not use @code{@@file} -for symbols in a programming language; use @code{@@code}. - -Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. -For example,@refill - -@example -The @@file@{.el@} files are in -the @@file@{/usr/local/emacs/lisp@} directory. -@end example - -@noindent -produces - -@quotation -The @file{.el} files are in -the @file{/usr/local/emacs/lisp} directory. -@end quotation - -@node dfn, cite, file, Indicating -@comment node-name, next, previous, up -@subsection @code{@@dfn}@{@var{term}@} -@findex dfn - -Use the @code{@@dfn} command to identify the introductory or defining -use of a technical term. Use the command only in passages whose -purpose is to introduce a term which will be used again or which the -reader ought to know. Mere passing mention of a term for the first -time does not deserve @code{@@dfn}. The command generates italics in -the printed manual, and double quotation marks in the Info file. For -example:@refill - -@example -Getting rid of a file is called @@dfn@{deleting@} it. -@end example - -@noindent -produces - -@quotation -Getting rid of a file is called @dfn{deleting} it. -@end quotation - -As a general rule, a sentence containing the defining occurrence of a -term should be a definition of the term. The sentence does not need -to say explicitly that it is a definition, but it should contain the -information of a definition---it should make the meaning clear. - -@node cite, url, dfn, Indicating -@comment node-name, next, previous, up -@subsection @code{@@cite}@{@var{reference}@} -@findex cite - -Use the @code{@@cite} command for the name of a book that lacks a -companion Info file. The command produces italics in the printed -manual, and quotation marks in the Info file.@refill - -(If a book is written in Texinfo, it is better to use a cross reference -command since a reader can easily follow such a reference in Info. -@xref{xref, , @code{@@xref}}.)@refill - -@ignore -@c node ctrl, , cite, Indicating -@comment node-name, next, previous, up -@c subsection @code{@@ctrl}@{@var{ctrl-char}@} -@findex ctrl - -The @code{@@ctrl} command is seldom used. It describes an @sc{ascii} -control character by inserting the actual character into the Info -file. - -Usually, in Texinfo, you talk what you type as keyboard entry by -describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for -@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control -character that is typed on the keyboard by the user. When talking -about a control character appearing in a file or a string, do not use -@code{@@kbd} since the control character is not typed. Also, do not -use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, -to make it easier for a reader to understand.@refill - -@code{@@ctrl} is an idea from the beginnings of Texinfo which may not -really fit in to the scheme of things. But there may be times when -you want to use the command. The pattern is -@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character -whose control-equivalent is wanted. For example, to specify -@samp{control-f}, you would enter@refill - -@example -@@ctrl@{f@} -@end example - -@noindent -produces - -@quotation -@ctrl{f} -@end quotation - -In the Info file, this generates the specified control character, output -literally into the file. This is done so a user can copy the specified -control character (along with whatever else he or she wants) into another -Emacs buffer and use it. Since the `control-h',`control-i', and -`control-j' characters are formatting characters, they should not be -indicated with @code{@@ctrl}.@refill - -In a printed manual, @code{@@ctrl} generates text to describe or -identify that control character: an uparrow followed by the character -@var{ch}.@refill -@end ignore - - -@node url, email, cite, Indicating -@subsection @code{@@url}@{@var{uniform-resource-locator}@} -@findex url -@cindex Uniform resource locator, indicating -@cindex URL, indicating - -Use the @code{@@url} to indicate a uniform resource locator on the World -Wide Web. This is analogous to @code{@@file}, @code{@@var}, etc., and -is purely for markup purposes. It does not produce a link you can -follow in HTML output (the @code{@@uref} command does, @pxref{uref,, -@code{@@uref}}). It is useful for example URL's which do not actually -exist. For example: - -@c Two lines because one is too long for smallbook format. -@example -For example, the url might be -@@url@{http://host.domain.org/path@}. -@end example - - -@node email, , url, Indicating -@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} -@findex email - -Use the @code{@@email} command to indicate an electronic mail address. -It takes one mandatory argument, the address, and one optional argument, the -text to display (the default is the address itself). - -@cindex mailto link -In Info and @TeX{}, the address is shown in angle brackets, preceded by -the text to display if any. In HTML output, @code{@@email} produces a -@samp{mailto} link that usually brings up a mail composition window. -For example: - -@example -Send bug reports to @@email@{bug-texinfo@@@@prep.ai.mit.edu@}. -Send suggestions to the @@email@{bug-texinfo@@@@prep.ai.mit.edu, same place@}. -@end example -@noindent produces -@example -Send bug reports to @email{bug-texinfo@@prep.ai.mit.edu}. -Send suggestions to the @email{bug-texinfo@@prep.ai.mit.edu, same place}. -@end example - - -@node Emphasis, , Indicating, Marking Text -@comment node-name, next, previous, up -@section Emphasizing Text -@cindex Emphasizing text - -Usually, Texinfo changes the font to mark words in the text according to -what category the words belong to; an example is the @code{@@code} command. -Most often, this is the best way to mark words. -However, sometimes you will want to emphasize text without indicating a -category. Texinfo has two commands to do this. Also, Texinfo has -several commands that specify the font in which @TeX{} will typeset -text. These commands have no affect on Info and only one of them, -the @code{@@r} command, has any regular use.@refill - -@menu -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -* Customized Highlighting:: How to define highlighting commands. -@end menu - -@node emph & strong, Smallcaps, Emphasis, Emphasis -@comment node-name, next, previous, up -@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} -@cindex Emphasizing text, font for -@findex emph -@findex strong - -The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} -produces @emph{italics} and @code{@@strong} produces -@strong{bold}.@refill - -@need 800 -For example, - -@example -@group -@@quotation -@@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@} -files in the directory. -@@end quotation -@end group -@end example - -@iftex -@noindent -produces the following in printed output: - -@quotation -@strong{Caution}: @code{rm * .[^.]*} removes @emph{all} -files in the directory. -@end quotation - -@noindent -and the following in Info: -@end iftex -@ifinfo -@noindent -produces: -@end ifinfo - -@example - *Caution*: `rm * .[^.]*' removes *all* - files in the directory. -@end example - -The @code{@@strong} command is seldom used except to mark what is, in -effect, a typographical element, such as the word `Caution' in the -preceding example. - -In the Info file, both @code{@@emph} and @code{@@strong} put asterisks -around the text.@refill - -@quotation -@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the -word @samp{Note}; Info will mistake the combination for a cross -reference. Use a phrase such as @strong{Please note} or -@strong{Caution} instead.@refill -@end quotation - -@node Smallcaps, Fonts, emph & strong, Emphasis -@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font -@cindex Small caps font -@findex sc @r{(small caps font)} - -@iftex -Use the @samp{@@sc} command to set text in the printed output in @sc{a -small caps font} and set text in the Info file in upper case letters.@refill -@end iftex -@ifinfo -Use the @samp{@@sc} command to set text in the printed output in a -small caps font and set text in the Info file in upper case letters.@refill -@end ifinfo - -Write the text between braces in lower case, like this:@refill - -@example -The @@sc@{acm@} and @@sc@{ieee@} are technical societies. -@end example - -@noindent -This produces: - -@display -The @sc{acm} and @sc{ieee} are technical societies. -@end display - -@TeX{} typesets the small caps font in a manner that prevents the -letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case. The Info formatting -commands set all small caps text in upper case.@refill - -@ifinfo -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in full-size capitals. Use full-size capitals -sparingly.@refill -@end ifinfo -@iftex -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals -sparingly.@refill -@end iftex - -You may also use the small caps font for a jargon word such as -@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill - -There are subtleties to using the small caps font with a jargon word -such as @sc{cdr}, a word used in Lisp programming. In this case, you -should use the small caps font when the word refers to the second and -subsequent elements of a list (the @sc{cdr} of the list), but you -should use @samp{@@code} when the word refers to the Lisp function of -the same spelling.@refill - -@node Fonts, Customized Highlighting, Smallcaps, Emphasis -@comment node-name, next, previous, up -@subsection Fonts for Printing, Not Info -@cindex Fonts for printing, not for Info -@findex i @r{(italic font)} -@findex b @r{(bold font)} -@findex t @r{(typewriter font)} -@findex r @r{(Roman font)} - -Texinfo provides four font commands that specify font changes in the -printed manual but have no effect in the Info file. @code{@@i} -requests @i{italic} font (in some versions of @TeX{}, a slanted font -is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the -@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a -@r{roman} font, which is the usual font in which text is printed. All -four commands apply to an argument that follows, surrounded by -braces.@refill - -Only the @code{@@r} command has much use: in example programs, you -can use the @code{@@r} command to convert code comments from the -fixed-width font to a roman font. This looks better in printed -output.@refill - -@need 700 -For example, - -@example -@group -@@lisp -(+ 2 2) ; @@r@{Add two plus two.@} -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -(+ 2 2) ; @r{Add two plus two.} -@end lisp - -If possible, you should avoid using the other three font commands. If -you need to use one, it probably indicates a gap in the Texinfo -language.@refill - -@node Customized Highlighting, , Fonts, Emphasis -@comment node-name, next, previous, up -@subsection Customized Highlighting -@cindex Highlighting, customized -@cindex Customized highlighting - -@c I think this whole section is obsolete with the advent of macros -@c --karl, 15sep96. -You can use regular @TeX{} commands inside of @code{@@iftex} @dots{} -@code{@@end iftex} to create your own customized highlighting commands -for Texinfo. The easiest way to do this is to equate your customized -commands with pre-existing commands, such as those for italics. Such -new commands work only with @TeX{}.@refill - -@findex definfoenclose -@cindex Enclosure command for Info -You can use the @code{@@definfoenclose} command inside of -@code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info -with the same names as new commands for @TeX{}. -@code{@@definfoenclose} creates new commands for Info that mark text by -enclosing it in strings that precede and follow the text. -@footnote{Currently, @code{@@definfoenclose} works only with -@code{texinfo-format-buffer} and @code{texinfo-format-region}, not with -@code{makeinfo}.}@refill - -Here is how to create a new @@-command called @code{@@phoo} that causes -@TeX{} to typeset its argument in italics and causes Info to display the -argument between @samp{//} and @samp{\\}.@refill - -@need 1300 -For @TeX{}, write the following to equate the @code{@@phoo} command with -the existing @code{@@i} italics command:@refill - -@example -@group -@@iftex -@@global@@let@@phoo=@@i -@@end iftex -@end group -@end example - -@noindent -This defines @code{@@phoo} as a command that causes @TeX{} to typeset -the argument to @code{@@phoo} in italics. @code{@@global@@let} tells -@TeX{} to equate the next argument with the argument that follows the -equals sign. - -@need 1300 -For Info, write the following to tell the Info formatters to enclose the -argument between @samp{//} and @samp{\\}: - -@example -@group -@@ifinfo -@@definfoenclose phoo, //, \\ -@@end ifinfo -@end group -@end example - -@noindent -Write the @code{@@definfoenclose} command on a line and follow it with -three arguments separated by commas (commas are used as separators in an -@code{@@node} line in the same way).@refill - -@itemize @bullet -@item -The first argument to @code{@@definfoenclose} is the @@-command name -@strong{without} the @samp{@@}; - -@item -the second argument is the Info start delimiter string; and, - -@item -the third argument is the Info end delimiter string. -@end itemize - -@noindent -The latter two arguments enclose the highlighted text in the Info file. -A delimiter string may contain spaces. Neither the start nor end -delimiter is required. However, if you do not provide a start -delimiter, you must follow the command name with two commas in a row; -otherwise, the Info formatting commands will misinterpret the end -delimiter string as a start delimiter string.@refill - -After you have defined @code{@@phoo} both for @TeX{} and for Info, you -can then write @code{@@phoo@{bar@}} to see @samp{//bar\\} -in Info and see -@ifinfo -@samp{bar} in italics in printed output. -@end ifinfo -@iftex -@i{bar} in italics in printed output. -@end iftex - -Note that each definition applies to its own formatter: one for @TeX{}, -the other for Info. - -@need 1200 -Here is another example: - -@example -@group -@@ifinfo -@@definfoenclose headword, , : -@@end ifinfo -@@iftex -@@global@@let@@headword=@@b -@@end iftex -@end group -@end example - -@noindent -This defines @code{@@headword} as an Info formatting command that -inserts nothing before and a colon after the argument and as a @TeX{} -formatting command to typeset its argument in bold. - -@node Quotations and Examples, Lists and Tables, Marking Text, Top -@comment node-name, next, previous, up -@chapter Quotations and Examples - -Quotations and examples are blocks of text consisting of one or more -whole paragraphs that are set off from the bulk of the text and -treated differently. They are usually indented.@refill - -In Texinfo, you always begin a quotation or example by writing an -@@-command at the beginning of a line by itself, and end it by writing -an @code{@@end} command that is also at the beginning of a line by -itself. For instance, you begin an example by writing @code{@@example} -by itself at the beginning of a line and end the example by writing -@code{@@end example} on a line by itself, at the beginning of that -line.@refill -@findex end - -@menu -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. -@end menu - -@node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples -@section The Block Enclosing Commands - -Here are commands for quotations and examples:@refill - -@table @code -@item @@quotation -Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default.@refill - -@item @@example -Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled.@refill - -@item @@lisp -Illustrate Lisp code. The text is printed in a fixed-width font, -and indented but not filled.@refill - -@item @@smallexample -Illustrate code, commands, and the like. Similar to -@code{@@example}, except that in @TeX{} this command typesets text in -a smaller font for the smaller @code{@@smallbook} format than for the -8.5 by 11 inch format.@refill - -@item @@smalllisp -Illustrate Lisp code. Similar to @code{@@lisp}, except that -in @TeX{} this command typesets text in a smaller font for the smaller -@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill - -@item @@display -Display illustrative text. The text is indented but not filled, and -no font is specified (so, by default, the font is roman).@refill - -@item @@format -Print illustrative text. The text is not indented and not filled -and no font is specified (so, by default, the font is roman).@refill -@end table - -The @code{@@exdent} command is used within the above constructs to -undo the indentation of a line. - -The @code{@@flushleft} and @code{@@flushright} commands are used to line -up the left or right margins of unfilled text.@refill - -The @code{@@noindent} command may be used after one of the above -constructs to prevent the following text from being indented as a new -paragraph.@refill - -You can use the @code{@@cartouche} command within one of the above -constructs to highlight the example or quotation by drawing a box with -rounded corners around it. (The @code{@@cartouche} command affects -only the printed manual; it has no effect in the Info file; see -@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@node quotation, example, Block Enclosing Commands, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@quotation} -@cindex Quotations -@findex quotation - -The text of a quotation is -processed normally except that:@refill - -@itemize @bullet -@item -the margins are closer to the center of the page, so the whole of the -quotation is indented;@refill - -@item -the first lines of paragraphs are indented no more than other -lines;@refill - -@item -in the printed output, interparagraph spacing is reduced.@refill -@end itemize - -@quotation -This is an example of text written between an @code{@@quotation} -command and an @code{@@end quotation} command. An @code{@@quotation} -command is most often used to indicate text that is excerpted from -another (real or hypothetical) printed work.@refill -@end quotation - -Write an @code{@@quotation} command as text on a line by itself. This -line will disappear from the output. Mark the end of the quotation -with a line beginning with and containing only @code{@@end quotation}. -The @code{@@end quotation} line will likewise disappear from the -output. Thus, the following,@refill - -@example -@@quotation -This is -a foo. -@@end quotation -@end example - -@noindent -produces - -@quotation -This is a foo. -@end quotation - -@node example, noindent, quotation, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@example} -@cindex Examples, formatting them -@cindex Formatting examples -@findex example - -The @code{@@example} command is used to indicate an example that is -not part of the running text, such as computer input or output.@refill - -@example -@group -This is an example of text written between an -@code{@@example} command -and an @code{@@end example} command. -The text is indented but not filled. -@end group - -@group -In the printed manual, the text is typeset in a -fixed-width font, and extra spaces and blank lines are -significant. In the Info file, an analogous result is -obtained by indenting each line with five spaces. -@end group -@end example - -Write an @code{@@example} command at the beginning of a line by itself. -This line will disappear from the output. Mark the end of the example -with an @code{@@end example} command, also written at the beginning of a -line by itself. The @code{@@end example} will disappear from the -output.@refill - -@need 700 -For example, - -@example -@@example -mv foo bar -@@end example -@end example - -@noindent -produces - -@example -mv foo bar -@end example - -Since the lines containing @code{@@example} and @code{@@end example} -will disappear, you should put a blank line before the -@code{@@example} and another blank line after the @code{@@end -example}. (Remember that blank lines between the beginning -@code{@@example} and the ending @code{@@end example} will appear in -the output.)@refill - -@quotation -@strong{Caution:} Do not use tabs in the lines of an example (or anywhere -else in Texinfo, for that matter)! @TeX{} treats tabs as single -spaces, and that is not what they look like. This is a problem with -@TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to -convert tabs in a region to multiple spaces.)@refill -@end quotation - -Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text continues after an example should not be -indented. The @code{@@noindent} command prevents a piece of text from -being indented as if it were a new paragraph. -@ifinfo -(@xref{noindent}.) -@end ifinfo - -(The @code{@@code} command is used for examples of code that are -embedded within sentences, not set off from preceding and following -text. @xref{code, , @code{@@code}}.) - -@node noindent, Lisp Example, example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@noindent} -@findex noindent - -An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. However, you can prevent this by writing @code{@@noindent} -at the beginning of a line by itself preceding the continuation -text.@refill - -@need 1500 -For example: - -@example -@group -@@example -This is an example -@@end example - -@@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@@code@{@@@@display@} and @@code@{@@@@end display@}.) -@end group -@end example - -@noindent -produces - -@display -@example -This is an example -@end example -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3.5\baselineskip -@end tex - -@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@code{@@display} and @code{@@end display}.) -@end display - -To adjust the number of blank lines properly in the Info file output, -remember that the line containing @code{@@noindent} does not generate a -blank line, and neither does the @code{@@end example} line.@refill - -In the Texinfo source file for this manual, each line that says -`produces' is preceded by a line containing @code{@@noindent}.@refill - -Do not put braces after an @code{@@noindent} command; they are not -necessary, since @code{@@noindent} is a command used outside of -paragraphs (@pxref{Command Syntax}).@refill - -@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@lisp} -@cindex Lisp example -@findex lisp - -The @code{@@lisp} command is used for Lisp code. It is synonymous -with the @code{@@example} command. - -@lisp -This is an example of text written between an -@code{@@lisp} command and an @code{@@end lisp} command. -@end lisp - -Use @code{@@lisp} instead of @code{@@example} to preserve information -regarding the nature of the example. This is useful, for example, if -you write a function that evaluates only and all the Lisp code in a -Texinfo file. Then you can use the Texinfo file as a Lisp -library.@footnote{It would be straightforward to extend Texinfo to work -in a similar fashion for C, Fortran, or other languages.}@refill - -Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by -itself.@refill - -@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@smallexample} and @code{@@smalllisp} -@cindex Small book example -@cindex Example for a small book -@cindex Lisp example for a small book -@findex smallexample -@findex smalllisp - -In addition to the regular @code{@@example} and @code{@@lisp} commands, -Texinfo has two other ``example-style'' commands. These are the -@code{@@smallexample} and @code{@@smalllisp} commands. Both these -commands are designed for use with the @code{@@smallbook} command that -causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format.@refill - -In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands -typeset text in a smaller font for the smaller @code{@@smallbook} -format than for the 8.5 by 11 inch format. Consequently, many examples -containing long lines fit in a narrower, @code{@@smallbook} page -without needing to be shortened. Both commands typeset in the normal -font size when you format for the 8.5 by 11 inch size; indeed, -in this situation, the @code{@@smallexample} and @code{@@smalllisp} -commands are defined to be the @code{@@example} and @code{@@lisp} -commands.@refill - -In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are -equivalent to the @code{@@example} and @code{@@lisp} commands, and work -exactly the same.@refill - -Mark the end of @code{@@smallexample} or @code{@@smalllisp} with -@code{@@end smallexample} or @code{@@end smalllisp}, -respectively.@refill - -@iftex -Here is an example written in the small font used by the -@code{@@smallexample} and @code{@@smalllisp} commands: - -@ifclear smallbook -@display -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3\baselineskip -{\ninett -\dots{} to make sure that you have the freedom to -distribute copies of free software (and charge for -this service if you wish), that you receive source -code or can get it if you want it, that you can -change the software or use pieces of it in new free -programs; and that you know you can do these things.} -@end tex -@end display -@end ifclear -@end iftex -@ifset smallbook -@iftex -@smallexample -This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. -@end smallexample -@end iftex -@end ifset -@ifinfo -@smallexample -This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. -@end smallexample -@end ifinfo - -The @code{@@smallexample} and @code{@@smalllisp} commands make it -easier to prepare smaller format manuals without forcing you to edit -examples by hand to fit them onto narrower pages.@refill - -As a general rule, a printed document looks better if you write all the -examples in a chapter consistently in @code{@@example} or in -@code{@@smallexample}. Only occasionally should you mix the two -formats.@refill - -@xref{smallbook, , Printing ``Small'' Books}, for more information -about the @code{@@smallbook} command.@refill - -@node display, format, smallexample & smalllisp, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@display} -@cindex Display formatting -@findex display - -The @code{@@display} command begins a kind of example. It is like the -@code{@@example} command -except that, in -a printed manual, @code{@@display} does not select the fixed-width -font. In fact, it does not specify the font at all, so that the text -appears in the same font it would have appeared in without the -@code{@@display} command.@refill - -@display -This is an example of text written between an @code{@@display} command -and an @code{@@end display} command. The @code{@@display} command -indents the text, but does not fill it. -@end display - -@node format, exdent, display, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@format} -@findex format - -The @code{@@format} command is similar to @code{@@example} except -that, in the printed manual, @code{@@format} does not select the -fixed-width font and does not narrow the margins.@refill - -@format -This is an example of text written between an @code{@@format} command -and an @code{@@end format} command. As you can see -from this example, -the @code{@@format} command does not fill the text. -@end format - -@node exdent, flushleft & flushright, format, Quotations and Examples -@section @code{@@exdent}: Undoing a Line's Indentation -@cindex Indentation undoing -@findex exdent - -The @code{@@exdent} command removes any indentation a line might have. -The command is written at the beginning of a line and applies only to -the text that follows the command that is on the same line. Do not use -braces around the text. In a printed manual, the text on an -@code{@@exdent} line is printed in the roman font.@refill - -@code{@@exdent} is usually used within examples. Thus,@refill - -@example -@group -@@example -This line follows an @@@@example command. -@@exdent This line is exdented. -This line follows the exdented line. -The @@@@end example comes on the next line. -@@end group -@end group -@end example - -@noindent -produces - -@example -@group -This line follows an @@example command. -@exdent This line is exdented. -This line follows the exdented line. -The @@end example comes on the next line. -@end group -@end example - -In practice, the @code{@@exdent} command is rarely used. -Usually, you un-indent text by ending the example and -returning the page to its normal width.@refill - -@node flushleft & flushright, cartouche, exdent, Quotations and Examples -@section @code{@@flushleft} and @code{@@flushright} -@findex flushleft -@findex flushright - -The @code{@@flushleft} and @code{@@flushright} commands line up the -ends of lines on the left and right margins of a page, -but do not fill the text. The commands are written on lines of their -own, without braces. The @code{@@flushleft} and @code{@@flushright} -commands are ended by @code{@@end flushleft} and @code{@@end -flushright} commands on lines of their own.@refill - -@need 1500 -For example, - -@example -@group -@@flushleft -This text is -written flushleft. -@@end flushleft -@end group -@end example - -@noindent -produces - -@quotation -@flushleft -This text is -written flushleft. -@end flushleft -@end quotation - - -@code{@@flushright} produces the type of indentation often used in the -return address of letters. For example, - -@example -@group -@@flushright -Here is an example of text written -flushright. The @@code@{@@flushright@} command -right justifies every line but leaves the -left end ragged. -@@end flushright -@end group -@end example - -@noindent -produces - -@flushright -Here is an example of text written -flushright. The @code{@@flushright} command -right justifies every line but leaves the -left end ragged. -@end flushright - -@node cartouche, , flushleft & flushright, Quotations and Examples -@section Drawing Cartouches Around Examples -@findex cartouche -@cindex Box with rounded corners - -In a printed manual, the @code{@@cartouche} command draws a box with -rounded corners around its contents. You can use this command to -further highlight an example or quotation. For instance, you could -write a manual in which one type of example is surrounded by a cartouche -for emphasis.@refill - -The @code{@@cartouche} command affects only the printed manual; it has -no effect in the Info file.@refill - -@need 1500 -For example, - -@example -@group -@@example -@@cartouche -% pwd -/usr/local/share/emacs -@@end cartouche -@@end example -@end group -@end example - -@noindent -surrounds the two-line example with a box with rounded corners, in the -printed manual. - -@iftex -In a printed manual, the example looks like this:@refill - -@example -@group -@cartouche -% pwd -/usr/local/lib/emacs/info -@end cartouche -@end group -@end example -@end iftex - - -@node Lists and Tables, Indices, Quotations and Examples, Top -@chapter Lists and Tables -@cindex Making lists and tables -@cindex Lists and tables, making -@cindex Tables and lists, making - -Texinfo has several ways of making lists and tables. Lists can be -bulleted or numbered; two-column tables can highlight the items in -the first column; multi-column tables are also supported. - -@menu -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. -@end menu - -@ifinfo -@node Introducing Lists, itemize, Lists and Tables, Lists and Tables -@heading Introducing Lists -@end ifinfo - -Texinfo automatically indents the text in lists or tables, and numbers -an enumerated list. This last feature is useful if you modify the -list, since you do not need to renumber it yourself.@refill - -Numbered lists and tables begin with the appropriate @@-command at the -beginning of a line, and end with the corresponding @code{@@end} -command on a line by itself. The table and itemized-list commands -also require that you write formatting information on the same line as -the beginning @@-command.@refill - -Begin an enumerated list, for example, with an @code{@@enumerate} -command and end the list with an @code{@@end enumerate} command. -Begin an itemized list with an @code{@@itemize} command, followed on -the same line by a formatting command such as @code{@@bullet}, and end -the list with an @code{@@end itemize} command.@refill -@findex end - -Precede each element of a list with an @code{@@item} or @code{@@itemx} -command.@refill - -@sp 1 -@noindent -Here is an itemized list of the different kinds of table and lists:@refill - -@itemize @bullet -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end itemize - -@sp 1 -@noindent -Here is an enumerated list with the same items:@refill - -@enumerate -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end enumerate - -@sp 1 -@noindent -And here is a two-column table with the same items and their -@w{@@-commands}:@refill - -@table @code -@item @@itemize -Itemized lists with and without bullets. - -@item @@enumerate -Enumerated lists, using numbers or letters. - -@item @@table -@itemx @@ftable -@itemx @@vtable -Two-column tables with indexing. -@end table - -@node itemize, enumerate, Introducing Lists, Lists and Tables -@comment node-name, next, previous, up -@section Making an Itemized List -@cindex Itemization -@findex itemize - -The @code{@@itemize} command produces sequences of indented -paragraphs, with a bullet or other mark inside the left margin -at the beginning of each paragraph for which such a mark is desired.@refill - -Begin an itemized list by writing @code{@@itemize} at the beginning of -a line. Follow the command, on the same line, with a character or a -Texinfo command that generates a mark. Usually, you will write -@code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any character or any special symbol that results in -a single character in the Info file. (When you write @code{@@bullet} -or @code{@@minus} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.)@refill - -Write the text of the indented paragraphs themselves after the -@code{@@itemize}, up to another line that says @code{@@end -itemize}.@refill - -Before each paragraph for which a mark in the margin is desired, write -a line that says just @code{@@item}. Do not write any other text on this -line.@refill -@findex item - -Usually, you should put a blank line before an @code{@@item}. This -puts a blank line in the Info file. (@TeX{} inserts the proper -interline whitespace in either case.) Except when the entries are -very brief, these blank lines make the list look better.@refill - -Here is an example of the use of @code{@@itemize}, followed by the -output it produces. Note that @code{@@bullet} produces an @samp{*} in -Info and a round dot in @TeX{}.@refill - -@example -@group -@@itemize @@bullet -@@item -Some text for foo. - -@@item -Some text -for bar. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -Some text for foo. - -@item -Some text -for bar. -@end itemize -@end quotation - -Itemized lists may be embedded within other itemized lists. Here is a -list marked with dashes embedded in a list marked with bullets:@refill - -@example -@group -@@itemize @@bullet -@@item -First item. - -@@itemize @@minus -@@item -Inner item. - -@@item -Second inner item. -@@end itemize - -@@item -Second outer item. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -First item. - -@itemize @minus -@item -Inner item. - -@item -Second inner item. -@end itemize - -@item -Second outer item. -@end itemize -@end quotation - -@node enumerate, Two-column Tables, itemize, Lists and Tables -@comment node-name, next, previous, up -@section Making a Numbered or Lettered List -@cindex Enumeration -@findex enumerate - -@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,, -@code{@@itemize}}), except that the labels on the items are -successive integers or letters instead of bullets. - -Write the @code{@@enumerate} command at the beginning of a line. The -command does not require an argument, but accepts either a number or a -letter as an option. Without an argument, @code{@@enumerate} starts the -list with the number @samp{1}. With a numeric argument, such as -@samp{3}, the command starts the list with that number. With an upper -or lower case letter, such as @samp{a} or @samp{A}, the command starts -the list with that letter.@refill - -Write the text of the enumerated list in the same way you write an -itemized list: put @code{@@item} on a line of its own before the start -of each paragraph that you want enumerated. Do not write any other text -on the line beginning with @code{@@item}.@refill - -You should put a blank line between entries in the list. -This generally makes it easier to read the Info file.@refill - -@need 1500 -Here is an example of @code{@@enumerate} without an argument:@refill - -@example -@group -@@enumerate -@@item -Underlying causes. - -@@item -Proximate causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate -@item -Underlying causes. - -@item -Proximate causes. -@end enumerate -@sp 1 -Here is an example with an argument of @kbd{3}:@refill -@sp 1 -@example -@group -@@enumerate 3 -@@item -Predisposing causes. - -@@item -Precipitating causes. - -@@item -Perpetuating causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate 3 -@item -Predisposing causes. - -@item -Precipitating causes. - -@item -Perpetuating causes. -@end enumerate -@sp 1 -Here is a brief summary of the alternatives. The summary is constructed -using @code{@@enumerate} with an argument of @kbd{a}.@refill -@sp 1 -@enumerate a -@item -@code{@@enumerate} - -Without an argument, produce a numbered list, starting with the number -1.@refill - -@item -@code{@@enumerate @var{positive-integer}} - -With a (positive) numeric argument, start a numbered list with that -number. You can use this to continue a list that you interrupted with -other text.@refill - -@item -@code{@@enumerate @var{upper-case-letter}} - -With an upper case letter as argument, start a list -in which each item is marked -by a letter, beginning with that upper case letter.@refill - -@item -@code{@@enumerate @var{lower-case-letter}} - -With a lower case letter as argument, start a list -in which each item is marked by -a letter, beginning with that lower case letter.@refill -@end enumerate - -You can also nest enumerated lists, as in an outline.@refill - -@node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables -@section Making a Two-column Table -@cindex Tables, making two-column -@findex table - -@code{@@table} is similar to @code{@@itemize} (@pxref{itemize,, -@code{@@itemize}}), but allows you to specify a name or heading line for -each item. The @code{@@table} command is used to produce two-column -tables, and is especially useful for glossaries, explanatory -exhibits, and command-line option summaries. - -@menu -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. -@end menu - -@ifinfo -@node table, ftable vtable, Two-column Tables, Two-column Tables -@subheading Using the @code{@@table} Command - -Use the @code{@@table} command to produce two-column tables.@refill -@end ifinfo - -Write the @code{@@table} command at the beginning of a line and follow -it on the same line with an argument that is a Texinfo ``indicating'' -command such as @code{@@code}, @code{@@samp}, @code{@@var}, or -@code{@@kbd} (@pxref{Indicating}). Although these commands are usually -followed by arguments in braces, in this case you use the command name -without an argument because @code{@@item} will supply the argument. -This command will be applied to the text that goes into the first column -of each item and determines how it will be highlighted. For example, -@code{@@code} will cause the text in the first column to be highlighted -with an @code{@@code} command. (We recommend @code{@@code} for -@code{@@table}'s of command-line options.) - -@findex asis -You may also choose to use the @code{@@asis} command as an argument to -@code{@@table}. @code{@@asis} is a command that does nothing; if you -use this command after @code{@@table}, @TeX{} and the Info formatting -commands output the first column entries without added highlighting -(``as is'').@refill - -(The @code{@@table} command may work with other commands besides those -listed here. However, you can only use commands that normally take -arguments in braces.)@refill - -Begin each table entry with an @code{@@item} command at the beginning -of a line. Write the first column text on the same line as the -@code{@@item} command. Write the second column text on the line -following the @code{@@item} line and on subsequent lines. (You do not -need to type anything for an empty second column entry.) You may -write as many lines of supporting text as you wish, even several -paragraphs. But only text on the same line as the @code{@@item} will -be placed in the first column.@refill -@findex item - -Normally, you should put a blank line before an @code{@@item} line. -This puts a blank like in the Info file. Except when the entries are -very brief, a blank line looks better.@refill - -@need 1500 -The following table, for example, highlights the text in the first -column with an @code{@@samp} command:@refill - -@example -@group -@@table @@samp -@@item foo -This is the text for -@@samp@{foo@}. - -@@item bar -Text for @@samp@{bar@}. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @samp -@item foo -This is the text for -@samp{foo}. -@item bar -Text for @samp{bar}. -@end table - -If you want to list two or more named items with a single block of -text, use the @code{@@itemx} command. (@xref{itemx, , -@code{@@itemx}}.)@refill - -@node ftable vtable, itemx, table, Two-column Tables -@comment node-name, next, previous, up -@subsection @code{@@ftable} and @code{@@vtable} -@cindex Tables with indexes -@cindex Indexing table entries automatically -@findex ftable -@findex vtable - -The @code{@@ftable} and @code{@@vtable} commands are the same as the -@code{@@table} command except that @code{@@ftable} automatically enters -each of the items in the first column of the table into the index of -functions and @code{@@vtable} automatically enters each of the items in -the first column of the table into the index of variables. This -simplifies the task of creating indices. Only the items on the same -line as the @code{@@item} commands are indexed, and they are indexed in -exactly the form that they appear on that line. @xref{Indices, , -Creating Indices}, for more information about indices.@refill - -Begin a two-column table using @code{@@ftable} or @code{@@vtable} by -writing the @@-command at the beginning of a line, followed on the same -line by an argument that is a Texinfo command such as @code{@@code}, -exactly as you would for an @code{@@table} command; and end the table -with an @code{@@end ftable} or @code{@@end vtable} command on a line by -itself. - -See the example for @code{@@table} in the previous section. - -@node itemx, , ftable vtable, Two-column Tables -@comment node-name, next, previous, up -@subsection @code{@@itemx} -@cindex Two named items for @code{@@table} -@findex itemx - -Use the @code{@@itemx} command inside a table when you have two or more -first column entries for the same item, each of which should appear on a -line of its own. Use @code{@@itemx} for all but the first entry; -@code{@@itemx} should always follow an @code{@@item} command. The -@code{@@itemx} command works exactly like @code{@@item} except that it -does not generate extra vertical space above the first column text. - -@need 1000 -For example, - -@example -@group -@@table @@code -@@item upcase -@@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding upper case (lower -case) character or string. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @code -@item upcase -@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding upper case (lower -case) character or string.@refill -@end table - -@noindent -(Note also that this example illustrates multi-line supporting text in -a two-column table.)@refill - - -@node Multi-column Tables, , Two-column Tables, Lists and Tables -@section Multi-column Tables -@cindex Tables, making multi-column -@findex multitable - -@code{@@multitable} allows you to construct tables with any number of -columns, with each column having any width you like. - -You define the column widths on the @code{@@multitable} line itself, and -write each row of the actual table following an @code{@@item} command, -with columns separated by an @code{@@tab} command. Finally, @code{@@end -multitable} completes the table. Details in the sections below. - -@menu -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. -@end menu - -@node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables -@subsection Multitable Column Widths -@cindex Multitable column widths -@cindex Column widths, defining for multitables -@cindex Widths, defining multitable column - -You can define the column widths for a multitable in two ways: as -fractions of the line length; or with a prototype row. Mixing the two -methods is not supported. In either case, the widths are defined -entirely on the same line as the @code{@@multitable} command. - -@enumerate -@item -@findex columnfractions -@cindex Line length, column widths as fraction of -To specify column widths as fractions of the line length, write -@code{@@columnfractions} and the decimal numbers (presumably less than -1) after the @code{@@multitable} command, as in: - -@example -@@multitable @@columnfractions .33 .33 .33 -@end example - -@noindent The fractions need not add up exactly to 1.0, as these do -not. This allows you to produce tables that do not need the full line -length. - -@item -@cindex Prototype row, column widths defined by -To specify a prototype row, write the longest entry for each column -enclosed in braces after the @code{@@multitable} command. For example: - -@example -@@multitable @{some text for column one@} @{for column two@} -@end example - -@noindent -The first column will then have the width of the typeset `some text for -column one', and the second column the width of `for column two'. - -The prototype entries need not appear in the table itself. - -Although we used simple text in this example, the prototype entries can -contain Texinfo commands; markup commands such as @code{@@code} are -particularly likely to be useful. - -@end enumerate - - -@node Multitable Rows, , Multitable Column Widths, Multi-column Tables -@subsection Multitable Rows -@cindex Multitable rows -@cindex Rows, of a multitable - -@findex item -@cindex tab -After the @code{@@multitable} command defining the column widths (see -the previous section), you begin each row in the body of a multitable -with @code{@@item}, and separate the column entries with @code{@@tab}. -Line breaks are not special within the table body, and you may break -input lines in your source file as necessary. - -Here is a complete example of a multi-column table (the text is from -@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, -emacs, The GNU Emacs Manual}): - -@example -@@multitable @@columnfractions .15 .45 .4 -@@item Key @@tab Command @@tab Description -@@item C-x 2 -@@tab @@code@{split-window-vertically@} -@@tab Split the selected window into two windows, -with one above the other. -@@item C-x 3 -@@tab @@code@{split-window-horizontally@} -@@tab Split the selected window into two windows -positioned side by side. -@@item C-Mouse-2 -@@tab -@@tab In the mode line or scroll bar of a window, -split that window. -@@end multitable -@end example - -@noindent produces: - -@multitable @columnfractions .15 .45 .4 -@item Key @tab Command @tab Description -@item C-x 2 -@tab @code{split-window-vertically} -@tab Split the selected window into two windows, -with one above the other. -@item C-x 3 -@tab @code{split-window-horizontally} -@tab Split the selected window into two windows -positioned side by side. -@item C-Mouse-2 -@tab -@tab In the mode line or scroll bar of a window, -split that window. -@end multitable - - -@node Indices, Insertions, Lists and Tables, Top -@comment node-name, next, previous, up -@chapter Creating Indices -@cindex Indices -@cindex Creating indices - -Using Texinfo, you can generate indices without having to sort and -collate entries manually. In an index, the entries are listed in -alphabetical order, together with information on how to find the -discussion of each entry. In a printed manual, this information -consists of page numbers. In an Info file, this information is a menu -entry leading to the first node referenced.@refill - -Texinfo provides several predefined kinds of index: an index -for functions, an index for variables, an index for concepts, and so -on. You can combine indices or use them for other than their -canonical purpose. If you wish, you can define your own indices.@refill - -@menu -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. -@end menu - -@node Index Entries, Predefined Indices, Indices, Indices -@comment node-name, next, previous, up -@section Making Index Entries -@cindex Index entries, making -@cindex Entries, making index - -When you are making index entries, it is good practice to think of the -different ways people may look for something. Different people -@emph{do not} think of the same words when they look something up. A -helpful index will have items indexed under all the different words -that people may use. For example, one reader may think it obvious that -the two-letter names for indices should be listed under ``Indices, -two-letter names'', since the word ``Index'' is the general concept. -But another reader may remember the specific concept of two-letter -names and search for the entry listed as ``Two letter names for -indices''. A good index will have both entries and will help both -readers.@refill - -Like typesetting, the construction of an index is a highly skilled, -professional art, the subtleties of which are not appreciated until you -need to do it yourself.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - -@node Predefined Indices, Indexing Commands, Index Entries, Indices -@comment node-name, next, previous, up -@section Predefined Indices - -Texinfo provides six predefined indices:@refill - -@itemize @bullet -@item -A @dfn{concept index} listing concepts that are discussed.@refill - -@item -A @dfn{function index} listing functions (such as entry points of -libraries).@refill - -@item -A @dfn{variables index} listing variables (such as global variables -of libraries).@refill - -@item -A @dfn{keystroke index} listing keyboard commands.@refill - -@item -A @dfn{program index} listing names of programs.@refill - -@item -A @dfn{data type index} listing data types (such as structures defined in -header files).@refill -@end itemize - -@noindent -Not every manual needs all of these, and most manuals use two or three -of them. This manual has two indices: a -concept index and an @@-command index (that is actually the function -index but is called a command index in the chapter heading). Two or -more indices can be combined into one using the @code{@@synindex} or -@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill - -@node Indexing Commands, Combining Indices, Predefined Indices, Indices -@comment node-name, next, previous, up -@section Defining the Entries of an Index -@cindex Defining indexing entries -@cindex Index entries -@cindex Entries for an index -@cindex Specifying index entries -@cindex Creating index entries - -The data to make an index come from many individual indexing commands -scattered throughout the Texinfo source file. Each command says to add -one entry to a particular index; after formatting, the index will give -the current page number or node name as the reference.@refill - -An index entry consists of an indexing command at the beginning of a -line followed, on the rest of the line, by the entry.@refill - -For example, this section begins with the following five entries for -the concept index:@refill - -@example -@@cindex Defining indexing entries -@@cindex Index entries -@@cindex Entries for an index -@@cindex Specifying index entries -@@cindex Creating index entries -@end example - -Each predefined index has its own indexing command---@code{@@cindex} -for the concept index, @code{@@findex} for the function index, and so -on.@refill - -@cindex Writing index entries -@cindex Index entry writing -Concept index entries consist of text. The best way to write an index -is to choose entries that are terse yet clear. If you can do this, -the index often looks better if the entries are not capitalized, but -written just as they would appear in the middle of a sentence. -(Capitalize proper names and acronyms that always call for upper case -letters.) This is the case convention we use in most GNU manuals' -indices. - -If you don't see how to make an entry terse yet clear, make it longer -and clear---not terse and confusing. If many of the entries are several -words long, the index may look better if you use a different convention: -to capitalize the first word of each entry. But do not capitalize a -case-sensitive name such as a C or Lisp function name or a shell -command; that would be a spelling error. - -Whichever case convention you use, please use it consistently! - -@ignore -Concept index entries consist of English text. The usual convention -is to capitalize the first word of each such index entry, unless that -word is the name of a function, variable, or other such entity that -should not be capitalized. However, if your concept index entries are -consistently short (one or two words each) it may look better for each -regular entry to start with a lower case letter, aside from proper -names and acronyms that always call for upper case letters. Whichever -convention you adapt, please be consistent! -@end ignore - -Entries in indices other than the concept index are symbol names in -programming languages, or program names; these names are usually -case-sensitive, so use upper and lower case as required for them. - -By default, entries for a concept index are printed in a small roman -font and entries for the other indices are printed in a small -@code{@@code} font. You may change the way part of an entry is -printed with the usual Texinfo commands, such as @code{@@file} for -file names and @code{@@emph} for emphasis (@pxref{Marking -Text}).@refill -@cindex Index font types - -@cindex Predefined indexing commands -@cindex Indexing commands, predefined -The six indexing commands for predefined indices are: - -@table @code -@item @@cindex @var{concept} -@findex cindex -Make an entry in the concept index for @var{concept}.@refill - -@item @@findex @var{function} -@findex findex -Make an entry in the function index for @var{function}.@refill - -@item @@vindex @var{variable} -@findex vindex -Make an entry in the variable index for @var{variable}.@refill - -@item @@kindex @var{keystroke} -@findex kindex -Make an entry in the key index for @var{keystroke}.@refill - -@item @@pindex @var{program} -@findex pindex -Make an entry in the program index for @var{program}.@refill - -@item @@tindex @var{data type} -@findex tindex -Make an entry in the data type index for @var{data type}.@refill -@end table - -@quotation -@strong{Caution:} Do not use a colon in an index entry. In Info, a -colon separates the menu entry name from the node name. An extra -colon confuses Info. -@xref{Menu Parts, , The Parts of a Menu}, -for more information about the structure of a menu entry.@refill -@end quotation - -If you write several identical index entries in different places in a -Texinfo file, the index in the printed manual will list all the pages to -which those entries refer. However, the index in the Info file will -list @strong{only} the node that references the @strong{first} of those -index entries. Therefore, it is best to write indices in which each -entry refers to only one place in the Texinfo file. Fortunately, this -constraint is a feature rather than a loss since it means that the index -will be easy to use. Otherwise, you could create an index that lists -several pages for one entry and your reader would not know to which page -to turn. If you have two identical entries for one topic, change the -topics slightly, or qualify them to indicate the difference.@refill - -You are not actually required to use the predefined indices for their -canonical purposes. For example, suppose you wish to index some C -preprocessor macros. You could put them in the function index along -with actual functions, just by writing @code{@@findex} commands for -them; then, when you print the ``Function Index'' as an unnumbered -chapter, you could give it the title `Function and Macro Index' and -all will be consistent for the reader. Or you could put the macros in -with the data types by writing @code{@@tindex} commands for them, and -give that index a suitable title so the reader will understand. -(@xref{Printing Indices & Menus}.)@refill - -@node Combining Indices, New Indices, Indexing Commands, Indices -@comment node-name, next, previous, up -@section Combining Indices -@cindex Combining indices -@cindex Indices, combining them - -Sometimes you will want to combine two disparate indices such as functions -and concepts, perhaps because you have few enough of one of them that -a separate index for them would look silly.@refill - -You could put functions into the concept index by writing -@code{@@cindex} commands for them instead of @code{@@findex} commands, -and produce a consistent manual by printing the concept index with the -title `Function and Concept Index' and not printing the `Function -Index' at all; but this is not a robust procedure. It works only if -your document is never included as part of another -document that is designed to have a separate function index; if your -document were to be included with such a document, the functions from -your document and those from the other would not end up together. -Also, to make your function names appear in the right font in the -concept index, you would need to enclose every one of them between -the braces of @code{@@code}.@refill - -@menu -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. -@end menu - -@node syncodeindex, synindex, Combining Indices, Combining Indices -@subsection @code{@@syncodeindex} -@findex syncodeindex - -When you want to combine functions and concepts into one index, you -should index the functions with @code{@@findex} and index the concepts -with @code{@@cindex}, and use the @code{@@syncodeindex} command to -redirect the function index entries into the concept index.@refill -@findex syncodeindex - -The @code{@@syncodeindex} command takes two arguments; they are the name -of the index to redirect, and the name of the index to redirect it to. -The template looks like this:@refill - -@example -@@syncodeindex @var{from} @var{to} -@end example - -@cindex Predefined names for indices -@cindex Two letter names for indices -@cindex Indices, two letter names -@cindex Names for indices -For this purpose, the indices are given two-letter names:@refill - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table - -Write an @code{@@syncodeindex} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. For example, -to merge a function index with a concept index, write the -following:@refill - -@example -@@syncodeindex fn cp -@end example - -@noindent -This will cause all entries designated for the function index to merge -in with the concept index instead.@refill - -To merge both a variables index and a function index into a concept -index, write the following:@refill - -@example -@group -@@syncodeindex vr cp -@@syncodeindex fn cp -@end group -@end example - -@cindex Fonts for indices -The @code{@@syncodeindex} command puts all the entries from the `from' -index (the redirected index) into the @code{@@code} font, overriding -whatever default font is used by the index to which the entries are -now directed. This way, if you direct function names from a function -index into a concept index, all the function names are printed in the -@code{@@code} font as you would expect.@refill - -@node synindex, , syncodeindex, Combining Indices -@subsection @code{@@synindex} -@findex synindex - -The @code{@@synindex} command is nearly the same as the -@code{@@syncodeindex} command, except that it does not put the -`from' index entries into the @code{@@code} font; rather it puts -them in the roman font. Thus, you use @code{@@synindex} when you -merge a concept index into a function index.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - -@node New Indices, , Combining Indices, Indices -@section Defining New Indices -@cindex Defining new indices -@cindex Indices, defining new -@cindex New index defining -@findex defindex -@findex defcodeindex - -In addition to the predefined indices, you may use the -@code{@@defindex} and @code{@@defcodeindex} commands to define new -indices. These commands create new indexing @@-commands with which -you mark index entries. The @code{@@defindex }command is used like -this:@refill - -@example -@@defindex @var{name} -@end example - -The name of an index should be a two letter word, such as @samp{au}. -For example:@refill - -@example -@@defindex au -@end example - -This defines a new index, called the @samp{au} index. At the same -time, it creates a new indexing command, @code{@@auindex}, that you -can use to make index entries. Use the new indexing command just as -you would use a predefined indexing command.@refill - -For example, here is a section heading followed by a concept index -entry and two @samp{au} index entries.@refill - -@example -@@section Cognitive Semantics -@@cindex kinesthetic image schemas -@@auindex Johnson, Mark -@@auindex Lakoff, George -@end example - -@noindent -(Evidently, @samp{au} serves here as an abbreviation for ``author''.) -Texinfo constructs the new indexing command by concatenating the name -of the index with @samp{index}; thus, defining an @samp{au} index -leads to the automatic creation of an @code{@@auindex} command.@refill - -Use the @code{@@printindex} command to print the index, as you do with -the predefined indices. For example:@refill - -@example -@group -@@node Author Index, Subject Index, , Top -@@unnumbered Author Index - -@@printindex au -@end group -@end example - -The @code{@@defcodeindex} is like the @code{@@defindex} command, except -that, in the printed output, it prints entries in an @code{@@code} font -instead of a roman font. Thus, it parallels the @code{@@findex} command -rather than the @code{@@cindex} command.@refill - -You should define new indices within or right after the end-of-header -line of a Texinfo file, before any @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Header}).@refill - -@node Insertions, Breaks, Indices, Top -@comment node-name, next, previous, up -@chapter Special Insertions -@cindex Inserting special characters and symbols -@cindex Special insertions - -Texinfo provides several commands for inserting characters that have -special meaning in Texinfo, such as braces, and for other graphic -elements that do not correspond to simple characters you can type. - -@iftex -These are: - -@itemize @bullet -@item Braces, @samp{@@} and periods. -@item Whitespace within and around a sentence. -@item Accents. -@item Dots and bullets. -@item The @TeX{} logo and the copyright symbol. -@item Mathematical expressions. -@end itemize -@end iftex - -@menu -* Braces Atsigns:: How to insert braces, @samp{@@}. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* pounds:: How to insert the pounds currency symbol. -* minus:: How to insert a minus sign. -* math:: How to format a mathematical expression. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -* Images:: How to include graphics. -@end menu - - -@node Braces Atsigns, Inserting Space, Insertions, Insertions -@section Inserting @@ and Braces -@cindex Inserting @@, braces -@cindex Braces, inserting -@cindex Special characters, commands to insert -@cindex Commands to insert special characters - -@samp{@@} and curly braces are special characters in Texinfo. To insert -these characters so they appear in text, you must put an @samp{@@} in -front of these characters to prevent Texinfo from misinterpreting -them. - -Do not put braces after any of these commands; they are not -necessary. - -@menu -* Inserting An Atsign:: How to insert @samp{@@}. -* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. -@end menu - -@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns -@subsection Inserting @samp{@@} with @@@@ -@findex @@ @r{(single @samp{@@})} - -@code{@@@@} stands for a single @samp{@@} in either printed or Info -output. - -Do not put braces after an @code{@@@@} command. - -@node Inserting Braces, , Inserting An Atsign, Braces Atsigns -@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} -@findex @{ @r{(single @samp{@{})} -@findex @} @r{(single @samp{@}})} - -@code{@@@{} stands for a single @samp{@{} in either printed or Info -output. - -@code{@@@}} stands for a single @samp{@}} in either printed or Info -output. - -Do not put braces after either an @code{@@@{} or an @code{@@@}} -command. - - -@node Inserting Space, Inserting Accents, Braces Atsigns, Insertions -@section Inserting Space - -@cindex Inserting space -@cindex Spacing, inserting -@cindex Whitespace, inserting -The following sections describe commands that control spacing of various -kinds within and after sentences. - -@menu -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* dmn:: How to format a dimension. -@end menu - -@node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space -@subsection Not Ending a Sentence - -@cindex Not ending a sentence -@cindex Sentence non-ending punctuation -@cindex Periods, inserting -Depending on whether a period or exclamation point or question mark is -inside or at the end of a sentence, less or more space is inserted after -a period in a typeset manual. Since it is not always possible for -Texinfo to determine when a period ends a sentence and when it is used -in an abbreviation, special commands are needed in some circumstances. -(Usually, Texinfo can guess how to handle periods, so you do not need to -use the special commands; you just enter a period as you would if you -were using a typewriter, which means you put two spaces after the -period, question mark, or exclamation mark that ends a sentence.) - -@findex : @r{(suppress widening)} -Use the @code{@@:}@: command after a period, question mark, -exclamation mark, or colon that should not be followed by extra space. -For example, use @code{@@:}@: after periods that end abbreviations -which are not at the ends of sentences. - -@need 700 -For example, - -@example -The s.o.p.@@: has three parts @dots{} -The s.o.p. has three parts @dots{} -@end example - -@noindent -@ifinfo -produces -@end ifinfo -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after @samp{s.o.p.} in the second -line.@refill -@end iftex - -@quotation -The s.o.p.@: has three parts @dots{}@* -The s.o.p. has three parts @dots{} -@end quotation - -@noindent -(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating -Procedure''.) - -@code{@@:} has no effect on the Info output. Do not put braces after -@code{@@:}. - - -@node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space -@subsection Ending a Sentence - -@cindex Ending a Sentence -@cindex Sentence ending punctuation - -@findex . @r{(end of sentence)} -@findex ! @r{(end of sentence)} -@findex ? @r{(end of sentence)} -Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an -exclamation point, and @code{@@?}@: instead of a question mark at the end -of a sentence that ends with a single capital letter. Otherwise, @TeX{} -will think the letter is an abbreviation and will not insert the correct -end-of-sentence spacing. Here is an example: - -@example -Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end example - -@noindent -@ifinfo -produces -@end ifinfo -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after the @samp{W} in the first -line. -@end iftex - -@quotation -Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end quotation - -In the Info file output, @code{@@.}@: is equivalent to a simple -@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. - -The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to -work well with the Emacs sentence motion commands (@pxref{Sentences,,, -emacs, The GNU Emacs Manual}). This made it necessary for them to be -incompatible with some other formatting systems that use @@-commands. - -Do not put braces after any of these commands. - - -@node Multiple Spaces, dmn, Ending a Sentence, Inserting Space -@subsection Multiple Spaces - -@cindex Multiple spaces -@cindex Whitespace, inserting -@findex (space) -@findex (tab) -@findex (newline) - -Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, -and newline) into a single space. Info output, on the other hand, -preserves whitespace as you type it, except for changing a newline into -a space; this is why it is important to put two spaces at the end of -sentences in Texinfo documents. - -Occasionally, you may want to actually insert several consecutive -spaces, either for purposes of example (what your program does with -multiple spaces as input), or merely for purposes of appearance in -headings or lists. Texinfo supports three commands: -@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of -which insert a single space into the output. (Here, -@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a -space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab -character and end-of-line, i.e., when @samp{@@} is the last character on -a line.) - -For example, -@example -Spacey@@ @@ @@ @@ -example. -@end example - -@noindent produces - -@example -Spacey@ @ @ @ -example. -@end example - -Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by -@code{@@multitable} (@pxref{Multi-column Tables}). - -Do not follow any of these commands with braces. - - -@node dmn, , Multiple Spaces, Inserting Space -@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension -@cindex Thin space between number, dimension -@cindex Dimension formatting -@cindex Format a dimension -@findex dmn - -At times, you may want to write @samp{12@dmn{pt}} or -@samp{8.5@dmn{in}} with little or no space between the number and the -abbreviation for the dimension. You can use the @code{@@dmn} command -to do this. On seeing the command, @TeX{} inserts just enough space -for proper typesetting; the Info formatting commands insert no space -at all, since the Info file does not require it.@refill - -To use the @code{@@dmn} command, write the number and then follow it -immediately, with no intervening space, by @code{@@dmn}, and then by -the dimension within braces. For example, - -@example -A4 paper is 8.27@@dmn@{in@} wide. -@end example - -@noindent -produces - -@quotation -A4 paper is 8.27@dmn{in} wide. -@end quotation - -Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}} -or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file. -In these cases, however, the formatters may insert a line break between -the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if -you write a period after an abbreviation within a sentence, you should -write @samp{@@:} after the period to prevent @TeX{} from inserting extra -whitespace, as shown here. @xref{Inserting Space}. - - -@node Inserting Accents, Dots Bullets, Inserting Space, Insertions -@section Inserting Accents - -@cindex Inserting accents -@cindex Accents, inserting -@cindex Floating accents, inserting - -Here is a table with the commands Texinfo provides for inserting -floating accents. The commands with non-alphabetic names do not take -braces around their argument (which is taken to be the next character). -(Exception: @code{@@,} @emph{does} take braces around its argument.) -This is so as to make the source as convenient to type and read as -possible, since accented characters are very common in some languages. - -@findex " -@cindex Umlaut accent -@findex ' -@cindex Acute accent -@findex = -@cindex Macron accent -@findex ^ -@cindex Circumflex accent -@findex ` -@cindex Grave accent -@findex ~ -@cindex Tilde accent -@findex , -@cindex Cedilla accent -@findex dotaccent -@cindex Dot accent -@findex H -@cindex Hungariam umlaut accent -@findex ringaccent -@cindex Ring accent -@findex tieaccent -@cindex Tie-after accent -@findex u -@cindex Breve accent -@findex ubaraccent -@cindex Underbar accent -@findex udotaccent -@cindex Underdot accent -@findex v -@cindex Check accent -@multitable {@@questiondown@{@}} {Output} {macron/overbar accent} -@item Command @tab Output @tab What -@item @t{@@"o} @tab @"o @tab umlaut accent -@item @t{@@'o} @tab @'o @tab acute accent -@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent -@item @t{@@=o} @tab @=o @tab macron/overbar accent -@item @t{@@^o} @tab @^o @tab circumflex accent -@item @t{@@`o} @tab @`o @tab grave accent -@item @t{@@~o} @tab @~o @tab tilde accent -@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent -@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut -@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent -@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent -@item @t{@@u@{o@}} @tab @u{o} @tab breve accent -@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent -@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent -@item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent -@end multitable - -This table lists the Texinfo commands for inserting other characters -commonly used in languages other than English. - -@findex questiondown -@cindex @questiondown{} -@findex exclamdown -@cindex @exclamdown{} -@findex aa -@cindex @aa{} -@findex AA -@cindex @AA{} -@findex ae -@cindex @ae{} -@findex AE -@cindex @AE{} -@findex dotless -@cindex @dotless{i} -@cindex @dotless{j} -@cindex Dotless i, j -@findex l -@cindex @l{} -@findex L -@cindex @L{} -@findex o -@cindex @o{} -@findex O -@cindex @O{} -@findex oe -@cindex @oe{} -@findex OE -@cindex @OE{} -@findex ss -@cindex @ss{} -@cindex Es-zet -@cindex Sharp S -@cindex German S -@multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S} -@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! -@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? -@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle -@item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures -@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i -@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j -@item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l -@item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash -@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures -@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S -@end multitable - - -@node Dots Bullets, TeX and copyright, Inserting Accents, Insertions -@section Inserting Ellipsis, Dots, and Bullets -@cindex Dots, inserting -@cindex Bullets, inserting -@cindex Ellipsis, inserting -@cindex Inserting ellipsis -@cindex Inserting dots -@cindex Special typesetting commands -@cindex Typesetting commands for dots, etc. - -An @dfn{ellipsis} (a line of dots) is not typeset as a string of -periods, so a special command is used for ellipsis in Texinfo. The -@code{@@bullet} command is special, too. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. (You need to use braces -with these commands because you can use them next to other text; without -the braces, the formatters would be confused. @xref{Command Syntax, , -@@-Command Syntax}, for further information.)@refill - -@menu -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. -@end menu - - -@node dots, bullet, Dots Bullets, Dots Bullets -@subsection @code{@@dots}@{@} (@dots{}) -@findex dots -@cindex Inserting dots -@cindex Dots, inserting - -Use the @code{@@dots@{@}} command to generate an ellipsis, which is -three dots in a row, appropriately spaced, like this: `@dots{}'. Do -not simply write three periods in the input file; that would work for -the Info file output, but would produce the wrong amount of space -between the periods in the printed manual. - -Similarly, the @code{@@enddots@{@}} command generates an -end-of-sentence ellipsis (four dots) @enddots{} - -@iftex -Here is an ellipsis: @dots{} -Here are three periods in a row: ... - -In printed output, the three periods in a row are closer together than -the dots in the ellipsis. -@end iftex - - -@node bullet, , dots, Dots Bullets -@subsection @code{@@bullet}@{@} (@bullet{}) -@findex bullet - -Use the @code{@@bullet@{@}} command to generate a large round dot, or -the closest possible thing to one. In Info, an asterisk is used.@refill - -Here is a bullet: @bullet{} - -When you use @code{@@bullet} in @code{@@itemize}, you do not need to -type the braces, because @code{@@itemize} supplies them. -(@xref{itemize, , @code{@@itemize}}.)@refill - - -@node TeX and copyright, pounds, Dots Bullets, Insertions -@section Inserting @TeX{} and the Copyright Symbol - -The logo `@TeX{}' is typeset in a special fashion and it needs an -@@-command. The copyright symbol, `@copyright{}', is also special. -Each of these commands is followed by a pair of braces, @samp{@{@}}, -without any whitespace between the name of the command and the -braces.@refill - -@menu -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright}@{@}. -@end menu - - -@node tex, copyright symbol, TeX and copyright, TeX and copyright -@subsection @code{@@TeX}@{@} (@TeX{}) -@findex tex (command) - -Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed -manual, this is a special logo that is different from three ordinary -letters. In Info, it just looks like @samp{TeX}. The -@code{@@TeX@{@}} command is unique among Texinfo commands in that the -@kbd{T} and the @kbd{X} are in upper case.@refill - - -@node copyright symbol, , tex, TeX and copyright -@subsection @code{@@copyright}@{@} (@copyright{}) -@findex copyright - -Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In -a printed manual, this is a @samp{c} inside a circle, and in Info, -this is @samp{(C)}.@refill - - -@node pounds, minus, TeX and copyright, Insertions -@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling -@findex pounds - -Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a -printed manual, this is the symbol for the currency pounds sterling. -In Info, it is a @samp{#}. Other currency symbols are unfortunately not -available. - - -@node minus, math, pounds, Insertions -@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign -@findex minus - -Use the @code{@@minus@{@}} command to generate a minus sign. In a -fixed-width font, this is a single hyphen, but in a proportional font, -the symbol is the customary length for a minus sign---a little longer -than a hyphen, shorter than an em-dash: - -@display -@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, - -`-' is a hyphen generated with the character @samp{-}, - -`---' is an em-dash for text. -@end display - -@noindent -In the fixed-width font used by Info, @code{@@minus@{@}} is the same -as a hyphen. - -You should not use @code{@@minus@{@}} inside @code{@@code} or -@code{@@example} because the width distinction is not made in the -fixed-width font they use. - -When you use @code{@@minus} to specify the mark beginning each entry in -an itemized list, you do not need to type the braces -(@pxref{itemize, , @code{@@itemize}}.) - - -@node math, Glyphs, minus, Insertions -@section @code{@@math}: Inserting Mathematical Expressions -@findex math -@cindex Mathematical expressions - -You can write a short mathematical expression with the @code{@@math} -command. Write the mathematical expression between braces, like this: - -@example -@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} -@end example - -@iftex -@need 1000 -@noindent -This produces the following in @TeX{}: - -@display -@math{(a + b)(a + b) = a^2 + 2ab + b^2} -@end display - -@noindent -and the following in Info: -@end iftex -@ifinfo -@noindent -This produces the following in Info: -@end ifinfo - -@example -(a + b)(a + b) = a^2 + 2ab + b^2 -@end example - -Thus, the @code{@@math} command has no effect on the Info output. - -For complex mathematical expressions, you can also use @TeX{} directly -(@pxref{Raw Formatter Commands}). When you use @TeX{} directly, -remember to write the mathematical expression between one or two -@samp{$} (dollar-signs) as appropriate. - - -@node Glyphs, Images, math, Insertions -@section Glyphs for Examples -@cindex Glyphs - -In Texinfo, code is often illustrated in examples that are delimited -by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and -@code{@@end lisp}. In such examples, you can indicate the results of -evaluation or an expansion using @samp{@result{}} or -@samp{@expansion{}}. Likewise, there are commands to insert glyphs -to indicate -printed output, error messages, equivalence of expressions, and the -location of point.@refill - -The glyph-insertion commands do not need to be used within an example, but -most often they are. Every glyph-insertion command is followed by a pair of -left- and right-hand braces.@refill - -@menu -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. -@end menu - -@node Glyphs Summary, result, Glyphs, Glyphs -@ifinfo -@subheading Glyphs Summary - -Here are the different glyph commands:@refill -@end ifinfo - -@table @asis -@item @result{} -@code{@@result@{@}} points to the result of an expression.@refill - -@item @expansion{} -@code{@@expansion@{@}} shows the results of a macro expansion.@refill - -@item @print{} -@code{@@print@{@}} indicates printed output.@refill - -@item @error{} -@code{@@error@{@}} indicates that the following text is an error -message.@refill - -@item @equiv{} -@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill - -@item @point{} -@code{@@point@{@}} shows the location of point.@refill -@end table - - -@menu -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: -@end menu - -@node result, expansion, Glyphs Summary, Glyphs -@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation -@cindex Result of an expression -@cindex Indicating evaluation -@cindex Evaluation glyph -@cindex Value of an expression, indicating - -Use the @code{@@result@{@}} command to indicate the result of -evaluating an expression.@refill - -@iftex -The @code{@@result@{@}} command is displayed as @samp{=>} in Info and -as @samp{@result{}} in the printed output. -@end iftex -@ifinfo -The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info -and as a double stemmed arrow in the printed output.@refill -@end ifinfo - -Thus, the following, - -@lisp -(cdr '(1 2 3)) - @result{} (2 3) -@end lisp - -@noindent -may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. - - -@node expansion, Print Glyph, result, Glyphs -@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion -@cindex Expansion, indicating it - -When an expression is a macro call, it expands into a new expression. -You can indicate the result of the expansion with the -@code{@@expansion@{@}} command.@refill - -@iftex -The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and -as @samp{@expansion{}} in the printed output. -@end iftex -@ifinfo -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in Info and as a long arrow with a flat base in the printed output.@refill -@end ifinfo - -@need 700 -For example, the following - -@example -@group -@@lisp -(third '(a b c)) - @@expansion@{@} (car (cdr (cdr '(a b c)))) - @@result@{@} c -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -@group -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end group -@end lisp - -@noindent -which may be read as: - -@quotation -@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; -the result of evaluating the expression is @code{c}. -@end quotation - -@noindent -Often, as in this case, an example looks better if the -@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented -five spaces.@refill - - -@node Print Glyph, Error Glyph, expansion, Glyphs -@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output -@cindex Printed output, indicating it - -Sometimes an expression will print output during its execution. You -can indicate the printed output with the @code{@@print@{@}} command.@refill - -@iftex -The @code{@@print@{@}} command is displayed as @samp{-|} in Info and -as @samp{@print{}} in the printed output. -@end iftex -@ifinfo -The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info -and similarly, as a horizontal dash butting against a vertical bar, in -the printed output.@refill -@end ifinfo - -In the following example, the printed text is indicated with -@samp{@print{}}, and the value of the expression follows on the -last line.@refill - -@lisp -@group -(progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end lisp - -@noindent -In a Texinfo source file, this example is written as follows: - -@lisp -@group -@@lisp -(progn (print 'foo) (print 'bar)) - @@print@{@} foo - @@print@{@} bar - @@result@{@} bar -@@end lisp -@end group -@end lisp - - -@node Error Glyph, Equivalence, Print Glyph, Glyphs -@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message -@cindex Error message, indicating it - -A piece of code may cause an error when you evaluate it. You can -designate the error message with the @code{@@error@{@}} command.@refill - -@iftex -The @code{@@error@{@}} command is displayed as @samp{error-->} in Info -and as @samp{@error{}} in the printed output. -@end iftex -@ifinfo -The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info -and as the word `error' in a box in the printed output.@refill -@end ifinfo - -@need 700 -Thus, - -@example -@@lisp -(+ 23 'x) -@@error@{@} Wrong type argument: integer-or-marker-p, x -@@end lisp -@end example - -@noindent -produces - -@lisp -(+ 23 'x) -@error{} Wrong type argument: integer-or-marker-p, x -@end lisp - -@noindent -This indicates that the following error message is printed -when you evaluate the expression: - -@lisp -Wrong type argument: integer-or-marker-p, x -@end lisp - -@samp{@error{}} itself is not part of the error message. - - -@node Equivalence, Point Glyph, Error Glyph, Glyphs -@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence -@cindex Equivalence, indicating it - -Sometimes two expressions produce identical results. You can indicate the -exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill - -@iftex -The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and -as @samp{@equiv{}} in the printed output. -@end iftex -@ifinfo -The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info -and as a three parallel horizontal lines in the printed output.@refill -@end ifinfo - -Thus, - -@example -@@lisp -(make-sparse-keymap) @@equiv@{@} (list 'keymap) -@@end lisp -@end example - -@noindent -produces - -@lisp -(make-sparse-keymap) @equiv{} (list 'keymap) -@end lisp - -@noindent -This indicates that evaluating @code{(make-sparse-keymap)} produces -identical results to evaluating @code{(list 'keymap)}. - - -@node Point Glyph, , Equivalence, Glyphs -@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer -@cindex Point, indicating it in a buffer - -Sometimes you need to show an example of text in an Emacs buffer. In -such examples, the convention is to include the entire contents of the -buffer in question between two lines of dashes containing the buffer -name.@refill - -You can use the @samp{@@point@{@}} command to show the location of point -in the text in the buffer. (The symbol for point, of course, is not -part of the text in the buffer; it indicates the place @emph{between} -two characters where point is located.)@refill - -@iftex -The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and -as @samp{@point{}} in the printed output. -@end iftex -@ifinfo -The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info -and as a small five pointed star in the printed output.@refill -@end ifinfo - -The following example shows the contents of buffer @file{foo} before -and after evaluating a Lisp command to insert the word @code{changed}.@refill - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -@example -@group -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -In a Texinfo source file, the example is written like this:@refill - -@example -@@example ----------- Buffer: foo ---------- -This is the @@point@{@}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @@result@{@} nil ----------- Buffer: foo ---------- -This is the changed @@point@{@}contents of foo. ----------- Buffer: foo ---------- -@@end example -@end example - - -@c this should be described with figures when we have them -@c perhaps in the quotation/example chapter. -@node Images, , Glyphs, Insertions -@section Inserting Images - -@cindex Images, inserting -@cindex Pictures, inserting -@findex image - -You can insert an image in an external file with the @code{@@image} -command: - -@example -@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} -@end example - -@cindex Formats for images -@cindex Image formats -The @var{filename} argument is mandatory, and must not have an -extension, because the different processors support different formats: -@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript -format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for -Info output (more or less as if it was an @code{@@example}). HTML -output requires @file{@var{filename}.jpg}. - -@cindex Width of images -@cindex Height of images -@cindex Aspect ratio of images -@cindex Distorting images -The optional @var{width} and @var{height} arguments specify the size to -scale the image to (they are ignored for Info output). If they are both -specified, the image is presented in its natural size (given in the -file); if only one is specified, the other is scaled proportionately; -and if both are specified, both are respected, thus possibly distorting -the original image by changing its aspect ratio. - -@cindex Dimensions and image sizes -The @var{width} and @var{height} may be specified using any valid @TeX{} -dimension, namely: - -@table @asis -@item pt -@cindex Points (dimension) -point (72.27pt = 1in) -@item pc -@cindex Picas -pica (1pc = 12pt) -@item bp -@cindex Big points -big point (72bp = 1in) -@item in -@cindex Inches -inch -@item cm -@cindex Centimeters -centimeter (2.54cm = 1in) -@item mm -@cindex Millimeters -millimeter (10mm = 1cm) -@item dd -@cindex Did@^ot points -did@^ot point (1157dd = 1238pt) -@item cc -@cindex Ciceros -cicero (1cc = 12dd) -@item sp -@cindex Scaled points -scaled point (65536sp = 1pt) -@end table - -@pindex ridt.eps -For example, the following will scale a file @file{ridt.eps} to one -inch vertically, with the width scaled proportionately: - -@example -@@image@{ridt,,1in@} -@end example - -@pindex epsf.tex -For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be -installed somewhere that @TeX{} can find it. This file is included in -the Texinfo distribution and is available from -@uref{ftp://ftp.tug.org/tex/epsf.tex}. - - -@node Breaks, Definition Commands, Insertions, Top -@chapter Making and Preventing Breaks -@cindex Making line and page breaks -@cindex Preventing line and page breaks - -Usually, a Texinfo file is processed both by @TeX{} and by one of the -Info formatting commands. Line, paragraph, or page breaks sometimes -occur in the `wrong' place in one or other form of output. You must -ensure that text looks right both in the printed manual and in the -Info file.@refill - -For example, in a printed manual, page breaks may occur awkwardly in -the middle of an example; to prevent this, you can hold text together -using a grouping command that keeps the text from being split across -two pages. Conversely, you may want to force a page break where none -would occur normally. Fortunately, problems like these do not often -arise. When they do, use the break, break prevention, or pagination -commands.@refill - -@menu -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. -@end menu - -@ifinfo -@node Break Commands, Line Breaks, Breaks, Breaks -@heading The Break Commands -@end ifinfo -@iftex -@sp 1 -@end iftex - -The break commands create or allow line and paragraph breaks:@refill - -@table @code -@item @@* -Force a line break. - -@item @@sp @var{n} -Skip @var{n} blank lines.@refill - -@item @@- -Insert a discretionary hyphen. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Define hyphen points in @var{hy-phen-a-ted words}. -@end table - -The line-break-prevention command holds text together all on one -line:@refill - -@table @code -@item @@w@{@var{text}@} -Prevent @var{text} from being split and hyphenated across two lines.@refill -@end table -@iftex -@sp 1 -@end iftex - -The pagination commands apply only to printed output, since Info -files do not have pages.@refill - -@table @code -@item @@page -Start a new page in the printed manual.@refill - -@item @@group -Hold text together that must appear on one printed page.@refill - -@item @@need @var{mils} -Start a new printed page if not enough space on this one.@refill -@end table - -@node Line Breaks, - and hyphenation, Break Commands, Breaks -@comment node-name, next, previous, up -@section @code{@@*}: Generate Line Breaks -@findex * @r{(force line break)} -@cindex Line breaks -@cindex Breaks in a line - -The @code{@@*} command forces a line break in both the printed manual and -in Info.@refill - -@need 700 -For example, - -@example -This line @@* is broken @@*in two places. -@end example - -@noindent -produces - -@example -@group -This line - is broken -in two places. -@end group -@end example - -@noindent -(Note that the space after the first @code{@@*} command is faithfully -carried down to the next line.)@refill - -@need 800 -The @code{@@*} command is often used in a file's copyright page:@refill - -@example -@group -This is edition 2.0 of the Texinfo documentation,@@* -and is for @dots{} -@end group -@end example - -@noindent -In this case, the @code{@@*} command keeps @TeX{} from stretching the -line across the whole page in an ugly manner.@refill - -@quotation -@strong{Please note:} Do not write braces after an @code{@@*} command; -they are not needed.@refill - -Do not write an @code{@@refill} command at the end of a paragraph -containing an @code{@@*} command; it will cause the paragraph to be -refilled after the line break occurs, negating the effect of the line -break.@refill -@end quotation - -@node - and hyphenation, w, Line Breaks, Breaks -@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate - -@findex - -@findex hyphenation -@cindex Hyphenation, helping @TeX{} do -@cindex Fine-tuning, and hyphenation - -Although @TeX{}'s hyphenation algorithm is generally pretty good, it -does miss useful hyphenation points from time to time. (Or, far more -rarely, insert an incorrect hyphenation.) So, for documents with an -unusual vocabulary or when fine-tuning for a printed edition, you may -wish to help @TeX{} out. Texinfo supports two commands for this: - -@table @code -@item @@- -Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does -not have to) hyphenate. This is especially useful when you notice -an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull -hboxes}). @TeX{} will not insert any hyphenation points in a word -containing @code{@@-}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you -put a @samp{-} at each hyphenation point. For example: -@example -@@hyphenation@{man-u-script man-u-scripts@} -@end example -@noindent @TeX{} only uses the specified hyphenation points when the -words match exactly, so give all necessary variants. -@end table - -Info output is not hyphenated, so these commands have no effect there. - -@node w, sp, - and hyphenation, Breaks -@comment node-name, next, previous, up -@section @code{@@w}@{@var{text}@}: Prevent Line Breaks -@findex w @r{(prevent line break)} -@cindex Line breaks, preventing -@cindex Hyphenation, preventing - -@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks -within @var{text}.@refill - -You can use the @code{@@w} command to prevent @TeX{} from automatically -hyphenating a long name or phrase that happens to fall near the end of a -line.@refill - -@example -You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}. -@end example - -@noindent -produces - -@quotation -You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}. -@end quotation - -@quotation -@strong{Caution:} Do not write an @code{@@refill} command at the end -of a paragraph containing an @code{@@w} command; it will cause the -paragraph to be refilled and may thereby negate the effect of the -@code{@@w} command.@refill -@end quotation - -@node sp, page, w, Breaks -@comment node-name, next, previous, up -@section @code{@@sp} @var{n}: Insert Blank Lines -@findex sp @r{(line spacing)} -@cindex Spaces (blank lines) -@cindex Blank lines -@cindex Line spacing - -A line beginning with and containing only @code{@@sp @var{n}} -generates @var{n} blank lines of space in both the printed manual and -the Info file. @code{@@sp} also forces a paragraph break. For -example,@refill - -@example -@@sp 2 -@end example - -@noindent -generates two blank lines. - -The @code{@@sp} command is most often used in the title page.@refill - -@ignore -@c node br, page, sp, Breaks -@comment node-name, next, previous, up -@c section @code{@@br}: Generate Paragraph Breaks -@findex br @r{(paragraph breaks)} -@cindex Paragraph breaks -@cindex Breaks in a paragraph - -The @code{@@br} command forces a paragraph break. It inserts a blank -line. You can use the command within or at the end of a line. If -used within a line, the @code{@@br@{@}} command must be followed by -left and right braces (as shown here) to mark the end of the -command.@refill - -@need 700 -For example, - -@example -@group -This line @@br@{@}contains and is ended by paragraph breaks@@br -and is followed by another line. -@end group -@end example - -@noindent -produces - -@example -@group -This line - -contains and is ended by paragraph breaks - -and is followed by another line. -@end group -@end example - -The @code{@@br} command is seldom used. -@end ignore - -@node page, group, sp, Breaks -@comment node-name, next, previous, up -@section @code{@@page}: Start a New Page -@cindex Page breaks -@findex page - -A line containing only @code{@@page} starts a new page in a printed -manual. The command has no effect on Info files since they are not -paginated. An @code{@@page} command is often used in the @code{@@titlepage} -section of a Texinfo file to start the copyright page.@refill - -@node group, need, page, Breaks -@comment node-name, next, previous, up -@section @code{@@group}: Prevent Page Breaks -@cindex Group (hold text together vertically) -@cindex Holding text together vertically -@cindex Vertically holding text together -@findex group - -The @code{@@group} command (on a line by itself) is used inside an -@code{@@example} or similar construct to begin an unsplittable vertical -group, which will appear entirely on one page in the printed output. -The group is terminated by a line containing only @code{@@end group}. -These two lines produce no output of their own, and in the Info file -output they have no effect at all.@refill - -@c Once said that these environments -@c turn off vertical spacing between ``paragraphs''. -@c Also, quotation used to work, but doesn't in texinfo-2.72 -Although @code{@@group} would make sense conceptually in a wide -variety of contexts, its current implementation works reliably only -within @code{@@example} and variants, and within @code{@@display}, -@code{@@format}, @code{@@flushleft} and @code{@@flushright}. -@xref{Quotations and Examples}. (What all these commands have in -common is that each line of input produces a line of output.) In -other contexts, @code{@@group} can cause anomalous vertical -spacing.@refill - -@need 750 -This formatting requirement means that you should write: - -@example -@group -@@example -@@group -@dots{} -@@end group -@@end example -@end group -@end example - -@noindent -with the @code{@@group} and @code{@@end group} commands inside the -@code{@@example} and @code{@@end example} commands. - -The @code{@@group} command is most often used to hold an example -together on one page. In this Texinfo manual, more than 100 examples -contain text that is enclosed between @code{@@group} and @code{@@end -group}. - -If you forget to end a group, you may get strange and unfathomable -error messages when you run @TeX{}. This is because @TeX{} keeps -trying to put the rest of the Texinfo file onto the one page and does -not start to generate error messages until it has processed -considerable text. It is a good rule of thumb to look for a missing -@code{@@end group} if you get incomprehensible error messages in -@TeX{}.@refill - -@node need, , group, Breaks -@comment node-name, next, previous, up -@section @code{@@need @var{mils}}: Prevent Page Breaks -@cindex Need space at page bottom -@findex need - -A line containing only @code{@@need @var{n}} starts -a new page in a printed manual if fewer than @var{n} mils (thousandths -of an inch) remain on the current page. Do not use -braces around the argument @var{n}. The @code{@@need} command has no -effect on Info files since they are not paginated.@refill - -@need 800 -This paragraph is preceded by an @code{@@need} command that tells -@TeX{} to start a new page if fewer than 800 mils (eight-tenths -inch) remain on the page. It looks like this:@refill - -@example -@group -@@need 800 -This paragraph is preceded by @dots{} -@end group -@end example - -The @code{@@need} command is useful for preventing orphans (single -lines at the bottoms of printed pages).@refill - -@node Definition Commands, Footnotes, Breaks, Top -@chapter Definition Commands -@cindex Definition commands - -The @code{@@deffn} command and the other @dfn{definition commands} -enable you to describe functions, variables, macros, commands, user -options, special forms and other such artifacts in a uniform -format.@refill - -In the Info file, a definition causes the entity -category---`Function', `Variable', or whatever---to appear at the -beginning of the first line of the definition, followed by the -entity's name and arguments. In the printed manual, the command -causes @TeX{} to print the entity's name and its arguments on the left -margin and print the category next to the right margin. In both -output formats, the body of the definition is indented. Also, the -name of the entity is entered into the appropriate index: -@code{@@deffn} enters the name into the index of functions, -@code{@@defvr} enters it into the index of variables, and so -on.@refill - -A manual need not and should not contain more than one definition for -a given name. An appendix containing a summary should use -@code{@@table} rather than the definition commands.@refill - -@menu -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: -@end menu - -@node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands -@section The Template for a Definition -@cindex Definition template -@cindex Template for a definition - -The @code{@@deffn} command is used for definitions of entities that -resemble functions. To write a definition using the @code{@@deffn} -command, write the @code{@@deffn} command at the beginning of a line -and follow it on the same line by the category of the entity, the name -of the entity itself, and its arguments (if any). Then write the body -of the definition on succeeding lines. (You may embed examples in the -body.) Finally, end the definition with an @code{@@end deffn} command -written on a line of its own. (The other definition commands follow -the same format.)@refill - -The template for a definition looks like this: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@deffn Command forward-word count -This command moves point forward @@var@{count@} words -(or backward if @@var@{count@} is negative). @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@quotation -@deffn Command forward-word count -This function moves point forward @var{count} words -(or backward if @var{count} is negative). @dots{} -@end deffn -@end quotation - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', -write braces around it. For example:@refill - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@dots{} -@@end deffn -@end group -@end example - -@noindent -Otherwise, the second word will be mistaken for the name of the -entity.@refill - -Some of the definition commands are more general than others. The -@code{@@deffn} command, for example, is the general definition command -for functions and the like---for entities that may take arguments. When -you use this command, you specify the category to which the entity -belongs. The @code{@@deffn} command possesses three predefined, -specialized variations, @code{@@defun}, @code{@@defmac}, and -@code{@@defspec}, that specify the category for you: ``Function'', -``Macro'', and ``Special Form'' respectively. (In Lisp, a special form -is an entity much like a function.) The @code{@@defvr} command also is -accompanied by several predefined, specialized variations for describing -particular kinds of variables.@refill - -The template for a specialized definition, such as @code{@@defun}, is -similar to the template for a generalized definition, except that you -do not need to specify the category:@refill - -@example -@group -@@defun @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@noindent -Thus, - -@example -@group -@@defun buffer-end flag -This function returns @@code@{(point-min)@} if @@var@{flag@} -is less than 1, @@code@{(point-max)@} otherwise. -@dots{} -@@end defun -@end group -@end example - -@noindent -produces - -@quotation -@defun buffer-end flag -This function returns @code{(point-min)} if @var{flag} is less than 1, -@code{(point-max)} otherwise. @dots{} -@end defun -@end quotation - -@noindent -@xref{Sample Function Definition, Sample Function Definition, A Sample -Function Definition}, for a more detailed example of a function -definition, including the use of @code{@@example} inside the -definition.@refill - -The other specialized commands work like @code{@@defun}.@refill - -@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands -@section Optional and Repeated Arguments -@cindex Optional and repeated arguments -@cindex Repeated and optional arguments -@cindex Arguments, repeated and optional -@cindex Syntax, optional & repeated arguments -@cindex Meta-syntactic chars for arguments - -Some entities take optional or repeated arguments, which may be -specified by a distinctive glyph that uses square brackets and -ellipses. For @w{example}, a special form often breaks its argument list -into separate arguments in more complicated ways than a -straightforward function.@refill - -@iftex -An argument enclosed within square brackets is optional. -Thus, the phrase -@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that -@var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end iftex -@c The following looks better in Info (no `r', `samp' and `code'): -@ifinfo -An argument enclosed within square brackets is optional. -Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @var{repeated-args}@dots{} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end ifinfo - -Here is the @code{@@defspec} line of an example of an imaginary -special form:@refill - -@quotation -@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -@end defspec -@tex -\vskip \parskip -@end tex -@end quotation - -@noindent -In this example, the arguments @var{from} and @var{to} are optional, -but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the -form.@refill - -In a Texinfo source file, this @code{@@defspec} line is written like -this (except it would not be split over two lines, as it is in this -example).@refill - -@example -@group -@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} - [@@var@{inc@}]]) @@var@{body@}@@dots@{@} -@end group -@end example - -@noindent -The function is listed in the Command and Variable Index under -@samp{foobar}.@refill - -@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands -@section Two or More `First' Lines -@cindex Two `First' Lines for @code{@@deffn} -@cindex Grouping two definitions together -@cindex Definitions grouped together -@findex deffnx - -To create two or more `first' or header lines for a definition, follow -the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. -The @code{@@deffnx} command works exactly like @code{@@deffn} -except that it does not generate extra vertical white space between it -and the preceding line.@refill - -@need 1000 -For example, - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@@deffnx @{Interactive Command@} isearch-backward -These two search commands are similar except @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@deffn {Interactive Command} isearch-forward -@deffnx {Interactive Command} isearch-backward -These two search commands are similar except @dots{} -@end deffn - -Each of the other definition commands has an `x' form: @code{@@defunx}, -@code{@@defvrx}, @code{@@deftypefunx}, etc. - -The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. - -@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands -@section The Definition Commands - -Texinfo provides more than a dozen definition commands, all of which -are described in this section.@refill - -The definition commands automatically enter the name of the entity in -the appropriate index: for example, @code{@@deffn}, @code{@@defun}, -and @code{@@defmac} enter function names in the index of functions; -@code{@@defvr} and @code{@@defvar} enter variable names in the index -of variables.@refill - -Although the examples that follow mostly illustrate Lisp, the commands -can be used for other programming languages.@refill - -@menu -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. -@end menu - -@node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail -@subsection Functions and Similar Entities - -This section describes the commands for describing functions and similar -entities:@refill - -@table @code -@findex deffn -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -The @code{@@deffn} command is the general definition command for -functions, interactive commands, and similar entities that may take -arguments. You must choose a term to describe the category of entity -being defined; for example, ``Function'' could be used if the entity is -a function. The @code{@@deffn} command is written at the beginning of a -line and is followed on the same line by the category of entity being -described, the name of this particular entity, and its arguments, if -any. Terminate the definition with @code{@@end deffn} on a line of its -own.@refill - -@need 750 -For example, here is a definition: - -@example -@group -@@deffn Command forward-char nchars -Move point forward @@var@{nchars@} characters. -@@end deffn -@end group -@end example - -@noindent -This shows a rather terse definition for a ``command'' named -@code{forward-char} with one argument, @var{nchars}. - -@code{@@deffn} prints argument names such as @var{nchars} in italics or -upper case, as if @code{@@var} had been used, because we think of these -names as metasyntactic variables---they stand for the actual argument -values. Within the text of the description, write an argument name -explicitly with @code{@@var} to refer to the value of the argument. In -the example above, we used @samp{@@var@{nchars@}} in this way. - -The template for @code{@@deffn} is: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@findex defun -@item @@defun @var{name} @var{arguments}@dots{} -The @code{@@defun} command is the definition command for functions. -@code{@@defun} is equivalent to @samp{@@deffn Function -@dots{}}.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defun set symbol new-value -Change the value of the symbol @@var@{symbol@} -to @@var@{new-value@}. -@@end defun -@end group -@end example - -@noindent -shows a rather terse definition for a function @code{set} whose -arguments are @var{symbol} and @var{new-value}. The argument names on -the @code{@@defun} line automatically appear in italics or upper case as -if they were enclosed in @code{@@var}. Terminate the definition with -@code{@@end defun} on a line of its own.@refill - -The template is: - -@example -@group -@@defun @var{function-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@code{@@defun} creates an entry in the index of functions. - -@findex defmac -@item @@defmac @var{name} @var{arguments}@dots{} -The @code{@@defmac} command is the definition command for macros. -@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and -works like @code{@@defun}.@refill - -@findex defspec -@item @@defspec @var{name} @var{arguments}@dots{} -The @code{@@defspec} command is the definition command for special -forms. (In Lisp, a special form is an entity much like a function, -@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.) -@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} -@dots{}} and works like @code{@@defun}.@refill -@end table - -@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail -@subsection Variables and Similar Entities - -Here are the commands for defining variables and similar -entities:@refill - -@table @code -@findex defvr -@item @@defvr @var{category} @var{name} -The @code{@@defvr} command is a general definition command for -something like a variable---an entity that records a value. You must -choose a term to describe the category of entity being defined; for -example, ``Variable'' could be used if the entity is a variable. -Write the @code{@@defvr} command at the beginning of a line and -followed it on the same line by the category of the entity and the -name of the entity.@refill - -Capitalize the category name like a title. If the name of the category -contains spaces, as in the name ``User Option'', enclose it in braces. -Otherwise, the second word will be mistaken for the name of the entity. -For example, - -@example -@group -@@defvr @{User Option@} fill-column -This buffer-local variable specifies -the maximum width of filled lines. -@dots{} -@@end defvr -@end group -@end example - -Terminate the definition with @code{@@end defvr} on a line of its -own.@refill - -The template is: - -@example -@group -@@defvr @var{category} @var{name} -@var{body-of-definition} -@@end defvr -@end group -@end example - -@code{@@defvr} creates an entry in the index of variables for @var{name}. - -@findex defvar -@item @@defvar @var{name} -The @code{@@defvar} command is the definition command for variables. -@code{@@defvar} is equivalent to @samp{@@defvr Variable -@dots{}}.@refill - -@need 750 -For example: - -@example -@group -@@defvar kill-ring -@dots{} -@@end defvar -@end group -@end example - -The template is: - -@example -@group -@@defvar @var{name} -@var{body-of-definition} -@@end defvar -@end group -@end example - -@code{@@defvar} creates an entry in the index of variables for -@var{name}.@refill - -@findex defopt -@item @@defopt @var{name} -@cindex User options, marking -The @code{@@defopt} command is the definition command for @dfn{user -options}, i.e., variables intended for users to change according to -taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs -Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}.@refill -@end table - - -@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail -@subsection Functions in Typed Languages - -The @code{@@deftypefn} command and its variations are for describing -functions in languages in which you must declare types of variables and -functions, such as C and C++. - -@table @code -@findex deftypefn -@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefn} command is the general definition command for -functions and similar entities that may take arguments and that are -typed. The @code{@@deftypefn} command is written at the beginning of -a line and is followed on the same line by the category of entity -being described, the type of the returned value, the name of this -particular entity, and its arguments, if any.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@deftypefn @{Library Function@} int foobar - (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefn -@end group -@end example - -@need 1000 -@noindent -(where the text before the ``@dots{}'', shown above as two lines, would -actually be a single line in a real Texinfo file) produces the following -in Info: - -@smallexample -@group --- Library Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end smallexample -@iftex - -In a printed manual, it produces: - -@quotation -@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefn -@end quotation -@end iftex - -This means that @code{foobar} is a ``library function'' that returns an -@code{int}, and its arguments are @var{foo} (an @code{int}) and -@var{bar} (a @code{float}).@refill - -The argument names that you write in @code{@@deftypefn} are not subject -to an implicit @code{@@var}---since the actual names of the arguments in -@code{@@deftypefn} are typically scattered among data type names and -keywords, Texinfo cannot find them without help. Instead, you must write -@code{@@var} explicitly around the argument names. In the example -above, the argument names are @samp{foo} and @samp{bar}.@refill - -The template for @code{@@deftypefn} is:@refill - -@example -@group -@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} -@var{body-of-description} -@@end deftypefn -@end group -@end example - -@noindent -Note that if the @var{category} or @var{data type} is more than one -word then it must be enclosed in braces to make it a single argument.@refill - -If you are describing a procedure in a language that has packages, -such as Ada, you might consider using @code{@@deftypefn} in a manner -somewhat contrary to the convention described in the preceding -paragraphs.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypefn stacks private push - (@@var@{s@}:in out stack; - @@var@{n@}:in integer) -@dots{} -@@end deftypefn -@end group -@end example - -@noindent -(The @code{@@deftypefn} arguments are shown split into three lines, but -would be a single line in a real Texinfo file.) - -In this instance, the procedure is classified as belonging to the -package @code{stacks} rather than classified as a `procedure' and its -data type is described as @code{private}. (The name of the procedure -is @code{push}, and its arguments are @var{s} and @var{n}.)@refill - -@code{@@deftypefn} creates an entry in the index of functions for -@var{name}.@refill - -@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} -@findex deftypefun -The @code{@@deftypefun} command is the specialized definition command -for functions in typed languages. The command is equivalent to -@samp{@@deftypefn Function @dots{}}.@refill - -@need 800 -@noindent -Thus, - -@smallexample -@group -@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefun -@end group -@end smallexample - -@noindent -produces the following in Info: - -@example -@group --- Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypefun int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefun -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@group -@@deftypefun @var{type} @var{name} @var{arguments}@dots{} -@var{body-of-description} -@@end deftypefun -@end group -@end example - -@code{@@deftypefun} creates an entry in the index of functions for -@var{name}.@refill - -@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -@findex deftypefun -The @code{@@deftypemethod} command is the definition command for methods -in object-oriented typed languages, such as C++ and Java. It is similar -to the @code{@@deftypefn} with the addition of the @var{class} parameter -to specify the class containing the method. - -@end table - - -@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail -@subsection Variables in Typed Languages - -Variables in typed languages are handled in a manner similar to -functions in typed languages. @xref{Typed Functions}. The general -definition command @code{@@deftypevr} corresponds to -@code{@@deftypefn} and the specialized definition command -@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill - -@table @code -@findex deftypevr -@item @@deftypevr @var{category} @var{data-type} @var{name} -The @code{@@deftypevr} command is the general definition command for -something like a variable in a typed language---an entity that records -a value. You must choose a term to describe the category of the -entity being defined; for example, ``Variable'' could be used if the -entity is a variable.@refill - -The @code{@@deftypevr} command is written at the beginning of a line -and is followed on the same line by the category of the entity -being described, the data type, and the name of this particular -entity.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevr @{Global Flag@} int enable -@dots{} -@@end deftypevr -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Global Flag: int enable -@dots{} -@end group -@end example -@iftex - -@noindent -and the following in a printed manual: - -@quotation -@deftypevr {Global Flag} int enable -@dots{} -@end deftypevr -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@@deftypevr @var{category} @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevr -@end example - -@code{@@deftypevr} creates an entry in the index of variables for -@var{name}.@refill - -@findex deftypevar -@item @@deftypevar @var{data-type} @var{name} -The @code{@@deftypevar} command is the specialized definition command -for variables in typed languages. @code{@@deftypevar} is equivalent -to @samp{@@deftypevr Variable @dots{}}.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevar int fubar -@dots{} -@@end deftypevar -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Variable: int fubar -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypevar int fubar -@dots{} -@end deftypevar -@end quotation -@end iftex - -@need 800 -@noindent -The template is: - -@example -@group -@@deftypevar @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevar -@end group -@end example - -@code{@@deftypevar} creates an entry in the index of variables for -@var{name}.@refill -@end table - -@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail -@subsection Object-Oriented Programming - -Here are the commands for formatting descriptions about abstract -objects, such as are used in object-oriented programming. A class is -a defined type of abstract object. An instance of a class is a -particular object that has the type of the class. An instance -variable is a variable that belongs to the class but for which each -instance has its own value.@refill - -In a definition, if the name of a class is truly a name defined in the -programming system for a class, then you should write an @code{@@code} -around it. Otherwise, it is printed in the usual text font.@refill - -@table @code -@findex defcv -@item @@defcv @var{category} @var{class} @var{name} -The @code{@@defcv} command is the general definition command for -variables associated with classes in object-oriented programming. The -@code{@@defcv} command is followed by three arguments: the category of -thing being defined, the class to which it belongs, and its -name. Thus,@refill - -@example -@group -@@defcv @{Class Option@} Window border-pattern -@dots{} -@@end defcv -@end group -@end example - -@noindent -illustrates how you would write the first line of a definition of the -@code{border-pattern} class option of the class @code{Window}.@refill - -The template is - -@example -@group -@@defcv @var{category} @var{class} @var{name} -@dots{} -@@end defcv -@end group -@end example - -@code{@@defcv} creates an entry in the index of variables. - -@findex defivar -@item @@defivar @var{class} @var{name} -The @code{@@defivar} command is the definition command for instance -variables in object-oriented programming. @code{@@defivar} is -equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill - -The template is: - -@example -@group -@@defivar @var{class} @var{instance-variable-name} -@var{body-of-definition} -@@end defivar -@end group -@end example - -@code{@@defivar} creates an entry in the index of variables. - -@findex defop -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defop} command is the general definition command for -entities that may resemble methods in object-oriented programming. -These entities take arguments, as functions do, but are associated -with particular classes of objects.@refill - -For example, some systems have constructs called @dfn{wrappers} that -are associated with classes as methods are, but that act more like -macros than like functions. You could use @code{@@defop Wrapper} to -describe one of these.@refill - -Sometimes it is useful to distinguish methods and @dfn{operations}. -You can think of an operation as the specification for a method. -Thus, a window system might specify that all window classes have a -method named @code{expose}; we would say that this window system -defines an @code{expose} operation on windows in general. Typically, -the operation has a name and also specifies the pattern of arguments; -all methods that implement the operation must accept the same -arguments, since applications that use the operation do so without -knowing which method will implement it.@refill - -Often it makes more sense to document operations than methods. For -example, window application developers need to know about the -@code{expose} operation, but need not be concerned with whether a -given class of windows has its own method to implement this operation. -To describe this operation, you would write:@refill - -@example -@@defop Operation windows expose -@end example - -The @code{@@defop} command is written at the beginning of a line and -is followed on the same line by the overall name of the category of -operation, the name of the class of the operation, the name of the -operation, and its arguments, if any.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defop -@end group -@end example - -@code{@@defop} creates an entry, such as `@code{expose} on -@code{windows}', in the index of functions.@refill - -@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} -@findex defmethod -The @code{@@defmethod} command is the definition command for methods -in object-oriented programming. A method is a kind of function that -implements an operation for a particular class of objects and its -subclasses. In the Lisp Machine, methods actually were functions, but -they were usually defined with @code{defmethod}. - -@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. -The command is written at the beginning of a line and is followed by -the name of the class of the method, the name of the method, and its -arguments, if any.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defmethod @code{bar-class} bar-method argument -@dots{} -@@end defmethod -@end group -@end example - -@noindent -illustrates the definition for a method called @code{bar-method} of -the class @code{bar-class}. The method takes an argument.@refill - -The template is: - -@example -@group -@@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defmethod -@end group -@end example - -@code{@@defmethod} creates an entry, such as `@code{bar-method} on -@code{bar-class}', in the index of functions.@refill - -@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -@findex defmethod -The @code{@@deftypemethod} command is the definition command for methods -in object-oriented typed languages, such as C++ and Java. It is similar -to the @code{@@defmethod} command with the addition of the -@var{data-type} parameter to specify the return type of the method. - -@end table - - -@node Data Types, , Abstract Objects, Def Cmds in Detail -@subsection Data Types - -Here is the command for data types:@refill - -@table @code -@findex deftp -@item @@deftp @var{category} @var{name} @var{attributes}@dots{} -The @code{@@deftp} command is the generic definition command for data -types. The command is written at the beginning of a line and is -followed on the same line by the category, by the name of the type -(which is a word like @code{int} or @code{float}), and then by names of -attributes of objects of that type. Thus, you could use this command -for describing @code{int} or @code{float}, in which case you could use -@code{data type} as the category. (A data type is a category of -certain objects for purposes of deciding which operations can be -performed on them.)@refill - -In Lisp, for example, @dfn{pair} names a particular data -type, and an object of that type has two slots called the -@sc{car} and the @sc{cdr}. Here is how you would write the first line -of a definition of @code{pair}.@refill - -@example -@group -@@deftp @{Data type@} pair car cdr -@dots{} -@@end deftp -@end group -@end example - -@need 950 -The template is: - -@example -@group -@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@var{body-of-definition} -@@end deftp -@end group -@end example - -@code{@@deftp} creates an entry in the index of data types. -@end table - -@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands -@section Conventions for Writing Definitions -@cindex Definition conventions -@cindex Conventions for writing definitions - -When you write a definition using @code{@@deffn}, @code{@@defun}, or -one of the other definition commands, please take care to use -arguments that indicate the meaning, as with the @var{count} argument -to the @code{forward-word} function. Also, if the name of an argument -contains the name of a type, such as @var{integer}, take care that the -argument actually is of that type.@refill - -@node Sample Function Definition, , Def Cmd Conventions, Definition Commands -@section A Sample Function Definition -@cindex Function definitions -@cindex Command definitions -@cindex Macro definitions -@cindex Sample function definition - -A function definition uses the @code{@@defun} and @code{@@end defun} -commands. The name of the function follows immediately after the -@code{@@defun} command and it is followed, on the same line, by the -parameter list.@refill - -Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs -Lisp Reference Manual}. - -@quotation -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just -like @code{funcall} but with one difference: the last of -@var{arguments} is a list of arguments to give to -@var{function}, rather than a single argument. We also say -that this list is @dfn{appended} to the other arguments. - -@code{apply} returns the result of calling @var{function}. -As with @code{funcall}, @var{function} must either be a Lisp -function or a primitive function; special forms and macros -do not make sense in @code{apply}. - -@example -(setq f 'list) - @result{} list -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @result{} 10 -(apply '+ '(1 2 3 4)) - @result{} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end example - -An interesting example of using @code{apply} is found in the description -of @code{mapcar}.@refill -@end defun -@end quotation - -@need 1200 -In the Texinfo source file, this example looks like this: - -@example -@group -@@defun apply function &rest arguments - -@@code@{apply@} calls @@var@{function@} with -@@var@{arguments@}, just like @@code@{funcall@} but with one -difference: the last of @@var@{arguments@} is a list of -arguments to give to @@var@{function@}, rather than a single -argument. We also say that this list is @@dfn@{appended@} -to the other arguments. -@end group - -@group -@@code@{apply@} returns the result of calling -@@var@{function@}. As with @@code@{funcall@}, -@@var@{function@} must either be a Lisp function or a -primitive function; special forms and macros do not make -sense in @@code@{apply@}. -@end group - -@group -@@example -(setq f 'list) - @@result@{@} list -(apply f 'x 'y 'z) -@@error@{@} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @@result@{@} 10 -(apply '+ '(1 2 3 4)) - @@result@{@} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @@result@{@} (a b c x y z) -@@end example -@end group - -@group -An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}.@@refill -@@end defun -@end group -@end example - -@noindent -In this manual, this function is listed in the Command and Variable -Index under @code{apply}.@refill - -Ordinary variables and user options are described using a format like -that for functions except that variables do not take arguments. - - -@node Footnotes, Conditionals, Definition Commands, Top -@chapter Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon -the primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.}@refill - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu - -@node Footnote Commands, Footnote Styles, Footnotes, Footnotes -@section Footnote Commands - -In Texinfo, footnotes are created with the @code{@@footnote} command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. Footnotes may -be of any length (they will be broken across pages if necessary), but -are usually short. The template is: - -@example -ordinary text@@footnote@{@var{text of footnote}@} -@end example - -As shown here, the @code{@@footnote} command should come right after the -text being footnoted, with no intervening space; otherwise, the -formatters the footnote mark might end up starting up a line. - -For example, this clause is followed by a sample -footnote@footnote{Here is the sample footnote.}; in the Texinfo -source, it looks like this:@refill - -@example -@dots{}a sample footnote@@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -@strong{Warning:} Don't use footnotes in the argument of the -@code{@@item} command for a @code{@@table} table. This doesn't work, and -because of limitations of @TeX{}, there is no way to fix it. You must -put the footnote into the body text of the table. - -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line.@refill - -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}.@refill - - -@node Footnote Styles, , Footnote Commands, Footnotes -@section Footnote Styles - -Info has two footnote styles, which determine where the text of the -footnote is located:@refill - -@itemize @bullet -@cindex @samp{@r{End}} node footnote style -@item -In the `End' node style, all the footnotes for a single node -are placed at the end of that node. The footnotes are separated from -the rest of the node by a line of dashes with the word -@samp{Footnotes} within it. Each footnote begins with an -@samp{(@var{n})} reference mark.@refill - -@need 700 -@noindent -Here is an example of a single footnote in the end of node style:@refill - -@example -@group - --------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node.@refill - -The name of the node containing the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node.@refill - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style:@refill - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) Note that the first syllable of "Texinfo" is -pronounced like "speck", not "hex". @dots{} -@end group -@end smallexample -@end itemize - -A Texinfo file may be formatted into an Info file with either footnote -style.@refill - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{texinfo-format-buffer} and -@code{texinfo-format-region} use the `separate' style and -@code{makeinfo} uses the `end' style.@refill - -@c !!! note: makeinfo's --footnote-style option overrides footnotestyle -@ignore -If you use @code{makeinfo} to create the Info file, the -@samp{--footnote-style} option determines which style is used, -@samp{end} for the end of node style or @samp{separate} for the -separate node style. Thus, to format the Texinfo manual in the -separate node style, you would use the following shell command:@refill - -@example -makeinfo --footnote-style=separate texinfo.texi -@end example - -@noindent -To format the Texinfo manual in the end of node style, you would -type:@refill - -@example -makeinfo --footnote-style=end texinfo.texi -@end example -@end ignore -@ignore -If you use @code{texinfo-format-buffer} or -@code{texinfo-format-region} to create the Info file, the value of the -@code{texinfo-footnote-style} variable controls the footnote style. -It can be either @samp{"separate"} for the separate node style or -@samp{"end"} for the end of node style. (You can change the value of -this variable with the @kbd{M-x edit-options} command (@pxref{Edit -Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or -with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining -and Setting Variables, emacs, The GNU Emacs Manual}).@refill - -The @code{texinfo-footnote-style} variable also controls the style if -you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} -command in Emacs.@refill -@end ignore -This chapter contains two footnotes.@refill - - -@node Conditionals, Macros, Footnotes, Top -@comment node-name, next, previous, up -@chapter Conditionally Visible Text -@cindex Conditionally visible text -@cindex Text, conditionally visible -@cindex Visibility of conditional text -@cindex If text conditionally visible - -Sometimes it is good to use different text for a printed manual and -its corresponding Info file. In this case, you can use the -@dfn{conditional commands} to specify which text is for the printed manual -and which is for the Info file.@refill - -@menu -* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. -* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. -* Raw Formatter Commands:: Using raw @TeX{} or HTML commands. -* set clear value:: Designating which text to format (for - all output formats); and how to set a - flag to a string that you can insert. -@end menu - -@node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals -@ifinfo -@heading Conditional Commands -@end ifinfo - -@findex ifinfo -@code{@@ifinfo} begins segments of text that should be ignored -by @TeX{} when it -typesets the printed manual. The segment of text appears only -in the Info file. -The @code{@@ifinfo} command should appear on a line by itself; end -the Info-only text with a line containing @code{@@end ifinfo} by -itself. At the beginning of a Texinfo file, the Info permissions are -contained within a region marked by @code{@@ifinfo} and @code{@@end -ifinfo}. (@xref{Info Summary and Permissions}.)@refill - -@findex iftex -@findex ifhtml -The @code{@@iftex} and @code{@@end iftex} commands are similar to the -@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they -specify text that will appear in the printed manual but not in the Info -file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which -specify text to appear only in HTML output.@refill - -For example, - -@example -@@iftex -This text will appear only in the printed manual. -@@end iftex -@@ifinfo -However, this text will appear only in Info. -@@end ifinfo -@end example - -@noindent -The preceding example produces the following line: -@iftex -This text will appear only in the printed manual. -@end iftex -@ifinfo -However, this text will appear only in Info. -@end ifinfo - -@noindent -Note how you only see one of the two lines, depending on whether you -are reading the Info version or the printed version of this -manual.@refill - -The @code{@@titlepage} command is a special variant of @code{@@iftex} that -is used for making the title and copyright pages of the printed -manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill - - -@node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals -@section Conditional Not Commands -@findex ifnothtml -@findex ifnotinfo -@findex ifnottex - -You can specify text to be included in any output format @emph{other} -than some given one with the @code{@@ifnot@dots{}} commands: -@example -@@ifnothtml @dots{} @@end ifnothtml -@@ifnotinfo @dots{} @@end ifnotinfo -@@ifnottex @dots{} @@end ifnottex -@end example -@noindent -(The @code{@@ifnot@dots{}} command and the @code{@@end} command must -actually appear on lines by themselves.) - -If the output file is not being made for the given format, the region is -included. Otherwise, it is ignored. - -The regions delimited by these commands are ordinary Texinfo source as -with @code{@@iftex}, not raw formatter source as with @code{@@tex}. - - -@node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals -@section Raw Formatter Commands -@cindex @TeX{} commands, using ordinary -@cindex HTML commands, using ordinary -@cindex Raw formatter commands -@cindex Ordinary @TeX{} commands, using -@cindex Ordinary HTML commands, using -@cindex Commands using raw @TeX{} -@cindex Commands using raw HTML -@cindex plain @TeX{} - -Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you -can embed some raw @TeX{} commands. Info will ignore these commands -since they are only in that part of the file which is seen by @TeX{}. -You can write the @TeX{} commands as you would write them in a normal -@TeX{} file, except that you must replace the @samp{\} used by @TeX{} -with an @samp{@@}. For example, in the @code{@@titlepage} section of a -Texinfo file, you can use the @TeX{} command @code{@@vskip} to format -the copyright page. (The @code{@@titlepage} command causes Info to -ignore the region automatically, as it does with the @code{@@iftex} -command.) - -However, many features of plain @TeX{} will not work, as they are -overridden by Texinfo features. - -@findex tex -You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} -commands, by delineating a region with the @code{@@tex} and @code{@@end -tex} commands. (The @code{@@tex} command also causes Info to ignore the -region, like the @code{@@iftex} command.) The sole exception is that -@code{@@} chracter still introduces a command, so that @code{@@end tex} -can be recognized properly. - -@cindex Mathematical expressions -For example, here is a mathematical expression written in -plain @TeX{}: - -@example -@@tex -$$ \chi^2 = \sum_@{i=1@}^N - \left (y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@@end tex -@end example - -@noindent -The output of this example will appear only in a printed manual. If -you are reading this in Info, you will not see the equation that appears -in the printed manual. -@iftex -In a printed manual, the above expression looks like -this: -@end iftex - -@tex -$$ \chi^2 = \sum_{i=1}^N - \left(y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@end tex - -@findex ifhtml -@findex html -Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit -a region to be included in HTML output only, and @code{@@html @dots{} -@@end ifhtml} for a region of raw HTML (again, except that @code{@@} is -still the escape character, so the @code{@@end} command can be -recognized.) - - -@node set clear value, , Raw Formatter Commands, Conditionals -@comment node-name, next, previous, up -@section @code{@@set}, @code{@@clear}, and @code{@@value} - -You can direct the Texinfo formatting commands to format or ignore parts -of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, -and @code{@@ifclear} commands.@refill - -In addition, you can use the @code{@@set @var{flag}} command to set the -value of @var{flag} to a string of characters; and use -@code{@@value@{@var{flag}@}} to insert that string. You can use -@code{@@set}, for example, to set a date and use @code{@@value} to -insert the date in several places in the Texinfo file.@refill - -@menu -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. -@end menu - - -@node ifset ifclear, value, set clear value, set clear value -@subsection @code{@@ifset} and @code{@@ifclear} - -@findex ifset -When a @var{flag} is set, the Texinfo formatting commands format text -between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end -ifset} commands. When the @var{flag} is cleared, the Texinfo formatting -commands do @emph{not} format the text. - -Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a -@var{flag}; a @dfn{flag} can be any single word. The format for the -command looks like this:@refill -@findex set - -@example -@@set @var{flag} -@end example - -Write the conditionally formatted text between @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, like this:@refill - -@example -@group -@@ifset @var{flag} -@var{conditional-text} -@@end ifset -@end group -@end example - -For example, you can create one document that has two variants, such as -a manual for a `large' and `small' model:@refill - -@example -You can use this machine to dig up shrubs -without hurting them. - -@@set large - -@@ifset large -It can also dig up fully grown trees. -@@end ifset - -Remember to replant promptly @dots{} -@end example - -@noindent -In the example, the formatting commands will format the text between -@code{@@ifset large} and @code{@@end ifset} because the @code{large} -flag is set.@refill - -@findex clear -Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear}, -a flag. Clearing a flag is the opposite of setting a flag. The -command looks like this:@refill - -@example -@@clear @var{flag} -@end example - -@noindent -Write the command on a line of its own. - -When @var{flag} is cleared, the Texinfo formatting commands do -@emph{not} format the text between @code{@@ifset @var{flag}} and -@code{@@end ifset}; that text is ignored and does not appear in either -printed or Info output.@refill - -For example, if you clear the flag of the preceding example by writing -an @code{@@clear large} command after the @code{@@set large} command -(but before the conditional text), then the Texinfo formatting commands -ignore the text between the @code{@@ifset large} and @code{@@end ifset} -commands. In the formatted output, that text does not appear; in both -printed and Info output, you see only the lines that say, ``You can use -this machine to dig up shrubs without hurting them. Remember to replant -promptly @dots{}''. - -@findex ifclear -If a flag is cleared with an @code{@@clear @var{flag}} command, then -the formatting commands format text between subsequent pairs of -@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag -is set with @code{@@set @var{flag}}, then the formatting commands do -@emph{not} format text between an @code{@@ifclear} and an @code{@@end -ifclear} command; rather, they ignore that text. An @code{@@ifclear} -command looks like this:@refill - -@example -@@ifclear @var{flag} -@end example - -@need 700 -In brief, the commands are:@refill - -@table @code -@item @@set @var{flag} -Tell the Texinfo formatting commands that @var{flag} is set.@refill - -@item @@clear @var{flag} -Tell the Texinfo formatting commands that @var{flag} is cleared.@refill - -@item @@ifset @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to format -the text up to the following @code{@@end ifset} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -ignore text up to the following @code{@@end ifset} command.@refill - -@item @@ifclear @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to ignore -the text up to the following @code{@@end ifclear} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -format the text up to the following @code{@@end ifclear} -command.@refill -@end table - -@node value, value Example, ifset ifclear, set clear value -@subsection @code{@@value} -@findex value - -You can use the @code{@@set} command to specify a value for a flag, -which is expanded by the @code{@@value} command. The value is a string -a characters. - -Write the @code{@@set} command like this: - -@example -@@set foo This is a string. -@end example - -@noindent -This sets the value of @code{foo} to ``This is a string.'' - -The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with -the string to which @var{flag} is set.@refill - -Thus, when @code{foo} is set as shown above, the Texinfo formatters convert - -@example -@group -@@value@{foo@} -@exdent @r{to} -This is a string. -@end group -@end example - -You can write an @code{@@value} command within a paragraph; but you -must write an @code{@@set} command on a line of its own. - -If you write the @code{@@set} command like this: - -@example -@@set foo -@end example - -@noindent -without specifying a string, the value of @code{foo} is an empty string. - -If you clear a previously set flag with an @code{@@clear @var{flag}} -command, a subsequent @code{@@value@{flag@}} command is invalid and the -string is replaced with an error message that says @samp{@{No value for -"@var{flag}"@}}. - -For example, if you set @code{foo} as follows:@refill - -@example -@@set how-much very, very, very -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{how-much@} wet day. -@exdent @r{into} -It is a very, very, very wet day. -@end group -@end example - -If you write - -@example -@@clear how-much -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{how-much@} wet day. -@exdent @r{into} -It is a @{No value for "how-much"@} wet day. -@end group -@end example - -@node value Example, , value, set clear value -@subsection @code{@@value} Example - -You can use the @code{@@value} command to limit the number of places you -need to change when you record an update to a manual. -Here is how it is done in @cite{The GNU Make Manual}: - -@need 1000 -@noindent -Set the flags: - -@example -@group -@@set EDITION 0.35 Beta -@@set VERSION 3.63 Beta -@@set UPDATED 14 August 1992 -@@set UPDATE-MONTH August 1992 -@end group -@end example - -@need 750 -@noindent -Write text for the first @code{@@ifinfo} section, for people reading the -Texinfo file: - -@example -@group -This is Edition @@value@{EDITION@}, -last updated @@value@{UPDATED@}, -of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, Version @@value@{VERSION@}. -@end group -@end example - -@need 1000 -@noindent -Write text for the title page, for people reading the printed manual: -@c List only the month and the year since that looks less fussy on a -@c printed cover than a date that lists the day as well. - -@example -@group -@@title GNU Make -@@subtitle A Program for Directing Recompilation -@@subtitle Edition @@value@{EDITION@}, @dots{} -@@subtitle @@value@{UPDATE-MONTH@} -@end group -@end example - -@noindent -(On a printed cover, a date listing the month and the year looks less -fussy than a date listing the day as well as the month and year.) - -@need 750 -@noindent -Write text for the Top node, for people reading the Info file: - -@example -@group -This is Edition @@value@{EDITION@} -of the @@cite@{GNU Make Manual@}, -last updated @@value@{UPDATED@} -for @@code@{make@} Version @@value@{VERSION@}. -@end group -@end example - -@need 950 -After you format the manual, the text in the first @code{@@ifinfo} -section looks like this: - -@example -@group -This is Edition 0.35 Beta, last updated 14 August 1992, -of `The GNU Make Manual', for `make', Version 3.63 Beta. -@end group -@end example - -When you update the manual, change only the values of the flags; you do -not need to rewrite the three sections. - - -@node Macros, Format/Print Hardcopy, Conditionals, Top -@chapter Macros: Defining New Texinfo Commands -@cindex Macros -@cindex Defining new Texinfo commands -@cindex New Texinfo commands, defining -@cindex Texinfo commands, defining new -@cindex User-defined Texinfo commands - -A Texinfo @dfn{macro} allows you to define a new Texinfo command as any -sequence of text and/or existing commands (including other macros). The -macro can have any number of @dfn{parameters}---text you supply each -time you use the macro. (This has nothing to do with the -@code{@@defmac} command, which is for documenting macros in the subject -of the manual; @pxref{Def Cmd Template}.) - -@menu -* Defining Macros:: Both defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -@end menu - - -@node Defining Macros, Invoking Macros, Macros, Macros -@section Defining Macros -@cindex Defining macros -@cindex Macro definitions - -@findex macro -You use the Texinfo @code{@@macro} command to define a macro. For example: - -@example -@@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@} -@var{text} @dots{} \@var{param1}\ @dots{} -@@end macro -@end example - -The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to -arguments supplied when the macro is subsequently used in the document -(see the next section). - -If a macro needs no parameters, you can define it either with an empty -list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro -foo}). - -@cindex Body of a macro -@cindex Mutually recursive macros -@cindex Recursion, mutual -The definition or @dfn{body} of the macro can contain any Texinfo -commands, including previously-defined macros. (It is not possible to -have mutually recursive Texinfo macros.) In the body, instances of a -parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in -the example above, are replaced by the corresponding argument from the -macro invocation. - -@findex unmacro -@cindex Macros, undefining -@cindex Undefining macros -You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. -It is not an error to undefine a macro that is already undefined. -For example: - -@example -@@unmacro foo -@end example - - -@node Invoking Macros, , Defining Macros, Macros -@section Invoking Macros -@cindex Invoking macros -@cindex Macro invocation - -After a macro is defined (see the previous section), you can use -(@dfn{invoke}) it in your document like this: - -@example -@@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@} -@end example - -@noindent and the result will be just as if you typed the body of -@var{macro-name} at that spot. For example: - -@example -@@macro foo @{p, q@} -Together: \p\ & \q\. -@@end macro -@@foo@{a, b@} -@end example - -@noindent produces: - -@display -Together: a & b. -@end display - -@cindex Backslash, and macros -Thus, the arguments and parameters are separated by commas and delimited -by braces; any whitespace after (but not before) a comma is ignored. To -insert a comma, brace, or backslash in an argument, prepend a backslash, -as in - -@example -@@@var{macro-name} @{\\\@{\@}\,@} -@end example - -@noindent -which will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macro-name}. - -If the macro is defined to take a single argument, and is invoked -without any braces, the entire rest of the line after the macro name is -supplied as the argument. For example: - -@example -@@macro bar @{p@} -Twice: \p\, \p\. -@@end macro -@@bar aah -@end example - -@noindent produces: - -@display -Twice: aah, aah. -@end display - - -@node Format/Print Hardcopy, Create an Info File, Macros, Top -@comment node-name, next, previous, up -@chapter Format and Print Hardcopy -@cindex Format and print hardcopy -@cindex Hardcopy, printing it -@cindex Making a printed manual -@cindex Sorting indices -@cindex Indices, sorting -@cindex @TeX{} index sorting -@pindex texindex - -There are three major shell commands for making a printed manual from a -Texinfo file: one for converting the Texinfo file into a file that will be -printed, a second for sorting indices, and a third for printing the -formatted document. When you use the shell commands, you can either -work directly in the operating system shell or work within a shell -inside GNU Emacs.@refill - -If you are using GNU Emacs, you can use commands provided by Texinfo -mode instead of shell commands. In addition to the three commands to -format a file, sort the indices, and print the result, Texinfo mode -offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue.@refill - -@menu -* Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format in a shell. -* Format with texi2dvi:: A simpler way to use the shell. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What you need to do to use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -@end menu - -@node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy -@ifinfo -@heading Use @TeX{} -@end ifinfo - -The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, if used right, -does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain -@TeX{}}, for information on how to obtain @TeX{}.) - -The @code{makeinfo}, @code{texinfo-format-region}, and -@code{texinfo-format-buffer} commands read the very same @@-commands -in the Texinfo file as does @TeX{}, but process them differently to -make an Info file; see @ref{Create an Info File}.@refill - -@node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format using @code{tex} and @code{texindex} -@cindex Shell formatting with @code{tex} and @code{texindex} -@cindex Formatting with @code{tex} and @code{texindex} -@cindex DVI file - -Format the Texinfo file with the shell command @code{tex} followed by -the name of the Texinfo file. For example: - -@example -tex foo.texi -@end example - -@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary -files containing information for indices, cross references, etc. The -DVI file (for @dfn{DeVice Independent} file) can be printed on virtually -any printe (see the following sections). - -@pindex texindex -The @code{tex} formatting command itself does not sort the indices; it -writes an output file of unsorted index data. (The @code{texi2dvi} -command automatically generates indices; see @ref{Format with texi2dvi,, -Format using @code{texi2dvi}}.) To generate a printed index after -running the @code{tex} command, you first need a sorted index to work -from. The @code{texindex} command sorts indices. (The source file -@file{texindex.c} comes as part of the standard Texinfo distribution, -among other places.)@refill - -@cindex Names of index files -The @code{tex} formatting command outputs unsorted index files under -names that obey a standard convention: the name of your main input file -with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c, -Web2c}) extension removed, followed by the two letter names of indices. -For example, the raw index output files for the input file -@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn}, -@file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the -arguments to give to @code{texindex}.@refill - -@need 1000 -@cindex Wildcards -@cindex Globbing -Instead of specifying all the unsorted index file names explicitly, you -can use @samp{??} as shell wildcards and give the command in this -form:@refill - -@example -texindex foo.?? -@end example - -@noindent -This command will run @code{texindex} on all the unsorted index files, -including any that you have defined yourself using @code{@@defindex} -or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} -even if there are similarly named files with two letter extensions -that are not index files, such as @samp{foo.el}. The @code{texindex} -command reports but otherwise ignores such files.)@refill - -For each file specified, @code{texindex} generates a sorted index file -whose name is made by appending @samp{s} to the input file name. The -@code{@@printindex} command knows to look for a file of that name -(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the -raw index output file.@refill - -After you have sorted the indices, you need to rerun the @code{tex} -formatting command on the Texinfo file. This regenerates the DVI file, -this time with up-to-date index entries. - -Finally, you may need to run @code{tex} one more time, to get the page -numbers in the cross-references correct. - -To summarize, this is a four step process: - -@enumerate -@item -Run @code{tex} on your Texinfo file. This generates a DVI file (with -undefined cross-references and no indices), and the raw index files -(with two letter extensions). - -@item -Run @code{texindex} on the raw index files. This creates the -corresponding sorted index files (with three letter extensions). - -@item -Run @code{tex} again on your Texinfo file. This regenerates the DVI -file, this time with indices and defined cross-references, but with page -numbers for the cross-references from last time, generally incorrect. - -@item -Run @code{tex} one last time. This time the correct page numbers are -written for the cross-references. -@end enumerate - -@pindex texi2dvi -Alternatively, it's a one-step process: run @code{texi2dvi}. - -You need not run @code{texindex} each time after you run @code{tex}. If -you do not, on the next run, the @code{tex} formatting command will use -whatever sorted index files happen to exist from the previous use of -@code{texindex}. This is usually ok while you are -debugging.@refill - -@node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format using @code{texi2dvi} -@pindex texi2dvi @r{(shell script)} - -The @code{texi2dvi} command is a shell script that automatically runs -both @code{tex} and @code{texindex} as many times as necessary to -produce a DVI file with up-to-date, sorted indices. It simplifies the -@code{tex}---@code{texindex}---@code{tex} sequence described in the -previous section. - -@need 1000 -The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is the -shell prompt):@refill - -@example -prompt$ @kbd{texi2dvi @var{filename}@dots{}} -@end example - -@node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Shell Print Using @code{lpr -d} -@pindex lpr @r{(DVI print command)} - -The precise command to print a DVI file depends on your system -installation, but @samp{lpr -d} is common. The command may require the -DVI file name without any extension or with a @samp{.dvi} -extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.) - -The following commands, for example, will (probably) suffice to sort the -indices, format, and print the @cite{Bison Manual}: - -@example -@group -tex bison.texinfo -texindex bison.?? -tex bison.texinfo -lpr -d bison.dvi -@end group -@end example - -@noindent -(Remember that the shell commands may be different at your site; but -these are commonly used versions.)@refill - -@need 1000 -Using the @code{texi2dvi} shell script, you simply need type:@refill - -@example -@group -texi2dvi bison.texinfo -lpr -d bison.dvi -@end group -@end example - -@node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy -@comment node-name, next, previous, up -@section From an Emacs Shell -@cindex Print, format from Emacs shell -@cindex Format, print from Emacs shell -@cindex Shell, format, print from -@cindex Emacs shell, format, print from -@cindex GNU Emacs shell, format, print from - -You can give formatting and printing commands from a shell within GNU -Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Format/Print -Hardcopy, , Format and Print Hardcopy}, for details.@refill - -You can switch to and from the shell buffer while @code{tex} is -running and do other editing. If you are formatting a long document -on a slow machine, this can be very convenient.@refill - -You can also use @code{texi2dvi} from an Emacs shell. For example, -here is how to use @code{texi2dvi} to format and print @cite{Using and -Porting GNU CC} from a shell within Emacs: - -@example -@group -texi2dvi gcc.texinfo -lpr -d gcc.dvi -@end group -@end example -@ifinfo - -@xref{Texinfo Mode Printing}, for more information about formatting -and printing in Texinfo mode.@refill -@end ifinfo - -@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy -@section Formatting and Printing in Texinfo Mode -@cindex Region printing in Texinfo mode -@cindex Format and print in Texinfo mode -@cindex Print and format in Texinfo mode - -Texinfo mode provides several predefined key commands for @TeX{} -formatting and printing. These include commands for sorting indices, -looking at the printer queue, killing the formatting job, and -recentering the display of the buffer in which the operations -occur.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -Run @code{texi2dvi} on the current buffer.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -Run @TeX{} on the current region.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}.@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -Print a DVI file that was made with @code{texinfo-tex-region} or -@code{texinfo-tex-buffer}.@refill - -@item C-c C-t C-q -@itemx M-x tex-show-print-queue -Show the print queue.@refill - -@item C-c C-t C-d -@itemx M-x texinfo-delete-from-print-queue -Delete a job from the print queue; you will be prompted for the job -number shown by a preceding @kbd{C-c C-t C-q} command -(@code{texinfo-show-tex-print-queue}).@refill - -@item C-c C-t C-k -@itemx M-x tex-kill-job -Kill the currently running @TeX{} job started by -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other -process running in the Texinfo shell buffer.@refill - -@item C-c C-t C-x -@itemx M-x texinfo-quit-job -Quit a @TeX{} formatting job that has stopped because of an error by -sending an @key{x} to it. When you do this, @TeX{} preserves a record -of what it did in a @file{.log} file.@refill - -@item C-c C-t C-l -@itemx M-x tex-recenter-output-buffer -Redisplay the shell buffer in which the @TeX{} printing and formatting -commands are run to show its most recent output.@refill -@end table - -@need 1000 -Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right):@refill - -@example -@group -C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} -C-c C-t C-p @r{Print the DVI file.} -C-c C-t C-q @r{Display the printer queue.} -@end group -@end example - -The Texinfo mode @TeX{} formatting commands start a subshell in Emacs -called the @file{*tex-shell*}. The @code{texinfo-tex-command}, -@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} -commands are all run in this shell. - -You can watch the commands operate in the @samp{*tex-shell*} buffer, -and you can switch to and from and use the @samp{*tex-shell*} buffer -as you would any other shell buffer.@refill - -@need 1500 -The formatting and print commands depend on the values of several variables. -The default values are:@refill - -@example -@group - @r{Variable} @r{Default value} - -texinfo-texi2dvi-command "texi2dvi" -texinfo-tex-command "tex" -texinfo-texindex-command "texindex" -texinfo-delete-from-print-queue-command "lprm" -texinfo-tex-trailer "@@bye" -tex-start-of-header "%**start" -tex-end-of-header "%**end" -tex-dvi-print-command "lpr -d" -tex-show-queue-command "lpq" -@end group -@end example - -You can change the values of these variables with the @kbd{M-x -edit-options} command (@pxref{Edit Options, , Editing Variable Values, -emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command -(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU -Emacs Manual}), or with your @file{.emacs} initialization file -(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill - -@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Using the Local Variables List -@cindex Local variables -@cindex Compile command for formatting -@cindex Format with the compile command - -Yet another way to apply the @TeX{} formatting command to a Texinfo file -is to put that command in a @dfn{local variables list} at the end of the -Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} -commands as a @code{compile-command} and have Emacs run it by typing -@kbd{M-x compile}. This creates a special shell called the -@file{*compilation*} buffer in which Emacs runs the compile command. -For example, at the end of the @file{gdb.texinfo} file, after the -@code{@@bye}, you could put the following:@refill - -@example -@group -Local Variables: -compile-command: "texi2dvi gdb.texinfo" -End: -@end group -@end example - -@noindent -This technique is most often used by programmers who also compile programs -this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill - - -@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy -@comment node-name, next, previous, up -@section @TeX{} Formatting Requirements Summary -@cindex Requirements for formatting -@cindex Minimal requirements for formatting -@cindex Formatting requirements - -Every Texinfo file that is to be input to @TeX{} must begin with a -@code{\input} command and must contain an @code{@@setfilename} command: - -@example -\input texinfo -@@setfilename @var{arg-not-used-by-@TeX{}} -@end example - -@noindent -The first command instructs @TeX{} to load the macros it needs to -process a Texinfo file and the second command opens auxiliary files. - -Every Texinfo file must end with a line that terminates @TeX{}'s -processing and forces out unfinished pages: - -@example -@@bye -@end example - -Strictly speaking, these lines are all a Texinfo file needs to be -processed successfully by @TeX{}. - -Usually, however, the beginning includes an @code{@@settitle} command to -define the title of the printed manual, an @code{@@setchapternewpage} -command, a title page, a copyright page, and permissions. Besides an -@code{@@bye}, the end of a file usually includes indices and a table of -contents. (And of course most manuals contain a body of text as well.) - -@iftex -For more information, see -@ref{settitle, , @code{@@settitle}}, -@ref{setchapternewpage, , @code{@@setchapternewpage}}, -@ref{Headings, ,Page Headings}, -@ref{Titlepage & Copyright Page}, -@ref{Printing Indices & Menus}, and -@ref{Contents}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{settitle, , @code{@@settitle}},@* -@ref{setchapternewpage, , @code{@@setchapternewpage}},@* -@ref{Headings, ,Page Headings},@* -@ref{Titlepage & Copyright Page},@* -@ref{Printing Indices & Menus}, and@* -@ref{Contents}. -@end ifinfo - - -@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Preparing to Use @TeX{} -@cindex Preparing to use @TeX{} -@cindex @TeX{} input initialization -@cindex @code{TEXINPUTS} environment variable -@vindex TEXINPUTS -@cindex @b{.profile} initialization file -@cindex @b{.cshrc} initialization file -@cindex Initialization file for @TeX{} input - -@TeX{} needs to know where to find the @file{texinfo.tex} file that you -have told it to input with the @samp{\input texinfo} command at the -beginning of the first line. The @file{texinfo.tex} file tells @TeX{} -how to handle @@-commands; it is included in all standard GNU -distributions. - -@pindex texinfo.tex@r{, installing} -Usually, the @file{texinfo.tex} file is put under the default directory -that contains @TeX{} macros -(@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when -GNU Emacs or other GNU software is installed. In this case, @TeX{} will -find the file and you do not need to do anything special. -Alternatively, you can put @file{texinfo.tex} in the current directory -when you run @TeX{}, and @TeX{} will find it there. - -@pindex epsf.tex@r{, installing} -Also, you should install @file{epsf.tex} in the same place as -@file{texinfo.tex}, if it is not already installed from another -distribution. This file is needed to support the @code{@@image} command -(@pxref{Images}). - -@pindex texinfo.cnf @r{installation} -@cindex Customizing of @TeX{} for Texinfo -@cindex Site-wide Texinfo configuration file -Optionally, you may create an additional @file{texinfo.cnf}, and install -it as well. This file is read by @TeX{} at the @code{@@setfilename} -command (@pxref{setfilename,, @code{@@setfilename}}). You can put any -commands you like there according to local site-wide conventions, and -they will be read by @TeX{} when processing any Texinfo document. For -example, if @file{texinfo.cnf} contains the a single line -@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will -be processed with that page size in effect. If you have nothing to put -in @file{texinfo.cnf}, you do not need to create it. - -@vindex TEXINPUTS -If neither of the above locations for these system files suffice for -you, you can specify the directories explicitly. For -@file{texinfo.tex}, you can do this by writing the complete path for the -file after the @code{\input} command. Another way, that works for both -@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} -might read), is to set the @code{TEXINPUTS} environment variable in your -@file{.cshrc} or @file{.profile} file. - -Which you use of @file{.cshrc} or @file{.profile} depends on -whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, -@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) -command interpreter. The latter read the @file{.cshrc} file for -initialization information, and the former read @file{.profile}. - -In a @file{.cshrc} file, you could use the following @code{csh} command -sequence: - -@example -setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros -@end example - -@need 1000 -In a @file{.profile} file, you could use the following @code{sh} command -sequence: - -@example -@group -TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros -export TEXINPUTS -@end group -@end example - -@noindent -This would cause @TeX{} to look for @file{\input} file first in the current -directory, indicated by the @samp{.}, then in a hypothetical user's -@file{me/mylib} directory, and finally in a system directory. - - -@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Overfull ``hboxes'' -@cindex Overfull @samp{hboxes} -@cindex @samp{hboxes}, overfull -@cindex Final output - -@TeX{} is sometimes unable to typeset a line without extending it into -the right margin. This can occur when @TeX{} comes upon what it -interprets as a long word that it cannot hyphenate, such as an -electronic mail network address or a very long title. When this -happens, @TeX{} prints an error message like this:@refill - -@example -Overfull \hbox (20.76302pt too wide) -@end example - -@noindent -(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. -The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill - -@TeX{} also provides the line number in the Texinfo source file and -the text of the offending line, which is marked at all the places that -@TeX{} knows how to hyphenate words. -@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -for more information about typesetting errors.@refill - -If the Texinfo file has an overfull hbox, you can rewrite the sentence -so the overfull hbox does not occur, or you can decide to leave it. A -small excursion into the right margin often does not matter and may not -even be noticeable.@refill - -@cindex Black rectangle in hardcopy -@cindex Rectangle, ugly, black in hardcopy -However, unless told otherwise, @TeX{} will print a large, ugly, black -rectangle beside the line that contains the overfull hbox. This is so -you will notice the location of the problem if you are correcting a -draft.@refill - -@need 1000 -@findex finalout -To prevent such a monstrosity from marring your final printout, write -the following in the beginning of the Texinfo file on a line of its own, -before the @code{@@titlepage} command:@refill - -@example -@@finalout -@end example - -@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Printing ``Small'' Books -@findex smallbook -@cindex Small book size -@cindex Book, printing small -@cindex Page sizes for books -@cindex Size of printed book - -By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch -format. However, you can direct @TeX{} to typeset a document in a 7 by -9.25 inch format that is suitable for bound books by inserting the -following command on a line by itself at the beginning of the Texinfo -file, before the title page:@refill - -@example -@@smallbook -@end example - -@noindent -(Since regular sized books are often about 7 by 9.25 inches, this -command might better have been called the @code{@@regularbooksize} -command, but it came to be called the @code{@@smallbook} command by -comparison to the 8.5 by 11 inch format.)@refill - -If you write the @code{@@smallbook} command between the -start-of-header and end-of-header lines, the Texinfo mode @TeX{} -region formatting command, @code{texinfo-tex-region}, will format the -region in ``small'' book size (@pxref{Start of Header}).@refill - -The Free Software Foundation distributes printed copies of @cite{The GNU -Emacs Manual} and other manuals in the ``small'' book size. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}, for information about commands that make it easier -to produce examples for a smaller manual.@refill - -Alternatively, to avoid embedding this physical paper size in your -document, use @code{texi2dvi} to format your document (@pxref{Format -with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then -other people do not have to change the document source file to format it -differently. - - -@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Printing on A4 Paper -@cindex A4 paper, printing on -@cindex Paper size, European A4 -@cindex European A4 paper -@findex afourpaper - -You can tell @TeX{} to typeset a document for printing on European size -A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself between @code{@@iftex} and @code{@@end iftex} lines near -the beginning of the Texinfo file, before the title page:@refill - -For example, this is how you would write the header for this manual:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename texinfo -@@settitle Texinfo -@@syncodeindex vr fn -@@iftex -@@afourpaper -@@end iftex -@@c %**end of header -@end group -@end example - -Alternatively, to avoid embedding this physical paper size in your -document, use @code{texi2dvi} to format your document (@pxref{Format -with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then -other people do not have to change the document source file to format it -differently. - -@pindex texinfo.cnf -Another alternative: put the @code{@@afourpaper} command in the file -@file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex} -there.) This will automatically typeset all the Texinfo documents at -your site with that paper size in effect. - - -@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Cropmarks and Magnification - -@findex cropmarks -@cindex Cropmarks for printing -@cindex Printing cropmarks -You can attempt to direct @TeX{} to print cropmarks at the corners of -pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} -command on a line by itself between @code{@@iftex} and @code{@@end -iftex} lines near the beginning of the Texinfo file, before the title -page, like this:@refill - -@example -@group -@@iftex -@@cropmarks -@@end iftex -@end group -@end example - -This command is mainly for printers that typeset several pages on one -sheet of film; but you can attempt to use it to mark the corners of a -book set to 7 by 9.25 inches with the @code{@@smallbook} command. -(Printers will not produce cropmarks for regular sized output that is -printed on regular sized paper.) Since different printing machines work -in different ways, you should explore the use of this command with a -spirit of adventure. You may have to redefine the command in the -@file{texinfo.tex} definitions file.@refill - -@findex mag @r{(@TeX{} command)} -@cindex Magnified printing -@cindex Larger or smaller pages -You can attempt to direct @TeX{} to typeset pages larger or smaller than -usual with the @code{\mag} @TeX{} command. Everything that is typeset -is scaled proportionally larger or smaller. (@code{\mag} stands for -``magnification''.) This is @emph{not} a Texinfo @@-command, but is a -plain @TeX{} command that is prefixed with a backslash. You have to -write this command between @code{@@tex} and @code{@@end tex} -(@pxref{Raw Formatter Commands}). - -Follow the @code{\mag} command with an @samp{=} and then a number that -is 1000 times the magnification you desire. For example, to print pages -at 1.2 normal size, write the following near the beginning of the -Texinfo file, before the title page:@refill - -@example -@group -@@tex -\mag=1200 -@@end tex -@end group -@end example - -With some printing technologies, you can print normal-sized copies that -look better than usual by using a larger-than-normal master.@refill - -Depending on your system, @code{\mag} may not work or may work only at -certain magnifications. Be prepared to experiment.@refill - -@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top -@comment node-name, next, previous, up -@chapter Creating an Info File -@cindex Creating an Info file -@cindex Info, creating an on-line file -@cindex Formatting a file for Info - -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same.@refill - -A Texinfo file must contain an @code{@@setfilename} line near its -beginning, otherwise the Info formatting commands will fail. - -For information on installing the Info file in the Info system, see -@ref{Install an Info File}.@refill - -@menu -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. -@end menu - -@node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File -@ifinfo -@heading @code{makeinfo} Preferred -@end ifinfo - -The @code{makeinfo} utility creates an Info file from a Texinfo source -file more quickly than either of the Emacs formatting commands and -provides better error messages. We recommend it. @code{makeinfo} is a -C program that is independent of Emacs. You do not need to run Emacs to -use @code{makeinfo}, which means you can use @code{makeinfo} on machines -that are too small to run Emacs. You can run @code{makeinfo} in -any one of three ways: from an operating system shell, from a shell -inside Emacs, or by typing a key command in Texinfo mode in Emacs. -@refill - -The @code{texinfo-format-region} and the @code{texinfo-format-buffer} -commands are useful if you cannot run @code{makeinfo}. Also, in some -circumstances, they format short regions or buffers more quickly than -@code{makeinfo}.@refill - -@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File -@section Running @code{makeinfo} from a Shell - -To create an Info file from a Texinfo file, type @code{makeinfo} -followed by the name of the Texinfo file. Thus, to create the Info -file for Bison, type the following to the shell: -is the prompt):@refill - -@example -makeinfo bison.texinfo -@end example - -(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill - -@ifinfo -Sometimes you will want to specify options. For example, if you wish -to discover which version of @code{makeinfo} you are using, -type:@refill - -@example -makeinfo --version -@end example - -@xref{makeinfo options}, for more information. -@end ifinfo - - -@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File -@comment node-name, next, previous, up -@section Options for @code{makeinfo} -@cindex @code{makeinfo} options -@cindex Options for @code{makeinfo} - -The @code{makeinfo} command takes a number of options. Most often, -options are used to set the value of the fill column and specify the -footnote style. Each command line option is a word preceded by -@samp{--} or a letter preceded by @samp{-}. You can use abbreviations -for the long option names as long as they are unique.@refill - -For example, you could use the following shell command to create an Info -file for @file{bison.texinfo} in which each line is filled to only 68 -columns:@refill - -@example -makeinfo --fill-column=68 bison.texinfo -@end example - -You can write two or more options in sequence, like this:@refill - -@example -makeinfo --no-split --fill-column=70 @dots{} -@end example - -@noindent -This would keep the Info file together as one possibly very long -file and would also set the fill column to 70.@refill - -The options are: - -@table @code - -@item -D @var{var} -@opindex -D @var{var} -Cause the variable @var{var} to be defined. This is equivalent to -@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}). - -@item --error-limit=@var{limit} -@opindex --error-limit=@var{limit} -Set the maximum number of errors that @code{makeinfo} will report -before exiting (on the assumption that continuing would be useless); -default 100. - -@need 150 -@item --fill-column=@var{width} -@opindex --fill-column=@var{width} -Specify the maximum number of columns in a line; this is the right-hand -edge of a line. Paragraphs that are filled will be filled to this -width. (Filling is the process of breaking up and connecting lines so -that lines are the same length as or shorter than the number specified -as the fill column. Lines are broken between words.) The default value -is 72. - -@item --footnote-style=@var{style} -@opindex --footnote-style=@var{style} -Set the footnote style to @var{style}, either @samp{end} for the end -node style (the default) or @samp{separate} for the separate node style. -The value set by this option overrides the value set in a Texinfo file -by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the -footnote style is @samp{separate}, @code{makeinfo} makes a new node -containing the footnotes found in the current node. When the footnote -style is @samp{end}, @code{makeinfo} places the footnote references at -the end of the current node. - -@item --force -@opindex --force -Ordinarily, if the input file has errors, the output files are not -created. With this option, they are preserved. - -@item --help -@opindex --help -Print a usage message listing all available options, then exit successfully. - -@item -I @var{dir} -@opindex -I @var{dir} -Add @code{dir} to the directory search list for finding files that are -included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. - -@item --no-headers -@opindex --no-headers -Do not include menus or node lines in the output. This results in an -@sc{ascii} file that you cannot read in Info since it does not contain -the requisite nodes or menus. It is primarily useful to extract certain -pieces of a manual into separate files to be included in a distribution, -such as @file{INSTALL} files. - -@item --no-split -@opindex --no-split -Suppress the splitting stage of @code{makeinfo}. By default, large -output files (where the size is greater than 70k bytes) are split into -smaller subfiles, each one approximately 50k bytes. - -@item --no-pointer-validate -@itemx --no-validate -@opindex --no-pointer-validate -@opindex --no-validate -Suppress the pointer-validation phase of @code{makeinfo}. Normally, -after a Texinfo file is processed, some consistency checks are made to -ensure that cross references can be resolved, etc. -@xref{Pointer Validation}.@refill - -@item --no-warn -@opindex --no-warn -Suppress warning messages (but @emph{not} error messages). You might -want this if the file you are creating has examples of Texinfo cross -references within it, and the nodes that are referenced do not actually -exist. - -@item --no-number-footnotes -@opindex --no-number-footnotes -Suppress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@item --output=@var{file} -@itemx -o @var{file} -@opindex --output=@var{file} -@opindex -o @var{file} -Specify that the output should be directed to @var{file} and not to the -file name specified in the @code{@@setfilename} command found in the -Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output -goes to standard output and @samp{--no-split} is implied. - -@item -P @var{dir} -@opindex -P @var{dir} -Prepend @code{dir} to the directory search list for @code{@@include}. -See @samp{-I} for more details. - -@item --paragraph-indent=@var{indent} -@opindex --paragraph-indent=@var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command (@pxref{paragraphindent}). The value -of @var{indent} is interpreted as follows: - -@table @asis -@item @samp{asis} -Preserve any existing indentation at the starts of paragraphs. - -@item @samp{0} or @samp{none} -Delete any existing indentation. - -@item @var{num} -Indent each paragraph by that number of spaces. -@end table - -@item --reference-limit=@var{limit} -@opindex --reference-limit=@var{limit} -Set the value of the number of references to a node that -@code{makeinfo} will make without reporting a warning. If a node has more -than this number of references in it, @code{makeinfo} will make the -references but also report a warning. The default is 1000. - -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to -@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}). - -@item --verbose -@opindex --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -Normally, @code{makeinfo} only outputs messages if there are errors or -warnings. - -@item --version -@opindex --version -Print the version number, then exit successfully. - -@end table - - -@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File -@section Pointer Validation -@cindex Pointer validation with @code{makeinfo} -@cindex Validation of pointers - -If you do not suppress pointer-validation, @code{makeinfo} will check -the validity of the final Info file. Mostly, this means ensuring that -nodes you have referenced really exist. Here is a complete list of what -is checked:@refill - -@enumerate -@item -If a `Next', `Previous', or `Up' node reference is a reference to a -node in the current file and is not an external reference such as to -@file{(dir)}, then the referenced node must exist.@refill - -@item -In every node, if the `Previous' node is different from the `Up' node, -then the `Previous' node must also be pointed to by a `Next' node.@refill - -@item -Every node except the `Top' node must have an `Up' pointer.@refill - -@item -The node referenced by an `Up' pointer must contain a reference to the -current node in some manner other than through a `Next' reference. -This includes menu entries and cross references.@refill - -@item -If the `Next' reference of a node is not the same as the `Next' reference -of the `Up' reference, then the node referenced by the `Next' pointer -must have a `Previous' pointer that points back to the current node. -This rule allows the last node in a section to point to the first node -of the next chapter.@refill -@end enumerate - -@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File -@section Running @code{makeinfo} inside Emacs -@cindex Running @code{makeinfo} in Emacs -@cindex @code{makeinfo} inside Emacs -@cindex Shell, running @code{makeinfo} in - -You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the -@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In -Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c -C-m C-b} by default.@refill - -@table @kbd -@item C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@findex makeinfo-region - -@item C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@findex makeinfo-buffer -@end table - -When you invoke either @code{makeinfo-region} or -@code{makeinfo-buffer}, Emacs prompts for a file name, offering the -name of the visited file as the default. You can edit the default -file name in the minibuffer if you wish, before pressing @key{RET} to -start the @code{makeinfo} process.@refill - -The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands -run the @code{makeinfo} program in a temporary shell buffer. If -@code{makeinfo} finds any errors, Emacs displays the error messages in -the temporary buffer.@refill - -@cindex Errors, parsing -@cindex Parsing errors -@findex next-error -You can parse the error messages by typing @kbd{C-x `} -(@code{next-error}). This causes Emacs to go to and position the -cursor on the line in the Texinfo source that @code{makeinfo} thinks -caused the error. @xref{Compilation, , Running @code{make} or -Compilers Generally, emacs, The GNU Emacs Manual}, for more -information about using the @code{next-error} command.@refill - -In addition, you can kill the shell in which the @code{makeinfo} -command is running or make the shell buffer display its most recent -output.@refill - -@table @kbd -@item C-c C-m C-k -@itemx M-x makeinfo-kill-job -@findex makeinfo-kill-job -Kill the current running @code{makeinfo} job created by -@code{makeinfo-region} or @code{makeinfo-buffer}.@refill - -@item C-c C-m C-l -@itemx M-x makeinfo-recenter-output-buffer -@findex makeinfo-recenter-output-buffer -Redisplay the @code{makeinfo} shell buffer to display its most recent -output.@refill -@end table - -@noindent -(Note that the parallel commands for killing and recentering a @TeX{} -job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode -Printing}.)@refill - -You can specify options for @code{makeinfo} by setting the -@code{makeinfo-options} variable with either the @kbd{M-x -edit-options} or the @kbd{M-x set-variable} command, or by setting the -variable in your @file{.emacs} initialization file.@refill - -For example, you could write the following in your @file{.emacs} file:@refill - -@example -@group -(setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") -@end group -@end example - -@c If you write these three cross references using xref, you see -@c three references to the same named manual, which looks strange. -@iftex -For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and -Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs -Manual}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* -@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* -@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* -@ref{makeinfo options, , Options for @code{makeinfo}}. -@end ifinfo - -@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File -@comment node-name, next, previous, up -@section The @code{texinfo-format@dots{}} Commands -@findex texinfo-format-region -@findex texinfo-format-buffer - -In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo -file with the @code{texinfo-format-region} command. This formats the -current region and displays the formatted text in a temporary buffer -called @samp{*Info Region*}.@refill - -Similarly, you can format a buffer with the -@code{texinfo-format-buffer} command. This command creates a new -buffer and generates the Info file in it. Typing @kbd{C-x C-s} will -save the Info file under the name specified by the -@code{@@setfilename} line which must be near the beginning of the -Texinfo file.@refill - -@table @kbd -@item C-c C-e C-r -@itemx @code{texinfo-format-region} -Format the current region for Info. -@findex texinfo-format-region - -@item C-c C-e C-b -@itemx @code{texinfo-format-buffer} -Format the current buffer for Info. -@findex texinfo-format-buffer -@end table - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands provide you with some error checking, and other functions can -provide you with further help in finding formatting errors. These -procedures are described in an appendix; see @ref{Catching Mistakes}. -However, the @code{makeinfo} program is often faster and -provides better error checking (@pxref{makeinfo in Emacs}).@refill - -@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File -@comment node-name, next, previous, up -@section Batch Formatting -@cindex Batch formatting for Info -@cindex Info batch formatting - -You can format Texinfo files for Info using @code{batch-texinfo-format} -and Emacs Batch mode. You can run Emacs in Batch mode from any shell, -including a shell inside of Emacs. (@xref{Command Switches, , Command -Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill - -Here is a shell command to format all the files that end in -@file{.texinfo} in the current directory: - -@example -emacs -batch -funcall batch-texinfo-format *.texinfo -@end example - -@noindent -Emacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them.@refill - -Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; -it is not interactive. It kills the Batch mode Emacs on completion.@refill - -@code{batch-texinfo-format} is convenient if you lack @code{makeinfo} -and want to format several Texinfo files at once. When you use Batch -mode, you create a new Emacs process. This frees your current Emacs, so -you can continue working in it. (When you run -@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot -use that Emacs for anything else until the command finishes.)@refill - -@node Tag and Split Files, , Batch Formatting, Create an Info File -@comment node-name, next, previous, up -@section Tag Files and Split Files -@cindex Making a tag table automatically -@cindex Tag table, making automatically - -If a Texinfo file has more than 30,000 bytes, -@code{texinfo-format-buffer} automatically creates a tag table -for its Info file; @code{makeinfo} always creates a tag table. With -a @dfn{tag table}, Info can jump to new nodes more quickly than it can -otherwise.@refill - -@cindex Indirect subfiles -In addition, if the Texinfo file contains more than about 70,000 -bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the -large Info file into shorter @dfn{indirect} subfiles of about 50,000 -bytes each. Big files are split into smaller files so that Emacs does -not need to make a large buffer to hold the whole of a large Info -file; instead, Emacs allocates just enough memory for the small, split -off file that is needed at the time. This way, Emacs avoids wasting -memory when you run Info. (Before splitting was implemented, Info -files were always kept short and @dfn{include files} were designed as -a way to create a single, large printed manual out of the smaller Info -files. @xref{Include Files}, for more information. Include files are -still used for very large documents, such as @cite{The Emacs Lisp -Reference Manual}, in which each chapter is a separate file.)@refill - -When a file is split, Info itself makes use of a shortened version of -the original file that contains just the tag table and references to -the files that were split off. The split off files are called -@dfn{indirect} files.@refill - -The split off files have names that are created by appending @w{@samp{-1}}, -@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the -@code{@@setfilename} command. The shortened version of the original file -continues to have the name specified by @code{@@setfilename}.@refill - -At one stage in writing this document, for example, the Info file was saved -as @file{test-texinfo} and that file looked like this:@refill - -@example -@group -Info file: test-texinfo, -*-Text-*- -produced by texinfo-format-buffer -from file: new-texinfo-manual.texinfo - -^_ -Indirect: -test-texinfo-1: 102 -test-texinfo-2: 50422 -@end group -@group -test-texinfo-3: 101300 -^_^L -Tag table: -(Indirect) -Node: overview^?104 -Node: info file^?1271 -@end group -@group -Node: printed manual^?4853 -Node: conventions^?6855 -@dots{} -@end group -@end example - -@noindent -(But @file{test-texinfo} had far more nodes than are shown here.) Each of -the split off, indirect files, @file{test-texinfo-1}, -@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file -after the line that says @samp{Indirect:}. The tag table is listed after -the line that says @samp{Tag table:}. @refill - -In the list of indirect files, the number following the file name -records the cumulative number of bytes in the preceding indirect files, -not counting the file list itself, the tag table, or the permissions -text in each file. In the tag table, the number following the node name -records the location of the beginning of the node, in bytes from the -beginning.@refill - -If you are using @code{texinfo-format-buffer} to create Info files, -you may want to run the @code{Info-validate} command. (The -@code{makeinfo} command does such a good job on its own, you do not -need @code{Info-validate}.) However, you cannot run the @kbd{M-x -Info-validate} node-checking command on indirect files. For -information on how to prevent files from being split and how to -validate the structure of the nodes, see @ref{Using -Info-validate}.@refill - - -@node Install an Info File, Command List, Create an Info File, Top -@comment node-name, next, previous, up -@chapter Installing an Info File -@cindex Installing an Info file -@cindex Info file installation -@cindex @file{dir} directory for Info installation - -Info files are usually kept in the @file{info} directory. You can read -Info files using the standalone Info program or the Info reader built -into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) - -@menu -* Directory file:: The top level menu for all Info files. -* New Info File:: Listing a new info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: @code{install-info} options. -@end menu - -@node Directory file, New Info File, Install an Info File, Install an Info File -@ifinfo -@heading The @file{dir} File -@end ifinfo - -For Info to work, the @file{info} directory must contain a file that -serves as a top level directory for the Info system. By convention, -this file is called @file{dir}. (You can find the location of this file -within Emacs by typing @kbd{C-h i} to enter Info and then typing -@kbd{C-x C-f} to see the pathname to the @file{info} directory.) - -The @file{dir} file is itself an Info file. It contains the top level -menu for all the Info files in the system. The menu looks like -this:@refill - -@example -@group -* Menu: - -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -* Texinfo: (texinfo). With one source file, make - either a printed manual using - TeX or an Info file. -@dots{} -@end group -@end example - -Each of these menu entries points to the `Top' node of the Info file -that is named in parentheses. (The menu entry does not need to -specify the `Top' node, since Info goes to the `Top' node if no node -name is mentioned. @xref{Other Info Files, , Nodes in Other Info -Files}.)@refill - -Thus, the @samp{Info} entry points to the `Top' node of the -@file{info} file and the @samp{Emacs} entry points to the `Top' node -of the @file{emacs} file.@refill - -In each of the Info files, the `Up' pointer of the `Top' node refers -back to the @code{dir} file. For example, the line for the `Top' -node of the Emacs manual looks like this in Info:@refill - -@example -File: emacs Node: Top, Up: (DIR), Next: Distrib -@end example - -@noindent -(Note that in this case, the @file{dir} file name is written in upper -case letters---it can be written in either upper or lower case. Info -has a feature that it will change the case of the file name to lower -case if it cannot find the name as written.)@refill -@c !!! Can any file name be written in upper or lower case, -@c or is dir a special case? -@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 - - -@node New Info File, Other Info Directories, Directory file, Install an Info File -@section Listing a New Info File -@cindex Adding a new info file -@cindex Listing a new info file -@cindex New info file, listing it in @file{dir} file -@cindex Info file, listing new one -@cindex @file{dir} file listing - -To add a new Info file to your system, you must write a menu entry to -add to the menu in the @file{dir} file in the @file{info} directory. -For example, if you were adding documentation for GDB, you would write -the following new entry:@refill - -@example -* GDB: (gdb). The source-level C debugger. -@end example - -@noindent -The first part of the menu entry is the menu entry name, followed by a -colon. The second part is the name of the Info file, in parentheses, -followed by a period. The third part is the description. - -The name of an Info file often has a @file{.info} extension. Thus, the -Info file for GDB might be called either @file{gdb} or @file{gdb.info}. -The Info reader programs automatically try the file name both with and -without @file{.info}; so it is better to avoid clutter and not to write -@samp{.info} explicitly in the menu entry. For example, the GDB menu -entry should use just @samp{gdb} for the file name, not @samp{gdb.info}. - - -@node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File -@comment node-name, next, previous, up -@section Info Files in Other Directories -@cindex Installing Info in another directory -@cindex Info installed in another directory -@cindex Another Info directory - -If an Info file is not in the @file{info} directory, there are three -ways to specify its location:@refill - -@itemize @bullet -@item -Write the pathname in the @file{dir} file as the second part of the -menu.@refill - -@item -If you are using Emacs, list the name of the file in a second @file{dir} -file, in its directory; and then add the name of that directory to the -@code{Info-directory-list} variable in your personal or site -initialization file. - -This tells Emacs where to look for @file{dir} files. Emacs merges the -files named @file{dir} from each of the listed directories. (In Emacs -version 18, you can set the @code{Info-directory} variable to the name -of only one directory.)@refill - -@item -Specify the Info directory name in the @code{INFOPATH} environment -variable in your @file{.profile} or @file{.cshrc} initialization file. -(Only you and others who set this environment variable will be able to -find Info files whose location is specified this way.)@refill -@end itemize - -For example, to reach a test file in the @file{/home/bob/manuals} -directory, you could add an entry like this to the menu in the -@file{dir} file:@refill - -@example -* Test: (/home/bob/manuals/info-test). Bob's own test file. -@end example - -@noindent -In this case, the absolute file name of the @file{info-test} file is -written as the second part of the menu entry.@refill - -@vindex Info-directory-list -Alternatively, you could write the following in your @file{.emacs} -file:@refill - -@example -@group -(setq Info-directory-list - '("/home/bob/manuals" - "/usr/local/info")) -@end group -@end example - -@c reworded to avoid overfill hbox -This tells Emacs to merge the @file{dir} file from the -@file{/home/bob/manuals} directory with the @file{dir} file from the -@file{/usr/local/info} directory. Info will list the -@file{/home/bob/manuals/info-test} file as a menu entry in the -@file{/home/bob/manuals/dir} file.@refill - -@vindex INFOPATH -Finally, you can tell Info where to look by setting the @code{INFOPATH} -environment variable in your @file{.cshrc} or @file{.profile} file. If -you use a Bourne-compatible shell such as @code{sh} or @code{bash} for -your shell command interpreter, you set the @code{INFOPATH} environment -variable in the @file{.profile} initialization file; but if you use -@code{csh} or @code{tcsh}, you must set the variable in the -@file{.cshrc} initialization file. The two types of shells use -different syntax. - -@itemize @bullet -@item -In a @file{.cshrc} file, you could set the @code{INFOPATH} -variable as follows:@refill - -@smallexample -setenv INFOPATH .:~/manuals:/usr/local/emacs/info -@end smallexample - -@item -In a @file{.profile} file, you would achieve the same effect by -writing:@refill - -@smallexample -INFOPATH=.:$HOME/manuals:/usr/local/emacs/info -export INFOPATH -@end smallexample -@end itemize - -@noindent -The @samp{.} indicates the current directory as usual. Emacs uses the -@code{INFOPATH} environment variable to initialize the value of Emacs's -own @code{Info-directory-list} variable. - -@cindex @samp{:} @r{last in @code{INFOPATH}} -However you set @code{INFOPATH}, if its last character is a colon, this -is replaced by the default (compiled-in) path. This gives you a way to -augment the default path with new directories without having to list all -the standard places. For example (using @code{sh} syntax: - -@example -INFOPATH=/local/info: -export INFOPATH -@end example - -@noindent -will search @file{/local/info} first, then the standard directories. -Leading or doubled colons are not treated specially. - - -@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File -@section Installing Info Directory Files - -When you install an Info file onto your system, you can use the program -@code{install-info} to update the Info directory file @file{dir}. -Normally the makefile for the package runs @code{install-info}, just -after copying the Info file into its proper installed location. - -@findex dircategory -@findex direntry -In order for the Info file to work with @code{install-info}, you should -use the commands @code{@@dircategory} and @code{@@direntry} in the -Texinfo source file. Use @code{@@direntry} to specify the menu entry to -add to the Info directory file, and use @code{@@dircategory} to specify -which part of the Info directory to put it in. Here is how these -commands are used in this manual: - -@smallexample -@@dircategory Texinfo documentation system -@@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -@@end direntry -@end smallexample - -Here's what this produces in the Info file: - -@smallexample -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -END-INFO-DIR-ENTRY -@end smallexample - -@noindent -The @code{install-info} program sees these lines in the Info file, and -that is how it knows what to do. - -Always use the @code{@@direntry} and @code{@@dircategory} commands near -the beginning of the Texinfo input, before the first @code{@@node} -command. If you use them later on in the input, @code{install-info} -will not notice them. - -If you use @code{@@dircategory} more than once in the Texinfo source, -each usage specifies one category; the new menu entry is added to the -Info directory file in each of the categories you specify. If you use -@code{@@direntry} more than once, each usage specifies one menu entry; -each of these menu entries is added to the directory in each of the -specified categories. - - -@node Invoking install-info, , Installing Dir Entries, Install an Info File -@section Invoking install-info - -@pindex install-info - -@code{install-info} inserts menu entries from an Info file into the -top-level @file{dir} file in the Info system (see the previous sections -for an explanation of how the @file{dir} file works). It's most often -run as part of software installation, or when constructing a dir file -for all manuals on a system. Synopsis: - -@example -install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] -@end example - -If @var{info-file} or @var{dir-file} are not specified, the various -options (described below) that define them must be. There are no -compile-time defaults, and standard input is never used. -@code{install-info} can read only one info file and write only one dir -file per invocation. - -@cindex @file{dir}, created by @code{install-info} -If @var{dir-file} (however specified) does not exist, -@code{install-info} creates it if possible (with no entries). - -Options: - -@table @code -@item --delete -@opindex --delete -Delete the entries in @var{info-file} from @var{dir-file}. The file -name in the entry in @var{dir-file} must be @var{info-file} (except for -an optional @samp{.info} in either one). Don't insert any new entries. - -@item --dir-file=@var{name} -@opindex --dir-file=@var{name} -Specify file name of the Info directory file. This is equivalent to -using the @var{dir-file} argument. - -@item --entry=@var{text} -@opindex --entry=@var{text} -Insert @var{text} as an Info directory entry; @var{text} should have the -form of an Info menu item line plus zero or more extra lines starting -with whitespace. If you specify more than one entry, they are all -added. If you don't specify any entries, they are determined from -information in the Info file itself. - -@item --help -@opindex --help -Display a usage message listing basic usage and all available options, -then exit successfully. - -@item --info-file=@var{file} -@opindex --info-file=@var{file} -Specify Info file to install in the directory. -This is equivalent to using the @var{info-file} argument. - -@item --info-dir=@var{dir} -@opindex --info-dir=@var{dir} -Equivalent to @samp{--dir-file=@var{dir}/dir}. - -@item --item=@var{text} -@opindex --item=@var{text} -Same as @samp{--entry=@var{text}}. An Info directory entry is actually -a menu item. - -@item --quiet -@opindex --quiet -Suppress warnings. - -@item --remove -@opindex --remove -Same as @samp{--delete}. - -@item --section=@var{sec} -@opindex --section=@var{sec} -Put this file's entries in section @var{sec} of the directory. If you -specify more than one section, all the entries are added in each of the -sections. If you don't specify any sections, they are determined from -information in the Info file itself. - -@item --version -@opindex --version -@cindex version number, finding -Display version information and exit successfully. - -@end table - - -@node Command List, Tips, Install an Info File, Top -@appendix @@-Command List -@cindex Alphabetical @@-command list -@cindex List of @@-commands -@cindex @@-command list - -Here is an alphabetical list of the @@-commands in Texinfo. Square -brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, -@samp{@dots{}}, indicates repeated text.@refill - -@sp 1 -@table @code -@item @@@var{whitespace} -An @code{@@} followed by a space, tab, or newline produces a normal, -stretchable, interword space. @xref{Multiple Spaces}. - -@item @@! -Generate an exclamation point that really does end a sentence (usually -after an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@" -@itemx @@' -Generate an umlaut or acute accent, respectively, over the next -character, as in @"o and @'o. @xref{Inserting Accents}. - -@item @@* -Force a line break. Do not end a paragraph that uses @code{@@*} with -an @code{@@refill} command. @xref{Line Breaks}.@refill - -@item @@,@{@var{c}@} -Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting -Accents}. - -@item @@- -Insert a discretionary hyphenation point. @xref{- and hyphenation}. - -@item @@. -Produce a period that really does end a sentence (usually after an -end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@: -Indicate to @TeX{} that an immediately preceding period, question -mark, exclamation mark, or colon does not end a sentence. Prevent -@TeX{} from inserting extra whitespace as it does at the end of a -sentence. The command has no effect on the Info file output. -@xref{Not Ending a Sentence}.@refill - -@item @@= -Generate a macro (bar) accent over the next character, as in @=o. -@xref{Inserting Accents}. - -@item @@? -Generate a question mark that really does end a sentence (usually after -an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@@@ -Stands for an at sign, @samp{@@}. -@xref{Braces Atsigns, , Inserting @@ and braces}. - -@item @@^ -@itemx @@` -Generate a circumflex (hat) or grave accent, respectively, over the next -character, as in @^o. -@xref{Inserting Accents}. - -@item @@@{ -Stands for a left brace, @samp{@{}. -@xref{Braces Atsigns, , Inserting @@ and braces}. - -@item @@@} -Stands for a right-hand brace, @samp{@}}.@* -@xref{Braces Atsigns, , Inserting @@ and braces}. - -@item @@= -Generate a tilde accent over the next character, as in @~N. -@xref{Inserting Accents}. - -@item @@AA@{@} -@itemx @@aa@{@} -Generate the uppercase and lowercase Scandinavian A-ring letters, -respectively: @AA{}, @aa{}. @xref{Inserting Accents}. - -@item @@AE@{@} -@itemx @@ae@{@} -Generate the uppercase and lowercase AE ligatures, respectively: -@AE{}, @ae{}. @xref{Inserting Accents}. - -@item @@afourpaper -Change page dimensions for the A4 paper size. -Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}. -@xref{A4 Paper}. - -@item @@appendix @var{title} -Begin an appendix. The title appears in the table -of contents of a printed manual. In Info, the title is -underlined with asterisks. @xref{unnumbered & appendix, , The -@code{@@unnumbered} and @code{@@appendix} Commands}.@refill - -@item @@appendixsec @var{title} -@itemx @@appendixsection @var{title} -Begin an appendix section within an appendix. The section title appears -in the table of contents of a printed manual. In Info, the title is -underlined with equal signs. @code{@@appendixsection} is a longer -spelling of the @code{@@appendixsec} command. @xref{unnumberedsec -appendixsec heading, , Section Commands}.@refill - -@item @@appendixsubsec @var{title} -Begin an appendix subsection within an appendix. The title appears -in the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , Subsection Commands}.@refill - -@item @@appendixsubsubsec @var{title} -Begin an appendix subsubsection within an appendix subsection. The -title appears in the table of contents of a printed manual. In Info, -the title is underlined with periods. @xref{subsubsection,, The -`subsub' Commands}.@refill - -@item @@asis -Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to -print the table's first column without highlighting (``as is''). -@xref{Two-column Tables, , Making a Two-column Table}.@refill - -@item @@author @var{author} -Typeset @var{author} flushleft and underline it. @xref{title -subtitle author, , The @code{@@title} and @code{@@author} -Commands}.@refill - -@item @@b@{@var{text}@} -Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill - -@ignore -@item @@br -Force a paragraph break. If used within a line, follow @code{@@br} -with braces. @xref{br, , @code{@@br}}.@refill -@end ignore - -@item @@bullet@{@} -Generate a large round dot, or the closest possible -thing to one. @xref{bullet, , @code{@@bullet}}.@refill - -@item @@bye -Stop formatting a file. The formatters do not see the contents of a -file following an @code{@@bye} command. @xref{Ending a File}.@refill - -@item @@c @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -either the Info file or the printed manual. A synonym for -@code{@@comment}. @xref{Comments, , Comments}.@refill - -@item @@cartouche -Highlight an example or quotation by drawing a box with rounded -corners around it. Pair with @code{@@end cartouche}. No effect in -Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@item @@center @var{line-of-text} -Center the line of text following the command. -@xref{titlefont center sp, , @code{@@center}}.@refill - -@item @@centerchap @var{line-of-text} -Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, -@code{@@chapter}}. - -@item @@chapheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{majorheading & chapheading, , @code{@@majorheading} -and @code{@@chapheading}}.@refill - -@item @@chapter @var{title} -Begin a chapter. The chapter title appears in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{chapter, , @code{@@chapter}}.@refill - -@item @@cindex @var{entry} -Add @var{entry} to the index of concepts. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@cite@{@var{reference}@} -Highlight the name of a book or other reference that lacks a -companion Info file. @xref{cite, , @code{@@cite}}.@refill - -@item @@clear @var{flag} -Unset @var{flag}, preventing the Texinfo formatting commands from -formatting text between subsequent pairs of @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, and preventing -@code{@@value@{@var{flag}@}} from expanding to the value to which -@var{flag} is set. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@code@{@var{sample-code}@} -Highlight text that is an expression, a syntactically complete token -of a program, or a program name. @xref{code, , @code{@@code}}.@refill - -@item @@comment @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -either the Info file or the printed manual. A synonym for @code{@@c}. -@xref{Comments, , Comments}.@refill - -@item @@contents -Print a complete table of contents. Has no effect in Info, which uses -menus instead. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@copyright@{@} -Generate a copyright symbol. @xref{copyright symbol, , -@code{@@copyright}}.@refill - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Describe an @sc{ascii} control character. Insert actual control character -into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill -@end ignore - -@item @@defcodeindex @var{index-name} -Define a new index and its indexing command. Print entries in an -@code{@@code} font. @xref{New Indices, , Defining New -Indices}.@refill - -@item @@defcv @var{category} @var{class} @var{name} -@itemx @@defcvx @var{category} @var{class} @var{name} -Format a description for a variable associated with a class in -object-oriented programming. Takes three arguments: the category of -thing being defined, the class to which it belongs, and its name. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} -Format a description for a function, interactive command, or similar -entity that may take arguments. @code{@@deffn} takes as arguments the -category of entity being described, the name of this particular -entity, and its arguments, if any. @xref{Definition Commands}.@refill - -@item @@defindex @var{index-name} -Define a new index and its indexing command. Print entries in a roman -font. @xref{New Indices, , Defining New Indices}.@refill - -@c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96. -@item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -Create new @@-command for Info that marks text by enclosing it in -strings that precede and follow the text. Write definition inside of -@code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized -Highlighting}.@refill - -@item @@defivar @var{class} @var{instance-variable-name} -@itemx @@defivarx @var{class} @var{instance-variable-name} -This command formats a description for an instance variable in -object-oriented programming. The command is equivalent to @samp{@@defcv -@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defmac @var{macro-name} @var{arguments}@dots{} -@itemx @@defmacx @var{macro-name} @var{arguments}@dots{} -Format a description for a macro. The command is equivalent to -@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} -Format a description for a method in object-oriented programming. The -command is equivalent to @samp{@@defop Method @dots{}}. Takes as -arguments the name of the class of the method, the name of the -method, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} -Format a description for an operation in object-oriented programming. -@code{@@defop} takes as arguments the overall name of the category of -operation, the name of the class of the operation, the name of the -operation, and its arguments, if any. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@defopt @var{option-name} -@itemx @@defoptx @var{option-name} -Format a description for a user option. The command is equivalent to -@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defspec @var{special-form-name} @var{arguments}@dots{} -@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} -Format a description for a special form. The command is equivalent to -@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} -Format a description for a data type. @code{@@deftp} takes as arguments -the category, the name of the type (which is a word like @samp{int} or -@samp{float}), and then the names of attributes of objects of that type. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a function or similar entity that may take -arguments and that is typed. @code{@@deftypefn} takes as arguments the -classification of entity being described, the type, the name of the -entity, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} -@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} -Format a description for a function in a typed language. -The command is equivalent to @samp{@@deftypefn Function @dots{}}. -@xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -Format a description for a typed method in object-oriented programming. -Takes as arguments the name of the class of the method, the return type -of the method, the name of the method, and its arguments, if any. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypevr @var{classification} @var{data-type} @var{name} -@itemx @@deftypevrx @var{classification} @var{data-type} @var{name} -Format a description for something like a variable in a typed -language---an entity that records a value. Takes as arguments the -classification of entity being described, the type, and the name of the -entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in -Detail}. - -@item @@deftypevar @var{data-type} @var{variable-name} -@itemx @@deftypevarx @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@defun @var{function-name} @var{arguments}@dots{} -@itemx @@defunx @var{function-name} @var{arguments}@dots{} -Format a description for functions. The command is equivalent to -@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvar @var{variable-name} -@itemx @@defvarx @var{variable-name} -Format a description for variables. The command is equivalent to -@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvr @var{category} @var{name} -@itemx @@defvrx @var{category} @var{name} -Format a description for any kind of variable. @code{@@defvr} takes -as arguments the category of the entity and the name of the entity. -@xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@detailmenu@{@} -Avoid @code{makeinfo} confusion stemming from the detailed node listing -in a master menu. @xref{Master Menu Parts}. - -@item @@dfn@{@var{term}@} -Highlight the introductory or defining use of a term. -@xref{dfn, , @code{@@dfn}}.@refill - -@item @@dircategory @var{dirpart} -Specify a part of the Info directory menu where this file's entry should -go. @xref{Installing Dir Entries}. - -@item @@direntry -Begin the Info directory menu entry for this file. -@xref{Installing Dir Entries}. - -@need 100 -@item @@display -Begin a kind of example. Indent text, do not fill, do not select a -new font. Pair with @code{@@end display}. @xref{display, , -@code{@@display}}.@refill - -@item @@dmn@{@var{dimension}@} -Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a -thin space before @var{dimension}. No effect in Info. -@xref{dmn, , @code{@@dmn}}.@refill - -@item @@dotaccent@{@var{c}@} -Generate a dot accent over the character @var{c}, as in @dotaccent{oo}. -@xref{Inserting Accents}. - -@item @@dots@{@} -Insert an ellipsis: @samp{@dots{}}. -@xref{dots, , @code{@@dots}}.@refill - -@item @@email@{@var{address}[, @var{displayed-text}]@} -Indicate an electronic mail address. -@xref{email, , @code{@@email}}.@refill - -@need 100 -@item @@emph@{@var{text}@} -Highlight @var{text}; text is displayed in @emph{italics} in printed -output, and surrounded by asterisks in Info. @xref{Emphasis, , -Emphasizing Text}. - -@item @@end @var{environment} -Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting -Commands,,@@-commands}. - -@item @@enddots@{@} -Generate an end-of-sentence of ellipsis, like this @enddots{} -@xref{dots,,@code{@@dots@{@}}}. - -@need 100 -@item @@enumerate [@var{number-or-letter}] -Begin a numbered list, using @code{@@item} for each entry. -Optionally, start list with @var{number-or-letter}. Pair with -@code{@@end enumerate}. @xref{enumerate, , -@code{@@enumerate}}.@refill - -@need 100 -@item @@equiv@{@} -Indicate to the reader the exact equivalence of two forms with a -glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill - -@item @@error@{@} -Indicate to the reader with a glyph that the following text is -an error message: @samp{@error{}}. @xref{Error Glyph}.@refill - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for even-numbered (left-hand) -pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, , -How to Make Your Own Headings}.@refill - -@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for every page. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@example -Begin an example. Indent text, do not fill, and select fixed-width font. -Pair with @code{@@end example}. @xref{example, , -@code{@@example}}.@refill - -@item @@exclamdown@{@} -Produce an upside-down exclamation point. @xref{Inserting Accents}. - -@item @@exdent @var{line-of-text} -Remove any indentation a line might have. @xref{exdent, , -Undoing the Indentation of a Line}.@refill - -@item @@expansion@{@} -Indicate the result of a macro expansion to the reader with a special -glyph: @samp{@expansion{}}. -@xref{expansion, , @expansion{} Indicating an Expansion}.@refill - -@item @@file@{@var{filename}@} -Highlight the name of a file, buffer, node, or directory. @xref{file, , -@code{@@file}}.@refill - -@item @@finalout -Prevent @TeX{} from printing large black warning rectangles beside -over-wide lines. @xref{Overfull hboxes}.@refill - -@need 100 -@item @@findex @var{entry} -Add @var{entry} to the index of functions. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@need 200 -@item @@flushleft -@itemx @@flushright -Left justify every line but leave the right end ragged. -Leave font as is. Pair with @code{@@end flushleft}. -@code{@@flushright} analogous. -@xref{flushleft & flushright, , @code{@@flushleft} and -@code{@@flushright}}.@refill - -@need 200 -@item @@footnote@{@var{text-of-footnote}@} -Enter a footnote. Footnote text is printed at the bottom of the page -by @TeX{}; Info may format in either `End' node or `Separate' node style. -@xref{Footnotes}.@refill - -@item @@footnotestyle @var{style} -Specify an Info file's footnote style, either @samp{end} for the end -node style or @samp{separate} for the separate node style. -@xref{Footnotes}.@refill - -@item @@format -Begin a kind of example. Like @code{@@example} or @code{@@display}, -but do not narrow the margins and do not select the fixed-width font. -Pair with @code{@@end format}. @xref{example, , -@code{@@example}}.@refill - -@item @@ftable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of functions. Pair with @code{@@end ftable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@item @@group -Hold text together that must appear on one printed page. Pair with -@code{@@end group}. Not relevant to Info. @xref{group, , -@code{@@group}}.@refill - -@item @@H@{@var{c}@} -Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. - -@item @@heading @var{title} -Print an unnumbered section-like heading in the text, but not in the -table of contents of a printed manual. In Info, the title is -underlined with equal signs. @xref{unnumberedsec appendixsec heading, -, Section Commands}.@refill - -@item @@headings @var{on-off-single-double} -Turn page headings on or off, and/or specify single-sided or double-sided -page headings for printing. @xref{headings on off, , The -@code{@@headings} Command}. - -@item @@html -Enter HTML completely. Pair with @code{@@end html}. @xref{Raw -Formatter Commands}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Explicitly define hyphenation points. @xref{- and hyphenation,, -@code{@@-} and @code{@@hyphenation}}. - -@item @@i@{@var{text}@} -Print @var{text} in @i{italic} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@ifclear @var{flag} -If @var{flag} is cleared, the Texinfo formatting commands format text -between @code{@@ifclear @var{flag}} and the following @code{@@end -ifclear} command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@ifhtml -@itemx @@ifinfo -Begin a stretch of text that will be ignored by @TeX{} when it typesets -the printed manual. The text appears only in the HTML resp.@: Info -file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. -@xref{Conditionals}. - -@item @@ifnothtml -@itemx @@ifnotinfo -@itemx @@ifnottex -Begin a stretch of text that will be ignored in one output format but -not the others. The text appears only in the format not specified. -Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@: -@code{@@end ifnotinfo}. @xref{Conditionals}. - -@item @@ifset @var{flag} -If @var{flag} is set, the Texinfo formatting commands format text -between @code{@@ifset @var{flag}} and the following @code{@@end ifset} -command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@iftex -Begin a stretch of text that will not appear in the Info file, but -will be processed only by @TeX{}. Pair with @code{@@end iftex}. -@xref{Conditionals, , Conditionally Visible Text}.@refill - -@item @@ignore -Begin a stretch of text that will not appear in either the Info file -or the printed output. Pair with @code{@@end ignore}. -@xref{Comments, , Comments and Ignored Text}.@refill - -@item @@image@{@var{filename}, [@var{width}], [@var{height}]@} -Include graphics image in external @var{filename} scaled to the given -@var{width} and/or @var{height}. @xref{Images}. - -@item @@include @var{filename} -Incorporate the contents of the file @var{filename} into the Info file -or printed document. @xref{Include Files}.@refill - -@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} -Make a cross reference to an Info file for which there is no printed -manual. @xref{inforef, , Cross references using -@code{@@inforef}}.@refill - -@item \input @var{macro-definitions-file} -Use the specified macro definitions file. This command is used only -in the first line of a Texinfo file to cause @TeX{} to make use of the -@file{texinfo} macro definitions file. The backslash in @code{\input} -is used instead of an @code{@@} because @TeX{} does not -recognize @code{@@} until after it has read the definitions file. -@xref{Header, , The Texinfo File Header}.@refill - -@item @@item -Indicate the beginning of a marked paragraph for @code{@@itemize} and -@code{@@enumerate}; indicate the beginning of the text of a first column -entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. -@xref{Lists and Tables}.@refill - -@item @@itemize @var{mark-generating-character-or-command} -Produce a sequence of indented paragraphs, with a mark inside the left -margin at the beginning of each paragraph. Pair with @code{@@end -itemize}. @xref{itemize, , @code{@@itemize}}.@refill - -@item @@itemx -Like @code{@@item} but do not generate extra vertical space above the -item text. @xref{itemx, , @code{@@itemx}}.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate text that is characters of input to be typed by -users. @xref{kbd, , @code{@@kbd}}.@refill - -@item @@kbdinputstyle @var{style} -Specify when @code{@@kbd} should use a font distinct from @code{@@code}. -@xref{kbd, , @code{@@kbd}}.@refill - -@item @@key@{@var{key-name}@} -Indicate a name for a key on a keyboard. -@xref{key, , @code{@@key}}.@refill - -@item @@kindex @var{entry} -Add @var{entry} to the index of keys. -@xref{Index Entries, , Defining the Entries of an Index}.@refill - -@item @@L@{@} -@itemx @@l@{@} -Generate the uppercase and lowercase Polish suppressed-L letters, -respectively: @L{}, @l{}. - -@c Possibly this can be tossed now that we have macros. --karl, 16sep96. -@c Yes, let's toss it, it's pretty weird. --karl, 15jun97. -@c @item @@global@@let@var{new-command}=@var{existing-command} -@c Equate a new highlighting command with an existing one. Only for -@c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end -@c iftex}. @xref{Customized Highlighting}.@refill - -@item @@lisp -Begin an example of Lisp code. Indent text, do not fill, and select -fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, , -@code{@@lisp}}.@refill - -@item @@lowersections -Change subsequent chapters to sections, sections to subsections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@item @@macro @var{macro-name} @{@var{params}@} -Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}. -Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining -Macros}. - -@item @@majorheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. Generate more vertical whitespace before -the heading than the @code{@@chapheading} command. In Info, the chapter -heading line is underlined with asterisks. @xref{majorheading & -chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. -@xref{math, , @code{@@math}: Inserting Mathematical Expressions}. - -@item @@menu -Mark the beginning of a menu of nodes in Info. No effect in a printed -manual. Pair with @code{@@end menu}. @xref{Menus}.@refill - -@item @@minus@{@} -Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill - -@item @@multitable @var{column-width-spec} -Begin a multi-column table. Pair with @code{@@end multitable}. -@xref{Multitable Column Widths}. - -@item @@need @var{n} -Start a new page in a printed manual if fewer than @var{n} mils -(thousandths of an inch) remain on the current page. @xref{need, , -@code{@@need}}.@refill - -@item @@node @var{name, next, previous, up} -Define the beginning of a new node in Info, and serve as a locator for -references for @TeX{}. @xref{node, , @code{@@node}}.@refill - -@item @@noindent -Prevent text from being indented as if it were a new paragraph. -@xref{noindent, , @code{@@noindent}}.@refill - -@item @@O@{@} -@itemx @@o@{@} -Generate the uppercase and lowercase O-with-slash letters, respectively: -@O{}, @o{}. - -@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for odd-numbered (right-hand) -pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, , -How to Make Your Own Headings}.@refill - -@item @@OE@{@} -@itemx @@oe@{@} -Generate the uppercase and lowercase OE ligatures, respectively: -@OE{}, @oe{}. @xref{Inserting Accents}. - -@item @@page -Start a new page in a printed manual. No effect in Info. -@xref{page, , @code{@@page}}.@refill - -@item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces; delete indentation -if the value of @var{indent} is 0; and do not change indentation if -@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph -Indenting}.@refill - -@item @@pindex @var{entry} -Add @var{entry} to the index of programs. @xref{Index Entries, , Defining -the Entries of an Index}.@refill - -@item @@point@{@} -Indicate the position of point in a buffer to the reader with a -glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating -Point in a Buffer}.@refill - -@item @@pounds@{@} -Generate the pounds sterling currency sign. -@xref{pounds,,@code{@@pounds@{@}}}. - -@item @@print@{@} -Indicate printed output to the reader with a glyph: -@samp{@print{}}. @xref{Print Glyph}.@refill - -@item @@printindex @var{index-name} -Print an alphabetized two-column index in a printed manual or generate -an alphabetized menu of index entries for Info. @xref{Printing -Indices & Menus}.@refill - -@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with a lower case `see' in a printed -manual. Use within parentheses only. Do not follow command with a -punctuation mark---the Info formatting commands automatically insert -terminating punctuation as needed. Only the first argument is mandatory. -@xref{pxref, , @code{@@pxref}}.@refill - -@item @@questiondown@{@} -Generate an upside-down question mark. @xref{Inserting Accents}. - -@item @@quotation -Narrow the margins to indicate text that is quoted from another real -or imaginary work. Write command on a line of its own. Pair with -@code{@@end quotation}. @xref{quotation, , -@code{@@quotation}}.@refill - -@need 100 -@item @@r@{@var{text}@} -Print @var{text} in @r{roman} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@raisesections -Change subsequent sections to chapters, subsections to sections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@need 300 -@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference. In a printed manual, the reference does not start -with a `See'. Follow command with a punctuation mark. Only the first -argument is mandatory. @xref{ref, , @code{@@ref}}.@refill - -@need 300 -@item @@refill -In Info, refill and indent the paragraph after all the other processing -has been done. No effect on @TeX{}, which always refills. This command -is no longer needed, since all formatters now automatically refill. -@xref{Refilling Paragraphs}.@refill - -@need 300 -@item @@result@{@} -Indicate the result of an expression to the reader with a special -glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill - -@item @@ringaccent@{@var{c}@} -Generate a ring accent over the next character, as in @ringaccent{o}. -@xref{Inserting Accents}. - -@item @@samp@{@var{text}@} -Highlight @var{text} that is a literal example of a sequence of -characters. Used for single characters, for statements, and often for -entire shell commands. @xref{samp, , @code{@@samp}}.@refill - -@item @@sc@{@var{text}@} -Set @var{text} in a printed output in @sc{the small caps font} and -set text in the Info file in uppercase letters. -@xref{Smallcaps}.@refill - -@item @@section @var{title} -Begin a section within a chapter. In a printed manual, the section -title is numbered and appears in the table of contents. In Info, the -title is underlined with equal signs. @xref{section, , -@code{@@section}}.@refill - -@item @@set @var{flag} [@var{string}] -Make @var{flag} active, causing the Texinfo formatting commands to -format text between subsequent pairs of @code{@@ifset @var{flag}} and -@code{@@end ifset} commands. Optionally, set value of @var{flag} to -@var{string}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@setchapternewpage @var{on-off-odd} -Specify whether chapters start on new pages, and if so, whether on -odd-numbered (right-hand) new pages. @xref{setchapternewpage, , -@code{@@setchapternewpage}}.@refill - -@item @@setfilename @var{info-file-name} -Provide a name to be used by the Info file. This command is essential -for @TeX{} formatting as well, even though it produces no output. -@xref{setfilename, , @code{@@setfilename}}.@refill - -@item @@settitle @var{title} -Provide a title for page headers in a printed manual. -@xref{settitle, , @code{@@settitle}}.@refill - -@item @@shortcontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@summarycontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@shorttitlepage@{@var{title}@} -Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. - -@need 400 -@item @@smallbook -Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format. @xref{smallbook, , -Printing Small Books}. Also, see @ref{smallexample & smalllisp, , -@code{@@smallexample} and @code{@@smalllisp}}.@refill - -@need 400 -@item @@smallexample -Indent text to indicate an example. Do not fill, select fixed-width -font. In @code{@@smallbook} format, print text in a smaller font than -with @code{@@example}. Pair with @code{@@end smallexample}. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}.@refill - -@need 400 -@item @@smalllisp -Begin an example of Lisp code. Indent text, do not fill, select -fixed-width font. In @code{@@smallbook} format, print text in a -smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & -smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill - -@need 700 -@item @@sp @var{n} -Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill - -@item @@ss@{@} -Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. - -@need 700 -@item @@strong @var{text} -Emphasize @var{text} by typesetting it in a @strong{bold} font for the -printed manual and by surrounding it with asterisks for Info. -@xref{emph & strong, , Emphasizing Text}.@refill - -@item @@subheading @var{title} -Print an unnumbered subsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@subsection @var{title} -Begin a subsection within a section. In a printed manual, the -subsection title is numbered and appears in the table of contents. In -Info, the title is underlined with hyphens. @xref{subsection, , -@code{@@subsection}}.@refill - -@item @@subsubheading @var{title} -Print an unnumbered subsubsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with periods. @xref{subsubsection, , The `subsub' -Commands}.@refill - -@item @@subsubsection @var{title} -Begin a subsubsection within a subsection. In a printed manual, -the subsubsection title is numbered and appears in the table of -contents. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@subtitle @var{title} -In a printed manual, set a subtitle in a normal sized font flush to -the right-hand side of the page. Not relevant to Info, which does not -have title pages. @xref{title subtitle author, , @code{@@title} -@code{@@subtitle} and @code{@@author} Commands}.@refill - -@item @@summarycontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@shortcontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@need 300 -@item @@syncodeindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument, printing the entries from the first index in -@code{@@code} font. @xref{Combining Indices}.@refill - -@need 300 -@item @@synindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument. Do not change the font of @var{from-index} -entries. @xref{Combining Indices}.@refill - -@need 100 -@item @@t@{@var{text}@} -Print @var{text} in a @t{fixed-width}, typewriter-like font. -No effect in Info. @xref{Fonts}.@refill - -@item @@tab -Separate columns in a multitable. @xref{Multitable Rows}. - -@need 400 -@item @@table @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. Write -each first column entry on the same line as @code{@@item}. First -column entries are printed in the font resulting from -@var{formatting-command}. Pair with @code{@@end table}. -@xref{Two-column Tables, , Making a Two-column Table}. -Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, -and @ref{itemx, , @code{@@itemx}}.@refill - -@item @@TeX@{@} -Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{} -and @copyright{}}.@refill - -@item @@tex -Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw -Formatter Commands}. - -@item @@thischapter -@itemx @@thischaptername -@itemx @@thisfile -@itemx @@thispage -@itemx @@thistitle -Only allowed in a heading or footing. Stands for the number and name of -the current chapter (in the format `Chapter 1: Title'), the chapter name -only, the filename, the current page number, and the title of the -document, respectively. @xref{Custom Headings, , How to Make Your Own -Headings}.@refill - -@item @@tieaccent@{@var{cc}@} -Generate a tie-after accent over the next two characters @var{cc}, as in -`@tieaccent{oo}'. @xref{Inserting Accents}. - -@item @@tindex @var{entry} -Add @var{entry} to the index of data types. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@title @var{title} -In a printed manual, set a title flush to the left-hand side of the -page in a larger than normal font and underline it with a black rule. -Not relevant to Info, which does not have title pages. @xref{title -subtitle author, , The @code{@@title} @code{@@subtitle} and -@code{@@author} Commands}.@refill - -@need 400 -@item @@titlefont@{@var{text}@} -In a printed manual, print @var{text} in a larger than normal font. -Not relevant to Info, which does not have title pages. -@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} -and @code{@@sp} Commands}.@refill - -@need 300 -@item @@titlepage -Indicate to Texinfo the beginning of the title page. Write command on -a line of its own. Pair with @code{@@end titlepage}. Nothing between -@code{@@titlepage} and @code{@@end titlepage} appears in Info. -@xref{titlepage, , @code{@@titlepage}}.@refill - -@need 150 -@item @@today@{@} -Insert the current date, in `1 Jan 1900' style. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@top @var{title} -In a Texinfo file to be formatted with @code{makeinfo}, identify the -topmost @code{@@node} line in the file, which must be written on the line -immediately preceding the @code{@@top} command. Used for -@code{makeinfo}'s node pointer insertion feature. The title is -underlined with asterisks. Both the @code{@@node} line and the @code{@@top} -line normally should be enclosed by @code{@@ifinfo} and @code{@@end -ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo -Pointer Creation, , Creating Pointers with @code{makeinfo}}. - -@item @@u@{@var{c}@} -@itemx @@ubaraccent@{@var{c}@} -@itemx @@udotaccent@{@var{c}@} -Generate a breve, underbar, or underdot accent, respectively, over or -under the character @var{c}, as in @u{o}, @ubaraccent{o}, -@udotaccent{o}. @xref{Inserting Accents}. - -@item @@unnumbered @var{title} -In a printed manual, begin a chapter that appears without chapter -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with asterisks. -@xref{unnumbered & appendix, , @code{@@unnumbered} and -@code{@@appendix}}.@refill - -@item @@unnumberedsec @var{title} -In a printed manual, begin a section that appears without section -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with equal signs. -@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill - -@item @@unnumberedsubsec @var{title} -In a printed manual, begin an unnumbered subsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with hyphens. -@xref{unnumberedsubsec appendixsubsec subheading, , -@code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@unnumberedsubsubsec @var{title} -In a printed manual, begin an unnumbered subsubsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@uref@{@var{url}[, @var{displayed-text}@} -Define a cross reference to an external uniform resource locator for the -World Wide Web. @xref{url, , @code{@@url}}.@refill - -@item @@url@{@var{url}@} -Indicate text that is a uniform resource locator for the World Wide -Web. @xref{url, , @code{@@url}}.@refill - -@item @@v@{@var{c}@} -Generate check accent over the character @var{c}, as in @v{o}. -@xref{Inserting Accents}. - -@item @@value@{@var{flag}@} -Replace @var{flag} with the value to which it is set by @code{@@set -@var{flag}}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Highlight a metasyntactic variable, which is something that stands for -another piece of text. @xref{var, , Indicating Metasyntactic -Variables}.@refill - -@need 400 -@item @@vindex @var{entry} -Add @var{entry} to the index of variables. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@need 400 -@item @@vskip @var{amount} -In a printed manual, insert whitespace so as to push text on the -remainder of the page towards the bottom of the page. Used in -formatting the copyright page with the argument @samp{0pt plus -1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used -only in contexts ignored for Info. @xref{Copyright & Permissions, , -The Copyright Page and Printed Permissions}.@refill - -@need 400 -@item @@vtable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of variables. Pair with @code{@@end vtable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@need 400 -@item @@w@{@var{text}@} -Prevent @var{text} from being split across two lines. Do not end a -paragraph that uses @code{@@w} with an @code{@@refill} command. -@xref{w, , @code{@@w}}.@refill - -@need 400 -@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with `See' in a printed manual. Follow -command with a punctuation mark. Only the first argument is -mandatory. @xref{xref, , @code{@@xref}}.@refill -@end table - - -@node Tips, Sample Texinfo File, Command List, Top -@appendix Tips and Hints - -Here are some tips for writing Texinfo documentation:@refill - -@cindex Tips -@cindex Usage tips -@cindex Hints -@itemize @bullet -@item -Write in the present tense, not in the past or the future. - -@item -Write actively! For example, write ``We recommend that @dots{}'' rather -than ``It is recommended that @dots{}''. - -@item -Use 70 or 72 as your fill column. Longer lines are hard to read. - -@item -Include a copyright notice and copying permissions. -@end itemize - -@subsubheading Index, Index, Index! - -Write many index entries, in different ways. -Readers like indices; they are helpful and convenient. - -Although it is easiest to write index entries as you write the body of -the text, some people prefer to write entries afterwards. In either -case, write an entry before the paragraph to which it applies. This -way, an index entry points to the first page of a paragraph that is -split across pages. - -Here are more hints we have found valuable: - -@itemize @bullet -@item -Write each index entry differently, so each entry refers to a different -place in the document. - -@item -Write index entries only where a topic is discussed significantly. For -example, it is not useful to index ``debugging information'' in a -chapter on reporting bugs. Someone who wants to know about debugging -information will certainly not find it in that chapter. - -@item -Consistently capitalize the first word of every concept index entry, -or else consistently use lower case. Terse entries often call for -lower case; longer entries for capitalization. Whichever case -convention you use, please use one or the other consistently! Mixing -the two styles looks bad. - -@item -Always capitalize or use upper case for those words in an index for -which this is proper, such as names of countries or acronyms. Always -use the appropriate case for case-sensitive names, such as those in C or -Lisp. - -@item -Write the indexing commands that refer to a whole section immediately -after the section command, and write the indexing commands that refer to -the paragraph before the paragraph. - -@need 1000 -In the example that follows, a blank line comes after the index -entry for ``Leaping'': - -@example -@group -@@section The Dog and the Fox -@@cindex Jumping, in general -@@cindex Leaping - -@@cindex Dog, lazy, jumped over -@@cindex Lazy dog jumped over -@@cindex Fox, jumps over dog -@@cindex Quick fox jumps over dog -The quick brown fox jumps over the lazy dog. -@end group -@end example - -@noindent -(Note that the example shows entries for the same concept that are -written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so -readers can look up the concept in different ways.) -@end itemize - -@subsubheading Blank Lines - -@itemize @bullet -@item -Insert a blank line between a sectioning command and the first following -sentence or paragraph, or between the indexing commands associated with -the sectioning command and the first following sentence or paragraph, as -shown in the tip on indexing. Otherwise, a formatter may fold title and -paragraph together. - -@item -Always insert a blank line before an @code{@@table} command and after an -@code{@@end table} command; but never insert a blank line after an -@code{@@table} command or before an @code{@@end table} command. - -@need 1000 -For example, - -@example -@group -Types of fox: - -@@table @@samp -@@item Quick -Jump over lazy dogs. -@end group - -@group -@@item Brown -Also jump over lazy dogs. -@@end table - -@end group -@group -@@noindent -On the other hand, @dots{} -@end group -@end example - -Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end -itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the -same way. -@end itemize - -@subsubheading Complete Phrases - -Complete phrases are easier to read than @dots{} - -@itemize @bullet -@item -Write entries in an itemized list as complete sentences; or at least, as -complete phrases. Incomplete expressions @dots{} awkward @dots{} like -this. - -@item -Write the prefatory sentence or phrase for a multi-item list or table as -a complete expression. Do not write ``You can set:''; instead, write -``You can set these variables:''. The former expression sounds cut off. -@end itemize - -@subsubheading Editions, Dates and Versions - -Write the edition and version numbers and date in three places in every -manual: - -@enumerate -@item -In the first @code{@@ifinfo} section, for people reading the Texinfo file. - -@item -In the @code{@@titlepage} section, for people reading the printed manual. - -@item -In the `Top' node, for people reading the Info file. -@end enumerate - -@noindent -Also, it helps to write a note before the first @code{@@ifinfo} -section to explain what you are doing. - -@need 800 -@noindent -For example: - -@example -@group -@@c ===> NOTE! <== -@@c Specify the edition and version numbers and date -@@c in *three* places: -@@c 1. First ifinfo section 2. title page 3. top node -@@c To find the locations, search for !!set -@end group - -@group -@@ifinfo -@@c !!set edition, date, version -This is Edition 4.03, January 1992, -of the @@cite@{GDB Manual@} for GDB Version 4.3. -@dots{} -@end group -@end example - -@noindent ----or use @code{@@set} and @code{@@value} -(@pxref{value Example, , @code{@@value} Example}). - -@subsubheading Definition Commands - -Definition commands are @code{@@deffn}, @code{@@defun}, -@code{@@defmac}, and the like, and enable you to write descriptions in -a uniform format.@refill - -@itemize @bullet -@item -Write just one definition command for each entity you define with a -definition command. The automatic indexing feature creates an index -entry that leads the reader to the definition. - -@item -Use @code{@@table} @dots{} @code{@@end table} in an appendix that -contains a summary of functions, not @code{@@deffn} or other definition -commands. -@end itemize - -@subsubheading Capitalization - -@itemize @bullet -@item -Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or -@samp{i} in upper case. - -@item -Capitalize ``Info''; it is a name. - -@item -Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase -@samp{T} and @samp{X}. This command causes the formatters to -typeset the name according to the wishes of Donald Knuth, who wrote -@TeX{}. -@end itemize - -@subsubheading Spaces - -Do not use spaces to format a Texinfo file, except inside of -@code{@@example} @dots{} @code{@@end example} and similar commands. - -@need 700 -For example, @TeX{} fills the following: - -@example -@group - @@kbd@{C-x v@} - @@kbd@{M-x vc-next-action@} - Perform the next logical operation - on the version-controlled file - corresponding to the current buffer. -@end group -@end example - -@need 950 -@noindent -so it looks like this: - -@iftex -@quotation - @kbd{C-x v} - @kbd{M-x vc-next-action} - Perform the next logical operation on the version-controlled file - corresponding to the current buffer. -@end quotation -@end iftex -@ifinfo -@quotation -`C-x v' `M-x vc-next-action' Perform the next logical operation on the -version-controlled file corresponding to the current buffer. -@end quotation -@end ifinfo - -@noindent -In this case, the text should be formatted with -@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. - -@subsubheading @@code, @@samp, @@var, and @samp{---} - -@itemize @bullet -@item -Use @code{@@code} around Lisp symbols, including command names. -For example, - -@example -The main function is @@code@{vc-next-action@}, @dots{} -@end example - -@item -Avoid putting letters such as @samp{s} immediately after an -@samp{@@code}. Such letters look bad. - -@item -Use @code{@@var} around meta-variables. Do not write angle brackets -around them. - -@item -Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} -typesets these as a long dash and the Info formatters reduce three -hyphens to two. -@end itemize - -@subsubheading Periods Outside of Quotes - -Place periods and other punctuation marks @emph{outside} of quotations, -unless the punctuation is part of the quotation. This practice goes -against publishing conventions in the United States, but enables the -reader to distinguish between the contents of the quotation and the -whole passage. - -For example, you should write the following sentence with the period -outside the end quotation marks: - -@example -Evidently, @samp{au} is an abbreviation for ``author''. -@end example - -@noindent -since @samp{au} does @emph{not} serve as an abbreviation for -@samp{author.} (with a period following the word). - -@subsubheading Introducing New Terms - -@itemize @bullet -@item -Introduce new terms so that a reader who does not know them can -understand them from context; or write a definition for the term. - -For example, in the following, the terms ``check in'', ``register'' and -``delta'' are all appearing for the first time; the example sentence should be -rewritten so they are understandable. - -@quotation -The major function assists you in checking in a file to your -version control system and registering successive sets of changes to -it as deltas. -@end quotation - -@item -Use the @code{@@dfn} command around a word being introduced, to indicate -that the reader should not expect to know the meaning already, and -should expect to learn the meaning from this passage. -@end itemize - -@subsubheading @@pxref - -@c !!! maybe include this in the tips on pxref -@ignore -By the way, it is okay to use pxref with something else in front of -it within the parens, as long as the pxref is followed by the close -paren, and the material inside the parens is not part of a larger -sentence. Also, you can use xref inside parens as part of a complete -sentence so long as you terminate the cross reference with punctuation. -@end ignore -Absolutely never use @code{@@pxref} except in the special context for -which it is designed: inside parentheses, with the closing parenthesis -following immediately after the closing brace. One formatter -automatically inserts closing punctuation and the other does not. This -means that the output looks right both in printed output and in an Info -file, but only when the command is used inside parentheses. - -@subsubheading Invoking from a Shell - -You can invoke programs such as Emacs, GCC, and @code{gawk} from a -shell. The documentation for each program should contain a section that -describes this. Unfortunately, if the node names and titles for these -sections are all different, readers find it hard to search for the -section.@refill - -Name such sections with a phrase beginning with the word -@w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way -users can find the section easily. - -@subsubheading ANSI C Syntax - -When you use @code{@@example} to describe a C function's calling -conventions, use the ANSI C syntax, like this:@refill - -@example -void dld_init (char *@@var@{path@}); -@end example - -@noindent -And in the subsequent discussion, refer to the argument values by -writing the same argument names, again highlighted with -@code{@@var}.@refill - -@need 800 -Avoid the obsolete style that looks like this:@refill - -@example -#include <dld.h> - -dld_init (path) -char *path; -@end example - -Also, it is best to avoid writing @code{#include} above the -declaration just to indicate that the function is declared in a -header file. The practice may give the misimpression that the -@code{#include} belongs near the declaration of the function. Either -state explicitly which header file holds the declaration or, better -yet, name the header file used for a group of functions at the -beginning of the section that describes the functions.@refill - -@subsubheading Bad Examples - -Here are several examples of bad writing to avoid: - -In this example, say, `` @dots{} you must @code{@@dfn}@{check -in@} the new version.'' That flows better. - -@quotation -When you are done editing the file, you must perform a -@code{@@dfn}@{check in@}. -@end quotation - -In the following example, say, ``@dots{} makes a unified interface such as VC -mode possible.'' - -@quotation -SCCS, RCS and other version-control systems all perform similar -functions in broadly similar ways (it is this resemblance which makes -a unified control mode like this possible). -@end quotation - -And in this example, you should specify what `it' refers to: - -@quotation -If you are working with other people, it assists in coordinating -everyone's changes so they do not step on each other. -@end quotation - -@subsubheading And Finally @dots{} - -@itemize @bullet -@item -Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last -sound in the name `Bach'. But pronounce Texinfo as in `speck': -``teckinfo''. - -@item -Write notes for yourself at the very end of a Texinfo file after the -@code{@@bye}. None of the formatters process text after the -@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} -@code{@@end ignore}. -@end itemize - - -@node Sample Texinfo File, Sample Permissions, Tips, Top -@appendix A Sample Texinfo File -@cindex Sample Texinfo file, no comments - -Here is a complete, short sample Texinfo file, without any commentary. -You can see this file, with comments, in the first chapter. -@xref{Short Sample, , A Short Sample Texinfo File}. - -@sp 1 -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header - -@@setchapternewpage odd - -@@ifinfo -This is a short example of a complete Texinfo file. - -Copyright 1990 Free Software Foundation, Inc. -@@end ifinfo - -@@titlepage -@@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} - -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage - -@@node Top, First Chapter, , (dir) -@@comment node-name, next, previous, up - -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Concept Index:: This index has two entries. -@@end menu - -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Sample index entry - -This is the contents of the first chapter. -@@cindex Another sample index entry - -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate - -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. - -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp - -@@contents -@@bye -@end example - - -@node Sample Permissions, Include Files, Sample Texinfo File, Top -@appendix Sample Permissions -@cindex Permissions -@cindex Copying permissions - -Texinfo files should contain sections that tell the readers that they -have the right to copy and distribute the Texinfo file, the Info file, -and the printed manual.@refill - -Also, if you are writing a manual about software, you should explain -that the software is free and either include the GNU General Public -License (GPL) or provide a reference to it. @xref{Distrib, , -Distribution, emacs, The GNU Emacs Manual}, for an example of the text -that could be used in the software ``Distribution'', ``General Public -License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, -, Texinfo Copying Conditions}, for an example of a brief explanation -of how the copying conditions provide you with rights. @refill - -@menu -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. -@end menu - -@node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions -@ifinfo -@appendixsec Inserting Permissions -@end ifinfo - -In a Texinfo file, the first @code{@@ifinfo} section usually begins -with a line that says what the file documents. This is what a person -reading the unprocessed Texinfo file or using the advanced Info -command @kbd{g *} sees first. @inforef{Expert, Advanced Info -commands, info}, for more information. (A reader using the regular -Info commands usually starts reading at the first node and skips -this first section, which is not in a node.)@refill - -In the @code{@@ifinfo} section, the summary sentence is followed by a -copyright notice and then by the copying permission notice. One of -the copying permission paragraphs is enclosed in @code{@@ignore} and -@code{@@end ignore} commands. This paragraph states that the Texinfo -file can be processed through @TeX{} and printed, provided the printed -manual carries the proper copying permission notice. This paragraph -is not made part of the Info file since it is not relevant to the Info -file; but it is a mandatory part of the Texinfo file since it permits -people to process the Texinfo file in @TeX{} and print the -results.@refill - -In the printed manual, the Free Software Foundation copying permission -notice follows the copyright notice and publishing information and is -located within the region delineated by the @code{@@titlepage} and -@code{@@end titlepage} commands. The copying permission notice is exactly -the same as the notice in the @code{@@ifinfo} section except that the -paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is -not part of the notice.@refill - -To make it simple to insert a permission notice into each section of -the Texinfo file, sample permission notices for each section are -reproduced in full below.@refill - -Note that you may need to specify the correct name of a section -mentioned in the permission notice. For example, in @cite{The GDB -Manual}, the name of the section referring to the General Public -License is called the ``GDB General Public License'', but in the -sample shown below, that section is referred to generically as the -``GNU General Public License''. If the Texinfo file does not carry a -copy of the General Public License, leave out the reference to it, but -be sure to include the rest of the sentence.@refill - -@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions -@comment node-name, next, previous, up -@appendixsec @samp{ifinfo} Copying Permissions -@cindex @samp{ifinfo} permissions - -In the @code{@@ifinfo} section of a Texinfo file, the standard Free -Software Foundation permission notice reads as follows:@refill - -@example -This file documents @dots{} - -Copyright 1997 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -@@ignore -Permission is granted to process this file through TeX -and print the results, provided the printed document -carries a copying permission notice identical to this -one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@@end ignore -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and provided -that the entire resulting derived work is distributed -under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute -translations of this manual into another language, -under the above conditions for modified versions, -except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -@end example - -@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions -@comment node-name, next, previous, up -@appendixsec Titlepage Copying Permissions -@cindex Titlepage permissions - -In the @code{@@titlepage} section of a Texinfo file, the standard Free -Software Foundation copying permission notice follows the copyright -notice and publishing information. The standard phrasing is as -follows:@refill - -@example -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and provided -that the entire resulting derived work is distributed -under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute -translations of this manual into another language, -under the above conditions for modified versions, -except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -@end example - - -@node Include Files, Headings, Sample Permissions, Top -@appendix Include Files -@cindex Include files - -When @TeX{} or an Info formatting command sees an @code{@@include} -command in a Texinfo file, it processes the contents of the file named -by the command and incorporates them into the DVI or Info file being -created. Index entries from the included file are incorporated into -the indices of the output file.@refill - -Include files let you keep a single large document as a collection of -conveniently small parts.@refill - -@menu -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. -@end menu - -@node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files -@appendixsec How to Use Include Files -@findex include - -To include another file within a Texinfo file, write the -@code{@@include} command at the beginning of a line and follow it on -the same line by the name of a file to be included. For -example:@refill - -@example -@@include buffers.texi -@end example - -An included file should simply be a segment of text that you expect to -be included as is into the overall or @dfn{outer} Texinfo file; it -should not contain the standard beginning and end parts of a Texinfo -file. In particular, you should not start an included file with a -line saying @samp{\input texinfo}; if you do, that phrase is inserted -into the output file as is. Likewise, you should not end an included -file with an @code{@@bye} command; nothing after @code{@@bye} is -formatted.@refill - -In the past, you were required to write an @code{@@setfilename} line at the -beginning of an included file, but no longer. Now, it does not matter -whether you write such a line. If an @code{@@setfilename} line exists -in an included file, it is ignored.@refill - -Conventionally, an included file begins with an @code{@@node} line that -is followed by an @code{@@chapter} line. Each included file is one -chapter. This makes it easy to use the regular node and menu creating -and updating commands to create the node pointers and menus within the -included file. However, the simple Emacs node and menu creating and -updating commands do not work with multiple Texinfo files. Thus you -cannot use these commands to fill in the `Next', `Previous', and `Up' -pointers of the @code{@@node} line that begins the included file. Also, -you cannot use the regular commands to create a master menu for the -whole file. Either you must insert the menus and the `Next', -`Previous', and `Up' pointers by hand, or you must use the GNU Emacs -Texinfo mode command, @code{texinfo-multiple-files-update}, that is -designed for @code{@@include} files.@refill - -@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files -@appendixsec @code{texinfo-multiple-files-update} -@findex texinfo-multiple-files-update - -GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} -command. This command creates or updates `Next', `Previous', and `Up' -pointers of included files as well as those in the outer or overall -Texinfo file, and it creates or updates a main menu in the outer file. -Depending whether you call it with optional arguments, the command -updates only the pointers in the first @code{@@node} line of the -included files or all of them:@refill - -@table @kbd -@item M-x texinfo-multiple-files-update -Called without any arguments:@refill - -@itemize @minus -@item -Create or update the `Next', `Previous', and `Up' pointers of the -first @code{@@node} line in each file included in an outer or overall -Texinfo file.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -Create or update a main menu in the outer file.@refill -@end itemize - -@item C-u M-x texinfo-multiple-files-update -Called with @kbd{C-u} as a prefix argument: - -@itemize @minus{} -@item -Create or update pointers in the first @code{@@node} line in each -included file. - -@item -Create or update the `Top' level node pointers of the outer file. - -@item -Create and insert a master menu in the outer file. The master menu -is made from all the menus in all the included files.@refill -@end itemize - -@item C-u 8 M-x texinfo-multiple-files-update -Called with a numeric prefix argument, such as @kbd{C-u 8}: - -@itemize @minus -@item -Create or update @strong{all} the `Next', `Previous', and `Up' pointers -of all the included files.@refill - -@item -Create or update @strong{all} the menus of all the included -files.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -And then create a master menu in the outer file. This is similar to -invoking @code{texinfo-master-menu} with an argument when you are -working with just one file.@refill -@end itemize -@end table - -Note the use of the prefix argument in interactive use: with a regular -prefix argument, just @w{@kbd{C-u}}, the -@code{texinfo-multiple-files-update} command inserts a master menu; -with a numeric prefix argument, such as @kbd{C-u 8}, the command -updates @strong{every} pointer and menu in @strong{all} the files and then inserts a -master menu.@refill - -@node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files -@appendixsec Include File Requirements -@cindex Include file requirements -@cindex Requirements for include files - -If you plan to use the @code{texinfo-multiple-files-update} command, -the outer Texinfo file that lists included files within it should -contain nothing but the beginning and end parts of a Texinfo file, and -a number of @code{@@include} commands listing the included files. It -should not even include indices, which should be listed in an included -file of their own.@refill - -Moreover, each of the included files must contain exactly one highest -level node (conventionally, @code{@@chapter} or equivalent), -and this node must be the first node in the included file. -Furthermore, each of these highest level nodes in each included file -must be at the same hierarchical level in the file structure. -Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an -@code{@@unnumbered} node. Thus, normally, each included file contains -one, and only one, chapter or equivalent-level node.@refill - -The outer file should contain only @emph{one} node, the `Top' node. It -should @emph{not} contain any nodes besides the single `Top' node. The -@code{texinfo-multiple-files-update} command will not process -them.@refill - -@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files -@appendixsec Sample File with @code{@@include} -@cindex Sample @code{@@include} file -@cindex Include file sample -@cindex @code{@@include} file sample - -Here is an example of a complete outer Texinfo file with @code{@@include} files -within it before running @code{texinfo-multiple-files-update}, which -would insert a main or master menu:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@c %**start of header -@@setfilename include-example.info -@@settitle Include Example -@c %**end of header -@end group - -@group -@@setchapternewpage odd -@@titlepage -@@sp 12 -@@center @@titlefont@{Include Example@} -@@sp 2 -@@center by Whom Ever -@end group - -@group -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1997 Free Software Foundation, Inc. -@@end titlepage -@end group - -@group -@@ifinfo -@@node Top, First, , (dir) -@@top Master Menu -@@end ifinfo -@end group - -@group -@@include foo.texinfo -@@include bar.texinfo -@@include concept-index.texinfo -@end group - -@group -@@summarycontents -@@contents - -@@bye -@end group -@end example - -An included file, such as @file{foo.texinfo}, might look like -this:@refill - -@example -@group -@@node First, Second, , Top -@@chapter First Chapter - -Contents of first chapter @dots{} -@end group -@end example - -The full contents of @file{concept-index.texinfo} might be as simple as this: - -@example -@group -@@node Concept Index, , Second, Top -@@unnumbered Concept Index - -@@printindex cp -@end group -@end example - -The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference -Manual} is named @file{elisp.texi}. This outer file contains a master -menu with 417 entries and a list of 41 @code{@@include} -files.@refill - -@node Include Files Evolution, , Sample Include File, Include Files -@comment node-name, next, previous, up -@appendixsec Evolution of Include Files - -When Info was first created, it was customary to create many small -Info files on one subject. Each Info file was formatted from its own -Texinfo source file. This custom meant that Emacs did not need to -make a large buffer to hold the whole of a large Info file when -someone wanted information; instead, Emacs allocated just enough -memory for the small Info file that contained the particular -information sought. This way, Emacs could avoid wasting memory.@refill - -References from one file to another were made by referring to the file -name as well as the node name. (@xref{Other Info Files, , Referring to -Other Info Files}. Also, see @ref{Four and Five Arguments, , -@code{@@xref} with Four and Five Arguments}.)@refill - -Include files were designed primarily as a way to create a single, -large printed manual out of several smaller Info files. In a printed -manual, all the references were within the same document, so @TeX{} -could automatically determine the references' page numbers. The Info -formatting commands used include files only for creating joint -indices; each of the individual Texinfo files had to be formatted for -Info individually. (Each, therefore, required its own -@code{@@setfilename} line.)@refill - -However, because large Info files are now split automatically, it is -no longer necessary to keep them small.@refill - -Nowadays, multiple Texinfo files are used mostly for large documents, -such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects -in which several different people write different sections of a -document simultaneously.@refill - -In addition, the Info formatting commands have been extended to work -with the @code{@@include} command so as to create a single large Info -file that is split into smaller files if necessary. This means that -you can write menus and cross references without naming the different -Texinfo files.@refill - - -@node Headings, Catching Mistakes, Include Files, Top -@appendix Page Headings -@cindex Headings -@cindex Footings -@cindex Page numbering -@cindex Page headings -@cindex Formatting headings and footings - -Most printed manuals contain headings along the top of every page -except the title and copyright pages. Some manuals also contain -footings. (Headings and footings have no meaning to Info, which is -not paginated.)@refill - -@menu -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. -@end menu - -@node Headings Introduced, Heading Format, Headings, Headings -@ifinfo -@heading Headings Introduced -@end ifinfo - -Texinfo provides standard page heading formats for manuals that are -printed on one side of each sheet of paper and for manuals that are -printed on both sides of the paper. Typically, you will use these -formats, but you can specify your own format if you wish.@refill - -In addition, you can specify whether chapters should begin on a new -page, or merely continue the same page as the previous chapter; and if -chapters begin on new pages, you can specify whether they must be -odd-numbered pages.@refill - -By convention, a book is printed on both sides of each sheet of paper. -When you open a book, the right-hand page is odd-numbered, and -chapters begin on right-hand pages---a preceding left-hand page is -left blank if necessary. Reports, however, are often printed on just -one side of paper, and chapters begin on a fresh page immediately -following the end of the preceding chapter. In short or informal -reports, chapters often do not begin on a new page at all, but are -separated from the preceding text by a small amount of whitespace.@refill - -The @code{@@setchapternewpage} command controls whether chapters begin -on new pages, and whether one of the standard heading formats is used. -In addition, Texinfo has several heading and footing commands that you -can use to generate your own heading and footing formats.@refill - -In Texinfo, headings and footings are single lines at the tops and -bottoms of pages; you cannot create multiline headings or footings. -Each header or footer line is divided into three parts: a left part, a -middle part, and a right part. Any part, or a whole line, may be left -blank. Text for the left part of a header or footer line is set -flushleft; text for the middle part is centered; and, text for the -right part is set flushright.@refill - -@node Heading Format, Heading Choice, Headings Introduced, Headings -@comment node-name, next, previous, up -@appendixsec Standard Heading Formats - -Texinfo provides two standard heading formats, one for manuals printed -on one side of each sheet of paper, and the other for manuals printed -on both sides of the paper. - -By default, nothing is specified for the footing of a Texinfo file, -so the footing remains blank.@refill - -The standard format for single-sided printing consists of a header -line in which the left-hand part contains the name of the chapter, the -central part is blank, and the right-hand part contains the page -number.@refill - -@need 950 -A single-sided page looks like this: - -@example -@group - _______________________ - | | - | chapter page number | - | | - | Start of text ... | - | ... | - | | - -@end group -@end example - -The standard format for two-sided printing depends on whether the page -number is even or odd. By convention, even-numbered pages are on the -left- and odd-numbered pages are on the right. (@TeX{} will adjust the -widths of the left- and right-hand margins. Usually, widths are -correct, but during double-sided printing, it is wise to check that -pages will bind properly---sometimes a printer will produce output in -which the even-numbered pages have a larger right-hand margin than the -odd-numbered pages.)@refill - -In the standard double-sided format, the left part of the left-hand -(even-numbered) page contains the page number, the central part is -blank, and the right part contains the title (specified by the -@code{@@settitle} command). The left part of the right-hand -(odd-numbered) page contains the name of the chapter, the central part -is blank, and the right part contains the page number.@refill - -@need 750 -Two pages, side by side as in an open book, look like this:@refill - -@example -@group - _______________________ _______________________ - | | | | - | page number title | | chapter page number | - | | | | - | Start of text ... | | More text ... | - | ... | | ... | - | | | | - -@end group -@end example - -@noindent -The chapter name is preceded by the word ``Chapter'', the chapter number -and a colon. This makes it easier to keep track of where you are in the -manual.@refill - -@node Heading Choice, Custom Headings, Heading Format, Headings -@comment node-name, next, previous, up -@appendixsec Specifying the Type of Heading - -@TeX{} does not begin to generate page headings for a standard Texinfo -file until it reaches the @code{@@end titlepage} command. Thus, the -title and copyright pages are not numbered. The @code{@@end -titlepage} command causes @TeX{} to begin to generate page headings -according to a standard format specified by the -@code{@@setchapternewpage} command that precedes the -@code{@@titlepage} section.@refill - -@need 1000 -There are four possibilities:@refill - -@table @asis -@item No @code{@@setchapternewpage} command -Cause @TeX{} to specify the single-sided heading format, with chapters -on new pages. This is the same as @code{@@setchapternewpage on}.@refill - -@item @code{@@setchapternewpage on} -Specify the single-sided heading format, with chapters on new pages.@refill - -@item @code{@@setchapternewpage off} -Cause @TeX{} to start a new chapter on the same page as the last page of -the preceding chapter, after skipping some vertical whitespace. Also -cause @TeX{} to typeset for single-sided printing. (You can override -the headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage odd} -Specify the double-sided heading format, with chapters on new pages.@refill -@end table - -@noindent -Texinfo lacks an @code{@@setchapternewpage even} command.@refill - -@node Custom Headings, , Heading Choice, Headings -@comment node-name, next, previous, up -@appendixsec How to Make Your Own Headings - -You can use the standard headings provided with Texinfo or specify -your own. By default, Texinfo has no footers, so if you specify them, -the available page size for the main text will be slightly reduced. - -@c Following paragraph is verbose to prevent overfull hboxes. -Texinfo provides six commands for specifying headings and -footings. The @code{@@everyheading} command and -@code{@@everyfooting} command generate page headers and footers -that are the same for both even- and odd-numbered pages. -The @code{@@evenheading} command and @code{@@evenfooting} -command generate headers and footers for even-numbered -(left-hand) pages; and the @code{@@oddheading} command and -@code{@@oddfooting} command generate headers and footers for -odd-numbered (right-hand) pages.@refill - -Write custom heading specifications in the Texinfo file immediately -after the @code{@@end titlepage} command. Enclose your specifications -between @code{@@iftex} and @code{@@end iftex} commands since the -@code{texinfo-format-buffer} command may not recognize them. Also, -you must cancel the predefined heading commands with the -@code{@@headings off} command before defining your own -specifications.@refill - -@need 1000 -Here is how to tell @TeX{} to place the chapter name at the left, the -page number in the center, and the date at the right of every header -for both even- and odd-numbered pages:@refill - -@example -@group -@@iftex -@@headings off -@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} -@@end iftex -@end group -@end example - -@noindent -You need to divide the left part from the central part and the central -part from the right part by inserting @samp{@@|} between parts. -Otherwise, the specification command will not be able to tell where -the text for one part ends and the next part begins.@refill - -Each part can contain text or @@-commands. The text -is printed as if the part were within an ordinary paragraph in the -body of the page. The @@-commands replace -themselves with the page number, date, chapter name, or -whatever.@refill - -@need 950 -Here are the six heading and footing commands:@refill - -@findex everyheading -@findex everyfooting -@table @code -@item @@everyheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} - -The `every' commands specify the format for both even- and odd-numbered -pages. These commands are for documents that are printed on one side -of each sheet of paper, or for documents in which you want symmetrical -headers or footers.@refill - -@findex evenheading -@findex evenfooting -@findex oddheading -@findex oddfooting -@item @@evenheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} - -@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} - -The `even' and `odd' commands specify the format for even-numbered -pages and odd-numbered pages. These commands are for books and -manuals that are printed on both sides of each sheet of paper. -@end table - -Use the @samp{@@this@dots{}} series of @@-commands to -provide the names of chapters -and sections and the page number. You can use the -@samp{@@this@dots{}} commands in the left, center, or right portions -of headers and footers, or anywhere else in a Texinfo file so long as -they are between @code{@@iftex} and @code{@@end iftex} commands.@refill - -@need 1000 -Here are the @samp{@@this@dots{}} commands:@refill - -@table @code -@findex thispage -@item @@thispage -Expands to the current page number.@refill -@c !!! Karl Berry says that `thissection' can fail on page breaks. -@ignore -@item @@thissection -Expands to the name of the current section.@refill -@end ignore - -@findex thischaptername -@item @@thischaptername -Expands to the name of the current chapter.@refill - -@findex thischapter -@item @@thischapter -Expands to the number and name of the current -chapter, in the format `Chapter 1: Title'.@refill - -@findex thistitle -@item @@thistitle -Expands to the name of the document, as specified by the -@code{@@settitle} command.@refill - -@findex thisfile -@item @@thisfile -For @code{@@include} files only: expands to the name of the current -@code{@@include} file. If the current Texinfo source file is not an -@code{@@include} file, this command has no effect. This command does -@emph{not} provide the name of the current Texinfo source file unless -it is an @code{@@include} file. (@xref{Include Files}, for more -information about @code{@@include} files.)@refill -@end table - -@noindent -You can also use the @code{@@today@{@}} command, which expands to the -current date, in `1 Jan 1900' format.@refill -@findex today - -Other @@-commands and text are printed in a header or footer just as -if they were in the body of a page. It is useful to incorporate text, -particularly when you are writing drafts:@refill - -@example -@group -@@iftex -@@headings off -@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter -@@everyfooting @@| @@| Version: 0.27: @@today@{@} -@@end iftex -@end group -@end example - -Beware of overlong titles: they may overlap another part of the -header or footer and blot it out.@refill - - -@node Catching Mistakes, Refilling Paragraphs, Headings, Top -@appendix Formatting Mistakes -@cindex Structure, catching mistakes in -@cindex Nodes, catching mistakes -@cindex Catching mistakes -@cindex Correcting mistakes -@cindex Mistakes, catching -@cindex Problems, catching -@cindex Debugging the Texinfo structure - -Besides mistakes in the content of your documentation, there -are two kinds of mistake you can make with Texinfo: you can make mistakes -with @@-commands, and you can make mistakes with the structure of the -nodes and chapters.@refill - -Emacs has two tools for catching the @@-command mistakes and two for -catching structuring mistakes.@refill - -For finding problems with @@-commands, you can run @TeX{} or a region -formatting command on the region that has a problem; indeed, you can -run these commands on each region as you write it.@refill - -For finding problems with the structure of nodes and chapters, you can use -@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} -command and you can use the @kbd{M-x Info-validate} command.@refill - -@menu -* makeinfo Preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with @TeX{} formatting. -* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. -@end menu - -@node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes -@ifinfo -@heading @code{makeinfo} Find Errors -@end ifinfo - -The @code{makeinfo} program does an excellent job of catching errors -and reporting them---far better than @code{texinfo-format-region} or -@code{texinfo-format-buffer}. In addition, the various functions for -automatically creating and updating node pointers and menus remove -many opportunities for human error.@refill - -If you can, use the updating commands to create and insert pointers -and menus. These prevent many errors. Then use @code{makeinfo} (or -its Texinfo mode manifestations, @code{makeinfo-region} and -@code{makeinfo-buffer}) to format your file and check for other -errors. This is the best way to work with Texinfo. But if you -cannot use @code{makeinfo}, or your problem is very puzzling, then you -may want to use the tools described in this appendix.@refill - -@node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Catching Errors with Info Formatting -@cindex Catching errors with Info formatting -@cindex Debugging with Info formatting - -After you have written part of a Texinfo file, you can use the -@code{texinfo-format-region} or the @code{makeinfo-region} command to -see whether the region formats properly.@refill - -Most likely, however, you are reading this section because for some -reason you cannot use the @code{makeinfo-region} command; therefore, the -rest of this section presumes that you are using -@code{texinfo-format-region}.@refill - -If you have made a mistake with an @@-command, -@code{texinfo-format-region} will stop processing at or after the -error and display an error message. To see where in the buffer the -error occurred, switch to the @samp{*Info Region*} buffer; the cursor -will be in a position that is after the location of the error. Also, -the text will not be formatted after the place where the error -occurred (or more precisely, where it was detected).@refill - -For example, if you accidentally end a menu with the command @code{@@end -menus} with an `s' on the end, instead of with @code{@@end menu}, you -will see an error message that says:@refill - -@example -@@end menus is not handled by texinfo -@end example - -@noindent -The cursor will stop at the point in the buffer where the error -occurs, or not long after it. The buffer will look like this:@refill - -@example -@group ----------- Buffer: *Info Region* ---------- -* Menu: - -* Using texinfo-show-structure:: How to use - `texinfo-show-structure' - to catch mistakes. -* Running Info-Validate:: How to check for - unreferenced nodes. -@@end menus -@point{} ----------- Buffer: *Info Region* ---------- -@end group -@end example - -The @code{texinfo-format-region} command sometimes provides slightly -odd error messages. For example, the following cross reference fails to format:@refill - -@example -(@@xref@{Catching Mistakes, for more info.) -@end example - -@noindent -In this case, @code{texinfo-format-region} detects the missing closing -brace but displays a message that says @samp{Unbalanced parentheses} -rather than @samp{Unbalanced braces}. This is because the formatting -command looks for mismatches between braces as if they were -parentheses.@refill - -Sometimes @code{texinfo-format-region} fails to detect mistakes. For -example, in the following, the closing brace is swapped with the -closing parenthesis:@refill - -@example -(@@xref@{Catching Mistakes), for more info.@} -@end example - -@noindent -Formatting produces: -@example -(*Note for more info.: Catching Mistakes) -@end example - -The only way for you to detect this error is to realize that the -reference should have looked like this:@refill - -@example -(*Note Catching Mistakes::, for more info.) -@end example - -Incidentally, if you are reading this node in Info and type @kbd{f -@key{RET}} (@code{Info-follow-reference}), you will generate an error -message that says: - -@example -No such node: "Catching Mistakes) The only way @dots{} -@end example - -@noindent -This is because Info perceives the example of the error as the first -cross reference in this node and if you type a @key{RET} immediately -after typing the Info @kbd{f} command, Info will attempt to go to the -referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info -will complete the node name of the correctly written example and take -you to the `Catching Mistakes' node. (If you try this, you can return -from the `Catching Mistakes' node by typing @kbd{l} -(@code{Info-last}).) - -@c !!! section on using Elisp debugger ignored. -@ignore -Sometimes @code{texinfo-format-region} will stop long after the -original error; this is because it does not discover the problem until -then. In this case, you will need to backtrack.@refill - -@c menu -@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. -@c end menu - -@c node Using the Emacs Lisp Debugger -@c appendixsubsec Using the Emacs Lisp Debugger -@c index Using the Emacs Lisp debugger -@c index Emacs Lisp debugger -@c index Debugger, using the Emacs Lisp - -If an error is especially elusive, you can turn on the Emacs Lisp -debugger and look at the backtrace; this tells you where in the -@code{texinfo-format-region} function the problem occurred. You can -turn on the debugger with the command:@refill - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} -@end example - -@noindent -and turn it off with - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} -@end example - -Often, when you are using the debugger, it is easier to follow what is -going on if you use the Emacs Lisp files that are not byte-compiled. -The byte-compiled sources send octal numbers to the debugger that may -look mysterious. To use the uncompiled source files, load -@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} -command.@refill - -The debugger will not catch an error if @code{texinfo-format-region} -does not detect one. In the example shown above, -@code{texinfo-format-region} did not find the error when the whole -list was formatted, but only when part of the list was formatted. -When @code{texinfo-format-region} did not find an error, the debugger -did not find one either. @refill - -However, when @code{texinfo-format-region} did report an error, it -invoked the debugger. This is the backtrace it produced:@refill - -@example ----------- Buffer: *Backtrace* ---------- -Signalling: (search-failed "[@},]") - re-search-forward("[@},]") - (while ...) - (let ...) - texinfo-format-parse-args() - (let ...) - texinfo-format-xref() - funcall(texinfo-format-xref) - (if ...) - (let ...) - (if ...) - (while ...) - texinfo-format-scan() - (save-excursion ...) - (let ...) - texinfo-format-region(103370 103631) -* call-interactively(texinfo-format-region) ----------- Buffer: *Backtrace* ---------- -@end example - -The backtrace is read from the bottom up. -@code{texinfo-format-region} was called interactively; and it, in -turn, called various functions, including @code{texinfo-format-scan}, -@code{texinfo-format-xref} and @code{texinfo-format-parse-args}. -Inside the function @code{texinfo-format-parse-args}, the function -@code{re-search-forward} was called; it was this function that could -not find the missing right-hand brace.@refill - -@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs -Manual}, for more information.@refill -@end ignore - -@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Catching Errors with @TeX{} Formatting -@cindex Catching errors with @TeX{} formatting -@cindex Debugging with @TeX{} formatting - -You can also catch mistakes when you format a file with @TeX{}.@refill - -Usually, you will want to do this after you have run -@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on -the same file, because @code{texinfo-format-buffer} sometimes displays -error messages that make more sense than @TeX{}. (@xref{Debugging -with Info}, for more information.)@refill - -For example, @TeX{} was run on a Texinfo file, part of which is shown -here:@refill - -@example ----------- Buffer: texinfo.texi ---------- -name of the Texinfo file as an extension. The -@@samp@{??@} are `wildcards' that cause the shell to -substitute all the raw index files. (@@xref@{sorting -indices, for more information about sorting -indices.)@@refill ----------- Buffer: texinfo.texi ---------- -@end example - -@noindent -(The cross reference lacks a closing brace.) -@TeX{} produced the following output, after which it stopped:@refill - -@example ----------- Buffer: *tex-shell* ---------- -Runaway argument? -@{sorting indices, for more information about sorting -indices.) @@refill @@ETC. -! Paragraph ended before @@xref was complete. -<to be read again> - @@par -l.27 - -? ----------- Buffer: *tex-shell* ---------- -@end example - -In this case, @TeX{} produced an accurate and -understandable error message: - -@example -Paragraph ended before @@xref was complete. -@end example - -@noindent -@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. -@samp{l.27} means that @TeX{} detected the problem on line 27 of the -Texinfo file. The @samp{?} is the prompt @TeX{} uses in this -circumstance.@refill - -Unfortunately, @TeX{} is not always so helpful, and sometimes you must -truly be a Sherlock Holmes to discover what went wrong.@refill - -In any case, if you run into a problem like this, you can do one of three -things.@refill - -@enumerate -@item -You can tell @TeX{} to continue running and ignore just this error by -typing @key{RET} at the @samp{?} prompt.@refill - -@item -You can tell @TeX{} to continue running and to ignore all errors as best -it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill - -This is often the best thing to do. However, beware: the one error -may produce a cascade of additional error messages as its consequences -are felt through the rest of the file. To stop @TeX{} when it is -producing such an avalanche of error messages, type @kbd{C-c} (or -@kbd{C-c C-c}, if you are running a shell inside Emacs). - -@item -You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} -at the @samp{?} prompt.@refill -@end enumerate - -Please note that if you are running @TeX{} inside Emacs, you need to -switch to the shell buffer and line at which @TeX{} offers the @samp{?} -prompt.@refill - -Sometimes @TeX{} will format a file without producing error messages even -though there is a problem. This usually occurs if a command is not ended -but @TeX{} is able to continue processing anyhow. For example, if you fail -to end an itemized list with the @code{@@end itemize} command, @TeX{} will -write a DVI file that you can print out. The only error message that -@TeX{} will give you is the somewhat mysterious comment that@refill - -@example -(@@end occurred inside a group at level 1) -@end example - -@noindent -However, if you print the DVI file, you will find that the text -of the file that follows the itemized list is entirely indented as if -it were part of the last item in the itemized list. The error message -is the way @TeX{} says that it expected to find an @code{@@end} -command somewhere in the file; but that it could not determine where -it was needed.@refill - -Another source of notoriously hard-to-find errors is a missing -@code{@@end group} command. If you ever are stumped by -incomprehensible errors, look for a missing @code{@@end group} command -first.@refill - -If the Texinfo file lacks header lines, -@TeX{} may stop in the -beginning of its run and display output that looks like the following. -The @samp{*} indicates that @TeX{} is waiting for input.@refill - -@example -This is TeX, Version 3.14159 (Web2c 7.0) -(test.texinfo [1]) -* -@end example - -@noindent -In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then -write the header lines in the Texinfo file and run the @TeX{} command -again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} -instead of @samp{@@}; and in this circumstance, you are working -directly with @TeX{}, not with Texinfo.)@refill - -@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Using @code{texinfo-show-structure} -@cindex Showing the structure of a file -@findex texinfo-show-structure - -It is not always easy to keep track of the nodes, chapters, sections, and -subsections of a Texinfo file. This is especially true if you are revising -or adding to a Texinfo file that someone else has written.@refill - -In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} -command lists all the lines that begin with the @@-commands that -specify the structure: @code{@@chapter}, @code{@@section}, -@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} -as prefix argument, if interactive), -the command also shows the @code{@@node} lines. The -@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in -Texinfo mode, by default.@refill - -The lines are displayed in a buffer called the @samp{*Occur*} buffer, -indented by hierarchical level. For example, here is a part of what was -produced by running @code{texinfo-show-structure} on this manual:@refill - -@example -@group - Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| - unnum\\|major\\|chapheading \\|heading \\|appendix\\)" - in buffer texinfo.texi. - @dots{} - 4177:@@chapter Nodes - 4198: @@heading Two Paths - 4231: @@section Node and Menu Illustration - 4337: @@section The @@code@{@@@@node@} Command - 4393: @@subheading Choosing Node and Pointer Names - 4417: @@subsection How to Write an @@code@{@@@@node@} Line - 4469: @@subsection @@code@{@@@@node@} Line Tips - @dots{} -@end group -@end example - -This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin -with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} -commands respectively. If you move your cursor into the @samp{*Occur*} -window, you can position the cursor over one of the lines and use the -@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to -the corresponding spot in the Texinfo file. @xref{Other Repeating -Search, , Using Occur, emacs, The GNU Emacs Manual}, for more -information about @code{occur-mode-goto-occurrence}.@refill - -The first line in the @samp{*Occur*} window describes the @dfn{regular -expression} specified by @var{texinfo-heading-pattern}. This regular -expression is the pattern that @code{texinfo-show-structure} looks for. -@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, -for more information.@refill - -When you invoke the @code{texinfo-show-structure} command, Emacs will -display the structure of the whole buffer. If you want to see the -structure of just a part of the buffer, of one chapter, for example, -use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the -region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is -how the example used above was generated. (To see the whole buffer -again, use @kbd{C-x n w} (@code{widen}).)@refill - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with -@code{@@node} as well as the lines beginning with the @@-sign commands -for @code{@@chapter}, @code{@@section}, and the like.@refill - -You can remind yourself of the structure of a Texinfo file by looking at -the list in the @samp{*Occur*} window; and if you have mis-named a node -or left out a section, you can correct the mistake.@refill - -@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Using @code{occur} -@cindex Occurrences, listing with @code{@@occur} -@findex occur - -Sometimes the @code{texinfo-show-structure} command produces too much -information. Perhaps you want to remind yourself of the overall structure -of a Texinfo file, and are overwhelmed by the detailed list produced by -@code{texinfo-show-structure}. In this case, you can use the @code{occur} -command directly. To do this, type@refill - -@example -@kbd{M-x occur} -@end example - -@noindent -and then, when prompted, type a @dfn{regexp}, a regular expression for -the pattern you want to match. (@xref{Regexps, , Regular Expressions, -emacs, The GNU Emacs Manual}.) The @code{occur} command works from -the current location of the cursor in the buffer to the end of the -buffer. If you want to run @code{occur} on the whole buffer, place -the cursor at the beginning of the buffer.@refill - -For example, to see all the lines that contain the word -@samp{@@chapter} in them, just type @samp{@@chapter}. This will -produce a list of the chapters. It will also list all the sentences -with @samp{@@chapter} in the middle of the line.@refill - -If you want to see only those lines that start with the word -@samp{@@chapter}, type @samp{^@@chapter} when prompted by -@code{occur}. If you want to see all the lines that end with a word -or phrase, end the last word with a @samp{$}; for example, -@samp{catching mistakes$}. This can be helpful when you want to see -all the nodes that are part of the same chapter or section and -therefore have the same `Up' pointer.@refill - -@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, -for more information.@refill - -@node Running Info-Validate, , Using occur, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Finding Badly Referenced Nodes -@findex Info-validate -@cindex Nodes, checking for badly referenced -@cindex Checking for badly referenced nodes -@cindex Looking for badly referenced nodes -@cindex Finding badly referenced nodes -@cindex Badly referenced nodes - -You can use the @code{Info-validate} command to check whether any of -the `Next', `Previous', `Up' or other node pointers fail to point to a -node. This command checks that every node pointer points to an -existing node. The @code{Info-validate} command works only on Info -files, not on Texinfo files.@refill - -The @code{makeinfo} program validates pointers automatically, so you -do not need to use the @code{Info-validate} command if you are using -@code{makeinfo}. You only may need to use @code{Info-validate} if you -are unable to run @code{makeinfo} and instead must create an Info file -using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or -if you write an Info file from scratch.@refill - -@menu -* Using Info-validate:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. -@end menu - -@node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate -@appendixsubsec Running @code{Info-validate} -@cindex Running @code{Info-validate} -@cindex Info validating a large file -@cindex Validating a large file - -To use @code{Info-validate}, visit the Info file you wish to check and -type:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note that the @code{Info-validate} command requires an upper case -`I'. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}.)@refill - -If your file is valid, you will receive a message that says ``File appears -valid''. However, if you have a pointer that does not point to a node, -error messages will be displayed in a buffer called @samp{*problems in -info file*}.@refill - -For example, @code{Info-validate} was run on a test file that contained -only the first node of this manual. One of the messages said:@refill - -@example -In node "Overview", invalid Next: Texinfo Mode -@end example - -@noindent -This meant that the node called @samp{Overview} had a `Next' pointer that -did not point to anything (which was true in this case, since the test file -had only one node in it).@refill - -Now suppose we add a node named @samp{Texinfo Mode} to our test case -but we do not specify a `Previous' for this node. Then we will get -the following error message:@refill - -@example -In node "Texinfo Mode", should have Previous: Overview -@end example - -@noindent -This is because every `Next' pointer should be matched by a -`Previous' (in the node where the `Next' points) which points back.@refill - -@code{Info-validate} also checks that all menu entries and cross references -point to actual nodes.@refill - -Note that @code{Info-validate} requires a tag table and does not work -with files that have been split. (The @code{texinfo-format-buffer} -command automatically splits large files.) In order to use -@code{Info-validate} on a large file, you must run -@code{texinfo-format-buffer} with an argument so that it does not split -the Info file; and you must create a tag table for the unsplit -file.@refill - -@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate -@comment node-name, next, previous, up -@appendixsubsec Creating an Unsplit File -@cindex Creating an unsplit file -@cindex Unsplit file creation - -You can run @code{Info-validate} only on a single Info file that has a -tag table. The command will not work on the indirect subfiles that -are generated when a master file is split. If you have a large file -(longer than 70,000 bytes or so), you need to run the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such -a way that it does not create indirect subfiles. You will also need -to create a tag table for the Info file. After you have done this, -you can run @code{Info-validate} and look for badly referenced -nodes.@refill - -The first step is to create an unsplit Info file. To prevent -@code{texinfo-format-buffer} from splitting a Texinfo file into -smaller Info files, give a prefix to the @kbd{M-x -texinfo-format-buffer} command:@refill - -@example -C-u M-x texinfo-format-buffer -@end example - -@noindent -or else - -@example -C-u C-c C-e C-b -@end example - -@noindent -When you do this, Texinfo will not split the file and will not create -a tag table for it. @refill -@cindex Making a tag table manually -@cindex Tag table, making manually - -@node Tagifying, Splitting, Unsplit, Running Info-Validate -@appendixsubsec Tagifying a File - -After creating an unsplit Info file, you must create a tag table for -it. Visit the Info file you wish to tagify and type:@refill - -@example -M-x Info-tagify -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an -Info file with a tag table that you can validate.@refill - -The third step is to validate the Info file:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-validate}.) -In brief, the steps are:@refill - -@example -@group -C-u M-x texinfo-format-buffer -M-x Info-tagify -M-x Info-validate -@end group -@end example - -After you have validated the node structure, you can rerun -@code{texinfo-format-buffer} in the normal way so it will construct a -tag table and split the file automatically, or you can make the tag -table and split the file manually.@refill - -@node Splitting, , Tagifying, Running Info-Validate -@comment node-name, next, previous, up -@appendixsubsec Splitting a File Manually -@cindex Splitting an Info file manually -@cindex Info file, splitting manually - -You should split a large file or else let the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it -for you automatically. (Generally you will let one of the formatting -commands do this job for you. @xref{Create an Info File}.)@refill - -The split-off files are called the indirect subfiles.@refill - -Info files are split to save memory. With smaller files, Emacs does not -have make such a large buffer to hold the information.@refill - -If an Info file has more than 30 nodes, you should also make a tag -table for it. @xref{Using Info-validate}, for information -about creating a tag table. (Again, tag tables are usually created -automatically by the formatting command; you only need to create a tag -table yourself if you are doing the job manually. Most likely, you -will do this for a large, unsplit file on which you have run -@code{Info-validate}.)@refill - -@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 -@ignore -Before running @code{Info-split}, you need to load the @code{info} library -into Emacs by giving the command @kbd{M-x load-library @key{RET} info -@key{RET}}. -@end ignore - -Visit the Info file you wish to tagify and split and type the two -commands:@refill - -@example -M-x Info-tagify -M-x Info-split -@end example - -@noindent -(Note that the @samp{I} in @samp{Info} is upper case.)@refill - -When you use the @code{Info-split} command, the buffer is modified into a -(small) Info file which lists the indirect subfiles. This file should be -saved in place of the original visited file. The indirect subfiles are -written in the same directory the original file is in, with names generated -by appending @samp{-} and a number to the original file name.@refill - -The primary file still functions as an Info file, but it contains just -the tag table and a directory of subfiles.@refill - - -@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top -@appendix Refilling Paragraphs -@cindex Refilling paragraphs -@cindex Filling paragraphs -@findex refill - -The @code{@@refill} command refills and, optionally, indents the first -line of a paragraph.@footnote{Perhaps the command should have been -called the @code{@@refillandindent} command, but @code{@@refill} is -shorter and the name was chosen before indenting was possible.} The -@code{@@refill} command is no longer important, but we describe it here -because you once needed it. You will see it in many old Texinfo -files.@refill - -Without refilling, paragraphs containing long @@-constructs may look -bad after formatting because the formatter removes @@-commands and -shortens some lines more than others. In the past, neither the -@code{texinfo-format-region} command nor the -@code{texinfo-format-buffer} command refilled paragraphs -automatically. The @code{@@refill} command had to be written at the -end of every paragraph to cause these formatters to fill them. (Both -@TeX{} and @code{makeinfo} have always refilled paragraphs -automatically.) Now, all the Info formatters automatically fill and -indent those paragraphs that need to be filled and indented.@refill - -The @code{@@refill} command causes @code{texinfo-format-region} and -@code{texinfo-format-buffer} to refill a paragraph in the Info file -@emph{after} all the other processing has been done. For this reason, -you can not use @code{@@refill} with a paragraph containing either -@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will -override those two commands.@refill - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands now automatically append @code{@@refill} to the end of each -paragraph that should be filled. They do not append @code{@@refill} to -the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} -and therefore do not refill or indent them.@refill - - -@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top -@comment node-name, next, previous, up -@appendix @@-Command Syntax -@cindex @@-command syntax - -The character @samp{@@} is used to start special Texinfo commands. -(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo -has four types of @@-command:@refill - -@table @asis -@item 1. Non-alphabetic commands. -These commands consist of an @@ followed by a punctuation mark or other -character that is not part of the alphabet. Non-alphabetic commands are -almost always part of the text within a paragraph, and never take any -argument. The two characters (@@ and the other one) are complete in -themselves; none is followed by braces. The non-alphabetic commands -are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}}, -@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and -@code{@@@}}.@refill - -@item 2. Alphabetic commands that do not require arguments. -These commands start with @@ followed by a word followed by left- and -right-hand braces. These commands insert special symbols in the -document; they do not require arguments. For example, -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', -and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill - -@item 3. Alphabetic commands that require arguments within braces. -These commands start with @@ followed by a letter or a word, followed by an -argument within braces. For example, the command @code{@@dfn} indicates -the introductory or defining use of a term; it is used as follows: @samp{In -Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill - -@item 4. Alphabetic commands that occupy an entire line. -These commands occupy an entire line. The line starts with @@, -followed by the name of the command (a word); for example, @code{@@center} -or @code{@@cindex}. If no argument is needed, the word is followed by -the end of the line. If there is an argument, it is separated from -the command name by a space. Braces are not used.@refill -@end table - -@cindex Braces and argument syntax -Thus, the alphabetic commands fall into classes that have -different argument syntaxes. You cannot tell to which class a command -belongs by the appearance of its name, but you can tell by the -command's meaning: if the command stands for a glyph, it is in -class 2 and does not require an argument; if it makes sense to use the -command together with other text as part of a paragraph, the command -is in class 3 and must be followed by an argument in braces; -otherwise, it is in class 4 and uses the rest of the line as its -argument.@refill - -The purpose of having a different syntax for commands of classes 3 and -4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command @code{@@refill}, which is always -used at the end of a paragraph immediately following the final period -or other punctuation character. @code{@@refill} takes no argument and -does @emph{not} require braces. @code{@@refill} never confuses the -Emacs paragraph commands because it cannot appear at the beginning of -a line.@refill - - -@node Obtaining TeX, Command and Variable Index, Command Syntax, Top -@appendix How to Obtain @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@c !!! Here is information about obtaining TeX. Update it whenever. -@c !!! Also consider updating TeX.README on prep. -@c Updated by RJC on 1 March 1995, conversation with MacKay. -@c Updated by kb@cs.umb.edu on 29 July 1996. -@c Updated by kb@cs.umb.edu on 25 April 1997. -@TeX{} is freely redistributable. You can obtain @TeX{} for Unix -systems via anonymous ftp or on physical media. The core material -consists of the Web2c @TeX{} distribution (@uref{http://www.tug.org/web2c}). - -Instructions for retrieval by anonymous ftp and information on other -available distributions: -@example -@uref{ftp://ftp.tug.org/tex/unixtex.ftp} -@uref{http://www.tug.org/unixtex.ftp} -@end example - -The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals; the University of -Washington maintains and supports a tape distribution; the @TeX{} Users -Group co-sponsors a complete CD-ROM @TeX{} distribution. - -@itemize @bullet - -@item -For the FSF Source Code CD-ROM, please contact: - -@iftex -@display -@group -Free Software Foundation, Inc. -59 Temple Place Suite 330 -Boston, MA @ @ 02111-1307 -USA -Telephone: @w{@t{+}1--617--542--5942} -Fax: (including Japan) @w{@t{+}1--617--542--2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031--13--2473 (KDD) -@w{ } @w{ } @w{ } 0066--3382--0158 (IDC) -Electronic mail: @code{gnu@@prep.ai.mit.edu} -@end group -@end display -@end iftex -@ifinfo -@display -@group -Free Software Foundation, Inc. -59 Temple Place Suite 330 -Boston, MA @w{ } 02111-1307 -USA - -Telephone: @w{@t{+}1-617-542-5942} -Fax: (including Japan) @w{@t{+}1-617-542-2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031-13-2473 (KDD) -@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) -Electronic mail: @code{gnu@@prep.ai.mit.edu} -@end group -@end display -@end ifinfo - -@item -To order a complete distribution on CD-ROM, please see -@uref{http://www.tug.org/tex-live.html}. (This distribution is also -available by FTP; see the URL's above.) - -@item -To order a full distribution from the University of Washington on either -a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge, -send $210 to: - -@display -@group -Pierre A. MacKay -Denny Hall, Mail Stop DH-10 -University of Washington -Seattle, WA @w{ } 98195 -USA -Telephone: @t{+}1--206--543--2268 -Electronic mail: @code{mackay@@cs.washington.edu} -@end group -@end display - -@noindent Please make checks payable to the University of Washington. -Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas -sites: please add to the base cost, if desired, $20.00 for shipment via -air parcel post, or $30.00 for shipment via courier. - -@end itemize - -Many other @TeX{} distributions are available; see -@uref{http://www.tug.org/}. - - -@c These are no longer ``new'', and the explanations -@c are all given elsewhere anyway, I think. --karl, 25apr97. -@ignore (the entire appendix) -@c node New Features, Command and Variable Index, Obtaining TeX, Top -@c appendix Second Edition Features - -@tex -% Widen the space for the first column so three control-character -% strings fit in the first column. Switched back to default .8in -% value at end of chapter. -\global\tableindent=1.0in -@end tex - -The second edition of the Texinfo manual describes more than 20 new -Texinfo mode commands and more than 50 previously undocumented Texinfo -@@-commands. This edition is more than twice the length of the first -edition.@refill - -Here is a brief description of the new commands.@refill - -@menu -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@end menu - -@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX -@c appendixsec New Texinfo Mode Commands - -Texinfo mode provides commands and features especially designed for -working with Texinfo files. More than 20 new commands have been -added, including commands for automatically creating and updating -both nodes and menus. This is a tedious task when done by hand.@refill - -The keybindings are intended to be somewhat mnemonic.@refill - -@c subheading Update all nodes and menus - -The @code{texinfo-master-menu} command is the primary command: - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -Create or update a master menu. -With @kbd{C-u} as a prefix argument, -first create or update all nodes -and regular menus. -@end table - -@c subheading Update Pointers - -@noindent -Create or update `Next', `Previous', and `Up' node pointers.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -Update a node. - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -Update every node in the buffer. -@end table - -@c subheading Update Menus - -@noindent -Create or update menus.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -Make or update a menu. - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -Make or update all the menus in a buffer. -With @kbd{C-u} as a prefix argument, -first update all the nodes. -@end table - -@c subheading Insert Title as Description - -@noindent -Insert a node's chapter or section title in the space for the -description in a menu entry line; position point so you can edit the -insert. (This command works somewhat differently than the other -insertion commands, which insert only a predefined string.)@refill - -@noindent -@xref{Inserting, Inserting Frequently Used Commands}. - -@table @kbd -@item C-c C-c C-d -Insert title. -@end table - -@c subheading Format for Info - -@noindent -Provide keybindings both for the Info formatting commands that are -written in Emacs Lisp and for @code{makeinfo} that is written in -C.@refill - -@noindent -@xref{Info Formatting}. - -@noindent -Use the Emacs lisp @code{texinfo-format@dots{}} commands: - -@table @kbd -@item C-c C-e C-r -Format the region. - -@item C-c C-e C-b -Format the buffer. -@end table - -@noindent -Use @code{makeinfo}: - -@table @kbd -@item C-c C-m C-r -Format the region. - -@item C-c C-m C-b -Format the buffer. - -@item C-c C-m C-l -Recenter the @code{makeinfo} output buffer. - -@item C-c C-m C-k -Kill the @code{makeinfo} formatting job. -@end table - -@c subheading Typeset and Print - -@noindent -Typeset and print Texinfo documents from within Emacs.@refill - -@ifinfo -@noindent -@xref{Printing}. -@end ifinfo -@iftex -@noindent -@xref{Printing, , Formatting and Printing}. -@end iftex - -@table @kbd -@item C-c C-t C-b -Run @code{texi2dvi} on the buffer. - -@item C-c C-t C-r -Run @TeX{} on the region. - -@item C-c C-t C-i -Run @code{texindex}. - -@item C-c C-t C-p -Print the DVI file. - -@item C-c C-t C-q -Show the print queue. - -@item C-c C-t C-d -Delete a job from the print queue. - -@item C-c C-t C-k -Kill the current @TeX{} formatting job. - -@item C-c C-t C-x -Quit a currently stopped @TeX{} formatting job. - -@item C-c C-t C-l -Recenter the output buffer. -@end table - -@c subheading Other Updating Commands - -@noindent -The ``other updating commands'' do not have standard keybindings because -they are used less frequently.@refill - -@noindent -@xref{Other Updating Commands}. - -@table @kbd -@item M-x texinfo-insert-node-lines -Insert missing @code{@@node} lines using -section titles as node names. - -@item M-x texinfo-multiple-files-update -Update a multi-file document. -With a numeric prefix, such as @kbd{C-u 8}, -update @strong{every} pointer and -menu in @strong{all} the files and -then insert a master menu. - -@item M-x texinfo-indent-menu-description -Indent descriptions in menus. - -@item M-x texinfo-sequential-node-update -Insert node pointers in strict sequence. -@end table - -@c node New Commands, , New Texinfo Mode Commands, Obtaining TeX -@c appendixsec New Texinfo @@-Commands - -The second edition of the Texinfo manual describes more than 50 -commands that were not described in the first edition. A third or so -of these commands existed in Texinfo but were not documented in the -manual; the others are new. Here is a listing, with brief -descriptions of them:@refill - -@c subheading Indexing - -@noindent -Create your own index, and merge indices.@refill - -@noindent -@xref{Indices}. - -@table @kbd -@item @@defindex @var{index-name} -Define a new index and its indexing command. -See also the @code{@@defcodeindex} command. - -@c written verbosely to avoid overfull hbox -@item @@synindex @var{from-index} @var{into-index} -Merge the @var{from-index} index into the @var{into-index} index. -See also the @code{@@syncodeindex} command. -@end table - -@c subheading Definitions - -@noindent -Describe functions, variables, macros, -commands, user options, special forms, and other such artifacts in a -uniform format.@refill - -@noindent -@xref{Definition Commands}. - -@table @kbd -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -Format a description for functions, interactive -commands, and similar entities. - -@item @@defvr, @@defop, @dots{} -15 other related commands. -@end table - -@c subheading Glyphs - -@noindent -Indicate the results of evaluation, expansion, -printed output, an error message, equivalence of expressions, and the -location of point.@refill - -@noindent -@xref{Glyphs}. - -@table @kbd -@item @@equiv@{@} -@itemx @equiv{} -Equivalence: - -@item @@error@{@} -@itemx @error{} -Error message - -@item @@expansion@{@} -@itemx @expansion{} -Macro expansion - -@item @@point@{@} -@itemx @point{} -Position of point - -@item @@print@{@} -@itemx @print{} -Printed output - -@item @@result@{@} -@itemx @result{} -Result of an expression -@end table - -@c subheading Page Headings - -@noindent -Customize page headings. - -@noindent -@xref{Headings}. - -@table @kbd -@item @@headings @var{on-off-single-double} -Headings on or off, single, or double-sided. - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Footings for even-numbered (left-hand) pages. - -@item @@evenheading, @@everyheading, @@oddheading, @dots{} -Five other related commands. - -@item @@thischapter -Insert name of chapter and chapter number. - -@item @@thischaptername, @@thisfile, @@thistitle, @@thispage -Related commands. -@end table - -@c subheading Formatting - -@noindent -Format blocks of text. - -@noindent -@xref{Quotations and Examples}, and@* -@ref{Lists and Tables, , Making Lists and Tables}. - -@table @kbd -@item @@cartouche -Draw rounded box surrounding text (not in Info). - -@item @@enumerate @var{optional-arg} -Enumerate a list with letters or numbers. - -@item @@exdent @var{line-of-text} -Remove indentation. - -@item @@flushleft -Left justify. - -@item @@flushright -Right justify. - -@item @@format -Do not narrow nor change font. - -@item @@ftable @var{formatting-command} -@itemx @@vtable @var{formatting-command} -Two-column table with indexing. - -@item @@lisp -For an example of Lisp code. - -@item @@smallexample -@itemx @@smalllisp -Like @@table and @@lisp @r{but for} @@smallbook. -@end table - -@c subheading Conditionals - -@noindent -Conditionally format text. - -@noindent -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@table @kbd -@item @@set @var{flag} [@var{string}] -Set a flag. Optionally, set value -of @var{flag} to @var{string}. - -@item @@clear @var{flag} -Clear a flag. - -@item @@value@{@var{flag}@} -Replace with value to which @var{flag} is set. - -@item @@ifset @var{flag} -Format, if @var{flag} is set. - -@item @@ifclear @var{flag} -Ignore, if @var{flag} is set. -@end table - -@c subheading @@heading series for Titles - -@noindent -Produce unnumbered headings that do not appear in a table of contents. - -@noindent -@xref{Structuring}. - -@table @kbd -@item @@heading @var{title} -Unnumbered section-like heading not listed -in the table of contents of a printed manual. - -@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading -Related commands. -@end table - -@need 1000 -@c subheading Font commands - -@need 1000 -@noindent -@xref{Smallcaps}, and @* -@ref{Fonts}. - -@table @kbd -@item @@r@{@var{text}@} -Print in roman font. - -@item @@sc@{@var{text}@} -Print in @sc{small caps} font. -@end table - -@c subheading Miscellaneous - -@noindent -See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* -see @ref{Customized Highlighting},@* -see @ref{Overfull hboxes},@* -see @ref{Footnotes},@* -see @ref{dmn, , Format a Dimension},@* -see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* -see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* -see @ref{minus, , Inserting a Minus Sign},@* -see @ref{paragraphindent, , Paragraph Indenting},@* -see @ref{Cross Reference Commands},@* -see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* -see @ref{Custom Headings, , How to Make Your Own Headings}. - -@table @kbd -@item @@author @var{author} -Typeset author's name. - -@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -@c Define a highlighting command for Info. (Info only.) - -@item @@finalout -Produce cleaner printed output. - -@item @@footnotestyle @var{end-or-separate} -Specify footnote style. - -@item @@dmn@{@var{dimension}@} -Format a dimension. - -@item @@global@@let@var{new-cmd}=@var{existing-cmd} -Define a highlighting command for @TeX{}. (@TeX{} only.) - -@item @@lowersections -Reduce hierarchical level of sectioning commands. - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. - -@item @@minus@{@} -Generate a minus sign. - -@item @@paragraphindent @var{asis-or-number} -Specify paragraph indentation. - -@item @@raisesections -Raise hierarchical level of sectioning commands. - -@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} -Make a reference. In the printed manual, the -reference does not start with the word `see'. - -@item @@title @var{title} -Typeset @var{title} in the alternative -title page format. - -@item @@subtitle @var{subtitle} -Typeset @var{subtitle} in the alternative -title page format. - -@item @@today@{@} -Insert the current date. -@end table -@tex -% Switch width of first column of tables back to default value -\global\tableindent=.8in -@end tex -@end ignore - -@node Command and Variable Index, Concept Index, Obtaining TeX, Top -@comment node-name, next, previous, up -@unnumbered Command and Variable Index - -This is an alphabetical list of all the @@-commands, assorted Emacs Lisp -functions, and several variables. To make the list easier to use, the -commands are listed without their preceding @samp{@@}.@refill - -@printindex fn - - -@node Concept Index, , Command and Variable Index, Top -@unnumbered Concept Index - -@printindex cp - - -@summarycontents -@contents -@bye diff --git a/gnu/usr.bin/texinfo/info/NEWS b/gnu/usr.bin/texinfo/info/NEWS deleted file mode 100644 index b13fb1531b5..00000000000 --- a/gnu/usr.bin/texinfo/info/NEWS +++ /dev/null @@ -1,200 +0,0 @@ -This release of Info is version 2.11. Please read the file README. - -Version 2.11, Sat Apr 1 09:15:21 1995 - -Changes since 2.7 beta: - -Although the basic code remains the same, there are numerous nits -fixed, including some display bugs, and a memory leak. Some changes -that have taken place with larger impact include the way in which the -(dir) node is built; I have added in support for "localdir" -directories among other things. Info files may be stored in -compressed formats, and in their own subdirectories; menu items which -do not explicitly name the node to which they are attached have the -menu item name looked up as an Info file if it is not found within the -current document. This means that the menu item: - -* Info:: The Info documentation reader. - -in (dir) refers to the info node "(info)Top". - -Please see the ChangeLog and documentation for details on other -changes. - -Version 2.7 beta, Wed Dec 30 02:02:38 1992 -Version 2.6 beta, Tue Dec 22 03:58:07 1992 -Version 2.5 beta, Tue Dec 8 14:50:35 1992 -Version 2.4 beta, Sat Nov 28 14:34:02 1992 -Version 2.3 beta, Fri Nov 27 01:04:13 1992 -Version 2.2 beta, Tue Nov 24 09:36:08 1992 -Version 2.1 beta, Tue Nov 17 23:29:36 1992 - -Changes since 2.5 beta: - -Note that versions 2.6 and 2.7 Beta were only released to a select group. - -* "info-" removed from the front of M-x commands. - -* Automatic footnote display. When you enter a node which contains - footnotes, and the variable "automatic-footnotes" is "On", Info pops - up a window containing the footnotes. Likewise, when you leave that - node, the window containing the footnotes goes away. - -* Cleaner built in documentation, and documentation functions. - - Use: - o `M-x describe-variable' to read a variable's documenation - o `M-x describe-key' to find out what a particular keystroke does. - o `M-x describe-function' to read a function's documentation. - o `M-x where-is' to find out what keys invoke a particular function. - -* Info can "tile" the displayed windows (via "M-x tile-windows"). If - the variable "automatic-tiling" is "On", then splitting a window or - deleting a window causes the remaining windows to be retiled. - -* You can save every keystroke you type in a "dribble file" by using the - `--dribble FILENAME' option. You can initially read keystrokes from an - alternate input stream with `--restore FILENAME', or by redirecting - input on the command line `info < old-dribble'. - -* New behaviour of menu items. If the label is the same as the - target node name, and the node couldn't be found in the current file, - treat the label as a file name. For example, a menu entry in "DIR" - might contain: - - * Emacs:: Cool text-editor. - - Info would not find the node "(dir)Emacs", so just plain "(emacs)" - would be tried. - -* New variable "ISO-Latin" allows you to use European machines with - 8-bit character sets. - -* Cleanups in echo area reading, and redisplay. Cleanups in handling the - window which shows possible completions. - -* Info can now read files that have been compressed. An array in filesys.c - maps extensions to programs that can decompress stdin, and write the results - to stdout. Currently, ".Z"/uncompress, ".z"/gunzip, and ".Y"/unyabba are - supported. The modeline for a compressed file shows "zz" in it. - -* There is a new variable "gc-compressed-files" which, if non-zero, says - it is okay to reclaim the file buffer space allocated to a file which - was compressed, if, and only if, that file's contents do not appear in - any history node. - -* New file `nodemenu.c' implements a few functions for manipulating - previously visited nodes. `C-x C-b' (list-visited-nodes) produces a - menu of the nodes that could be reached by info-history-node in some - window. `C-x b' (select-visited-node) is similar, but reads one of - the node names with completion. - -* Keystroke `M-r' (move_to_screen_line) allows the user to place the cursor at - the start of a specific screen line. Without a numeric argument, place the - cursor on the center line; with an arg, place the cursor on that line. - -* Interruptible display implemented. Basic display speedups and hacks. -* The message "*** Tags Out of Date ***" now means what it says. -* Index searching with `,' (info-index-next) has been improved. -* When scrolling with C-v, C-M-v, or M-v, only "Page Only" scrolling - will happen. - -* Continous scrolling (along with `]' (info-global-next) and `[' - (info-global-prev) works better. `]' and `[' accept numeric - arguments, moving that many nodes in that case. - -* `C-x w' (info-toggle-wrap) controls how lines wider than the width - of the screen are displayed. If a line is too long, a `$' is - displayed in the rightmost column of the window. - -* There are some new variables for controlling the behaviour of Info - interactively. The current list of variables is as follows: - - Variable Name Default Value Description - ------------- ------------- ----------- - `automatic-footnotes' On When "On", footnotes appear and - disappear automatically. - - `automatic-tiling' Off When "On", creating of deleting a - window resizes other windows. - - `visible-bell' Off If non-zero, try to use a visible bell. - - `errors-ring-bell' On If non-zero, errors cause a ring. - - `show-index-match' On If non-zero, the portion of the string - matched is highlighted by changing its - case. - - `scroll-behaviour' Continuous One of "Continuous", "Next Only", or - "Page Only". "Page Only" prevents you from - scrolling past the bottom or top of a node. - "Next Only" causes the Next or Prev node to - be selected when you scroll past the bottom - or top of a node. "Continous" moves - linearly through the files hierchichal - structure. - - `scroll-step' 0 Controls how scrolling is done for you when - the cursor moves out of the current window. - Non-zero means it is the number of lines - you would like the screen to shift. A - value of 0 means to center the line - containing the cursor in the window. - - `gc-compressed-files' Off If non-zero means it is okay to reclaim the - file buffer space allocated to a file which - was compressed, if, and only if, that - file's contents do not appear in the node - list of any window. - - `ISO-Latin' Off Non-zero means that you are using an ISO - Latin character set. By default, standard - ASCII characters are assumed. -________________________________________ -This release of Info is version 2.5 beta. - -Changes since 2.4 beta: - -* Index (i) and (,) commands fully implemented. -* "configure" script now shipped with Info. -* New function "set-variable" allows users to set various variables. -* User-settable behaviour on end or beginning of node scrolling. This - supercedes the SPC and DEL changes in 2.3 beta. - -________________________________________ -This release of Info is version 2.4 beta. - -Changes since 2.3 beta: - -* info-last-node now means move to the last node of this info file. -* info-history-node means move backwards through this window's node history. -* info-first-node moves to the first node in the Info file. This node is - not necessarily "Top"! -* SPC and DEL can select the Next or Prev node after printing an informative - message when pressed at the end/beg of a node. - ----------------------------------------- -This release of Info is version 2.3 beta. - -Changes since 2.2 beta: - -* M-x command lines if NAMED_COMMANDS is #defined. Variable in Makefile. -* Screen height changes made quite robust. -* Interactive function "set-screen-height" implements user height changes. -* Scrolling on some terminals is faster now. -* C-l with numeric arguement is fixed. - ----------------------------------------- -This release of Info is version 2.2 beta. - -Changes since 2.0: - -* C-g can now interrupt multi-file searches. -* Incremental search is fully implemented. -* Loading large tag tables is much faster now. -* makedoc.c replaces shell script, speeding incremental builds. -* Scrolling in redisplay is implemented. -* Recursive uses of the echo area made more robust. -* Garbage collection of unreferenced nodes. - diff --git a/gnu/usr.bin/texinfo/info/clib.c b/gnu/usr.bin/texinfo/info/clib.c deleted file mode 100644 index 67abc27d40d..00000000000 --- a/gnu/usr.bin/texinfo/info/clib.c +++ /dev/null @@ -1,112 +0,0 @@ -/* clib.c: Functions which we normally expect to find in the C library. - $Id: clib.c,v 1.3 2002/06/10 13:51:03 espie Exp $ - - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1995 Free Software Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - Written by Brian Fox (bfox@ai.mit.edu). */ - -#include <stdio.h> - -#if defined (HAVE_UNISTD_H) -#include <unistd.h> -#endif - -#if defined (HAVE_STDLIB_H) -#include <stdlib.h> -#endif - -#if defined (HAVE_STRING_H) -#include <string.h> -#endif - -#include <sys/errno.h> - -extern void *xmalloc (), *xrealloc (); -#include "general.h" - -#if !defined (errno) -extern int errno; -#endif - -#if !defined (HAVE_STRERROR) -extern char *sys_errlist[]; -extern int sys_nerr; - -char * -strerror (num) - int num; -{ - if (num >= sys_nerr) - return (""); - else - return (sys_errlist[num]); -} -#endif /* !HAVE_STRERROR */ - -#if !defined (HAVE_STRCASECMP) -/* This Unix doesn't have the strcasecmp () function. */ -int -strcasecmp (string1, string2) - char *string1, *string2; -{ - char ch1, ch2; - - for (;;) - { - ch1 = *string1++; - ch2 = *string2++; - - if (!(ch1 | ch2)) - return (0); - - ch1 = info_toupper (ch1); - ch2 = info_toupper (ch2); - - if (ch1 != ch2) - return (ch1 - ch2); - } -} - -/* Compare at most COUNT characters from string1 to string2. Case - doesn't matter. */ -int -strncasecmp (string1, string2, count) - char *string1, *string2; - int count; -{ - register char ch1, ch2; - - while (count) - { - ch1 = *string1++; - ch2 = *string2++; - - ch1 = info_toupper (ch1); - ch2 = info_toupper (ch2); - - if (ch1 == ch2) - count--; - else - break; - } - return (count); -} -#endif /* !STRCASECMP */ - diff --git a/gnu/usr.bin/texinfo/info/clib.h b/gnu/usr.bin/texinfo/info/clib.h deleted file mode 100644 index c559fe51b60..00000000000 --- a/gnu/usr.bin/texinfo/info/clib.h +++ /dev/null @@ -1,42 +0,0 @@ -/* clib.h: Declarations of functions which appear in clib.c (or libc.a). */ - -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1995 Free Software Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - Written by Brian Fox (bfox@ai.mit.edu). */ - -#if !defined (_CLIB_H_) -#define _CLIB_H_ - -#if !defined (HAVE_STRDUP) -extern char *strdup (); -#endif - -#if !defined (HAVE_STRERROR) -extern char *strerror (); -#endif - -#if !defined (HAVE_STRCASECMP) -extern int strcasecmp (); -extern int strncasecmp (); -#endif - -#endif /* !_CLIB_H_ */ - - diff --git a/gnu/usr.bin/texinfo/info/diffs b/gnu/usr.bin/texinfo/info/diffs deleted file mode 100644 index ff866daa836..00000000000 --- a/gnu/usr.bin/texinfo/info/diffs +++ /dev/null @@ -1,19 +0,0 @@ -*** indices.c.~1~ Tue Oct 26 16:36:35 1993 ---- indices.c Sat Nov 20 14:00:46 1993 -*************** -*** 253,259 **** - else - index_offset = -1; - -! old_offset == index_offset; - - /* The "last" string searched for is this one. */ - index_search = line; ---- 253,259 ---- - else - index_offset = -1; - -! old_offset = index_offset; - - /* The "last" string searched for is this one. */ - index_search = line; diff --git a/gnu/usr.bin/texinfo/info/dribble b/gnu/usr.bin/texinfo/info/dribble deleted file mode 100644 index 99d3a844815..00000000000 --- a/gnu/usr.bin/texinfo/info/dribble +++ /dev/null @@ -1,5 +0,0 @@ -mfoo -em -buffers - -ââ
\ No newline at end of file diff --git a/gnu/usr.bin/texinfo/info/echo_area.c b/gnu/usr.bin/texinfo/info/echo_area.c deleted file mode 100644 index 265e9880425..00000000000 --- a/gnu/usr.bin/texinfo/info/echo_area.c +++ /dev/null @@ -1,1508 +0,0 @@ -/* echo_area.c -- How to read a line in the echo area. */ - -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - Written by Brian Fox (bfox@ai.mit.edu). */ - -#include "info.h" - -#if defined (FD_SET) -# if defined (hpux) -# define fd_set_cast(x) (int *)(x) -# else -# define fd_set_cast(x) (fd_set *)(x) -# endif /* !hpux */ -#endif /* FD_SET */ - -/* Non-zero means that C-g was used to quit reading input. */ -int info_aborted_echo_area = 0; - -/* Non-zero means that the echo area is being used to read input. */ -int echo_area_is_active = 0; - -/* The address of the last command executed in the echo area. */ -VFunction *ea_last_executed_command = (VFunction *)NULL; - -/* Non-zero means that the last command executed while reading input - killed some text. */ -int echo_area_last_command_was_kill = 0; - -/* Variables which hold on to the current state of the input line. */ -static char input_line[1 + EA_MAX_INPUT]; -static char *input_line_prompt; -static int input_line_point; -static int input_line_beg; -static int input_line_end; -static NODE input_line_node = { - (char *)NULL, (char *)NULL, (char *)NULL, input_line, EA_MAX_INPUT, 0 -}; - -static void echo_area_initialize_node (); -static void push_echo_area (), pop_echo_area (); -static int echo_area_stack_depth (), echo_area_stack_contains_completions_p (); - -static void ea_kill_text (); - -/* Non-zero means we force the user to complete. */ -static int echo_area_must_complete_p = 0; -static int completions_window_p (); - -/* If non-null, this is a window which was specifically created to display - possible completions output. We remember it so we can delete it when - appropriate. */ -static WINDOW *echo_area_completions_window = (WINDOW *)NULL; - -/* Variables which keep track of the window which was active prior to - entering the echo area. */ -static WINDOW *calling_window = (WINDOW *)NULL; -static NODE *calling_window_node = (NODE *)NULL; -static long calling_window_point = 0; -static long calling_window_pagetop = 0; - -/* Remember the node and pertinent variables of the calling window. */ -static void -remember_calling_window (window) - WINDOW *window; -{ - /* Only do this if the calling window is not the completions window, or, - if it is the completions window and there is no other window. */ - if (!completions_window_p (window) || - ((window == windows) && !(window->next))) - { - calling_window = window; - calling_window_node = window->node; - calling_window_point = window->point; - calling_window_pagetop = window->pagetop; - } -} - -/* Restore the caller's window so that it shows the node that it was showing - on entry to info_read_xxx_echo_area (). */ -static void -restore_calling_window () -{ - register WINDOW *win, *compwin = (WINDOW *)NULL; - - /* If the calling window is still visible, and it is the window that - we used for completions output, then restore the calling window. */ - for (win = windows; win; win = win->next) - { - if (completions_window_p (win)) - compwin = win; - - if (win == calling_window && win == compwin) - { - window_set_node_of_window (calling_window, calling_window_node); - calling_window->point = calling_window_point; - calling_window->pagetop = calling_window_pagetop; - compwin = (WINDOW *)NULL; - break; - } - } - - /* Delete the completions window if it is still present, it isn't the - last window on the screen, and there aren't any prior echo area reads - pending which created a completions window. */ - if (compwin) - { - if ((compwin != windows || windows->next) && - !echo_area_stack_contains_completions_p ()) - { - WINDOW *next; - int pagetop, start, end, amount; - - next = compwin->next; - if (next) - { - start = next->first_row; - end = start + next->height; - amount = - (compwin->height + 1); - pagetop = next->pagetop; - } - - info_delete_window_internal (compwin); - - /* This is not necessary because info_delete_window_internal () - calls echo_area_inform_of_deleted_window (), which does the - right thing. */ -#if defined (UNNECESSARY) - echo_area_completions_window = (WINDOW *)NULL; -#endif /* UNNECESSARY */ - - if (next) - { - display_scroll_display (start, end, amount); - next->pagetop = pagetop; - display_update_display (windows); - } - } - } -} - -/* Set up a new input line with PROMPT. */ -static void -initialize_input_line (prompt) - char *prompt; -{ - input_line_prompt = prompt; - if (prompt) - strcpy (input_line, prompt); - else - input_line[0] = '\0'; - - input_line_beg = input_line_end = input_line_point = strlen (prompt); -} - -static char * -echo_area_after_read () -{ - char *return_value; - - if (info_aborted_echo_area) - { - info_aborted_echo_area = 0; - return_value = (char *)NULL; - } - else - { - if (input_line_beg == input_line_end) - return_value = strdup (""); - else - { - int line_len = input_line_end - input_line_beg; - return_value = (char *) xmalloc (1 + line_len); - strncpy (return_value, &input_line[input_line_beg], line_len); - return_value[line_len] = '\0'; - } - } - return (return_value); -} - -/* Read a line of text in the echo area. Return a malloc ()'ed string, - or NULL if the user aborted out of this read. WINDOW is the currently - active window, so that we can restore it when we need to. PROMPT, if - non-null, is a prompt to print before reading the line. */ -char * -info_read_in_echo_area (window, prompt) - WINDOW *window; - char *prompt; -{ - char *line; - - /* If the echo area is already active, remember the current state. */ - if (echo_area_is_active) - push_echo_area (); - - /* Initialize our local variables. */ - initialize_input_line (prompt); - - /* Initialize the echo area for the first (but maybe not the last) time. */ - echo_area_initialize_node (); - - /* Save away the original node of this window, and the window itself, - so echo area commands can temporarily use this window. */ - remember_calling_window (window); - - /* Let the rest of Info know that the echo area is active. */ - echo_area_is_active++; - active_window = the_echo_area; - - /* Read characters in the echo area. */ - info_read_and_dispatch (); - - echo_area_is_active--; - - /* Restore the original active window and show point in it. */ - active_window = calling_window; - restore_calling_window (); - display_cursor_at_point (active_window); - fflush (stdout); - - /* Get the value of the line. */ - line = echo_area_after_read (); - - /* If there is a previous loop waiting for us, restore it now. */ - if (echo_area_is_active) - pop_echo_area (); - - /* Return the results to the caller. */ - return (line); -} - -/* (re) Initialize the echo area node. */ -static void -echo_area_initialize_node () -{ - register int i; - - for (i = input_line_end; i < sizeof (input_line); i++) - input_line[i] = ' '; - - input_line[i - 1] = '\n'; - window_set_node_of_window (the_echo_area, &input_line_node); - input_line[input_line_end] = '\n'; -} - -/* Prepare to read characters in the echo area. This can initialize the - echo area node, but its primary purpose is to side effect the input - line buffer contents. */ -void -echo_area_prep_read () -{ - if (the_echo_area->node != &input_line_node) - echo_area_initialize_node (); - - the_echo_area->point = input_line_point; - input_line[input_line_end] = '\n'; - display_update_one_window (the_echo_area); - display_cursor_at_point (active_window); -} - - -/* **************************************************************** */ -/* */ -/* Echo Area Movement Commands */ -/* */ -/* **************************************************************** */ - -DECLARE_INFO_COMMAND (ea_forward, "Move forward a character") -{ - if (count < 0) - ea_backward (window, -count, key); - else - { - input_line_point += count; - if (input_line_point > input_line_end) - input_line_point = input_line_end; - } -} - -DECLARE_INFO_COMMAND (ea_backward, "Move backward a character") -{ - if (count < 0) - ea_forward (window, -count, key); - else - { - input_line_point -= count; - if (input_line_point < input_line_beg) - input_line_point = input_line_beg; - } -} - -DECLARE_INFO_COMMAND (ea_beg_of_line, "Move to the start of this line") -{ - input_line_point = input_line_beg; -} - -DECLARE_INFO_COMMAND (ea_end_of_line, "Move to the end of this line") -{ - input_line_point = input_line_end; -} - -#define alphabetic(c) (islower (c) || isupper (c) || isdigit (c)) - -/* Move forward a word in the input line. */ -DECLARE_INFO_COMMAND (ea_forward_word, "Move forward a word") -{ - int c; - - if (count < 0) - ea_backward_word (window, -count, key); - else - { - while (count--) - { - if (input_line_point == input_line_end) - return; - - /* If we are not in a word, move forward until we are in one. - Then, move forward until we hit a non-alphabetic character. */ - c = input_line[input_line_point]; - - if (!alphabetic (c)) - { - while (++input_line_point < input_line_end) - { - c = input_line[input_line_point]; - if (alphabetic (c)) - break; - } - } - - if (input_line_point == input_line_end) - return; - - while (++input_line_point < input_line_end) - { - c = input_line[input_line_point]; - if (!alphabetic (c)) - break; - } - } - } -} - -DECLARE_INFO_COMMAND (ea_backward_word, "Move backward a word") -{ - int c; - - if (count < 0) - ea_forward_word (window, -count, key); - else - { - while (count--) - { - if (input_line_point == input_line_beg) - return; - - /* Like ea_forward_word (), except that we look at the - characters just before point. */ - - c = input_line[input_line_point - 1]; - - if (!alphabetic (c)) - { - while ((--input_line_point) != input_line_beg) - { - c = input_line[input_line_point - 1]; - if (alphabetic (c)) - break; - } - } - - while (input_line_point != input_line_beg) - { - c = input_line[input_line_point - 1]; - if (!alphabetic (c)) - break; - else - --input_line_point; - } - } - } -} - -DECLARE_INFO_COMMAND (ea_delete, "Delete the character under the cursor") -{ - register int i; - - if (count < 0) - ea_rubout (window, -count, key); - else - { - if (input_line_point == input_line_end) - return; - - if (info_explicit_arg || count > 1) - { - int orig_point; - - orig_point = input_line_point; - ea_forward (window, count, key); - ea_kill_text (orig_point, input_line_point); - input_line_point = orig_point; - } - else - { - for (i = input_line_point; i < input_line_end; i++) - input_line[i] = input_line[i + 1]; - - input_line_end--; - } - } -} - -DECLARE_INFO_COMMAND (ea_rubout, "Delete the character behind the cursor") -{ - if (count < 0) - ea_delete (window, -count, key); - else - { - int start; - - if (input_line_point == input_line_beg) - return; - - start = input_line_point; - ea_backward (window, count, key); - - if (info_explicit_arg || count > 1) - ea_kill_text (start, input_line_point); - else - ea_delete (window, count, key); - } -} - -DECLARE_INFO_COMMAND (ea_abort, "Cancel or quit operation") -{ - /* If any text, just discard it, and restore the calling window's node. - If no text, quit. */ - if (input_line_end != input_line_beg) - { - terminal_ring_bell (); - input_line_end = input_line_point = input_line_beg; - if (calling_window->node != calling_window_node) - restore_calling_window (); - } - else - info_aborted_echo_area = 1; -} - -DECLARE_INFO_COMMAND (ea_newline, "Accept (or force completion of) this line") -{ - /* Stub does nothing. Simply here to see if it has been executed. */ -} - -DECLARE_INFO_COMMAND (ea_quoted_insert, "Insert next character verbatim") -{ - unsigned char character; - - character = info_get_another_input_char (); - ea_insert (window, count, character); -} - -DECLARE_INFO_COMMAND (ea_insert, "Insert this character") -{ - register int i; - - if ((input_line_end + 1) == EA_MAX_INPUT) - { - terminal_ring_bell (); - return; - } - - for (i = input_line_end + 1; i != input_line_point; i--) - input_line[i] = input_line[i - 1]; - - input_line[input_line_point] = key; - input_line_point++; - input_line_end++; -} - -DECLARE_INFO_COMMAND (ea_tab_insert, "Insert a TAB character") -{ - ea_insert (window, count, '\t'); -} - -/* Transpose the characters at point. If point is at the end of the line, - then transpose the characters before point. */ -DECLARE_INFO_COMMAND (ea_transpose_chars, "Transpose characters at point") -{ - /* Handle conditions that would make it impossible to transpose - characters. */ - if (!count || !input_line_point || (input_line_end - input_line_beg) < 2) - return; - - while (count) - { - int t; - if (input_line_point == input_line_end) - { - t = input_line[input_line_point - 1]; - - input_line[input_line_point - 1] = input_line[input_line_point - 2]; - input_line[input_line_point - 2] = t; - } - else - { - t = input_line[input_line_point]; - - input_line[input_line_point] = input_line[input_line_point - 1]; - input_line[input_line_point - 1] = t; - - if (count < 0 && input_line_point != input_line_beg) - input_line_point--; - else - input_line_point++; - } - - if (count < 0) - count++; - else - count--; - } -} - -/* **************************************************************** */ -/* */ -/* Echo Area Killing and Yanking */ -/* */ -/* **************************************************************** */ - -static char **kill_ring = (char **)NULL; -static int kill_ring_index = 0; /* Number of kills appearing in KILL_RING. */ -static int kill_ring_slots = 0; /* Number of slots allocated to KILL_RING. */ -static int kill_ring_loc = 0; /* Location of current yank pointer. */ - -/* The largest number of kills that we remember at one time. */ -static int max_retained_kills = 15; - -DECLARE_INFO_COMMAND (ea_yank, "Yank back the contents of the last kill") -{ - register int i; - register char *text; - - if (!kill_ring_index) - { - inform_in_echo_area ("Kill ring is empty"); - return; - } - - text = kill_ring[kill_ring_loc]; - - for (i = 0; text[i]; i++) - ea_insert (window, 1, text[i]); -} - -/* If the last command was yank, or yank_pop, and the text just before - point is identical to the current kill item, then delete that text - from the line, rotate the index down, and yank back some other text. */ -DECLARE_INFO_COMMAND (ea_yank_pop, "Yank back a previous kill") -{ - register int len; - - if (((ea_last_executed_command != ea_yank) && - (ea_last_executed_command != ea_yank_pop)) || - (kill_ring_index == 0)) - return; - - len = strlen (kill_ring[kill_ring_loc]); - - /* Delete the last yanked item from the line. */ - { - register int i, counter; - - counter = input_line_end - input_line_point; - - for (i = input_line_point - len; counter; i++, counter--) - input_line[i] = input_line[i + len]; - - input_line_end -= len; - input_line_point -= len; - } - - /* Get a previous kill, and yank that. */ - kill_ring_loc--; - if (kill_ring_loc < 0) - kill_ring_loc = kill_ring_index - 1; - - ea_yank (window, count, key); -} - -/* Delete the text from point to end of line. */ -DECLARE_INFO_COMMAND (ea_kill_line, "Kill to the end of the line") -{ - if (count < 0) - { - ea_kill_text (input_line_point, input_line_beg); - input_line_point = input_line_beg; - } - else - ea_kill_text (input_line_point, input_line_end); -} - -/* Delete the text from point to beg of line. */ -DECLARE_INFO_COMMAND (ea_backward_kill_line, - "Kill to the beginning of the line") -{ - if (count < 0) - ea_kill_text (input_line_point, input_line_end); - else - { - ea_kill_text (input_line_point, input_line_beg); - input_line_point = input_line_beg; - } -} - -/* Delete from point to the end of the current word. */ -DECLARE_INFO_COMMAND (ea_kill_word, "Kill the word following the cursor") -{ - int orig_point = input_line_point; - - if (count < 0) - ea_backward_kill_word (window, -count, key); - else - { - ea_forward_word (window, count, key); - - if (input_line_point != orig_point) - ea_kill_text (orig_point, input_line_point); - - input_line_point = orig_point; - } -} - -/* Delete from point to the start of the current word. */ -DECLARE_INFO_COMMAND (ea_backward_kill_word, - "Kill the word preceding the cursor") -{ - int orig_point = input_line_point; - - if (count < 0) - ea_kill_word (window, -count, key); - else - { - ea_backward_word (window, count, key); - - if (input_line_point != orig_point) - ea_kill_text (orig_point, input_line_point); - } -} - -/* The way to kill something. This appends or prepends to the last - kill, if the last command was a kill command. If FROM is less - than TO, then the killed text is appended to the most recent kill, - otherwise it is prepended. If the last command was not a kill command, - then a new slot is made for this kill. */ -static void -ea_kill_text (from, to) - int from, to; -{ - register int i, counter, distance; - int killing_backwards, slot; - char *killed_text; - - killing_backwards = (from > to); - - /* If killing backwards, reverse the values of FROM and TO. */ - if (killing_backwards) - { - int temp = from; - from = to; - to = temp; - } - - /* Remember the text that we are about to delete. */ - distance = to - from; - killed_text = (char *)xmalloc (1 + distance); - strncpy (killed_text, &input_line[from], distance); - killed_text[distance] = '\0'; - - /* Actually delete the text from the line. */ - counter = input_line_end - to; - - for (i = from; counter; i++, counter--) - input_line[i] = input_line[i + distance]; - - input_line_end -= distance; - - /* If the last command was a kill, append or prepend the killed text to - the last command's killed text. */ - if (echo_area_last_command_was_kill) - { - char *old, *new; - - slot = kill_ring_loc; - old = kill_ring[slot]; - new = (char *)xmalloc (1 + strlen (old) + strlen (killed_text)); - - if (killing_backwards) - { - /* Prepend TEXT to current kill. */ - strcpy (new, killed_text); - strcat (new, old); - } - else - { - /* Append TEXT to current kill. */ - strcpy (new, old); - strcat (new, killed_text); - } - - free (old); - free (killed_text); - kill_ring[slot] = new; - } - else - { - /* Try to store the kill in a new slot, unless that would cause there - to be too many remembered kills. */ - slot = kill_ring_index; - - if (slot == max_retained_kills) - slot = 0; - - if (slot + 1 > kill_ring_slots) - kill_ring = (char **) xrealloc - (kill_ring, - (kill_ring_slots += max_retained_kills) * sizeof (char *)); - - if (slot != kill_ring_index) - free (kill_ring[slot]); - else - kill_ring_index++; - - kill_ring[slot] = killed_text; - - kill_ring_loc = slot; - } - - /* Notice that the last command was a kill. */ - echo_area_last_command_was_kill++; -} - -/* **************************************************************** */ -/* */ -/* Echo Area Completion */ -/* */ -/* **************************************************************** */ - -/* Pointer to an array of REFERENCE to complete over. */ -static REFERENCE **echo_area_completion_items = (REFERENCE **)NULL; - -/* Sorted array of REFERENCE * which is the possible completions found in - the variable echo_area_completion_items. If there is only one element, - it is the only possible completion. */ -static REFERENCE **completions_found = (REFERENCE **)NULL; -static int completions_found_index = 0; -static int completions_found_slots = 0; - -/* The lowest common denominator found while completing. */ -static REFERENCE *LCD_completion; - -/* Internal functions used by the user calls. */ -static void build_completions (), completions_must_be_rebuilt (); - -/* Variable which holds the output of completions. */ -static NODE *possible_completions_output_node = (NODE *)NULL; - -static char *compwin_name = "*Completions*"; - -/* Return non-zero if WINDOW is a window used for completions output. */ -static int -completions_window_p (window) - WINDOW *window; -{ - int result = 0; - - if (internal_info_node_p (window->node) && - (strcmp (window->node->nodename, compwin_name) == 0)) - result = 1; - - return (result); -} - -/* Workhorse for completion readers. If FORCE is non-zero, the user cannot - exit unless the line read completes, or is empty. */ -char * -info_read_completing_internal (window, prompt, completions, force) - WINDOW *window; - char *prompt; - REFERENCE **completions; - int force; -{ - char *line; - - /* If the echo area is already active, remember the current state. */ - if (echo_area_is_active) - push_echo_area (); - - echo_area_must_complete_p = force; - - /* Initialize our local variables. */ - initialize_input_line (prompt); - - /* Initialize the echo area for the first (but maybe not the last) time. */ - echo_area_initialize_node (); - - /* Save away the original node of this window, and the window itself, - so echo area commands can temporarily use this window. */ - remember_calling_window (window); - - /* Save away the list of items to complete over. */ - echo_area_completion_items = completions; - completions_must_be_rebuilt (); - - active_window = the_echo_area; - echo_area_is_active++; - - /* Read characters in the echo area. */ - while (1) - { - info_read_and_dispatch (); - - line = echo_area_after_read (); - - /* Force the completion to take place if the user hasn't accepted - a default or aborted, and if FORCE is active. */ - if (force && line && *line && completions) - { - register int i; - - build_completions (); - - /* If there is only one completion, then make the line be that - completion. */ - if (completions_found_index == 1) - { - free (line); - line = strdup (completions_found[0]->label); - break; - } - - /* If one of the completions matches exactly, then that is okay, so - return the current line. */ - for (i = 0; i < completions_found_index; i++) - if (strcasecmp (completions_found[i]->label, line) == 0) - { - free (line); - line = strdup (completions_found[i]->label); - break; - } - - /* If no match, go back and try again. */ - if (i == completions_found_index) - { - inform_in_echo_area ("Not complete"); - continue; - } - } - break; - } - echo_area_is_active--; - - /* Restore the original active window and show point in it. */ - active_window = calling_window; - restore_calling_window (); - display_cursor_at_point (active_window); - fflush (stdout); - - echo_area_completion_items = (REFERENCE **)NULL; - completions_must_be_rebuilt (); - - /* If there is a previous loop waiting for us, restore it now. */ - if (echo_area_is_active) - pop_echo_area (); - - return (line); -} - -/* Read a line in the echo area with completion over COMPLETIONS. */ -char * -info_read_completing_in_echo_area (window, prompt, completions) - WINDOW *window; - char *prompt; - REFERENCE **completions; -{ - return (info_read_completing_internal (window, prompt, completions, 1)); -} - -/* Read a line in the echo area allowing completion over COMPLETIONS, but - not requiring it. */ -char * -info_read_maybe_completing (window, prompt, completions) - WINDOW *window; - char *prompt; - REFERENCE **completions; -{ - return (info_read_completing_internal (window, prompt, completions, 0)); -} - -DECLARE_INFO_COMMAND (ea_possible_completions, "List possible completions") -{ - if (!echo_area_completion_items) - { - ea_insert (window, count, key); - return; - } - - build_completions (); - - if (!completions_found_index) - { - terminal_ring_bell (); - inform_in_echo_area ("No completions"); - } - else if ((completions_found_index == 1) && (key != '?')) - { - inform_in_echo_area ("Sole completion"); - } - else - { - register int i, l; - int limit, count, max_label = 0; - - initialize_message_buffer (); - printf_to_message_buffer - ("There %s %d ", completions_found_index == 1 ? "is" : "are", - completions_found_index); - printf_to_message_buffer - ("completion%s:\n", completions_found_index == 1 ? "" : "s"); - - /* Find the maximum length of a label. */ - for (i = 0; i < completions_found_index; i++) - { - int len = strlen (completions_found[i]->label); - if (len > max_label) - max_label = len; - } - - max_label += 4; - - /* Find out how many columns we should print in. */ - limit = calling_window->width / max_label; - if (limit != 1 && (limit * max_label == calling_window->width)) - limit--; - - /* Avoid a possible floating exception. If max_label > width then - the limit will be 0 and a divide-by-zero fault will result. */ - if (limit == 0) - limit = 1; - - /* How many iterations of the printing loop? */ - count = (completions_found_index + (limit - 1)) / limit; - - /* Watch out for special case. If the number of completions is less - than LIMIT, then just do the inner printing loop. */ - if (completions_found_index < limit) - count = 1; - - /* Print the sorted items, up-and-down alphabetically. */ - for (i = 0; i < count; i++) - { - register int j; - - for (j = 0, l = i; j < limit; j++) - { - if (l >= completions_found_index) - break; - else - { - char *label; - int printed_length, k; - - label = completions_found[l]->label; - printed_length = strlen (label); - printf_to_message_buffer ("%s", label); - - if (j + 1 < limit) - { - for (k = 0; k < max_label - printed_length; k++) - printf_to_message_buffer (" "); - } - } - l += count; - } - printf_to_message_buffer ("\n"); - } - - /* Make a new node to hold onto possible completions. Don't destroy - dangling pointers. */ - { - NODE *temp; - - temp = message_buffer_to_node (); - add_gcable_pointer (temp->contents); - name_internal_node (temp, compwin_name); - possible_completions_output_node = temp; - } - - /* Find a suitable window for displaying the completions output. - First choice is an existing window showing completions output. - If there is only one window, and it is large, make another - (smaller) window, and use that one. Otherwise, use the caller's - window. */ - { - WINDOW *compwin; - - compwin = get_internal_info_window (compwin_name); - - if (!compwin) - { - /* If we can split the window to display most of the completion - items, then do so. */ - if (calling_window->height > (count * 2)) - { - int start, end, pagetop; - - active_window = calling_window; - - /* Perhaps we can scroll this window on redisplay. */ - start = calling_window->first_row; - pagetop = calling_window->pagetop; - - compwin = - window_make_window (possible_completions_output_node); - active_window = the_echo_area; - window_change_window_height - (compwin, -(compwin->height - (count + 2))); - - window_adjust_pagetop (calling_window); - remember_calling_window (calling_window); - -#if defined (SPLIT_BEFORE_ACTIVE) - /* If the pagetop hasn't changed, scrolling the calling - window is a reasonable thing to do. */ - if (pagetop == calling_window->pagetop) - { - end = start + calling_window->height; - display_scroll_display - (start, end, calling_window->prev->height + 1); - } -#else /* !SPLIT_BEFORE_ACTIVE */ - /* If the pagetop has changed, set the new pagetop here. */ - if (pagetop != calling_window->pagetop) - { - int newtop = calling_window->pagetop; - calling_window->pagetop = pagetop; - set_window_pagetop (calling_window, newtop); - } -#endif /* !SPLIT_BEFORE_ACTIVE */ - - echo_area_completions_window = compwin; - remember_window_and_node (compwin, compwin->node); - } - else - compwin = calling_window; - } - - if (compwin->node != possible_completions_output_node) - { - window_set_node_of_window - (compwin, possible_completions_output_node); - remember_window_and_node (compwin, compwin->node); - } - - display_update_display (windows); - } - } -} - -DECLARE_INFO_COMMAND (ea_complete, "Insert completion") -{ - if (!echo_area_completion_items) - { - ea_insert (window, count, key); - return; - } - - /* If KEY is SPC, and we are not forcing completion to take place, simply - insert the key. */ - if (!echo_area_must_complete_p && key == SPC) - { - ea_insert (window, count, key); - return; - } - - if (ea_last_executed_command == ea_complete) - { - /* If the keypress is a SPC character, and we have already tried - completing once, and there are several completions, then check - the batch of completions to see if any continue with a space. - If there are some, insert the space character and continue. */ - if (key == SPC && completions_found_index > 1) - { - register int i, offset; - - offset = input_line_end - input_line_beg; - - for (i = 0; i < completions_found_index; i++) - if (completions_found[i]->label[offset] == ' ') - break; - - if (completions_found[i]) - ea_insert (window, 1, ' '); - else - { - ea_possible_completions (window, count, key); - return; - } - } - else - { - ea_possible_completions (window, count, key); - return; - } - } - - input_line_point = input_line_end; - build_completions (); - - if (!completions_found_index) - terminal_ring_bell (); - else if (LCD_completion->label[0] == '\0') - ea_possible_completions (window, count, key); - else - { - register int i; - input_line_point = input_line_end = input_line_beg; - for (i = 0; LCD_completion->label[i]; i++) - ea_insert (window, 1, LCD_completion->label[i]); - } -} - -/* Utility REFERENCE used to store possible LCD. */ -static REFERENCE LCD_reference = { (char *)NULL, (char *)NULL, (char *)NULL }; - -static void remove_completion_duplicates (); - -/* Variables which remember the state of the most recent call - to build_completions (). */ -static char *last_completion_request = (char *)NULL; -static REFERENCE **last_completion_items = (REFERENCE **)NULL; - -/* How to tell the completion builder to reset internal state. */ -static void -completions_must_be_rebuilt () -{ - maybe_free (last_completion_request); - last_completion_request = (char *)NULL; - last_completion_items = (REFERENCE **)NULL; -} - -/* Build a list of possible completions from echo_area_completion_items, - and the contents of input_line. */ -static void -build_completions () -{ - register int i, len; - register REFERENCE *entry; - char *request; - int informed_of_lengthy_job = 0; - - /* If there are no items to complete over, exit immediately. */ - if (!echo_area_completion_items) - { - completions_found_index = 0; - LCD_completion = (REFERENCE *)NULL; - return; - } - - /* Check to see if this call to build completions is the same as the last - call to build completions. */ - len = input_line_end - input_line_beg; - request = (char *)xmalloc (1 + len); - strncpy (request, &input_line[input_line_beg], len); - request[len] = '\0'; - - if (last_completion_request && last_completion_items && - last_completion_items == echo_area_completion_items && - (strcmp (last_completion_request, request) == 0)) - { - free (request); - return; - } - - maybe_free (last_completion_request); - last_completion_request = request; - last_completion_items = echo_area_completion_items; - - /* Always start at the beginning of the list. */ - completions_found_index = 0; - LCD_completion = (REFERENCE *)NULL; - - for (i = 0; entry = echo_area_completion_items[i]; i++) - { - if (strncasecmp (request, entry->label, len) == 0) - add_pointer_to_array (entry, completions_found_index, - completions_found, completions_found_slots, - 20, REFERENCE *); - - if (!informed_of_lengthy_job && completions_found_index > 100) - { - informed_of_lengthy_job = 1; - window_message_in_echo_area ("Building completions..."); - } - } - - if (!completions_found_index) - return; - - /* Sort and prune duplicate entries from the completions array. */ - remove_completion_duplicates (); - - /* If there is only one completion, just return that. */ - if (completions_found_index == 1) - { - LCD_completion = completions_found[0]; - return; - } - - /* Find the least common denominator. */ - { - long shortest = 100000; - - for (i = 1; i < completions_found_index; i++) - { - register int j; - int c1, c2; - - for (j = 0; - (c1 = info_tolower (completions_found[i - 1]->label[j])) && - (c2 = info_tolower (completions_found[i]->label[j])); - j++) - if (c1 != c2) - break; - - if (shortest > j) - shortest = j; - } - - maybe_free (LCD_reference.label); - LCD_reference.label = (char *)xmalloc (1 + shortest); - strncpy (LCD_reference.label, completions_found[0]->label, shortest); - LCD_reference.label[shortest] = '\0'; - LCD_completion = &LCD_reference; - } - - if (informed_of_lengthy_job) - echo_area_initialize_node (); -} - -/* Function called by qsort. */ -static int -compare_references (entry1, entry2) - REFERENCE **entry1, **entry2; -{ - return (strcasecmp ((*entry1)->label, (*entry2)->label)); -} - -/* Prune duplicate entries from COMPLETIONS_FOUND. */ -static void -remove_completion_duplicates () -{ - register int i, j; - REFERENCE **temp; - int newlen; - - if (!completions_found_index) - return; - - /* Sort the items. */ - qsort (completions_found, completions_found_index, sizeof (REFERENCE *), - compare_references); - - for (i = 0, newlen = 1; i < completions_found_index - 1; i++) - { - if (strcmp (completions_found[i]->label, - completions_found[i + 1]->label) == 0) - completions_found[i] = (REFERENCE *)NULL; - else - newlen++; - } - - /* We have marked all the dead slots. It is faster to copy the live slots - twice than to prune the dead slots one by one. */ - temp = (REFERENCE **)xmalloc ((1 + newlen) * sizeof (REFERENCE *)); - for (i = 0, j = 0; i < completions_found_index; i++) - if (completions_found[i]) - temp[j++] = completions_found[i]; - - for (i = 0; i < newlen; i++) - completions_found[i] = temp[i]; - - completions_found[i] = (REFERENCE *)NULL; - completions_found_index = newlen; - free (temp); -} - -/* Scroll the "other" window. If there is a window showing completions, scroll - that one, otherwise scroll the window which was active on entering the read - function. */ -DECLARE_INFO_COMMAND (ea_scroll_completions_window, "Scroll the completions window") -{ - WINDOW *compwin; - int old_pagetop; - - compwin = get_internal_info_window (compwin_name); - - if (!compwin) - compwin = calling_window; - - old_pagetop = compwin->pagetop; - - /* Let info_scroll_forward () do the work, and print any messages that - need to be displayed. */ - info_scroll_forward (compwin, count, key); -} - -/* Function which gets called when an Info window is deleted while the - echo area is active. WINDOW is the window which has just been deleted. */ -void -echo_area_inform_of_deleted_window (window) - WINDOW *window; -{ - /* If this is the calling_window, forget what we remembered about it. */ - if (window == calling_window) - { - if (active_window != the_echo_area) - remember_calling_window (active_window); - else - remember_calling_window (windows); - } - - /* If this window was the echo_area_completions_window, then notice that - the window has been deleted. */ - if (window == echo_area_completions_window) - echo_area_completions_window = (WINDOW *)NULL; -} - -/* **************************************************************** */ -/* */ -/* Pushing and Popping the Echo Area */ -/* */ -/* **************************************************************** */ - -/* Push and Pop the echo area. */ -typedef struct { - char *line; - char *prompt; - REFERENCE **comp_items; - int point, beg, end; - int must_complete; - NODE node; - WINDOW *compwin; -} PUSHED_EA; - -static PUSHED_EA **pushed_echo_areas = (PUSHED_EA **)NULL; -static int pushed_echo_areas_index = 0; -static int pushed_echo_areas_slots = 0; - -/* Pushing the echo_area has a side effect of zeroing the completion_items. */ -static void -push_echo_area () -{ - PUSHED_EA *pushed; - - pushed = (PUSHED_EA *)xmalloc (sizeof (PUSHED_EA)); - pushed->line = strdup (input_line); - pushed->prompt = input_line_prompt; - pushed->point = input_line_point; - pushed->beg = input_line_beg; - pushed->end = input_line_end; - pushed->node = input_line_node; - pushed->comp_items = echo_area_completion_items; - pushed->must_complete = echo_area_must_complete_p; - pushed->compwin = echo_area_completions_window; - - add_pointer_to_array (pushed, pushed_echo_areas_index, pushed_echo_areas, - pushed_echo_areas_slots, 4, PUSHED_EA *); - - echo_area_completion_items = (REFERENCE **)NULL; -} - -static void -pop_echo_area () -{ - PUSHED_EA *popped; - - popped = pushed_echo_areas[--pushed_echo_areas_index]; - - strcpy (input_line, popped->line); - free (popped->line); - input_line_prompt = popped->prompt; - input_line_point = popped->point; - input_line_beg = popped->beg; - input_line_end = popped->end; - input_line_node = popped->node; - echo_area_completion_items = popped->comp_items; - echo_area_must_complete_p = popped->must_complete; - echo_area_completions_window = popped->compwin; - completions_must_be_rebuilt (); - - /* If the completion window no longer exists, forget about it. */ - if (echo_area_completions_window) - { - register WINDOW *win; - - for (win = windows; win; win = win->next) - if (echo_area_completions_window == win) - break; - - /* If the window wasn't found, then it has already been deleted. */ - if (!win) - echo_area_completions_window = (WINDOW *)NULL; - } - - free (popped); -} - -static int -echo_area_stack_depth () -{ - return (pushed_echo_areas_index); -} - -/* Returns non-zero if any of the prior stacked calls to read in the echo - area produced a completions window. */ -static int -echo_area_stack_contains_completions_p () -{ - register int i; - - for (i = 0; i < pushed_echo_areas_index; i++) - if (pushed_echo_areas[i]->compwin) - return (1); - - return (0); -} - -/* **************************************************************** */ -/* */ -/* Error Messages While Reading in Echo Area */ -/* */ -/* **************************************************************** */ - -#if defined (HAVE_SYS_TIME_H) -# include <sys/time.h> -# define HAVE_STRUCT_TIMEVAL -#endif /* HAVE_SYS_TIME_H */ - -static void -pause_or_input () -{ -#if defined (FD_SET) - struct timeval timer; - fd_set readfds; - int ready; - - FD_ZERO (&readfds); - FD_SET (fileno (stdin), &readfds); - timer.tv_sec = 2; - timer.tv_usec = 750; - ready = select (1, &readfds, (fd_set *)NULL, (fd_set *)NULL, &timer); -#endif /* FD_SET */ -} - -/* Print MESSAGE right after the end of the current line, and wait - for input or 2.75 seconds, whichever comes first. Then flush the - informational message that was printed. */ -void -inform_in_echo_area (message) - char *message; -{ - register int i; - char *text; - - text = strdup (message); - for (i = 0; text[i] && text[i] != '\n'; i++); - text[i] = '\0'; - - echo_area_initialize_node (); - sprintf (&input_line[input_line_end], "%s[%s]\n", - echo_area_is_active ? " ": "", text); - free (text); - the_echo_area->point = input_line_point; - display_update_one_window (the_echo_area); - display_cursor_at_point (active_window); - fflush (stdout); - pause_or_input (); - echo_area_initialize_node (); -} diff --git a/gnu/usr.bin/texinfo/info/echo_area.h b/gnu/usr.bin/texinfo/info/echo_area.h deleted file mode 100644 index 09c2bc7e22e..00000000000 --- a/gnu/usr.bin/texinfo/info/echo_area.h +++ /dev/null @@ -1,63 +0,0 @@ -/* echo_area.h -- Functions used in reading information from the echo area. */ - -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - Written by Brian Fox (bfox@ai.mit.edu). */ - -#if !defined (_ECHO_AREA_H_) -#define _ECHO_AREA_H_ - -#define EA_MAX_INPUT 256 - -extern int echo_area_is_active, info_aborted_echo_area; - -/* Non-zero means that the last command executed while reading input - killed some text. */ -extern int echo_area_last_command_was_kill; - -extern void inform_in_echo_area (), echo_area_inform_of_deleted_window (); -extern void echo_area_prep_read (); -extern VFunction *ea_last_executed_command; - -/* Read a line of text in the echo area. Return a malloc ()'ed string, - or NULL if the user aborted out of this read. WINDOW is the currently - active window, so that we can restore it when we need to. PROMPT, if - non-null, is a prompt to print before reading the line. */ -extern char *info_read_in_echo_area (); - -/* Read a line in the echo area with completion over COMPLETIONS. - Takes arguments of WINDOW, PROMPT, and COMPLETIONS, a REFERENCE **. */ -char *info_read_completing_in_echo_area (); - -/* Read a line in the echo area allowing completion over COMPLETIONS, but - not requiring it. Takes arguments of WINDOW, PROMPT, and COMPLETIONS, - a REFERENCE **. */ -extern char *info_read_maybe_completing (); - -extern void ea_insert (), ea_quoted_insert (); -extern void ea_beg_of_line (), ea_backward (), ea_delete (), ea_end_of_line (); -extern void ea_forward (), ea_abort (), ea_rubout (), ea_complete (); -extern void ea_newline (), ea_kill_line (), ea_transpose_chars (); -extern void ea_yank (), ea_tab_insert (), ea_possible_completions (); -extern void ea_backward_word (), ea_kill_word (), ea_forward_word (); -extern void ea_yank_pop (), ea_backward_kill_word (); -extern void ea_scroll_completions_window (); - -#endif /* _ECHO_AREA_H_ */ diff --git a/gnu/usr.bin/texinfo/info/general.h b/gnu/usr.bin/texinfo/info/general.h deleted file mode 100644 index 4b97dc8d8da..00000000000 --- a/gnu/usr.bin/texinfo/info/general.h +++ /dev/null @@ -1,94 +0,0 @@ -/* general.h -- Some generally useful defines. */ - -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - Written by Brian Fox (bfox@ai.mit.edu). */ - -#if !defined (_GENERAL_H_) -#define _GENERAL_H_ - -extern void *xmalloc (), *xrealloc (); - -#if defined (HAVE_UNISTD_H) -# include <unistd.h> -#endif /* HAVE_UNISTD_H */ - -#if defined (HAVE_STRING_H) -# include <string.h> -#else -# include <strings.h> -#endif /* !HAVE_STRING_H */ - -#include "clib.h" - -#define info_toupper(x) (islower (x) ? toupper (x) : x) -#define info_tolower(x) (isupper (x) ? tolower (x) : x) - -#if !defined (whitespace) -# define whitespace(c) ((c == ' ') || (c == '\t')) -#endif /* !whitespace */ - -#if !defined (whitespace_or_newline) -# define whitespace_or_newline(c) (whitespace (c) || (c == '\n')) -#endif /* !whitespace_or_newline */ - -#if !defined (__FUNCTION_DEF) -# define __FUNCTION_DEF -typedef int Function (); -typedef void VFunction (); -typedef char *CFunction (); -#endif /* _FUNCTION_DEF */ - -/* Add POINTER to the list of pointers found in ARRAY. SLOTS is the number - of slots that have already been allocated. INDEX is the index into the - array where POINTER should be added. GROW is the number of slots to grow - ARRAY by, in the case that it needs growing. TYPE is a cast of the type - of object stored in ARRAY (e.g., NODE_ENTRY *. */ -#define add_pointer_to_array(pointer, idx, array, slots, grow, type) \ - do { \ - if (idx + 2 >= slots) \ - array = (type *)(xrealloc (array, (slots += grow) * sizeof (type))); \ - array[idx++] = (type)pointer; \ - array[idx] = (type)NULL; \ - } while (0) - -#define maybe_free(x) do { if (x) free (x); } while (0) - -#if !defined (zero_mem) && defined (HAVE_MEMSET) -# define zero_mem(mem, length) memset (mem, 0, length) -#endif /* !zero_mem && HAVE_MEMSET */ - -#if !defined (zero_mem) && defined (HAVE_BZERO) -# define zero_mem(mem, length) bzero (mem, length) -#endif /* !zero_mem && HAVE_BZERO */ - -#if !defined (zero_mem) -# define zero_mem(mem, length) \ - do { \ - register int zi; \ - register unsigned char *place; \ - \ - place = (unsigned char *)mem; \ - for (zi = 0; zi < length; zi++) \ - place[zi] = 0; \ - } while (0) -#endif /* !zero_mem */ - -#endif /* !_GENERAL_H_ */ diff --git a/gnu/usr.bin/texinfo/info/info-stnd.texi b/gnu/usr.bin/texinfo/info/info-stnd.texi deleted file mode 100644 index 0ff5fd7fb28..00000000000 --- a/gnu/usr.bin/texinfo/info/info-stnd.texi +++ /dev/null @@ -1,1365 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename info-stnd.info -@settitle GNU Info -@set InfoProgVer 2.11 -@paragraphindent none -@footnotestyle end -@synindex vr cp -@synindex fn cp -@synindex ky cp -@comment %**end of header -@comment $Id: info-stnd.texi,v 1.3 2002/06/10 13:51:03 espie Exp $ - -@dircategory Texinfo documentation system -@direntry -* info program: (info-stnd). Standalone Info-reading program. -@end direntry - -@ifinfo -This file documents GNU Info, a program for viewing the on-line formatted -versions of Texinfo files. This documentation is different from the -documentation for the Info reader that is part of GNU Emacs. If you do -not know how to use Info, but have a working Info reader, you should -read that documentation first. - -Copyright @copyright{} 1992, 93, 96 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -sections entitled ``Copying'' and ``GNU General Public License'' are -included exactly as in the original, and provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Free Software Foundation. -@end ifinfo - -@titlepage -@title GNU Info User's Guide -@subtitle For GNU Info version @value{InfoProgVer} -@author Brian J. Fox (bfox@@ai.mit.edu) -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993 Free Software Foundation - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -sections entitled ``Copying'' and ``GNU General Public License'' are -included exactly as in the original, and provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Free Software Foundation. -@end titlepage - -@ifinfo -@node Top, What is Info, (dir), (dir) -@top The GNU Info Program - -This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files, version @value{InfoProgVer}. This -documentation is different from the documentation for the Info reader -that is part of GNU Emacs. -@end ifinfo - -@menu -* What is Info:: -* Options:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around - in a window. -* Node Commands:: Commands for selecting a new node. -* Searching Commands:: Commands for searching an Info file. -* Xref Commands:: Commands for selecting cross references. -* Window Commands:: Commands which manipulate multiple windows. -* Printing Nodes:: How to print out the contents of a node. -* Miscellaneous Commands:: A few commands that defy categories. -* Variables:: How to change the default behavior of Info. -* GNU Info Global Index:: Global index containing keystrokes, - command names, variable names, - and general concepts. -@end menu - -@node What is Info, Options, Top, Top -@chapter What is Info? - -@iftex -This file documents GNU Info, a program for viewing the on-line formatted -versions of Texinfo files, version @value{InfoProgVer}. -@end iftex - -@dfn{Info} is a program which is used to view Info files on an ASCII -terminal. @dfn{Info files} are the result of processing Texinfo files -with the program @code{makeinfo} or with one of the Emacs commands, such -as @code{M-x texinfo-format-buffer}. Texinfo itself is a documentation -system that uses a single source file to produce both on-line -information and printed output. You can typeset and print the -files that you read in Info.@refill - -@node Options, Cursor Commands, What is Info, Top -@chapter Command Line Options -@cindex command line options -@cindex arguments, command line - -GNU Info accepts several options to control the initial node being -viewed, and to specify which directories to search for Info files. Here -is a template showing an invocation of GNU Info from the shell: - -@example -info [--@var{option-name} @var{option-value}] @var{menu-item}@dots{} -@end example - -The following @var{option-names} are available when invoking Info from -the shell: - -@table @code -@cindex directory path -@item --directory @var{directory-path} -@itemx -d @var{directory-path} -Add @var{directory-path} to the list of directory paths searched when -Info needs to find a file. You may issue @code{--directory} multiple -times; once for each directory which contains Info files. -Alternatively, you may specify a value for the environment variable -@code{INFOPATH}; if @code{--directory} is not given, the value of -@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon -separated list of directory names. If you do not supply @code{INFOPATH} -or @code{--directory-path}, Info uses a default path. - -@item --file @var{filename} -@itemx -f @var{filename} -@cindex Info file, selecting -Specify a particular Info file to visit. By default, Info visits -the file @code{dir}; if you use this option, Info will start with -@code{(@var{filename})Top} as the first file and node. - -@item --node @var{nodename} -@itemx -n @var{nodename} -@cindex node, selecting -Specify a particular node to visit in the initial file that Info -loads. This is especially useful in conjunction with -@code{--file}@footnote{Of course, you can specify both the file and node -in a @code{--node} command; but don't forget to escape the open and -close parentheses from the shell as in: @code{info --node -"(emacs)Buffers"}}. You may specify @code{--node} multiple times; for -an interactive Info, each @var{nodename} is visited in its own window, -for a non-interactive Info (such as when @code{--output} is given) each -@var{nodename} is processed sequentially. - -@item --output @var{filename} -@itemx -o @var{filename} -@cindex file, outputting to -@cindex outputting to a file -Specify @var{filename} as the name of a file to which to direct output. -Each node that Info visits will be output to @var{filename} instead of -interactively viewed. A value of @code{-} for @var{filename} specifies -the standard output. - -@item --subnodes -@cindex @code{--subnodes}, command line option -This option only has meaning when given in conjunction with -@code{--output}. It means to recursively output the nodes appearing in -the menus of each node being output. Menu items which resolve to -external Info files are not output, and neither are menu items which are -members of an index. Each node is only output once. - -@item --help -@itemx -h -Produces a relatively brief description of the available Info options. - -@item --version -@cindex version information -Prints the version information of Info and exits. - -@item @var{menu-item} -@cindex menu, following -Info treats its remaining arguments as the names of menu items. The -first argument is a menu item in the initial node visited, while -the second argument is a menu item in the first argument's node. -You can easily move to the node of your choice by specifying the menu -names which describe the path to that node. For example, - -@example -info emacs buffers -@end example - -@noindent -first selects the menu item @samp{Emacs} in the node @samp{(dir)Top}, -and then selects the menu item @samp{Buffers} in the node -@samp{(emacs)Top}. -@end table - -@node Cursor Commands, Scrolling Commands, Options, Top -@chapter Moving the Cursor -@cindex cursor, moving - -Many people find that reading screens of text page by page is made -easier when one is able to indicate particular pieces of text with some -kind of pointing device. Since this is the case, GNU Info (both the -Emacs and standalone versions) have several commands which allow you to -move the cursor about the screen. The notation used in this manual to -describe keystrokes is identical to the notation used within the Emacs -manual, and the GNU Readline manual. @xref{Characters, , Character -Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the -notation. - -The following table lists the basic cursor movement commands in Info. -Each entry consists of the key sequence you should type to execute the -cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it -invokes @code{execute-extended-command}. @xref{M-x, , Executing an -extended command, emacs, the GNU Emacs Manual}, for more detailed -information.} command name (displayed in parentheses), and a short -description of what the command does. All of the cursor motion commands -can take an @dfn{numeric} argument (@pxref{Miscellaneous Commands, -@code{universal-argument}}), to find out how to supply them. With a -numeric argument, the motion commands are simply executed that -many times; for example, a numeric argument of 4 given to -@code{next-line} causes the cursor to move down 4 lines. With a -negative numeric argument, the motion is reversed; an argument of -4 -given to the @code{next-line} command would cause the cursor to move -@emph{up} 4 lines. - -@table @asis -@item @code{C-n} (@code{next-line}) -@kindex C-n -@findex next-line -Move the cursor down to the next line. - -@item @code{C-p} (@code{prev-line}) -@kindex C-p -@findex prev-line -Move the cursor up to the previous line. - -@item @code{C-a} (@code{beginning-of-line}) -@kindex C-a, in Info windows -@findex beginning-of-line -Move the cursor to the start of the current line. - -@item @code{C-e} (@code{end-of-line}) -@kindex C-e, in Info windows -@findex end-of-line -Move the cursor to the end of the current line. - -@item @code{C-f} (@code{forward-char}) -@kindex C-f, in Info windows -@findex forward-char -Move the cursor forward a character. - -@item @code{C-b} (@code{backward-char}) -@kindex C-b, in Info windows -@findex backward-char -Move the cursor backward a character. - -@item @code{M-f} (@code{forward-word}) -@kindex M-f, in Info windows -@findex forward-word -Move the cursor forward a word. - -@item @code{M-b} (@code{backward-word}) -@kindex M-b, in Info windows -@findex backward-word -Move the cursor backward a word. - -@item @code{M-<} (@code{beginning-of-node}) -@itemx @code{b} -@kindex b, in Info windows -@kindex M-< -@findex beginning-of-node -Move the cursor to the start of the current node. - -@item @code{M->} (@code{end-of-node}) -@kindex M-> -@findex end-of-node -Move the cursor to the end of the current node. - -@item @code{M-r} (@code{move-to-window-line}) -@kindex M-r -@findex move-to-window-line -Move the cursor to a specific line of the window. Without a numeric -argument, @code{M-r} moves the cursor to the start of the line in the -center of the window. With a numeric argument of @var{n}, @code{M-r} -moves the cursor to the start of the @var{n}th line in the window. -@end table - -@node Scrolling Commands, Node Commands, Cursor Commands, Top -@chapter Moving Text Within a Window -@cindex scrolling - -Sometimes you are looking at a screenful of text, and only part of the -current paragraph you are reading is visible on the screen. The -commands detailed in this section are used to shift which part of the -current node is visible on the screen. - -@table @asis -@item @code{SPC} (@code{scroll-forward}) -@itemx @code{C-v} -@kindex SPC, in Info windows -@kindex C-v -@findex scroll-forward -Shift the text in this window up. That is, show more of the node which -is currently below the bottom of the window. With a numeric argument, -show that many more lines at the bottom of the window; a numeric -argument of 4 would shift all of the text in the window up 4 lines -(discarding the top 4 lines), and show you four new lines at the bottom -of the window. Without a numeric argument, @key{SPC} takes the bottom -two lines of the window and places them at the top of the window, -redisplaying almost a completely new screenful of lines. - -@item @code{DEL} (@code{scroll-backward}) -@itemx @code{M-v} -@kindex DEL, in Info windows -@kindex M-v -@findex scroll-backward -Shift the text in this window down. The inverse of -@code{scroll-forward}. -@end table - -@cindex scrolling through node structure -The @code{scroll-forward} and @code{scroll-backward} commands can also -move forward and backward through the node structure of the file. If -you press @key{SPC} while viewing the end of a node, or @key{DEL} while -viewing the beginning of a node, what happens is controlled by the -variable @code{scroll-behavior}. @xref{Variables, -@code{scroll-behavior}}, for more information. - -@table @asis -@item @code{C-l} (@code{redraw-display}) -@kindex C-l -@findex redraw-display -Redraw the display from scratch, or shift the line containing the cursor -to a specified location. With no numeric argument, @samp{C-l} clears -the screen, and then redraws its entire contents. Given a numeric -argument of @var{n}, the line containing the cursor is shifted so that -it is on the @var{n}th line of the window. - -@item @code{C-x w} (@code{toggle-wrap}) -@kindex C-w -@findex toggle-wrap -Toggles the state of line wrapping in the current window. Normally, -lines which are longer than the screen width @dfn{wrap}, i.e., they are -continued on the next line. Lines which wrap have a @samp{\} appearing -in the rightmost column of the screen. You can cause such lines to be -terminated at the rightmost column by changing the state of line -wrapping in the window with @code{C-x w}. When a line which needs more -space than one screen width to display is displayed, a @samp{$} appears -in the rightmost column of the screen, and the remainder of the line is -invisible. -@end table - -@node Node Commands, Searching Commands, Scrolling Commands, Top -@chapter Selecting a New Node -@cindex nodes, selection of - -This section details the numerous Info commands which select a new node -to view in the current window. - -The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and -@samp{l}. - -When you are viewing a node, the top line of the node contains some Info -@dfn{pointers} which describe where the next, previous, and up nodes -are. Info uses this line to move about the node structure of the file -when you use the following commands: - -@table @asis -@item @code{n} (@code{next-node}) -@kindex n -@findex next-node -Select the `Next' node. - -@item @code{p} (@code{prev-node}) -@kindex p -@findex prev-node -Select the `Prev' node. - -@item @code{u} (@code{up-node}) -@kindex u -@findex up-node -Select the `Up' node. -@end table - -You can easily select a node that you have already viewed in this window -by using the @samp{l} command -- this name stands for "last", and -actually moves through the list of already visited nodes for this -window. @samp{l} with a negative numeric argument moves forward through -the history of nodes for this window, so you can quickly step between -two adjacent (in viewing history) nodes. - -@table @asis -@item @code{l} (@code{history-node}) -@kindex l -@findex history-node -Select the most recently selected node in this window. -@end table - -Two additional commands make it easy to select the most commonly -selected nodes; they are @samp{t} and @samp{d}. - -@table @asis -@item @code{t} (@code{top-node}) -@kindex t -@findex top-node -Select the node @samp{Top} in the current Info file. - -@item @code{d} (@code{dir-node}) -@kindex d -@findex dir-node -Select the directory node (i.e., the node @samp{(dir)}). -@end table - -Here are some other commands which immediately result in the selection -of a different node in the current window: - -@table @asis -@item @code{<} (@code{first-node}) -@kindex < -@findex first-node -Selects the first node which appears in this file. This node is most -often @samp{Top}, but it does not have to be. - -@item @code{>} (@code{last-node}) -@kindex > -@findex last-node -Select the last node which appears in this file. - -@item @code{]} (@code{global-next-node}) -@kindex ] -@findex global-next-node -Move forward or down through node structure. If the node that you are -currently viewing has a @samp{Next} pointer, that node is selected. -Otherwise, if this node has a menu, the first menu item is selected. If -there is no @samp{Next} and no menu, the same process is tried with the -@samp{Up} node of this node. - -@item @code{[} (@code{global-prev-node}) -@kindex [ -@findex global-prev-node -Move backward or up through node structure. If the node that you are -currently viewing has a @samp{Prev} pointer, that node is selected. -Otherwise, if the node has an @samp{Up} pointer, that node is selected, -and if it has a menu, the last item in the menu is selected. -@end table - -You can get the same behavior as @code{global-next-node} and -@code{global-prev-node} while simply scrolling through the file with -@key{SPC} and @key{DEL}; @xref{Variables, @code{scroll-behavior}}, for -more information. - -@table @asis -@item @code{g} (@code{goto-node}) -@kindex g -@findex goto-node -Read the name of a node and select it. No completion is done while -reading the node name, since the desired node may reside in a separate -file. The node must be typed exactly as it appears in the Info file. A -file name may be included as with any node specification, for example - -@example -@code{g(emacs)Buffers} -@end example - -finds the node @samp{Buffers} in the Info file @file{emacs}. - -@item @code{C-x k} (@code{kill-node}) -@kindex C-x k -@findex kill-node -Kill a node. The node name is prompted for in the echo area, with a -default of the current node. @dfn{Killing} a node means that Info tries -hard to forget about it, removing it from the list of history nodes kept -for the window where that node is found. Another node is selected in -the window which contained the killed node. - -@item @code{C-x C-f} (@code{view-file}) -@kindex C-x C-f -@findex view-file -Read the name of a file and selects the entire file. The command -@example -@code{C-x C-f @var{filename}} -@end example -is equivalent to typing -@example -@code{g(@var{filename})*} -@end example - -@item @code{C-x C-b} (@code{list-visited-nodes}) -@kindex C-x C-b -@findex list-visited-nodes -Make a window containing a menu of all of the currently visited nodes. -This window becomes the selected window, and you may use the standard -Info commands within it. - -@item @code{C-x b} (@code{select-visited-node}) -@kindex C-x b -@findex select-visited-node -Select a node which has been previously visited in a visible window. -This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is -created. -@end table - -@node Searching Commands, Xref Commands, Node Commands, Top -@chapter Searching an Info File -@cindex searching - -GNU Info allows you to search for a sequence of characters throughout an -entire Info file, search through the indices of an Info file, or find -areas within an Info file which discuss a particular topic. - -@table @asis -@item @code{s} (@code{search}) -@kindex s -@findex search -Read a string in the echo area and search for it. - -@item @code{C-s} (@code{isearch-forward}) -@kindex C-s -@findex isearch-forward -Interactively search forward through the Info file for a string as you -type it. - -@item @code{C-r} (@code{isearch-backward}) -@kindex C-r -@findex isearch-backward -Interactively search backward through the Info file for a string as -you type it. - -@item @code{i} (@code{index-search}) -@kindex i -@findex index-search -Look up a string in the indices for this Info file, and select a node -where the found index entry points to. - -@item @code{,} (@code{next-index-match}) -@kindex , -@findex next-index-match -Move to the node containing the next matching index item from the last -@samp{i} command. -@end table - -The most basic searching command is @samp{s} (@code{search}). The -@samp{s} command prompts you for a string in the echo area, and then -searches the remainder of the Info file for an occurrence of that string. -If the string is found, the node containing it is selected, and the -cursor is left positioned at the start of the found string. Subsequent -@samp{s} commands show you the default search string within @samp{[} and -@samp{]}; pressing @key{RET} instead of typing a new string will use the -default search string. - -@dfn{Incremental searching} is similar to basic searching, but the -string is looked up while you are typing it, instead of waiting until -the entire search string has been specified. - -@node Xref Commands, Window Commands, Searching Commands, Top -@chapter Selecting Cross References - -We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} -pointers which appear at the top of a node. In addition to these -pointers, a node may contain other pointers which refer you to a -different node, perhaps in another Info file. Such pointers are called -@dfn{cross references}, or @dfn{xrefs} for short. - -@menu -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. -@end menu - -@node Parts of an Xref, Selecting Xrefs, , Xref Commands -@section Parts of an Xref - -Cross references have two major parts: the first part is called the -@dfn{label}; it is the name that you can use to refer to the cross -reference, and the second is the @dfn{target}; it is the full name of -the node that the cross reference points to. - -The target is separated from the label by a colon @samp{:}; first the -label appears, and then the target. For example, in the sample menu -cross reference below, the single colon separates the label from the -target. - -@example -* Foo Label: Foo Target. More information about Foo. -@end example - -Note the @samp{.} which ends the name of the target. The @samp{.} is -not part of the target; it serves only to let Info know where the target -name ends. - -A shorthand way of specifying references allows two adjacent colons to -stand for a target name which is the same as the label name: - -@example -* Foo Commands:: Commands pertaining to Foo. -@end example - -In the above example, the name of the target is the same as the name of -the label, in this case @code{Foo Commands}. - -You will normally see two types of cross reference while viewing nodes: -@dfn{menu} references, and @dfn{note} references. Menu references -appear within a node's menu; they begin with a @samp{*} at the beginning -of a line, and continue with a label, a target, and a comment which -describes what the contents of the node pointed to contains. - -Note references appear within the body of the node text; they begin with -@code{*Note}, and continue with a label and a target. - -Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross references -can point to any valid node. They are used to refer you to a place -where more detailed information can be found on a particular subject. -Here is a cross reference which points to a node within the Texinfo -documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo -Manual}, for more information on creating your own texinfo cross -references. - -@node Selecting Xrefs, , Parts of an Xref, Xref Commands -@section Selecting Xrefs - -The following table lists the Info commands which operate on menu items. - -@table @asis -@item @code{1} (@code{menu-digit}) -@itemx @code{2} @dots{} @code{9} -@cindex 1 @dots{} 9, in Info windows -@kindex 1 @dots{} 9, in Info windows -@findex menu-digit -Within an Info window, pressing a single digit, (such as @samp{1}), -selects that menu item, and places its node in the current window. -For convenience, there is one exception; pressing @samp{0} selects the -@emph{last} item in the node's menu. - -@item @code{0} (@code{last-menu-item}) -@kindex 0, in Info windows -@findex last-menu-item -Select the last item in the current node's menu. - -@item @code{m} (@code{menu-item}) -@kindex m -@findex menu-item -Reads the name of a menu item in the echo area and selects its node. -Completion is available while reading the menu label. - -@item @code{M-x find-menu} -@findex find-menu -Move the cursor to the start of this node's menu. -@end table - -This table lists the Info commands which operate on note cross references. - -@table @asis -@item @code{f} (@code{xref-item}) -@itemx @code{r} -@kindex f -@kindex r -@findex xref-item -Reads the name of a note cross reference in the echo area and selects -its node. Completion is available while reading the cross reference -label. -@end table - -Finally, the next few commands operate on menu or note references alike: - -@table @asis -@item @code{TAB} (@code{move-to-next-xref}) -@kindex TAB, in Info windows -@findex move-to-next-xref -Move the cursor to the start of the next nearest menu item or note -reference in this node. You can then use @key{RET} -(@code{select-reference-this-line}) to select the menu or note reference. - -@item @code{M-TAB} (@code{move-to-prev-xref}) -@kindex M-TAB, in Info windows -@findex move-to-prev-xref -Move the cursor the start of the nearest previous menu item or note -reference in this node. - -@item @code{RET} (@code{select-reference-this-line}) -@kindex RET, in Info windows -@findex select-reference-this-line -Select the menu item or note reference appearing on this line. -@end table - -@node Window Commands, Printing Nodes, Xref Commands, Top -@chapter Manipulating Multiple Windows -@cindex windows, manipulating - -A @dfn{window} is a place to show the text of a node. Windows have a -view area where the text of the node is displayed, and an associated -@dfn{mode line}, which briefly describes the node being viewed. - -GNU Info supports multiple windows appearing in a single screen; each -window is separated from the next by its modeline. At any time, there -is only one @dfn{active} window, that is, the window in which the cursor -appears. There are commands available for creating windows, changing -the size of windows, selecting which window is active, and for deleting -windows. - -@menu -* The Mode Line:: What appears in the mode line? -* Basic Windows:: Manipulating windows in Info. -* The Echo Area:: Used for displaying errors and reading input. -@end menu - -@node The Mode Line, Basic Windows, , Window Commands -@section The Mode Line - -A @dfn{mode line} is a line of inverse video which appears at the bottom -of an Info window. It describes the contents of the window just above -it; this information includes the name of the file and node appearing in -that window, the number of screen lines it takes to display the node, -and the percentage of text that is above the top of the window. It can -also tell you if the indirect tags table for this Info file needs to be -updated, and whether or not the Info file was compressed when stored on -disk. - -Here is a sample mode line for a window containing an uncompressed file -named @file{dir}, showing the node @samp{Top}. - -@example -@group ------Info: (dir)Top, 40 lines --Top--------------------------------------- - ^^ ^ ^^^ ^^ - (file)Node #lines where -@end group -@end example - -When a node comes from a file which is compressed on disk, this is -indicated in the mode line with two small @samp{z}'s. In addition, if -the Info file containing the node has been split into subfiles, the name -of the subfile containing the node appears in the modeline as well: - -@example ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z--------------- -@end example - -When Info makes a node internally, such that there is no corresponding -info file on disk, the name of the node is surrounded by asterisks -(@samp{*}). The name itself tells you what the contents of the window -are; the sample mode line below shows an internally constructed node -showing possible completions: - -@example ------Info: *Completions*, 7 lines --All----------------------------------- -@end example - -@node Basic Windows, The Echo Area, The Mode Line, Window Commands -@section Window Commands - -It can be convenient to view more than one node at a time. To allow -this, Info can display more than one @dfn{window}. Each window has its -own mode line (@pxref{The Mode Line}) and history of nodes viewed in that -window (@pxref{Node Commands, , @code{history-node}}). - -@table @asis -@item @code{C-x o} (@code{next-window}) -@cindex windows, selecting -@kindex C-x o -@findex next-window -Select the next window on the screen. Note that the echo area can only be -selected if it is already in use, and you have left it temporarily. -Normally, @samp{C-x o} simply moves the cursor into the next window on -the screen, or if you are already within the last window, into the first -window on the screen. Given a numeric argument, @samp{C-x o} moves over -that many windows. A negative argument causes @samp{C-x o} to select -the previous window on the screen. - -@item @code{M-x prev-window} -@findex prev-window -Select the previous window on the screen. This is identical to -@samp{C-x o} with a negative argument. - -@item @code{C-x 2} (@code{split-window}) -@cindex windows, creating -@kindex C-x 2 -@findex split-window -Split the current window into two windows, both showing the same node. -Each window is one half the size of the original window, and the cursor -remains in the original window. The variable @code{automatic-tiling} -can cause all of the windows on the screen to be resized for you -automatically, please @pxref{Variables, , automatic-tiling} for more -information. - -@item @code{C-x 0} (@code{delete-window}) -@cindex windows, deleting -@kindex C-x 0 -@findex delete-window -Delete the current window from the screen. If you have made too many -windows and your screen appears cluttered, this is the way to get rid of -some of them. - -@item @code{C-x 1} (@code{keep-one-window}) -@kindex C-x 1 -@findex keep-one-window -Delete all of the windows excepting the current one. - -@item @code{ESC C-v} (@code{scroll-other-window}) -@kindex ESC C-v, in Info windows -@findex scroll-other-window -Scroll the other window, in the same fashion that @samp{C-v} might -scroll the current window. Given a negative argument, scroll the -"other" window backward. - -@item @code{C-x ^} (@code{grow-window}) -@kindex C-x ^ -@findex grow-window -Grow (or shrink) the current window. Given a numeric argument, grow -the current window that many lines; with a negative numeric argument, -shrink the window instead. - -@item @code{C-x t} (@code{tile-windows}) -@cindex tiling -@kindex C-x t -@findex tile-windows -Divide the available screen space among all of the visible windows. -Each window is given an equal portion of the screen in which to display -its contents. The variable @code{automatic-tiling} can cause -@code{tile-windows} to be called when a window is created or deleted. -@xref{Variables, , @code{automatic-tiling}}. -@end table - -@node The Echo Area, , Basic Windows, Window Commands -@section The Echo Area -@cindex echo area - -The @dfn{echo area} is a one line window which appears at the bottom of -the screen. It is used to display informative or error messages, and to -read lines of input from you when that is necessary. Almost all of the -commands available in the echo area are identical to their Emacs -counterparts, so please refer to that documentation for greater depth of -discussion on the concepts of editing a line of text. The following -table briefly lists the commands that are available while input is being -read in the echo area: - -@table @asis -@item @code{C-f} (@code{echo-area-forward}) -@kindex C-f, in the echo area -@findex echo-area-forward -Move forward a character. - -@item @code{C-b} (@code{echo-area-backward}) -@kindex C-b, in the echo area -@findex echo-area-backward -Move backward a character. - -@item @code{C-a} (@code{echo-area-beg-of-line}) -@kindex C-a, in the echo area -@findex echo-area-beg-of-line -Move to the start of the input line. - -@item @code{C-e} (@code{echo-area-end-of-line}) -@kindex C-e, in the echo area -@findex echo-area-end-of-line -Move to the end of the input line. - -@item @code{M-f} (@code{echo-area-forward-word}) -@kindex M-f, in the echo area -@findex echo-area-forward-word -Move forward a word. - -@item @code{M-b} (@code{echo-area-backward-word}) -@kindex M-b, in the echo area -@findex echo-area-backward-word -Move backward a word. - -@item @code{C-d} (@code{echo-area-delete}) -@kindex C-d, in the echo area -@findex echo-area-delete -Delete the character under the cursor. - -@item @code{DEL} (@code{echo-area-rubout}) -@kindex DEL, in the echo area -@findex echo-area-rubout -Delete the character behind the cursor. - -@item @code{C-g} (@code{echo-area-abort}) -@kindex C-g, in the echo area -@findex echo-area-abort -Cancel or quit the current operation. If completion is being read, -@samp{C-g} discards the text of the input line which does not match any -completion. If the input line is empty, @samp{C-g} aborts the calling -function. - -@item @code{RET} (@code{echo-area-newline}) -@kindex RET, in the echo area -@findex echo-area-newline -Accept (or forces completion of) the current input line. - -@item @code{C-q} (@code{echo-area-quoted-insert}) -@kindex C-q, in the echo area -@findex echo-area-quoted-insert -Insert the next character verbatim. This is how you can insert control -characters into a search string, for example. - -@item @var{printing character} (@code{echo-area-insert}) -@kindex printing characters, in the echo area -@findex echo-area-insert -Insert the character. - -@item @code{M-TAB} (@code{echo-area-tab-insert}) -@kindex M-TAB, in the echo area -@findex echo-area-tab-insert -Insert a TAB character. - -@item @code{C-t} (@code{echo-area-transpose-chars}) -@kindex C-t, in the echo area -@findex echo-area-transpose-chars -Transpose the characters at the cursor. -@end table - -The next group of commands deal with @dfn{killing}, and @dfn{yanking} -text. For an in depth discussion of killing and yanking, -@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} - -@table @asis -@item @code{M-d} (@code{echo-area-kill-word}) -@kindex M-d, in the echo area -@findex echo-area-kill-word -Kill the word following the cursor. - -@item @code{M-DEL} (@code{echo-area-backward-kill-word}) -@kindex M-DEL, in the echo area -@findex echo-area-backward-kill-word -Kill the word preceding the cursor. - -@item @code{C-k} (@code{echo-area-kill-line}) -@kindex C-k, in the echo area -@findex echo-area-kill-line -Kill the text from the cursor to the end of the line. - -@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) -@kindex C-x DEL, in the echo area -@findex echo-area-backward-kill-line -Kill the text from the cursor to the beginning of the line. - -@item @code{C-y} (@code{echo-area-yank}) -@kindex C-y, in the echo area -@findex echo-area-yank -Yank back the contents of the last kill. - -@item @code{M-y} (@code{echo-area-yank-pop}) -@kindex M-y, in the echo area -@findex echo-area-yank-pop -Yank back a previous kill, removing the last yanked text first. -@end table - -Sometimes when reading input in the echo area, the command that needed -input will only accept one of a list of several choices. The choices -represent the @dfn{possible completions}, and you must respond with one -of them. Since there are a limited number of responses you can make, -Info allows you to abbreviate what you type, only typing as much of the -response as is necessary to uniquely identify it. In addition, you can -request Info to fill in as much of the response as is possible; this -is called @dfn{completion}. - -The following commands are available when completing in the echo area: - -@table @asis -@item @code{TAB} (@code{echo-area-complete}) -@itemx @code{SPC} -@kindex TAB, in the echo area -@kindex SPC, in the echo area -@findex echo-area-complete -Insert as much of a completion as is possible. - -@item @code{?} (@code{echo-area-possible-completions}) -@kindex ?, in the echo area -@findex echo-area-possible-completions -Display a window containing a list of the possible completions of what -you have typed so far. For example, if the available choices are: - -@example -@group -bar -foliate -food -forget -@end group -@end example - -@noindent -and you have typed an @samp{f}, followed by @samp{?}, the possible -completions would contain: - -@example -@group -foliate -food -forget -@end group -@end example - -@noindent -i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} -or @key{TAB} would result in @samp{fo} appearing in the echo area, since -all of the choices which begin with @samp{f} continue with @samp{o}. -Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} -appearing in the echo area, since that is the only choice which begins -with @samp{fol}. - -@item @code{ESC C-v} (@code{echo-area-scroll-completions-window}) -@kindex ESC C-v, in the echo area -@findex echo-area-scroll-completions-window -Scroll the completions window, if that is visible, or the "other" -window if not. -@end table - -@node Printing Nodes, Miscellaneous Commands, Window Commands, Top -@chapter Printing Out Nodes -@cindex printing - -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. In general, we recommend that you use @TeX{} to format the -document and print sections of it, by running @code{tex} on the Texinfo -source file. - -@table @asis -@item @code{M-x print-node} -@findex print-node -@cindex INFO_PRINT_COMMAND, environment variable -Pipe the contents of the current node through the command in the -environment variable @code{INFO_PRINT_COMMAND}. If the variable does not -exist, the node is simply piped to @code{lpr}. -@end table - -@node Miscellaneous Commands, Variables, Printing Nodes, Top -@chapter Miscellaneous Commands - -GNU Info contains several commands which self-document GNU Info: - -@table @asis -@item @code{M-x describe-command} -@cindex functions, describing -@cindex commands, describing -@findex describe-command -Read the name of an Info command in the echo area and then display a -brief description of what that command does. - -@item @code{M-x describe-key} -@cindex keys, describing -@findex describe-key -Read a key sequence in the echo area, and then display the name and -documentation of the Info command that the key sequence invokes. - -@item @code{M-x describe-variable} -Read the name of a variable in the echo area and then display a brief -description of what the variable affects. - -@item @code{M-x where-is} -@findex where-is -Read the name of an Info command in the echo area, and then display -a key sequence which can be typed in order to invoke that command. - -@item @code{C-h} (@code{get-help-window}) -@itemx @code{?} -@kindex C-h -@kindex ?, in Info windows -@findex get-help-window -Create (or Move into) the window displaying @code{*Help*}, and place -a node containing a quick reference card into it. This window displays -the most concise information about GNU Info available. - -@item @code{h} (@code{get-info-help-node}) -@kindex h -@findex get-info-help-node -Try hard to visit the node @code{(info)Help}. The Info file -@file{info.texi} distributed with GNU Info contains this node. Of -course, the file must first be processed with @code{makeinfo}, and then -placed into the location of your Info directory. -@end table - -Here are the commands for creating a numeric argument: - -@table @asis -@item @code{C-u} (@code{universal-argument}) -@cindex numeric arguments -@kindex C-u -@findex universal-argument -Start (or multiply by 4) the current numeric argument. @samp{C-u} is -a good way to give a small numeric argument to cursor movement or -scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while -@samp{C-u C-u C-n} moves the cursor down 16 lines. - -@item @code{M-1} (@code{add-digit-to-numeric-arg}) -@itemx @code{M-2} @dots{} @code{M-9} -@kindex M-1 @dots{} M-9 -@findex add-digit-to-numeric-arg -Add the digit value of the invoking key to the current numeric -argument. Once Info is reading a numeric argument, you may just type -the digits of the argument, without the Meta prefix. For example, you -might give @samp{C-l} a numeric argument of 32 by typing: - -@example -@kbd{C-u 3 2 C-l} -@end example - -@noindent -or - -@example -@kbd{M-3 2 C-l} -@end example -@end table - -@samp{C-g} is used to abort the reading of a multi-character key -sequence, to cancel lengthy operations (such as multi-file searches) and -to cancel reading input in the echo area. - -@table @asis -@item @code{C-g} (@code{abort-key}) -@cindex cancelling typeahead -@cindex cancelling the current operation -@kindex C-g, in Info windows -@findex abort-key -Cancel current operation. -@end table - -The @samp{q} command of Info simply quits running Info. - -@table @asis -@item @code{q} (@code{quit}) -@cindex quitting -@kindex q -@findex quit -Exit GNU Info. -@end table - -If the operating system tells GNU Info that the screen is 60 lines tall, -and it is actually only 40 lines tall, here is a way to tell Info that -the operating system is correct. - -@table @asis -@item @code{M-x set-screen-height} -@findex set-screen-height -@cindex screen, changing the height of -Read a height value in the echo area and set the height of the -displayed screen to that value. -@end table - -Finally, Info provides a convenient way to display footnotes which might -be associated with the current node that you are viewing: - -@table @asis -@item @code{ESC C-f} (@code{show-footnotes}) -@kindex ESC C-f -@findex show-footnotes -@cindex footnotes, displaying -Show the footnotes (if any) associated with the current node in another -window. You can have Info automatically display the footnotes -associated with a node when the node is selected by setting the variable -@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}. -@end table - -@node Variables, GNU Info Global Index, Miscellaneous Commands, Top -@chapter Manipulating Variables - -GNU Info contains several @dfn{variables} whose values are looked at by -various Info commands. You can change the values of these variables, -and thus change the behavior of Info to more closely match your -environment and Info file reading manner. - -@table @asis -@item @code{M-x set-variable} -@cindex variables, setting -@findex set-variable -Read the name of a variable, and the value for it, in the echo area and -then set the variable to that value. Completion is available when -reading the variable name; often, completion is available when reading -the value to give to the variable, but that depends on the variable -itself. If a variable does @emph{not} supply multiple choices to -complete over, it expects a numeric value. - -@item @code{M-x describe-variable} -@cindex variables, describing -@findex describe-variable -Read the name of a variable in the echo area and then display a brief -description of what the variable affects. -@end table - -Here is a list of the variables that you can set in Info. - -@table @code -@item automatic-footnotes -@vindex automatic-footnotes -When set to @code{On}, footnotes appear and disappear automatically. -This variable is @code{On} by default. When a node is selected, a -window containing the footnotes which appear in that node is created, -and the footnotes are displayed within the new window. The window that -Info creates to contain the footnotes is called @samp{*Footnotes*}. If -a node is selected which contains no footnotes, and a @samp{*Footnotes*} -window is on the screen, the @samp{*Footnotes*} window is deleted. -Footnote windows created in this fashion are not automatically tiled so -that they can use as little of the display as is possible. - -@item automatic-tiling -@vindex automatic-tiling -When set to @code{On}, creating or deleting a window resizes other -windows. This variable is @code{Off} by default. Normally, typing -@samp{C-x 2} divides the current window into two equal parts. When -@code{automatic-tiling} is set to @code{On}, all of the windows are -resized automatically, keeping an equal number of lines visible in each -window. There are exceptions to the automatic tiling; specifically, the -windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} -resized through automatic tiling; they remain their original size. - -@item visible-bell -@vindex visible-bell -When set to @code{On}, GNU Info attempts to flash the screen instead of -ringing the bell. This variable is @code{Off} by default. Of course, -Info can only flash the screen if the terminal allows it; in the case -that the terminal does not allow it, the setting of this variable has no -effect. However, you can make Info perform quietly by setting the -@code{errors-ring-bell} variable to @code{Off}. - -@item errors-ring-bell -@vindex errors-ring-bell -When set to @code{On}, errors cause the bell to ring. The default -setting of this variable is @code{On}. - -@item gc-compressed-files -@vindex gc-compressed-files -When set to @code{On}, Info garbage collects files which had to be -uncompressed. The default value of this variable is @code{Off}. -Whenever a node is visited in Info, the Info file containing that node -is read into core, and Info reads information about the tags and nodes -contained in that file. Once the tags information is read by Info, it -is never forgotten. However, the actual text of the nodes does not need -to remain in core unless a particular Info window needs it. For -non-compressed files, the text of the nodes does not remain in core when -it is no longer in use. But de-compressing a file can be a time -consuming operation, and so Info tries hard not to do it twice. -@code{gc-compressed-files} tells Info it is okay to garbage collect the -text of the nodes of a file which was compressed on disk. - -@item show-index-match -@vindex show-index-match -When set to @code{On}, the portion of the matched search string is -highlighted in the message which explains where the matched search -string was found. The default value of this variable is @code{On}. -When Info displays the location where an index match was found, -(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the -string that you had typed is highlighted by displaying it in the inverse -case from its surrounding characters. - -@item scroll-behavior -@vindex scroll-behavior -Control what happens when forward scrolling is requested at the end of -a node, or when backward scrolling is requested at the beginning of a -node. The default value for this variable is @code{Continuous}. There -are three possible values for this variable: - -@table @code -@item Continuous -Try to get the first item in this node's menu, or failing that, the -@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. -This behavior is identical to using the @samp{]} -(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) -commands. - -@item Next Only -Only try to get the @samp{Next} node. - -@item Page Only -Simply give up, changing nothing. If @code{scroll-behavior} is -@code{Page Only}, no scrolling command can change the node that is being -viewed. -@end table - -@item scroll-step -@vindex scroll-step -The number of lines to scroll when the cursor moves out of the window. -Scrolling happens automatically if the cursor has moved out of the -visible portion of the node text when it is time to display. Usually -the scrolling is done so as to put the cursor on the center line of the -current window. However, if the variable @code{scroll-step} has a -nonzero value, Info attempts to scroll the node text by that many lines; -if that is enough to bring the cursor back into the window, that is what -is done. The default value of this variable is 0, thus placing the -cursor (and the text it is attached to) in the center of the window. -Setting this variable to 1 causes a kind of "smooth scrolling" which -some people prefer. - -@item ISO-Latin -@cindex ISO Latin characters -@vindex ISO-Latin -When set to @code{On}, Info accepts and displays ISO Latin characters. -By default, Info assumes an ASCII character set. @code{ISO-Latin} tells -Info that it is running in an environment where the European standard -character set is in use, and allows you to input such characters to -Info, as well as display them. -@end table - - - -@c the following is incomplete -@ignore -@c node Info for Sys Admins -@c chapter Info for System Administrators - -This text describes some common ways of setting up an Info hierarchy -from scratch, and details the various options that are available when -installing Info. This text is designed for the person who is installing -GNU Info on the system; although users may find the information present -in this section interesting, none of it is vital to understanding how to -use GNU Info. - -@menu -* Setting the INFOPATH:: Where are my Info files kept? -* Editing the DIR node:: What goes in `DIR', and why? -* Storing Info files:: Alternate formats allow flexibility in setups. -* Using `localdir':: Building DIR on the fly. -* Example setups:: Some common ways to organize Info files. -@end menu - -@c node Setting the INFOPATH -@c section Setting the INFOPATH - -Where are my Info files kept? - -@c node Editing the DIR node -@c section Editing the DIR node - -What goes in `DIR', and why? - -@c node Storing Info files -@c section Storing Info files - -Alternate formats allow flexibility in setups. - -@c node Using `localdir' -@c section Using `localdir' - -Building DIR on the fly. - -@c node Example setups -@c section Example setups - -Some common ways to organize Info files. -@end ignore - -@node GNU Info Global Index, , Variables, Top -@appendix Global Index - -@printindex cp - -@contents -@bye diff --git a/gnu/usr.bin/texinfo/info/info.1 b/gnu/usr.bin/texinfo/info/info.1 deleted file mode 100644 index f95687303d2..00000000000 --- a/gnu/usr.bin/texinfo/info/info.1 +++ /dev/null @@ -1,229 +0,0 @@ -.TH info 1 "7th December 1990" -.SH NAME -info \- GNU's hypertext system -.SH SYNOPSIS -.B info -[ -.B \-\-option-name option-value -] -.B \menu-item... -.SH COPYRIGHT -.if n Copyright (C) 1989, 1993 Free Software Foundation, Inc. -.if t Copyright \(co 1989, 1993 Free Software Foundation, Inc. -.SH DESCRIPTION -.LP -The GNU project has a hypertext system called -.I Info -which allows the same source file to be either printed as a -paper manual, or viewed using -.B info. -It is possible to use the -.B info -program from inside Emacs, or to use the stand-alone version described here. -This manual page gives a brief summary of its capabilities. - -.SH OPTIONS -.TP -.B \-\-directory directory-path -Add -.B directory-path -to the list of directory paths searched when -.B info -needs to find a file. You may issue -.B \-\-directory -multiple times. -Alternatively, you may specify a value for the environment variable -.B INFOPATH; -if -.B \-\-directory -is not given, the value of -.B INFOPATH -is used. The value of -.B INFOPATH -is a colon separated list of directory names. If you do not supply either -.B INFOPATH -or -.B \-\-directory-path, -.B info -uses a default path. -.TP -.B \-f filename -Specify a particular -.B info -file to visit. By default, -.B info -visits -the file -.B dir; -if you use this option, -.B info -will start with -.B (FILENAME)Top -as the first file and node. -.TP -.B \-n nodename -Specify a particular node to visit in the initial file that -.B info -loads. This is especially useful in conjunction with -.B \-\-file. -You may specify -.B \-\-node -multiple times. -.TP -.B -o file -Direct output to -.B file -instead of starting an interactive -.B info -session. -.TP -.B \-h -Produce a relatively brief description of the available -.B info -options. -.TP -.B \-\-version -Print the version information of -.B info -and exit. -.TP -.B menu-item -.B info -treats its remaining arguments as the names of menu items. -The first argument is a menu item in the initial node visited, -while the second argument is a menu item in the first argument's -node. You can easily move to the node of your choice by -specifying the menu names which describe the path to that node. -For example, - -.B info emacs buffers - -first selects the menu item -.B emacs -in the node -.B (dir)Top, -and then selects the menu item -.B buffers -in the node -.B (emacs)Top. -.SH COMMANDS -When in -.B info -the following commands are available: -.TP -.B h -Invoke the Info tutorial. -.TP -.B ? -Get a short summary of -.B info -commands. -.TP -.B h -Select the -.B info -node from the main directory; this is much more complete than just -using -.B ?. -.TP -.B Ctrl-g -Abort whatever you are doing. -.TP -.B Ctrl-l -Redraw the screen. -.PP -Selecting other nodes: -.TP -.B n -Move to the "next" node of this node. -.TP -.B p -Move to the "previous" node of this node. -.TP -.B u -Move to this node's "up" node. -.TP -.B m -Pick a menu item specified by name. Picking a menu item causes another -node to be selected. You do not need to type a complete nodename; if -you type a few letters and then a space or tab -.B info -will will try to fill in the rest of the nodename. If you ask for further -completion without typing any more characters you'll be given a list -of possibilities; you can also get the list with -.B ?. -If you type a few characters and then hit return -.B info -will try to do a completion, and if it is ambigous use the first possibility. -.TP -.B f -Follow a cross reference. You are asked for the name of the reference, -using command completion as for -.B m. -.TP -.B l -Move to the last node you were at. -.PP -Moving within a node: -.TP -.B Space -Scroll forward a page. -.TP -.B DEL -Scroll backward a page. -.TP -.B b -Go to the beginning of this node. -.PP -Advanced commands: -.TP -.B q -Quit -.B info. -.TP -.B 1 -Pick first item in node's menu. -.TP -.B 2 \-\- 5 -Pick second ... fifth item in node's menu. -.TP -.B g -Move to node specified by name. You may include a filename as well, -as -.B (FILENAME)NODENAME. -.TP -.B s -Search through this -.B info -file for a specified string, and select the node in which -the next occurrence is found. -.TP -.B M-x print-node -Pipe the contents of the current node through the command in the -environment variable -.B INFO_PRINT_COMMAND. -If the variable does not exist, the node is simply piped to -.B lpr. -.SH ENVIRONMENT -.TP -.B INFOPATH -A colon-separated list of directories to search for -.B info -files. Used if -.B \-\-directory -is not given. -.TP -.B INFO_PRINT_COMMAND -The command used for printing. -.SH SEE ALSO -.BR emacs (1) -.SH AUTHOR -.RS -Brian Fox, Free Software Foundation -.br -bfox@ai.mit.edu -.SH MANUAL AUTHOR -.RS -Robert Lupton; updated by Robert J. Chassell. -.br -rhl@astro.princeton.edu; bob@gnu.ai.mit.edu diff --git a/gnu/usr.bin/texinfo/info/info.texi b/gnu/usr.bin/texinfo/info/info.texi deleted file mode 100644 index 43ea852e4cc..00000000000 --- a/gnu/usr.bin/texinfo/info/info.texi +++ /dev/null @@ -1,916 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename info.info -@settitle Info 1.0 -@comment %**end of header -@comment $Id: info.texi,v 1.3 2002/06/10 13:51:03 espie Exp $ - -@dircategory Texinfo documentation system -@direntry -* Info: (info). Documentation browsing system. -@end direntry - -@ifinfo -This file describes how to use Info, -the on-line, menu-driven GNU documentation system. - -Copyright (C) 1989, 92, 96 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@end ifinfo - -@titlepage -@sp 11 -@center @titlefont{Info} -@sp 2 -@center The -@sp 2 -@center On-line, Menu-driven -@sp 2 -@center GNU Documentation System - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1989, 1992, 1993 Free Software Foundation, Inc. -@sp 2 - -Published by the Free Software Foundation @* -59 Temple Place - Suite 330 @* -Boston, MA 02111-1307, USA. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@end titlepage - -@ifinfo -@node Top, Getting Started, (dir), (dir) -@top Info: An Introduction - -Info is a program for reading documentation, which you are using now. - -To learn how to use Info, type the command @kbd{h}. It brings you -to a programmed instruction sequence. - -@c Need to make sure that `Info-help' goes to the right node, -@c which is the first node of the first chapter. (It should.) -@c (Info-find-node "info" -@c (if (< (window-height) 23) -@c "Help-Small-Screen" -@c "Help"))) - -To learn advanced Info commands, type @kbd{n} twice. This brings you to -@cite{Info for Experts}, skipping over the `Getting Started' chapter. -@end ifinfo - -@menu -* Getting Started:: Getting started using an Info reader. -* Advanced Info:: Advanced commands within Info. -* Create an Info File:: How to make your own Info file. -* The Standalone Info Program: (info-stnd.info). -@end menu - -@node Getting Started, Advanced Info, Top, Top -@comment node-name, next, previous, up -@chapter Getting Started - -This first part of the Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced -Info commands, and how to write an Info as distinct from a Texinfo -file. The third part is about how to generate Info files from -Texinfo files. - -@iftex -This manual is primarily designed for use on a computer, so that you can -try Info commands while reading about them. Reading it on paper is less -effective, since you must take it on faith that the commands described -really do what the manual says. By all means go through this manual now -that you have it; but please try going through the on-line version as -well. - -There are two ways of looking at the online version of this manual: - -@enumerate -@item -Type @code{info} at your shell's command line. This approach uses a -small stand-alone program designed just to read Info files. - -@item -Type @code{emacs} at the command line; then type @kbd{C-h i} (Control -@kbd{h}, followed by @kbd{i}). This approach uses the Info mode of the -Emacs program, an editor with many other capabilities. -@end enumerate - -In either case, then type @kbd{mInfo} (just the letters), followed by -@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should -be ready to follow the instructions in this manual as you read them on -the screen. -@c FIXME! (pesch@cygnus.com, 14 dec 1992) -@c Is it worth worrying about what-if the beginner goes to somebody -@c else's Emacs session, which already has an Info running in the middle -@c of something---in which case these simple instructions won't work? -@end iftex - -@menu -* Help-Small-Screen:: Starting Info on a Small Screen -* Help:: How to use Info -* Help-P:: Returning to the Previous node -* Help-^L:: The Space, Rubout, B and ^L commands. -* Help-M:: Menus -* Help-Adv:: Some advanced Info commands -* Help-Q:: Quitting Info -@end menu - -@node Help-Small-Screen, Help, , Getting Started -@comment node-name, next, previous, up -@section Starting Info on a Small Screen - -@iftex -(In Info, you only see this section if your terminal has a small -number of lines; most readers pass by it without seeing it.) -@end iftex - -Since your terminal has an unusually small number of lines on its -screen, it is necessary to give you special advice at the beginning. - -If you see the text @samp{--All----} at near the bottom right corner -of the screen, it means the entire text you are looking at fits on the -screen. If you see @samp{--Top----} instead, it means that there is -more text below that does not fit. To move forward through the text -and see another screen full, press the Space bar, @key{SPC}. To move -back up, press the key labeled @samp{Backspace} or @key{Delete}. - -@ifinfo -Here are 40 lines of junk, so you can try Spaces and Deletes and -see what they do. At the end are instructions of what you should do -next. - -This is line 17 @* -This is line 18 @* -This is line 19 @* -This is line 20 @* -This is line 21 @* -This is line 22 @* -This is line 23 @* -This is line 24 @* -This is line 25 @* -This is line 26 @* -This is line 27 @* -This is line 28 @* -This is line 29 @* -This is line 30 @* -This is line 31 @* -This is line 32 @* -This is line 33 @* -This is line 34 @* -This is line 35 @* -This is line 36 @* -This is line 37 @* -This is line 38 @* -This is line 39 @* -This is line 40 @* -This is line 41 @* -This is line 42 @* -This is line 43 @* -This is line 44 @* -This is line 45 @* -This is line 46 @* -This is line 47 @* -This is line 48 @* -This is line 49 @* -This is line 50 @* -This is line 51 @* -This is line 52 @* -This is line 53 @* -This is line 54 @* -This is line 55 @* -This is line 56 @* - -If you have managed to get here, go back to the beginning with -Delete, and come back here again, then you understand Space and -Delete. So now type an @kbd{n} ---just one character; don't type -the quotes and don't type the Return key afterward--- to -get to the normal start of the course. -@end ifinfo - -@node Help, Help-P, Help-Small-Screen, Getting Started -@comment node-name, next, previous, up -@section How to use Info - -You are talking to the program Info, for reading documentation. - - Right now you are looking at one @dfn{Node} of Information. -A node contains text describing a specific topic at a specific -level of detail. This node's topic is ``how to use Info''. - - The top line of a node is its @dfn{header}. This node's header (look at -it now) says that it is the node named @samp{Help} in the file -@file{info}. It says that the @samp{Next} node after this one is the node -called @samp{Help-P}. An advanced Info command lets you go to any node -whose name you know. - - Besides a @samp{Next}, a node can have a @samp{Previous} or an @samp{Up}. -This node has a @samp{Previous} but no @samp{Up}, as you can see. - - Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. - ->> Type @samp{n} to move there. Type just one character; - do not type the quotes and do not type a @key{RET} afterward. - -@samp{>>} in the margin means it is really time to try a command. - -@node Help-P, Help-^L, Help, Getting Started -@comment node-name, next, previous, up -@section Returning to the Previous node - -This node is called @samp{Help-P}. The @samp{Previous} node, as you see, -is @samp{Help}, which is the one you just came from using the @kbd{n} -command. Another @kbd{n} command now would take you to the next -node, @samp{Help-^L}. - ->> But do not do that yet. First, try the @kbd{p} command, which takes - you to the @samp{Previous} node. When you get there, you can do an - @kbd{n} again to return here. - - This all probably seems insultingly simple so far, but @emph{do not} be -led into skimming. Things will get more complicated soon. Also, -do not try a new command until you are told it is time to. Otherwise, -you may make Info skip past an important warning that was coming up. - ->> Now do an @kbd{n} to get to the node @samp{Help-^L} and learn more. - -@node Help-^L, Help-M, Help-P, Getting Started -@comment node-name, next, previous, up -@section The Space, Delete, B and ^L commands. - - This node's header tells you that you are now at node @samp{Help-^L}, and -that @kbd{p} would get you back to @samp{Help-P}. The node's title is -underlined; it says what the node is about (most nodes have titles). - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you -can see the string @samp{--Top-----} rather than @samp{--All----} near -the bottom right corner of the screen. - - The Space, Delete and @kbd{B} commands exist to allow you to ``move -around'' in a node that does not all fit on the screen at once. -Space moves forward, to show what was below the bottom of the screen. -Delete moves backward, to show what was above the top of the screen -(there is not anything above the top until you have typed some spaces). - ->> Now try typing a Space (afterward, type a Delete to return here). - - When you type the space, the two lines that were at the bottom of -the screen appear at the top, followed by more lines. Delete takes -the two lines from the top and moves them to the bottom, -@emph{usually}, but if there are not a full screen's worth of lines -above them they may not make it all the way to the bottom. - - If you type Space when there is no more to see, it rings the -bell and otherwise does nothing. The same goes for Delete when -the header of the node is visible. - - If your screen is ever garbaged, you can tell Info to print it out -again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down ``Control'' and -type an @key{L} or @kbd{l}). - ->> Type @kbd{C-l} now. - - To move back to the beginning of the node you are on, you can type -a lot of Deletes. You can also type simply @kbd{b} for beginning. ->> Try that now. (We have put in enough verbiage to push this past -the first screenful, but screens are so big nowadays that perhaps it -isn't enough. You may need to shrink your Emacs or Info window.) -Then come back, with Spaces. - - If your screen is very tall, all of this node might fit at once. -In that case, "b" won't do anything. Sorry; what can we do? - - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type -a @key{?} which prints out a brief list of commands. When you are -finished looking at the list, make it go away by typing a @key{SPC}. - ->> Type a @key{?} now. After it finishes, type a @key{SPC}. - - (If you are using the standalone Info reader, type `l' to return here.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use Space and Delete to move -around in them without being told. Since not all terminals have -the same size screen, it would be impossible to warn you anyway. - ->> Now type @kbd{n} to see the description of the @kbd{m} command. - -@node Help-M, Help-Adv, Help-^L, Getting Started -@comment node-name, next, previous, up -@section Menus - -Menus and the @kbd{m} command - - With only the @kbd{n} and @kbd{p} commands for moving between nodes, nodes -are restricted to a linear sequence. Menus allow a branching -structure. A menu is a list of other nodes you can move to. It is -actually just part of the text of the node formatted specially so that -Info can interpret it. The beginning of a menu is always identified -by a line which starts with @samp{* Menu:}. A node contains a menu if and -only if it has a line in it which starts that way. The only menu you -can use at any moment is the one in the node you are in. To use a -menu in any other node, you must move to that node first. - - After the start of the menu, each line that starts with a @samp{*} -identifies one subtopic. The line usually contains a brief name -for the subtopic (followed by a @samp{:}), the name of the node that talks -about that subtopic, and optionally some further description of the -subtopic. Lines in the menu that do not start with a @samp{*} have no -special meaning---they are only for the human reader's benefit and do -not define additional subtopics. Here is an example: - -@example -* Foo: FOO's Node This tells about FOO -@end example - -The subtopic name is Foo, and the node describing it is @samp{FOO's Node}. -The rest of the line is just for the reader's Information. -[[ But this line is not a real menu item, simply because there is -no line above it which starts with @samp{* Menu:}.]] - - When you use a menu to go to another node (in a way that will be -described soon), what you specify is the subtopic name, the first -thing in the menu line. Info uses it to find the menu line, extracts -the node name from it, and goes to that node. The reason that there -is both a subtopic name and a node name is that the node name must be -meaningful to the computer and may therefore have to be ugly looking. -The subtopic name can be chosen just to be convenient for the user to -specify. Often the node name is convenient for the user to specify -and so both it and the subtopic name are the same. There is an -abbreviation for this: - -@example -* Foo:: This tells about FOO -@end example - -@noindent -This means that the subtopic name and node name are the same; they are -both @samp{Foo}. - ->> Now use Spaces to find the menu in this node, then come back to - the front with a @kbd{b} and some Spaces. As you see, a menu is - actually visible in its node. If you cannot find a menu in a node - by looking at it, then the node does not have a menu and the - @kbd{m} command is not available. - - The command to go to one of the subnodes is @kbd{m}---but @emph{do -not do it yet!} Before you use @kbd{m}, you must understand the -difference between commands and arguments. So far, you have learned -several commands that do not need arguments. When you type one, Info -processes it and is instantly ready for another command. The @kbd{m} -command is different: it is incomplete without the @dfn{name of the -subtopic}. Once you have typed @kbd{m}, Info tries to read the -subtopic name. - - Now look for the line containing many dashes near the bottom of the -screen. There is one more line beneath that one, but usually it is -blank. If it is empty, Info is ready for a command, such as @kbd{n} -or @kbd{b} or Space or @kbd{m}. If that line contains text ending -in a colon, it mean Info is trying to read the @dfn{argument} to a -command. At such times, commands do not work, because Info tries to -use them as the argument. You must either type the argument and -finish the command you started, or type @kbd{Control-g} to cancel the -command. When you have done one of those things, the line becomes -blank again. - - The command to go to a subnode via a menu is @kbd{m}. After you type -the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }. -You must then type the name of the subtopic you want, and end it with -a @key{RET}. - - You can abbreviate the subtopic name. If the abbreviation is not -unique, the first matching subtopic is chosen. Some menus put -the shortest possible abbreviation for each subtopic name in capital -letters, so you can see how much you need to type. It does not -matter whether you use upper case or lower case when you type the -subtopic. You should not put any spaces at the end, or inside of the -item name, except for one space where a space appears in the item in -the menu. - - You can also use the @dfn{completion} feature to help enter the subtopic -name. If you type the Tab key after entering part of a name, it will -magically fill in more of the name---as much as follows uniquely from -what you have entered. - - If you move the cursor to one of the menu subtopic lines, then you do -not need to type the argument: you just type a Return, and it stands for -the subtopic of the line you are on. - -Here is a menu to give you a chance to practice. - -* Menu: The menu starts here. - -This menu gives you three ways of going to one place, Help-FOO. - -* Foo: Help-FOO. A node you can visit for fun.@* -* Bar: Help-FOO. Strange! two ways to get to the same place.@* -* Help-FOO:: And yet another!@* - - ->> Now type just an @kbd{m} and see what happens: - - Now you are ``inside'' an @kbd{m} command. Commands cannot be used -now; the next thing you will type must be the name of a subtopic. - - You can change your mind about doing the @kbd{m} by typing Control-g. - ->> Try that now; notice the bottom line clear. - ->> Then type another @kbd{m}. - ->> Now type @samp{BAR} item name. Do not type Return yet. - - While you are typing the item name, you can use the Delete key to -cancel one character at a time if you make a mistake. - ->> Type one to cancel the @samp{R}. You could type another @samp{R} to - replace it. You do not have to, since @samp{BA} is a valid abbreviation. - ->> Now you are ready to go. Type a @key{RET}. - - After visiting Help-FOO, you should return here. - ->> Type @kbd{n} to see more commands. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -Here is another way to get to Help-FOO, a menu. You can ignore this -if you want, or else try it (but then please come back to here). - -@menu -* Help-FOO:: -@end menu - -@node Help-FOO, , , Help-M -@comment node-name, next, previous, up -@subsection The @kbd{u} command - - Congratulations! This is the node @samp{Help-FOO}. Unlike the other -nodes you have seen, this one has an @samp{Up}: @samp{Help-M}, the node you -just came from via the @kbd{m} command. This is the usual -convention---the nodes you reach from a menu have @samp{Up} nodes that lead -back to the menu. Menus move Down in the tree, and @samp{Up} moves Up. -@samp{Previous}, on the other hand, is usually used to ``stay on the same -level but go backwards'' - - You can go back to the node @samp{Help-M} by typing the command -@kbd{u} for ``Up''. That puts you at the @emph{front} of the -node---to get back to where you were reading you have to type -some @key{SPC}s. - ->> Now type @kbd{u} to move back up to @samp{Help-M}. - -@node Help-Adv, Help-Q, Help-M, Getting Started -@comment node-name, next, previous, up -@section Some advanced Info commands - - The course is almost over, so please stick with it to the end. - - If you have been moving around to different nodes and wish to -retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will -do that, one node-step at a time. As you move from node to node, Info -records the nodes where you have been in a special history list. The -@kbd{l} command revisits nodes in the history list; each successive -@kbd{l} command moves one step back through the history. - - If you have been following directions, ad @kbd{l} command now will get -you back to @samp{Help-M}. Another @kbd{l} command would undo the -@kbd{u} and get you back to @samp{Help-FOO}. Another @kbd{l} would undo -the @kbd{m} and get you back to @samp{Help-M}. - ->> Try typing three @kbd{l}'s, pausing in between to see what each - @kbd{l} does. - -Then follow directions again and you will end up back here. - - Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to -where @emph{you} last were, whereas @kbd{p} always moves to the node -which the header says is the @samp{Previous} node (from this node, to -@samp{Help-M}). - - The @samp{d} command gets you instantly to the Directory node. -This node, which is the first one you saw when you entered Info, -has a menu which leads (directly, or indirectly through other menus), -to all the nodes that exist. - ->> Try doing a @samp{d}, then do an @kbd{l} to return here (yes, - @emph{do} return). - - Sometimes, in Info documentation, you will see a cross reference. -Cross references look like this: @xref{Help-Cross, Cross}. That is a -real, live cross reference which is named @samp{Cross} and points at -the node named @samp{Help-Cross}. - - If you wish to follow a cross reference, you must use the @samp{f} -command. The @samp{f} must be followed by the cross reference name -(in this case, @samp{Cross}). While you enter the name, you can use the -Delete key to edit your input. If you change your mind about following -any reference, you can use @kbd{Control-g} to cancel the command. - - Completion is available in the @samp{f} command; you can complete among -all the cross reference names in the current node by typing a Tab. - ->> Type @samp{f}, followed by @samp{Cross}, and a @key{RET}. - - To get a list of all the cross references in the current node, you can -type @kbd{?} after an @samp{f}. The @samp{f} continues to await a -cross reference name even after printing the list, so if you don't -actually want to follow a reference, you should type a @kbd{Control-g} -to cancel the @samp{f}. - ->> Type "f?" to get a list of the cross references in this node. Then - type a @kbd{Control-g} and see how the @samp{f} gives up. - ->> Now type @kbd{n} to see the last node of the course. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -@node Help-Cross, , , Help-Adv -@comment node-name, next, previous, up -@unnumberedsubsec The node reached by the cross reference in Info - - This is the node reached by the cross reference named @samp{Cross}. - - While this node is specifically intended to be reached by a cross -reference, most cross references lead to nodes that ``belong'' -someplace else far away in the structure of Info. So you cannot expect -the footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing back to -where you came from. In general, the @kbd{l} (el) command is the only -way to get back there. - ->> Type @kbd{l} to return to the node where the cross reference was. - -@node Help-Q, , Help-Adv, Getting Started -@comment node-name, next, previous, up -@section Quitting Info - - To get out of Info, back to what you were doing before, type @kbd{q} -for @dfn{Quit}. - - This is the end of the course on using Info. There are some other -commands that are meant for experienced users; they are useful, and you -can find them by looking in the directory node for documentation on -Info. Finding them will be a good exercise in using Info in the usual -manner. - ->> Type @samp{d} to go to the Info directory node; then type - @samp{mInfo} and Return, to get to the node about Info and - see what other help is available. - -@node Advanced Info, Create an Info File, Getting Started, Top -@comment node-name, next, previous, up -@chapter Info for Experts - -This chapter describes various advanced Info commands, and how to write -an Info as distinct from a Texinfo file. (However, in most cases, writing a -Texinfo file is better, since you can use it @emph{both} to generate an -Info file and to make a printed manual. @xref{Top,, Overview of -Texinfo, texinfo, Texinfo: The GNU Documentation Format}.) - -@menu -* Expert:: Advanced Info commands: g, s, e, and 1 - 5. -* Add:: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -* Menus:: How to add to or create menus in Info nodes. -* Cross-refs:: How to add cross-references to Info nodes. -* Tags:: How to make tag tables for Info files. -* Checking:: Checking an Info File -* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. -@end menu - -@node Expert, Add, , Advanced Info -@comment node-name, next, previous, up -@section Advanced Info Commands - -@kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{9}, and @kbd{e} - -If you know a node's name, you can go there by typing @kbd{g}, the -name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node -called @samp{Top} in this file (its directory node). -@kbd{gExpert@key{RET}} would come back here. - -Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. - -To go to a node in another file, you can include the filename in the -node name by putting it at the front, in parentheses. Thus, -@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is -node @samp{Top} in the file @file{dir}. - -The node name @samp{*} specifies the whole file. So you can look at -all of the current file by typing @kbd{g*@key{RET}} or all of any -other file with @kbd{g(FILENAME)@key{RET}}. - -The @kbd{s} command allows you to search a whole file for a string. -It switches to the next node if and when that is necessary. You -type @kbd{s} followed by the string to search for, terminated by -@key{RET}. To search for the same string again, just @kbd{s} followed -by @key{RET} will do. The file's nodes are scanned in the order -they are in in the file, which has no necessary relationship to the -order that they may be in in the tree structure of menus and @samp{next} pointers. -But normally the two orders are not very different. In any case, -you can always do a @kbd{b} to find out what node you have reached, if -the header is not visible (this can happen, because @kbd{s} puts your -cursor at the occurrence of the string, not at the beginning of the -node). - -If you grudge the system each character of type-in it requires, you -might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ... -@kbd{9}. They are short for the @kbd{m} command together with an -argument. @kbd{1} goes through the first item in the current node's -menu; @kbd{2} goes through the second item, etc. - -If you display supports multiple fonts, and you are using Emacs' Info -mode to read Info files, the @samp{*} for the fifth menu item is -underlines, and so is the @samp{*} for the ninth item; these underlines -make it easy to see at a glance which number to use for an item. - -On ordinary terminals, you won't have underlining. If you need to -actually count items, it is better to use @kbd{m} instead, and specify -the name. - -The Info command @kbd{e} changes from Info mode to an ordinary -Emacs editing mode, so that you can edit the text of the current node. -Type @kbd{C-c C-c} to switch back to Info. The @kbd{e} command is allowed -only if the variable @code{Info-enable-edit} is non-@code{nil}. - -@node Add, Menus, Expert, Advanced Info -@comment node-name, next, previous, up -@section Adding a new node to Info - -To add a new topic to the list in the Info directory, you must: -@enumerate -@item -Create some nodes, in some file, to document that topic. -@item -Put that topic in the menu in the directory. @xref{Menus, Menu}. -@end enumerate - -Usually, the way to create the nodes is with Texinfo @pxref{Top,, Overview of -Texinfo, texinfo, Texinfo: The GNU Documentation Format}); this has the -advantage that you can also make a printed manual from them. However, -if hyou want to edit an Info file, here is how. - - The new node can live in an existing documentation file, or in a new -one. It must have a @key{^_} character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a @key{^_}, a @key{^L}, or the end of file. Note: If you put in a -@key{^L} to end a new node, be sure that there is a @key{^_} after it -to start the next one, since @key{^L} cannot @emph{start} a node. -Also, a nicer way to make a node boundary be a page boundary as well -is to put a @key{^L} @emph{right after} the @key{^_}. - - The @key{^_} starting a node must be followed by a newline or a -@key{^L} newline, after which comes the node's header line. The -header line must give the node's name (by which Info finds it), -and state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if -there are any). As you can see, this node's @samp{Up} node is the node -@samp{Top}, which points at all the documentation for Info. The @samp{Next} -node is @samp{Menus}. - - The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up}, and @dfn{Next}, -may appear in any order, anywhere in the header line, but the -recommended order is the one in this sentence. Each keyword must be -followed by a colon, spaces and tabs, and then the appropriate name. -The name may be terminated with a tab, a comma, or a newline. A space -does not end it; node names may contain spaces. The case of letters -in the names is insignificant. - - A node name has two forms. A node in the current file is named by -what appears after the @samp{Node: } in that node's first line. For -example, this node's name is @samp{Add}. A node in another file is -named by @samp{(@var{filename})@var{node-within-file}}, as in -@samp{(info)Add} for this node. If the file name starts with ``./'', -then it is relative to the current directory; otherwise, it is relative -starting from the standard Info file directory of your site. -The name @samp{(@var{filename})Top} can be abbreviated to just -@samp{(@var{filename})}. By convention, the name @samp{Top} is used for -the ``highest'' node in any single file---the node whose @samp{Up} points -out of the file. The Directory node is @file{(dir)}. The @samp{Top} node -of a document file listed in the Directory should have an @samp{Up: -(dir)} in it. - - The node name @kbd{*} is special: it refers to the entire file. -Thus, @kbd{g*} shows you the whole current file. The use of the -node @kbd{*} is to make it possible to make old-fashioned, -unstructured files into nodes of the tree. - - The @samp{Node:} name, in which a node states its own name, must not -contain a filename, since Info when searching for a node does not -expect one to be there. The @samp{Next}, @samp{Previous} and @samp{Up} names may -contain them. In this node, since the @samp{Up} node is in the same file, -it was not necessary to use one. - - Note that the nodes in this file have a file name in the header -line. The file names are ignored by Info, but they serve as comments -to help identify the node for the user. - -@node Menus, Cross-refs, Add, Advanced Info -@comment node-name, next, previous, up -@section How to Create Menus - - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. -The @kbd{m} command searches the current node's menu for the topic which it -reads from the terminal. - - A menu begins with a line starting with @samp{* Menu:}. The rest of the -line is a comment. After the starting line, every line that begins -with a @samp{* } lists a single topic. The name of the topic--the -argument that the user must give to the @kbd{m} command to select this -topic---comes right after the star and space, and is followed by a -colon, spaces and tabs, and the name of the node which discusses that -topic. The node name, like node names following @samp{Next}, @samp{Previous} -and @samp{Up}, may be terminated with a tab, comma, or newline; it may also -be terminated with a period. - - If the node name and topic name are the same, then rather than -giving the name twice, the abbreviation @samp{* NAME::} may be used -(and should be used, whenever possible, as it reduces the visual -clutter in the menu). - - It is considerate to choose the topic names so that they differ -from each other very near the beginning---this allows the user to type -short abbreviations. In a long menu, it is a good idea to capitalize -the beginning of each item name which is the minimum acceptable -abbreviation for it (a long menu is more than 5 or so entries). - - The nodes listed in a node's menu are called its ``subnodes'', and -it is their ``superior''. They should each have an @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the -subnodes in a sequence of @samp{Next} and @samp{Previous} pointers so that someone who -wants to see them all need not keep revisiting the Menu. - - The Info Directory is simply the menu of the node @samp{(dir)Top}---that -is, node @samp{Top} in file @file{.../info/dir}. You can put new entries -in that menu just like any other menu. The Info Directory is @emph{not} the -same as the file directory called @file{info}. It happens that many of -Info's files live on that file directory, but they do not have to; and -files on that directory are not automatically listed in the Info -Directory node. - - Also, although the Info node graph is claimed to be a ``hierarchy'', -in fact it can be @emph{any} directed graph. Shared structures and -pointer cycles are perfectly possible, and can be used if they are -appropriate to the meaning to be expressed. There is no need for all -the nodes in a file to form a connected structure. In fact, this file -has two connected components. You are in one of them, which is under -the node @samp{Top}; the other contains the node @samp{Help} which the -@kbd{h} command goes to. In fact, since there is no garbage -collector, nothing terrible happens if a substructure is not pointed -to, but such a substructure is rather useless since nobody can -ever find out that it exists. - -@node Cross-refs, Tags, Menus, Advanced Info -@comment node-name, next, previous, up -@section Creating Cross References - - A cross reference can be placed anywhere in the text, unlike a menu -item which must go at the front of a line. A cross reference looks -like a menu item except that it has @samp{*note} instead of @kbd{*}. -It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are -so often part of node names. If you wish to enclose a cross reference -in parentheses, terminate it with a period first. Here are two -examples of cross references pointers: - -@example -*Note details: commands. (See *note 3: Full Proof.) -@end example - -They are just examples. The places they ``lead to'' do not really exist! - -@node Tags, Checking, Cross-refs, Advanced Info -@comment node-name, next, previous, up -@section Tag Tables for Info Files - - You can speed up the access to nodes of a large Info file by giving -it a tag table. Unlike the tag table for a program, the tag table for -an Info file lives inside the file itself and is used -automatically whenever Info reads in the file. - - To make a tag table, go to a node in the file using Emacs Info mode and type -@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the -file. - - Once the Info file has a tag table, you must make certain it is up -to date. If, as a result of deletion of text, any node moves back -more than a thousand characters in the file from the position -recorded in the tag table, Info will no longer be able to find that -node. To update the tag table, use the @code{Info-tagify} command again. - - An Info file tag table appears at the end of the file and looks like -this: - -@example -^_ -Tag Table: -File: info, Node: Cross-refs^?21419 -File: info, Node: Tags^?22145 -^_ -End Tag Table -@end example - -@noindent -Note that it contains one line per node, and this line contains -the beginning of the node's header (ending just after the node name), -a Delete character, and the character position in the file of the -beginning of the node. - -@node Checking, Emacs Info Variables, Tags, Advanced Info -@comment node-name, next, previous, up -@section Checking an Info File - - When creating an Info file, it is easy to forget the name of a node -when you are making a pointer to it from another node. If you put in -the wrong name for a node, this is not detected until someone -tries to go through the pointer using Info. Verification of the Info -file is an automatic process which checks all pointers to nodes and -reports any pointers which are invalid. Every @samp{Next}, @samp{Previous}, and -@samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{Previous} pointing back is -reported. Only pointers within the file are checked, because checking -pointers to other files would be terribly slow. But those are usually -few. - - To check an Info file, do @kbd{M-x Info-validate} while looking at -any node of the file with Emacs Info mode. - -@node Emacs Info Variables, , Checking, Advanced Info -@section Emacs Info-mode Variables - -The following variables may modify the behaviour of Info-mode in Emacs; -you may wish to set one or several of these variables interactively, or -in your @file{~/.emacs} init file. @xref{Examining, Examining and Setting -Variables, Examining and Setting Variables, emacs, The GNU Emacs -Manual}. - -@vtable @code -@item Info-enable-edit -Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command. A -non-@code{nil} value enables it. @xref{Add, Edit}. - -@item Info-enable-active-nodes -When set to a non-@code{nil} value, allows Info to execute Lisp code -associated with nodes. The Lisp code is executed when the node is -selected. - -@item Info-directory-list -The list of directories to search for Info files. Each element is a -string (directory name) or @code{nil} (try default directory). - -@item Info-directory -The standard directory for Info documentation files. Only used when the -function @code{Info-directory} is called. -@end vtable - -@node Create an Info File, , Advanced Info, Top -@comment node-name, next, previous, up -@chapter Creating an Info File from a Makeinfo file - -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same. - -@xref{Create an Info File, , Creating an Info File, texinfo, the Texinfo -Manual}, to learn how to create an Info file from a Texinfo file. - -@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU Documentation -Format}, to learn how to write a Texinfo file. - -@bye diff --git a/gnu/usr.bin/texinfo/info/userdoc.texi b/gnu/usr.bin/texinfo/info/userdoc.texi deleted file mode 100644 index f9349c65c50..00000000000 --- a/gnu/usr.bin/texinfo/info/userdoc.texi +++ /dev/null @@ -1,1270 +0,0 @@ -@c This file is meant to be included in any arbitrary piece of -@c documentation that wishes to describe the info program. Some day -@c info-stnd.texi should probably use this file instead of duplicating -@c its contents. -@c -@c This file documents the use of the standalone GNU Info program, -@c versions 2.7 and later. - -@ifclear InfoProgVer -@set InfoProgVer 2.11 -@end ifclear -@synindex vr cp -@synindex fn cp -@synindex ky cp - -@heading What is Info? - -This text documents the use of the GNU Info program, version -@value{InfoProgVer}. - -@dfn{Info} is a program which is used to view info files on an ASCII -terminal. @dfn{info files} are the result of processing texinfo files -with the program @code{makeinfo} or with the Emacs command @code{M-x -texinfo-format-buffer}. Finally, @dfn{texinfo} is a documentation -language which allows a printed manual and online documentation (an info -file) to be produced from a single source file. - -@menu -* Options:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around in a window. -* Node Commands:: Commands for selecting a new node. -* Searching Commands:: Commands for searching an info file. -* Xref Commands:: Commands for selecting cross references. -* Window Commands:: Commands which manipulate multiple windows. -* Printing Nodes:: How to print out the contents of a node. -* Miscellaneous Commands:: A few commands that defy categories. -* Variables:: How to change the default behaviour of Info. -@ifset NOTSET -* Info for Sys Admins:: How to setup Info. Using special options. -@end ifset -@ifset STANDALONE -* GNU Info Global Index:: Global index containing keystrokes, command names, - variable names, and general concepts. -@end ifset -@end menu - -@node Options -@chapter Command Line Options -@cindex command line options -@cindex arguments, command line - -GNU Info accepts several options to control the initial node being -viewed, and to specify which directories to search for info files. Here -is a template showing an invocation of GNU Info from the shell: - -@example -info [--@var{option-name} @var{option-value}] @var{menu-item}@dots{} -@end example - -The following @var{option-names} are available when invoking Info from -the shell: - -@table @code -@cindex directory path -@item --directory @var{directory-path} -@itemx -d @var{directory-path} -Adds @var{directory-path} to the list of directory paths searched when -Info needs to find a file. You may issue @code{--directory} multiple -times; once for each directory which contains info files. -Alternatively, you may specify a value for the environment variable -@code{INFOPATH}; if @code{--directory} is not given, the value of -@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon -separated list of directory names. If you do not supply -@code{INFOPATH} or @code{--directory-path} a default path is used. - -@item --file @var{filename} -@itemx -f @var{filename} -@cindex info file, selecting -Specifies a particular info file to visit. Instead of visiting the file -@code{dir}, Info will start with @code{(@var{filename})Top} as the first -file and node. - -@item --node @var{nodename} -@itemx -n @var{nodename} -@cindex node, selecting -Specifies a particular node to visit in the initial file loaded. This -is especially useful in conjunction with @code{--file}@footnote{Of -course, you can specify both the file and node in a @code{--node} -command; but don't forget to escape the open and close parentheses from -the shell as in: @code{info --node '(emacs)Buffers'}}. You may specify -@code{--node} multiple times; for an interactive Info, each -@var{nodename} is visited in its own window, for a non-interactive Info -(such as when @code{--output} is given) each @var{nodename} is processed -sequentially. - -@item --output @var{filename} -@itemx -o @var{filename} -@cindex file, outputting to -@cindex outputting to a file -Specify @var{filename} as the name of a file to output to. Each node -that Info visits will be output to @var{filename} instead of -interactively viewed. A value of @code{-} for @var{filename} specifies -the standard output. - -@item --subnodes -@cindex @code{--subnodes}, command line option -This option only has meaning when given in conjunction with -@code{--output}. It means to recursively output the nodes appearing in -the menus of each node being output. Menu items which resolve to -external info files are not output, and neither are menu items which are -members of an index. Each node is only output once. - -@item --help -@itemx -h -Produces a relatively brief description of the available Info options. - -@item --version -@cindex version information -Prints the version information of Info and exits. - -@item @var{menu-item} -@cindex menu, following -Remaining arguments to Info are treated as the names of menu items. The -first argument would be a menu item in the initial node visited, while -the second argument would be a menu item in the first argument's node. -You can easily move to the node of your choice by specifying the menu -names which describe the path to that node. For example, - -@example -info emacs buffers -@end example - -first selects the menu item @samp{Emacs} in the node @samp{(dir)Top}, -and then selects the menu item @samp{Buffers} in the node -@samp{(emacs)Top}. - -@end table - -@node Cursor Commands -@chapter Moving the Cursor -@cindex cursor, moving -Many people find that reading screens of text page by page is made -easier when one is able to indicate particular pieces of text with some -kind of pointing device. Since this is the case, GNU Info (both the -Emacs and standalone versions) have several commands which allow you to -move the cursor about the screen. The notation used in this manual to -describe keystrokes is identical to the notation used within the Emacs -manual, and the GNU Readline manual. @xref{Characters, , Character -Conventions, emacs, the GNU Emacs Manual}, if you are unfamilar with the -notation. - -The following table lists the basic cursor movement commands in Info. -Each entry consists of the key sequence you should type to execute the -cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it -invokes @code{execute-extended-command}. @xref{M-x, , Executing an -extended command, emacs, the GNU Emacs Manual}, for more detailed -information.} command name (displayed in parentheses), and a short -description of what the command does. All of the cursor motion commands -can take an @dfn{numeric} argument (@pxref{Miscellaneous Commands, -@code{universal-argument}}), to find out how to supply them. With a -numeric argument, the motion commands are simply executed that -many times; for example, a numeric argument of 4 given to -@code{next-line} causes the cursor to move down 4 lines. With a -negative numeric argument, the motion is reversed; an argument of -4 -given to the @code{next-line} command would cause the cursor to move -@emph{up} 4 lines. - -@table @asis -@item @code{C-n} (@code{next-line}) -@kindex C-n -@findex next-line -Moves the cursor down to the next line. - -@item @code{C-p} (@code{prev-line}) -@kindex C-p -@findex prev-line -Move the cursor up to the previous line. - -@item @code{C-a} (@code{beginning-of-line}) -@kindex C-a, in Info windows -@findex beginning-of-line -Move the cursor to the start of the current line. - -@item @code{C-e} (@code{end-of-line}) -@kindex C-e, in Info windows -@findex end-of-line -Moves the cursor to the end of the current line. - -@item @code{C-f} (@code{forward-char}) -@kindex C-f, in Info windows -@findex forward-char -Move the cursor forward a character. - -@item @code{C-b} (@code{backward-char}) -@kindex C-b, in Info windows -@findex backward-char -Move the cursor backward a character. - -@item @code{M-f} (@code{forward-word}) -@kindex M-f, in Info windows -@findex forward-word -Moves the cursor forward a word. - -@item @code{M-b} (@code{backward-word}) -@kindex M-b, in Info winows -@findex backward-word -Moves the cursor backward a word. - -@item @code{M-<} (@code{beginning-of-node}) -@itemx @code{b} -@kindex b, in Info winows -@kindex M-< -@findex beginning-of-node -Moves the cursor to the start of the current node. - -@item @code{M->} (@code{end-of-node}) -@kindex M-> -@findex end-of-node -Moves the cursor to the end of the current node. - -@item @code{M-r} (@code{move-to-window-line}) -@kindex M-r -@findex move-to-window-line -Moves the cursor to a specific line of the window. Without a numeric -argument, @code{M-r} moves the cursor to the start of the line in the -center of the window. With a numeric argument of @var{n}, @code{M-r} -moves the cursor to the start of the @var{n}th line in the window. -@end table - -@node Scrolling Commands -@chapter Moving Text Within a Window -@cindex scrolling - -Sometimes you are looking at a screenful of text, and only part of the -current paragraph you are reading is visible on the screen. The -commands detailed in this section are used to shift which part of the -current node is visible on the screen. - -@table @asis -@item @code{SPC} (@code{scroll-forward}) -@itemx @code{C-v} -@kindex SPC, in Info windows -@kindex C-v -@findex scroll-forward -Shift the text in this window up. That is, show more of the node which -is currently below the bottom of the window. With a numeric argument, -show that many more lines at the bottom of the window; a numeric -argument of 4 would shift all of the text in the window up 4 lines -(discarding the top 4 lines), and show you four new lines at the bottom -of the window. Without a numeric argument, @key{SPC} takes the bottom -two lines of the window and places them at the top of the window, -redisplaying almost a completely new screenful of lines. - -@item @code{DEL} (@code{scroll-backward}) -@itemx @code{M-v} -@kindex DEL, in Info windows -@kindex M-v -@findex scroll-backward -Shift the text in this window down. The inverse of -@code{scroll-forward}. - -@end table - -@cindex scrolling through node structure -The @code{scroll-forward} and @code{scroll-backward} commands can also -move forward and backward through the node structure of the file. If -you press @key{SPC} while viewing the end of a node, or @key{DEL} while -viewing the beginning of a node, what happens is controlled by the -variable @code{scroll-behaviour}. @xref{Variables, -@code{scroll-behaviour}}, for more information. - -@table @asis -@item @code{C-l} (@code{redraw-display}) -@kindex C-l -@findex redraw-display -Redraw the display from scratch, or shift the line containing the cursor -to a specified location. With no numeric argument, @samp{C-l} clears -the screen, and then redraws its entire contents. Given a numeric -argument of @var{n}, the line containing the cursor is shifted so that -it is on the @var{n}th line of the window. - -@item @code{C-x w} (@code{toggle-wrap}) -@kindex C-w -@findex toggle-wrap -Toggles the state of line wrapping in the current window. Normally, -lines which are longer than the screen width @dfn{wrap}, i.e., they are -continued on the next line. Lines which wrap have a @samp{\} appearing -in the rightmost column of the screen. You can cause such lines to be -terminated at the rightmost column by changing the state of line -wrapping in the window with @code{C-x w}. When a line which needs more -space than one screen width to display is displayed, a @samp{$} appears -in the rightmost column of the screen, and the remainder of the line is -invisible. -@end table - -@node Node Commands -@chapter Selecting a New Node -@cindex nodes, selection of - -This section details the numerous Info commands which select a new node -to view in the current window. - -The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and -@samp{l}. - -When you are viewing a node, the top line of the node contains some Info -@dfn{pointers} which describe where the next, previous, and up nodes -are. Info uses this line to move about the node structure of the file -when you use the following commands: - -@table @asis -@item @code{n} (@code{next-node}) -@kindex n -@findex next-node -Selects the `Next' node. - -@item @code{p} (@code{prev-node}) -@kindex p -@findex prev-node -Selects the `Prev' node. - -@item @code{u} (@code{up-node}) -@kindex u -@findex up-node -Selects the `Up' node. -@end table - -You can easily select a node that you have already viewed in this window -by using the @samp{l} command -- this name stands for "last", and -actually moves through the list of already visited nodes for this -window. @samp{l} with a negative numeric argument moves forward through -the history of nodes for this window, so you can quickly step between -two adjacent (in viewing history) nodes. - -@table @asis -@item @code{l} (@code{history-node}) -@kindex l -@findex history-node -Selects the most recently selected node in this window. -@end table - -Two additional commands make it easy to select the most commonly -selected nodes; they are @samp{t} and @samp{d}. - -@table @asis -@item @code{t} (@code{top-node}) -@kindex t -@findex top-node -Selects the node @samp{Top} in the current info file. - -@item @code{d} (@code{dir-node}) -@kindex d -@findex dir-node -Selects the directory node (i.e., the node @samp{(dir)}). -@end table - -Here are some other commands which immediately result in the selection -of a different node in the current window: - -@table @asis -@item @code{<} (@code{first-node}) -@kindex < -@findex first-node -Selects the first node which appears in this file. This node is most -often @samp{Top}, but it doesn't have to be. - -@item @code{>} (@code{last-node}) -@kindex > -@findex last-node -Selects the last node which appears in this file. - -@item @code{]} (@code{global-next-node}) -@kindex ] -@findex global-next-node -Moves forward or down through node structure. If the node that you are -currently viewing has a @samp{Next} pointer, that node is selected. -Otherwise, if this node has a menu, the first menu item is selected. If -there is no @samp{Next} and no menu, the same process is tried with the -@samp{Up} node of this node. - -@item @code{[} (@code{global-prev-node}) -@kindex [ -@findex global-prev-node -Moves backward or up through node structure. If the node that you are -currently viewing has a @samp{Prev} pointer, that node is selected. -Otherwise, if the node has an @samp{Up} pointer, that node is selected, -and if it has a menu, the last item in the menu is selected. -@end table - -You can get the same behaviour as @code{global-next-node} and -@code{global-prev-node} while simply scrolling through the file with -@key{SPC} and @key{DEL}; @xref{Variables, @code{scroll-behaviour}}, for -more information. - -@table @asis -@item @code{g} (@code{goto-node}) -@kindex g -@findex goto-node -Reads the name of a node and selects it. No completion is done while -reading the node name, since the desired node may reside in a separate -file. The node must be typed exactly as it appears in the info file. A -file name may be included as with any node specification, for example - -@example -@code{g(emacs)Buffers} -@end example - -finds the node @samp{Buffers} in the info file @file{emacs}. - -@item @code{C-x k} (@code{kill-node}) -@kindex C-x k -@findex kill-node -Kills a node. The node name is prompted for in the echo area, with a -default of the current node. @dfn{Killing} a node means that Info tries -hard to forget about it, removing it from the list of history nodes kept -for the window where that node is found. Another node is selected in -the window which contained the killed node. - -@item @code{C-x C-f} (@code{view-file}) -@kindex C-x C-f -@findex view-file -Reads the name of a file and selects the entire file. The command -@example -@code{C-x C-f @var{filename}} -@end example -is equivalent to typing -@example -@code{g(@var{filename})*} -@end example - -@item @code{C-x C-b} (@code{list-visited-nodes}) -@kindex C-x C-b -@findex list-visited-nodes -Makes a window containing a menu of all of the currently visited nodes. -This window becomes the selected window, and you may use the standard -Info commands within it. - -@item @code{C-x b} (@code{select-visited-node}) -@kindex C-x b -@findex select-visited-node -Selects a node which has been previously visited in a visible window. -This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is -created. -@end table - -@node Searching Commands -@chapter Searching an Info File -@cindex searching - -GNU Info allows you to search for a sequence of characters throughout an -entire info file, search through the indices of an info file, or find -areas within an info file which discuss a particular topic. - -@table @asis -@item @code{s} (@code{search}) -@kindex s -@findex search -Reads a string in the echo area and searches for it. - -@item @code{C-s} (@code{isearch-forward}) -@kindex C-s -@findex isearch-forward -Interactively searches forward through the info file for a string as you -type it. - -@item @code{C-r} (@code{isearch-backward}) -@kindex C-r -@findex isearch-backward -Interactively searches backward through the info file for a string as -you type it. - -@item @code{i} (@code{index-search}) -@kindex i -@findex index-search -Looks up a string in the indices for this info file, and selects a node -where the found index entry points to. - -@item @code{,} (@code{next-index-match}) -@kindex , -@findex next-index-match -Moves to the node containing the next matching index item from the last -@samp{i} command. -@end table - -The most basic searching command is @samp{s} (@code{search}). The -@samp{s} command prompts you for a string in the echo area, and then -searches the remainder of the info file for an ocurrence of that string. -If the string is found, the node containing it is selected, and the -cursor is left positioned at the start of the found string. Subsequent -@samp{s} commands show you the default search string within @samp{[} and -@samp{]}; pressing @key{RET} instead of typing a new string will use the -default search string. - -@dfn{Incremental searching} is similar to basic searching, but the -string is looked up while you are typing it, instead of waiting until -the entire search string has been specified. - -@node Xref Commands -@chapter Selecting Cross References - -We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} -pointers which appear at the top of a node. In addition to these -pointers, a node may contain other pointers which refer you to a -different node, perhaps in another info file. Such pointers are called -@dfn{cross references}, or @dfn{xrefs} for short. - -@menu -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. -@end menu - -@node Parts of an Xref -@section Parts of an Xref - -Cross references have two major parts: the first part is called the -@dfn{label}; it is the name that you can use to refer to the cross -reference, and the second is the @dfn{target}; it is the full name of -the node that the cross reference points to. - -The target is separated from the label by a colon @samp{:}; first the -label appears, and then the target. For example, in the sample menu -cross reference below, the single colon separates the label from the -target. - -@example -* Foo Label: Foo Target. More information about Foo. -@end example - -Note the @samp{.} which ends the name of the target. The @samp{.} is -not part of the target; it serves only to let Info know where the target -name ends. - -A shorthand way of specifying references allows two adjacent colons to -stand for a target name which is the same as the label name: - -@example -* Foo Commands:: Commands pertaining to Foo. -@end example - -In the above example, the name of the target is the same as the name of -the label, in this case @code{Foo Commands}. - -You will normally see two types of cross references while viewing nodes: -@dfn{menu} references, and @dfn{note} references. Menu references -appear within a node's menu; they begin with a @samp{*} at the beginning -of a line, and continue with a label, a target, and a comment which -describes what the contents of the node pointed to contains. - -Note references appear within the body of the node text; they begin with -@code{*Note}, and continue with a label and a target. - -Like @samp{Next}, @samp{Prev} and @samp{Up} pointers, cross references -can point to any valid node. They are used to refer you to a place -where more detailed information can be found on a particular subject. -Here is a cross reference which points to a node within the Texinfo -documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo -Manual}, for more information on creating your own texinfo cross -references. - -@node Selecting Xrefs -@section Selecting Xrefs - -The following table lists the Info commands which operate on menu items. - -@table @asis -@item @code{1} (@code{menu-digit}) -@itemx @code{2} @dots{} @code{9} -@cindex 1 @dots{} 9, in Info windows -@kindex 1 @dots{} 9, in Info windows -@findex menu-digit -Within an Info window, pressing a single digit, (such as @samp{1}), -selects that menu item, and places its node in the current window. -For convenience, there is one exception; pressing @samp{0} selects the -@emph{last} item in the node's menu. - -@item @code{0} (@code{last-menu-item}) -@kindex 0, in Info windows -@findex last-menu-item -Select the last item in the current node's menu. - -@item @code{m} (@code{menu-item}) -@kindex m -@findex menu-item -Reads the name of a menu item in the echo area and selects its node. -Completion is available while reading the menu label. - -@item @code{M-x find-menu} -@findex find-menu -Moves the cursor to the start of this node's menu. -@end table - -This table lists the Info commands which operate on note cross references. - -@table @asis -@item @code{f} (@code{xref-item}) -@itemx @code{r} -@kindex f -@kindex r -@findex xref-item -Reads the name of a note cross reference in the echo area and selects -its node. Completion is available while reading the cross reference -label. -@end table - -Finally, the next few commands operate on menu or note references alike: - -@table @asis -@item @code{TAB} (@code{move-to-next-xref}) -@kindex TAB, in Info windows -@findex move-to-next-xref -Moves the cursor to the start of the next nearest menu item or note -reference in this node. You can then use @key{RET} -(@code{select-reference-this-line} to select the menu or note reference. - -@item @code{M-TAB} (@code{move-to-prev-xref}) -@kindex M-TAB, in Info windows -@findex move-to-prev-xref -Moves the cursor the start of the nearest previous menu item or note -reference in this node. - -@item @code{RET} (@code{select-reference-this-line}) -@kindex RET, in Info windows -@findex select-reference-this-line -Selects the menu item or note reference appearing on this line. -@end table - -@node Window Commands -@chapter Manipulating Multiple Windows -@cindex windows, manipulating - -A @dfn{window} is a place to show the text of a node. Windows have a -view area where the text of the node is displayed, and an associated -@dfn{mode line}, which briefly describes the node being viewed. - -GNU Info supports multiple windows appearing in a single screen; each -window is separated from the next by its modeline. At any time, there -is only one @dfn{active} window, that is, the window in which the cursor -appears. There are commands available for creating windows, changing -the size of windows, selecting which window is active, and for deleting -windows. - -@menu -* The Mode Line:: What appears in the mode line? -* Basic Windows:: Manipulating windows in Info. -* The Echo Area:: Used for displaying errors and reading input. -@end menu - -@node The Mode Line -@section The Mode Line - -A @dfn{mode line} is a line of inverse video which appears at the bottom -of an info window. It describes the contents of the window just above -it; this information includes the name of the file and node appearing in -that window, the number of screen lines it takes to display the node, -and the percentage of text that is above the top of the window. It can -also tell you if the indirect tags table for this info file needs to be -updated, and whether or not the info file was compressed when stored on -disk. - -Here is a sample mode line for a window containing an uncompressed file -named @file{dir}, showing the node @samp{Top}. - -@example ------Info: (dir)Top, 40 lines --Top--------------------------------------- - ^^ ^ ^^^ ^^ - (file)Node #lines where -@end example - -When a node comes from a file which is compressed on disk, this is -indicated in the mode line with two small @samp{z}'s. In addition, if -the info file containing the node has been split into subfiles, the name -of the subfile containing the node appears in the modeline as well: - -@example ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z--------------- -@end example - -When Info makes a node internally, such that there is no corresponding -info file on disk, the name of the node is surrounded by asterisks -(@samp{*}). The name itself tells you what the contents of the window -are; the sample mode line below shows an internally constructed node -showing possible completions: - -@example ------Info: *Completions*, 7 lines --All----------------------------------- -@end example - -@node Basic Windows -@section Window Commands - -It can be convenient to view more than one node at a time. To allow -this, Info can display more than one @dfn{window}. Each window has its -own mode line (@pxref{The Mode Line}) and history of nodes viewed in that -window (@pxref{Node Commands, , @code{history-node}}). - -@table @asis -@item @code{C-x o} (@code{next-window}) -@cindex windows, selecting -@kindex C-x o -@findex next-window -Selects the next window on the screen. Note that the echo area can only be -selected if it is already in use, and you have left it temporarily. -Normally, @samp{C-x o} simply moves the cursor into the next window on -the screen, or if you are already within the last window, into the first -window on the screen. Given a numeric argument, @samp{C-x o} moves over -that many windows. A negative argument causes @samp{C-x o} to select -the previous window on the screen. - -@item @code{M-x prev-window} -@findex prev-window -Selects the previous window on the screen. This is identical to -@samp{C-x o} with a negative argument. - -@item @code{C-x 2} (@code{split-window}) -@cindex windows, creating -@kindex C-x 2 -@findex split-window -Splits the current window into two windows, both showing the same node. -Each window is one half the size of the original window, and the cursor -remains in the original window. The variable @code{automatic-tiling} -can cause all of the windows on the screen to be resized for you -automatically, please @pxref{Variables, , automatic-tiling} for more -information. - -@item @code{C-x 0} (@code{delete-window}) -@cindex windows, deleting -@kindex C-x 0 -@findex delete-window -Deletes the current window from the screen. If you have made too many -windows and your screen appears cluttered, this is the way to get rid of -some of them. - -@item @code{C-x 1} (@code{keep-one-window}) -@kindex C-x 1 -@findex keep-one-window -Deletes all of the windows excepting the current one. - -@item @code{ESC C-v} (@code{scroll-other-window}) -@kindex ESC C-v, in Info windows -@findex scroll-other-window -Scrolls the other window, in the same fashion that @samp{C-v} might -scroll the current window. Given a negative argument, the "other" -window is scrolled backward. - -@item @code{C-x ^} (@code{grow-window}) -@kindex C-x ^ -@findex grow-window -Grows (or shrinks) the current window. Given a numeric argument, grows -the current window that many lines; with a negative numeric argument, -the window is shrunk instead. - -@item @code{C-x t} (@code{tile-windows}) -@cindex tiling -@kindex C-x t -@findex tile-windows -Divides the available screen space among all of the visible windows. -Each window is given an equal portion of the screen in which to display -its contents. The variable @code{automatic-tiling} can cause -@code{tile-windows} to be called when a window is created or deleted. -@xref{Variables, , @code{automatic-tiling}}. -@end table - -@node The Echo Area -@section The Echo Area -@cindex echo area - -The @dfn{echo area} is a one line window which appears at the bottom of -the screen. It is used to display informative or error messages, and to -read lines of input from you when that is necessary. Almost all of the -commands available in the echo area are identical to their Emacs -counterparts, so please refer to that documentation for greater depth of -discussion on the concepts of editing a line of text. The following -table briefly lists the commands that are available while input is being -read in the echo area: - -@table @asis -@item @code{C-f} (@code{echo-area-forward}) -@kindex C-f, in the echo area -@findex echo-area-forward -Moves forward a character. - -@item @code{C-b} (@code{echo-area-backward}) -@kindex C-b, in the echo area -@findex echo-area-backward -Moves backward a character. - -@item @code{C-a} (@code{echo-area-beg-of-line}) -@kindex C-a, in the echo area -@findex echo-area-beg-of-line -Moves to the start of the input line. - -@item @code{C-e} (@code{echo-area-end-of-line}) -@kindex C-e, in the echo area -@findex echo-area-end-of-line -Moves to the end of the input line. - -@item @code{M-f} (@code{echo-area-forward-word}) -@kindex M-f, in the echo area -@findex echo-area-forward-word -Moves forward a word. - -@item @code{M-b} (@code{echo-area-backward-word}) -@kindex M-b, in the echo area -@findex echo-area-backward-word -Moves backward a word. - -@item @code{C-d} (@code{echo-area-delete}) -@kindex C-d, in the echo area -@findex echo-area-delete -Deletes the character under the cursor. - -@item @code{DEL} (@code{echo-area-rubout}) -@kindex DEL, in the echo area -@findex echo-area-rubout -Deletes the character behind the cursor. - -@item @code{C-g} (@code{echo-area-abort}) -@kindex C-g, in the echo area -@findex echo-area-abort -Cancels or quits the current operation. If completion is being read, -@samp{C-g} discards the text of the input line which does not match any -completion. If the input line is empty, @samp{C-g} aborts the calling -function. - -@item @code{RET} (@code{echo-area-newline}) -@kindex RET, in the echo area -@findex echo-area-newline -Accepts (or forces completion of) the current input line. - -@item @code{C-q} (@code{echo-area-quoted-insert}) -@kindex C-q, in the echo area -@findex echo-area-quoted-insert -Inserts the next character verbatim. This is how you can insert control -characters into a search string, for example. - -@item @var{printing character} (@code{echo-area-insert}) -@kindex printing characters, in the echo area -@findex echo-area-insert -Inserts the character. - -@item @code{M-TAB} (@code{echo-area-tab-insert}) -@kindex M-TAB, in the echo area -@findex echo-area-tab-insert -Inserts a TAB character. - -@item @code{C-t} (@code{echo-area-transpose-chars}) -@kindex C-t, in the echo area -@findex echo-area-transpose-chars -Transposes the characters at the cursor. -@end table - -The next group of commands deal with @dfn{killing}, and @dfn{yanking} -text. For an in depth discussion of killing and yanking, -@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} - -@table @asis -@item @code{M-d} (@code{echo-area-kill-word}) -@kindex M-d, in the echo area -@findex echo-area-kill-word -Kills the word following the cursor. - -@item @code{M-DEL} (@code{echo-area-backward-kill-word}) -@kindex M-DEL, in the echo area -@findex echo-area-backward-kill-word -Kills the word preceding the cursor. - -@item @code{C-k} (@code{echo-area-kill-line}) -@kindex C-k, in the echo area -@findex echo-area-kill-line -Kills the text from the cursor to the end of the line. - -@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) -@kindex C-x DEL, in the echo area -@findex echo-area-backward-kill-line -Kills the text from the cursor to the beginning of the line. - -@item @code{C-y} (@code{echo-area-yank}) -@kindex C-y, in the echo area -@findex echo-area-yank -Yanks back the contents of the last kill. - -@item @code{M-y} (@code{echo-area-yank-pop}) -@kindex M-y, in the echo area -@findex echo-area-yank-pop -Yanks back a previous kill, removing the last yanked text first. -@end table - -Sometimes when reading input in the echo area, the command that needed -input will only accept one of a list of several choices. The choices -represent the @dfn{possible completions}, and you must respond with one -of them. Since there are a limited number of responses you can make, -Info allows you to abbreviate what you type, only typing as much of the -response as is necessary to uniquely identify it. In addition, you can -request Info to fill in as much of the response as is possible; this -is called @dfn{completion}. - -The following commands are available when completing in the echo area: - -@table @asis -@item @code{TAB} (@code{echo-area-complete}) -@itemx @code{SPC} -@kindex TAB, in the echo area -@kindex SPC, in the echo area -@findex echo-area-complete -Inserts as much of a completion as is possible. - -@item @code{?} (@code{echo-area-possible-completions}) -@kindex ?, in the echo area -@findex echo-area-possible-completions -Displays a window containing a list of the possible completions of what -you have typed so far. For example, if the available choices are: -@example -bar -foliate -food -forget -@end example -and you have typed an @samp{f}, followed by @samp{?}, the possible -completions would contain: -@example -foliate -food -forget -@end example -i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} -or @key{TAB} would result in @samp{fo} appearing in the echo area, since -all of the choices which begin with @samp{f} continue with @samp{o}. -Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} -appearing in the echo area, since that is the only choice which begins -with @samp{fol}. - -@item @code{ESC C-v} (@code{echo-area-scroll-completions-window}) -@kindex ESC C-v, in the echo area -@findex echo-area-scroll-completions-window -Scrolls the completions window, if that is visible, or the "other" -window if not. -@end table - -@node Printing Nodes -@chapter Printing Out Nodes -@cindex printing - -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. In general, we recommend that you use @TeX{} to format the -document and print sections of it, by running @code{tex} on the texinfo -source file. - -@table @asis -@item @code{M-x print-node} -@findex print-node -@cindex INFO_PRINT_COMMAND, environment variable -Pipes the contents of the current node through the command in the -environment variable @code{INFO_PRINT_COMMAND}. If the variable doesn't -exist, the node is simply piped to @code{lpr}. -@end table - -@node Miscellaneous Commands -@chapter Miscellaneous Commands - -GNU Info contains several commands which self-document GNU Info: - -@table @asis -@item @code{M-x describe-command} -@cindex functions, describing -@cindex commands, describing -@findex describe-command -Reads the name of an Info command in the echo area and then displays a -brief description of what that command does. - -@item @code{M-x describe-key} -@cindex keys, describing -@findex describe-key -Reads a key sequence in the echo area, and then displays the name and -documentation of the Info command that the key sequence invokes. - -@item @code{M-x describe-variable} -Reads the name of a variable in the echo area and then displays a brief -description of what the variable affects. - -@item @code{M-x where-is} -@findex where-is -Reads the name of an Info command in the echo area, and then displays -a key sequence which can be typed in order to invoke that command. - -@item @code{C-h} (@code{get-help-window}) -@itemx @code{?} -@kindex C-h -@kindex ?, in Info windows -@findex get-help-window -Creates (or moves into) the window displaying @code{*Help*}, and places -a node containing a quick reference card into it. This window displays -the most concise information about GNU Info available. - -@item @code{h} (@code{get-info-help-node}) -@kindex h -@findex get-info-help-node -Tries hard to visit the node @code{(info)Help}. The info file -@file{info.texi} distributed with GNU Info contains this node. Of -course, the file must first be processed with @code{makeinfo}, and then -placed into the location of your info directory. -@end table - -Here are the commands for creating a numeric argument: - -@table @asis -@item @code{C-u} (@code{universal-argument}) -@cindex numeric arguments -@kindex C-u -@findex universal-argument -Starts (or multiplies by 4) the current numeric argument. @samp{C-u} is -a good way to give a small numeric argument to cursor movement or -scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while -@samp{C-u C-u C-n} moves the cursor down 16 lines. - -@item @code{M-1} (@code{add-digit-to-numeric-arg}) -@itemx @code{M-2} @dots{} @code{M-9} -@kindex M-1 @dots{} M-9 -@findex add-digit-to-numeric-arg -Adds the digit value of the invoking key to the current numeric -argument. Once Info is reading a numeric argument, you may just type -the digits of the argument, without the Meta prefix. For example, you -might give @samp{C-l} a numeric argument of 32 by typing: - -@example -@kbd{C-u 3 2 C-l} -@end example -or -@example -@kbd{M-3 2 C-l} -@end example -@end table - -@samp{C-g} is used to abort the reading of a multi-character key -sequence, to cancel lengthy operations (such as multi-file searches) and -to cancel reading input in the echo area. - -@table @asis -@item @code{C-g} (@code{abort-key}) -@cindex cancelling typeahead -@cindex cancelling the current operation -@kindex C-g, in Info windows -@findex abort-key -Cancels current operation. -@end table - -The @samp{q} command of Info simply quits running Info. - -@table @asis -@item @code{q} (@code{quit}) -@cindex quitting -@kindex q -@findex quit -Exits GNU Info. -@end table - -If the operating system tells GNU Info that the screen is 60 lines tall, -and it is actually only 40 lines tall, here is a way to tell Info that -the operating system is correct. - -@table @asis -@item @code{M-x set-screen-height} -@findex set-screen-height -@cindex screen, changing the height of -Reads a height value in the echo area and sets the height of the -displayed screen to that value. -@end table - -Finally, Info provides a convenient way to display footnotes which might -be associated with the current node that you are viewing: - -@table @asis -@item @code{ESC C-f} (@code{show-footnotes}) -@kindex ESC C-f -@findex show-footnotes -@cindex footnotes, displaying -Shows the footnotes (if any) associated with the current node in another -window. You can have Info automatically display the footnotes -associated with a node when the node is selected by setting the variable -@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}. -@end table - -@node Variables -@chapter Manipulating Variables - -GNU Info contains several @dfn{variables} whose values are looked at by various -Info commands. You can change the values of these variables, and thus -change the behaviour of Info to more closely match your environment and -info file reading manner. - -@table @asis -@item @code{M-x set-variable} -@cindex variables, setting -@findex set-variable -Reads the name of a variable, and the value for it, in the echo area and -then sets the variable to that value. Completion is available when -reading the variable name; often, completion is available when reading -the value to give to the variable, but that depends on the variable -itself. If a variable does @emph{not} supply multiple choices to -complete over, it expects a numeric value. - -@item @code{M-x describe-variable} -@cindex variables, describing -@findex describe-variable -Reads the name of a variable in the echo area and then displays a brief -description of what the variable affects. -@end table - -Here is a list of the variables that you can set in Info. - -@table @code -@item automatic-footnotes -@vindex automatic-footnotes -When set to @code{On}, footnotes appear and disappear automatically. -This variable is @code{On} by default. When a node is selected, a -window containing the footnotes which appear in that node is created, -and the footnotes are displayed within the new window. The window that -Info creates to contain the footnotes is called @samp{*Footnotes*}. If -a node is selected which contains no footnotes, and a @samp{*Footnotes*} -window is on the screen, the @samp{*Footnotes*} window is deleted. -Footnote windows created in this fashion are not automatically tiled so -that they can use as little of the display as is possible. - -@item automatic-tiling -@vindex automatic-tiling -When set to @code{On}, creating or deleting a window resizes other -windows. This variable is @code{Off} by default. Normally, typing -@samp{C-x 2} divides the current window into two equal parts. When -@code{automatic-tiling} is set to @code{On}, all of the windows are -resized automatically, keeping an equal number of lines visible in each -window. There are exceptions to the automatic tiling; specifically, the -windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} -resized through automatic tiling; they remain their original size. - -@item visible-bell -@vindex visible-bell -When set to @code{On}, GNU Info attempts to flash the screen instead of -ringing the bell. This variable is @code{Off} by default. Of course, -Info can only flash the screen if the terminal allows it; in the case -that the terminal does not allow it, the setting of this variable has no -effect. However, you can make Info perform quietly by setting the -@code{errors-ring-bell} variable to @code{Off}. - -@item errors-ring-bell -@vindex errors-ring-bell -When set to @code{On}, errors cause the bell to ring. The default -setting of this variable is @code{On}. - -@item gc-compressed-files -@vindex gc-compressed-files -When set to @code{On}, Info garbage collects files which had to be -uncompressed. The default value of this variable is @code{Off}. -Whenever a node is visited in Info, the info file containing that node -is read into core, and Info reads information about the tags and nodes -contained in that file. Once the tags information is read by Info, it -is never forgotten. However, the actual text of the nodes does not need -to remain in core unless a particular info window needs it. For -non-compressed files, the text of the nodes does not remain in core when -it is no longer in use. But de-compressing a file can be a time -consuming operation, and so Info tries hard not to do it twice. -@code{gc-compressed-files} tells Info it is okay to garbage collect the -text of the nodes of a file which was compressed on disk. - -@item show-index-match -@vindex show-index-match -When set to @code{On}, the portion of the matched search string is -highlighted in the message which explains where the matched search -string was found. The default value of this variable is @code{On}. -When Info displays the location where an index match was found, -(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the -string that you had typed is highlighted by displaying it in the inverse -case from its surrounding characters. - -@item scroll-behaviour -@vindex scroll-behaviour -Controls what happens when forward scrolling is requested at the end of -a node, or when backward scrolling is requested at the beginning of a -node. The default value for this variable is @code{Continuous}. There -are three possible values for this variable: - -@table @code -@item Continuous -Tries to get the first item in this node's menu, or failing that, the -@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. -This behaviour is identical to using the @samp{]} -(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) -commands. - -@item Next Only -Only tries to get the @samp{Next} node. - -@item Page Only -Simply gives up, changing nothing. If @code{scroll-behaviour} is -@code{Page Only}, no scrolling command can change the node that is being -viewed. -@end table - -@item scroll-step -@vindex scroll-step -The number of lines to scroll when the cursor moves out of the window. -Scrolling happens automatically if the cursor has moved out of the -visible portion of the node text when it is time to display. Usually -the scrolling is done so as to put the cursor on the center line of the -current window. However, if the variable @code{scroll-step} has a -nonzero value, Info attempts to scroll the node text by that many lines; -if that is enough to bring the cursor back into the window, that is what -is done. The default value of this variable is 0, thus placing the -cursor (and the text it is attached to) in the center of the window. -Setting this variable to 1 causes a kind of "smooth scrolling" which -some people prefer. - -@item ISO-Latin -@cindex ISO Latin characters -@vindex ISO-Latin -When set to @code{On}, Info accepts and displays ISO Latin characters. -By default, Info assumes an ASCII character set. @code{ISO-Latin} tells -Info that it is running in an environment where the European standard -character set is in use, and allows you to input such characters to -Info, as well as display them. -@end table - -@c The following node and its children are currently unfinished. Please feel -@c free to finish it! - -@ifset NOTSET -@node Info for Sys Admins -@chapter Info for System Administrators - -This text describes some common ways of setting up an Info heierarchy -from scratch, and details the various options that are available when -installing Info. This text is designed for the person who is installing -GNU Info on the system; although users may find the information present -in this section interesting, none of it is vital to understanding how to -use GNU Info. - -@menu -* Setting the INFOPATH:: Where are my Info files kept? -* Editing the DIR node:: What goes in `DIR', and why? -* Storing Info files:: Alternate formats allow flexibilty in setups. -* Using `localdir':: Building DIR on the fly. -* Example setups:: Some common ways to origanize Info files. -@end menu - -@node Setting the INFOPATH -@section Setting the INFOPATH -Where are my Info files kept? - -@node Editing the DIR node -@section Editing the DIR node -What goes in `DIR', and why? - -@node Storing Info files -@section Storing Info files -Alternate formats allow flexibilty in setups. - -@node Using `localdir' -@section Using `localdir' -Building DIR on the fly. - -@node Example setups -@section Example setups -Some common ways to origanize Info files. -@end ifset - -@ifset STANDALONE -@node GNU Info Global Index -@appendix Global Index -@printindex cp -@end ifset diff --git a/gnu/usr.bin/texinfo/info/xmalloc.c b/gnu/usr.bin/texinfo/info/xmalloc.c deleted file mode 100644 index 156989ed711..00000000000 --- a/gnu/usr.bin/texinfo/info/xmalloc.c +++ /dev/null @@ -1,80 +0,0 @@ -/* xmalloc.c -- safe versions of malloc and realloc */ - -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - This file has appeared in prior works by the Free Software Foundation; - thus it carries copyright dates from 1988 through 1993. - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993 Free Software - Foundation, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - Written by Brian Fox (bfox@ai.mit.edu). */ - -#if !defined (ALREADY_HAVE_XMALLOC) -#include <stdio.h> -#include <sys/types.h> - -extern void *malloc (), *realloc (); -static void memory_error_and_abort (); - -/* **************************************************************** */ -/* */ -/* Memory Allocation and Deallocation. */ -/* */ -/* **************************************************************** */ - -/* Return a pointer to free()able block of memory large enough - to hold BYTES number of bytes. If the memory cannot be allocated, - print an error message and abort. */ -void * -xmalloc (bytes) - int bytes; -{ - void *temp = malloc (bytes); - - if (!temp) - memory_error_and_abort ("xmalloc"); - return (temp); -} - -void * -xrealloc (pointer, bytes) - void *pointer; - int bytes; -{ - void *temp; - - if (!pointer) - temp = malloc (bytes); - else - temp = realloc (pointer, bytes); - - if (!temp) - memory_error_and_abort ("xrealloc"); - - return (temp); -} - -static void -memory_error_and_abort (fname) - char *fname; -{ - fprintf (stderr, "%s: Out of virtual memory!\n", fname); - abort (); -} -#endif /* !ALREADY_HAVE_XMALLOC */ diff --git a/gnu/usr.bin/texinfo/install.sh b/gnu/usr.bin/texinfo/install.sh deleted file mode 100644 index 58719246f04..00000000000 --- a/gnu/usr.bin/texinfo/install.sh +++ /dev/null @@ -1,238 +0,0 @@ -#! /bin/sh -# -# install - install a program, script, or datafile -# This comes from X11R5. -# -# Calling this script install-sh is preferred over install.sh, to prevent -# `make' implicit rules from creating a file called install from it -# when there is no Makefile. -# -# This script is compatible with the BSD install script, but was written -# from scratch. -# - - -# set DOITPROG to echo to test this script - -# Don't use :- since 4.3BSD and earlier shells don't like it. -doit="${DOITPROG-}" - - -# put in absolute paths if you don't have them in your path; or use env. vars. - -mvprog="${MVPROG-mv}" -cpprog="${CPPROG-cp}" -chmodprog="${CHMODPROG-chmod}" -chownprog="${CHOWNPROG-chown}" -chgrpprog="${CHGRPPROG-chgrp}" -stripprog="${STRIPPROG-strip}" -rmprog="${RMPROG-rm}" -mkdirprog="${MKDIRPROG-mkdir}" - -transformbasename="" -transform_arg="" -instcmd="$mvprog" -chmodcmd="$chmodprog 0755" -chowncmd="" -chgrpcmd="" -stripcmd="" -rmcmd="$rmprog -f" -mvcmd="$mvprog" -src="" -dst="" -dir_arg="" - -while [ x"$1" != x ]; do - case $1 in - -c) instcmd="$cpprog" - shift - continue;; - - -d) dir_arg=true - shift - continue;; - - -m) chmodcmd="$chmodprog $2" - shift - shift - continue;; - - -o) chowncmd="$chownprog $2" - shift - shift - continue;; - - -g) chgrpcmd="$chgrpprog $2" - shift - shift - continue;; - - -s) stripcmd="$stripprog" - shift - continue;; - - -t=*) transformarg=`echo $1 | sed 's/-t=//'` - shift - continue;; - - -b=*) transformbasename=`echo $1 | sed 's/-b=//'` - shift - continue;; - - *) if [ x"$src" = x ] - then - src=$1 - else - # this colon is to work around a 386BSD /bin/sh bug - : - dst=$1 - fi - shift - continue;; - esac -done - -if [ x"$src" = x ] -then - echo "install: no input file specified" - exit 1 -else - true -fi - -if [ x"$dir_arg" != x ]; then - dst=$src - src="" - - if [ -d $dst ]; then - instcmd=: - else - instcmd=mkdir - fi -else - -# Waiting for this to be detected by the "$instcmd $src $dsttmp" command -# might cause directories to be created, which would be especially bad -# if $src (and thus $dsttmp) contains '*'. - - if [ -f $src -o -d $src ] - then - true - else - echo "install: $src does not exist" - exit 1 - fi - - if [ x"$dst" = x ] - then - echo "install: no destination specified" - exit 1 - else - true - fi - -# If destination is a directory, append the input filename; if your system -# does not like double slashes in filenames, you may need to add some logic - - if [ -d $dst ] - then - dst="$dst"/`basename $src` - else - true - fi -fi - -## this sed command emulates the dirname command -dstdir=`echo $dst | sed -e 's,[^/]*$,,;s,/$,,;s,^$,.,'` - -# Make sure that the destination directory exists. -# this part is taken from Noah Friedman's mkinstalldirs script - -# Skip lots of stat calls in the usual case. -if [ ! -d "$dstdir" ]; then -defaultIFS=' -' -IFS="${IFS-${defaultIFS}}" - -oIFS="${IFS}" -# Some sh's can't handle IFS=/ for some reason. -IFS='%' -set - `echo ${dstdir} | sed -e 's@/@%@g' -e 's@^%@/@'` -IFS="${oIFS}" - -pathcomp='' - -while [ $# -ne 0 ] ; do - pathcomp="${pathcomp}${1}" - shift - - if [ ! -d "${pathcomp}" ] ; - then - $mkdirprog "${pathcomp}" - else - true - fi - - pathcomp="${pathcomp}/" -done -fi - -if [ x"$dir_arg" != x ] -then - $doit $instcmd $dst && - - if [ x"$chowncmd" != x ]; then $doit $chowncmd $dst; else true ; fi && - if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dst; else true ; fi && - if [ x"$stripcmd" != x ]; then $doit $stripcmd $dst; else true ; fi && - if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dst; else true ; fi -else - -# If we're going to rename the final executable, determine the name now. - - if [ x"$transformarg" = x ] - then - dstfile=`basename $dst` - else - dstfile=`basename $dst $transformbasename | - sed $transformarg`$transformbasename - fi - -# don't allow the sed command to completely eliminate the filename - - if [ x"$dstfile" = x ] - then - dstfile=`basename $dst` - else - true - fi - -# Make a temp file name in the proper directory. - - dsttmp=$dstdir/#inst.$$# - -# Move or copy the file name to the temp name - - $doit $instcmd $src $dsttmp && - - trap "rm -f ${dsttmp}" 0 && - -# and set any options; do chmod last to preserve setuid bits - -# If any of these fail, we abort the whole thing. If we want to -# ignore errors from any of these, just make sure not to ignore -# errors from the above "$doit $instcmd $src $dsttmp" command. - - if [ x"$chowncmd" != x ]; then $doit $chowncmd $dsttmp; else true;fi && - if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dsttmp; else true;fi && - if [ x"$stripcmd" != x ]; then $doit $stripcmd $dsttmp; else true;fi && - if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dsttmp; else true;fi && - -# Now rename the file to the real destination. - - $doit $rmcmd -f $dstdir/$dstfile && - $doit $mvcmd $dsttmp $dstdir/$dstfile - -fi && - - -exit 0 diff --git a/gnu/usr.bin/texinfo/makeinfo/macro.texi b/gnu/usr.bin/texinfo/makeinfo/macro.texi deleted file mode 100644 index 8a3fe802392..00000000000 --- a/gnu/usr.bin/texinfo/makeinfo/macro.texi +++ /dev/null @@ -1,177 +0,0 @@ -@c This file is included in makeinfo.texi. -@c -@ifinfo -@comment Here are some useful examples of the macro facility. - -@c Simply insert the right version of the texinfo name. -@macro texinfo{} -TeXinfo -@end macro - -@macro dfn{text} -@dfn{\text\} -@cpindex \text\ -@end macro - -@c Define a macro which expands to a pretty version of the name of the -@c Makeinfo program. -@macro makeinfo{} -@code{Makeinfo} -@end macro - -@c Define a macro which is used to define other macros. This one makes -@c a macro which creates a node and gives it a sectioning command. Note -@c that the created macro uses the original definition within the -@c expansion text. This takes advantage of the non-recursion feature of -@c macro execution. -@macro node_define{orig-name} -@macro \orig-name\{title} -@node \title\ -@\orig-name\ \title\ -@end macro -@end macro - -@c Now actually define a new set of sectioning commands. -@node_define {chapter} -@node_define {section} -@node_define {subsection} -@end ifinfo - -@chapter The Macro Facility - -This chapter describes the new macro facility. - -A @dfn{macro} is a command that you define in terms of other commands. -It doesn't exist as a @texinfo{} command until you define it as part of -the input file to @makeinfo{}. Once the command exists, it behaves much -as any other @texinfo{} command. Macros are a useful way to ease the -details and tedium of writing a `correct' info file. The following -sections explain how to write and invoke macros. - -@menu -* How to Use Macros in @texinfo{}:: - How to use the macro facility. - -* Using Macros Recursively:: - How to write a macro which does (or doesn't) recurse. - -* Using @texinfo{} Macros As Arguments:: - Passing a macro as an argument. -@end menu - -@section How to Use Macros in @texinfo{} - -Using macros in @texinfo{} is easy. First you define the macro. After -that, the macro command is available as a normal @texinfo{} command. -Here is what a definition looks like: - -@example -@@macro @var{name}@{@var{arg1}, @var{@dots{}} @var{argn}@} -@var{@texinfo{} commands@dots{}} -@@end macro -@end example - -The arguments that you specify that the macro takes are expanded with -the actual parameters used when calling the macro if they are seen -surrounded by backslashes. For example, here is a definition of -@code{@@codeitem}, a macro which can be used wherever @code{@@item} can -be used, but which surrounds its argument with @code{@@code@{@dots{}@}}. - -@example -@@macro codeitem@{item@} -@@item @@code@{\item\@} -@@end macro -@end example - -When the macro is expanded, all of the text between the @code{@@macro} -and @code{@@end macro} is inserted into the document at the expansion -point, with the actual parameters substituted for the named parameters. -So, a call to the above macro might look like: - -@example -@@codeitem@{Foo@} -@end example - -and @makeinfo{} would execute the following code: - -@example -@@item @@code@{Foo@} -@end example - -A special case is made for macros which only take a single argument, and -which are invoked without any brace characters (i.e., -@samp{@{}@dots{}@samp{@}}) surrounding an argument; the rest of the line -is supplied as is as the sole argument to the macro. This special case -allows one to redefine some standard @texinfo{} commands without -modifying the input file. Along with the non-recursive action of macro -invocation, one can easily redefine the sectioning commands to also -provide index entries: - -@example -@@macro chapter@{name@} -@@chapter \name\ -@@findex \name\ -@@end macro -@end example - -Thus, the text: - -@example -@@chapter strlen -@end example - -will expand to: - -@example -@@chapter strlen -@@findex strlen -@end example - -@section Using Macros Recursively - -Normally, while a particular macro is executing, any call to that macro -will be seen as a call to a builtin @texinfo{} command. This allows one -to redefine a builtin @texinfo{} command as a macro, and then use that -command within the definition of the macro itself. For example, one -might wish to make sure that whereever a term was defined with -@code{@@dfn@{@dots{}@}}, the location of the definition would appear -in the concept index for the manual. Here is a macro which redefines -@code{@@dfn} to do just that: - -@example -@@macro dfn@{text@} -@@dfn@{\text\@} -@@cpindex \text\ -@@end macro -@end example - -Note that we used the builtin @texinfo{} command @code{@@dfn} within our -overriding macro definition. - -This behaviour itself can be overridden for macro execution by writing a -special @dfn{macro control command} in the definition of the macro. The -command is considered special because it doesn't affect the output text -directly, rather, it affects the way in which the macro is defined. One -such special command is @code{@@allow-recursion}. - -@example -@@macro silly@{arg@} -@@allow-recursion -\arg\ -@@end macro -@end example - -Now @code{@@silly} is a macro that can be used within a call to itself: - -@example -This text @@silly@{@@silly@{some text@}@} is ``some text''. -@end example - -@section Using @texinfo{} Macros As Arguments - -@printindex cp -How to use @texinfo{} macros as arguments to other @texinfo{} macros. - -@bye - - diff --git a/gnu/usr.bin/texinfo/makeinfo/makeinfo.texi b/gnu/usr.bin/texinfo/makeinfo/makeinfo.texi deleted file mode 100644 index db9c10f3013..00000000000 --- a/gnu/usr.bin/texinfo/makeinfo/makeinfo.texi +++ /dev/null @@ -1,303 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename makeinfo.info -@set VERSION 1.61 -@paragraphindent none -@comment %**start of header -@comment $Id: makeinfo.texi,v 1.3 2002/06/10 13:51:03 espie Exp $ - -@dircategory Texinfo documentation system -@direntry -* makeinfo: (makeinfo). Convert Texinfo source to Info or plain ASCII. -@end direntry - -@ifinfo -This file is an extract from the @cite{Texinfo} manual.@* -It documents Makeinfo, a program that converts Texinfo -files into Info files. - -Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@end ifinfo - -@titlepage -@title GNU Makeinfo -@author Brian J. Fox and Robert J. Chassell - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1994, 1995 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@end titlepage - -@node Top -@chapter What is @code{makeinfo}? - -@iftex -This file documents the use of the @code{makeinfo} program, versions -@value{VERSION} and later. It is an extract from the @cite{Texinfo} manual. -@end iftex - -@code{makeinfo} is a program for converting @dfn{Texinfo} files into @dfn{Info} -files. Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output. - -You can read the on-line information using Info; type @code{info} to -learn about Info. -@ifinfo -@xref{Top, Texinfo, Overview of Texinfo, Texinfo, Texinfo}, -@end ifinfo -@iftex -See the @cite{Texinfo} manual, -@end iftex -to learn about the Texinfo documentation system. - -@menu -* Formatting Control:: Controlling the width of lines, paragraph - indentation, and other similar formatting. - -* Options:: Command line options which control the - behaviour of Makeinfo. - -* Pointer Validation:: How Makeinfo can help you to track node - references through complex Texinfo files. - -* Index:: Index of Concepts. -@end menu - -@c Removed this for 3.8 until it's time to rewrite it. -@c * The Macro Facility:: Makeinfo allows the use of @dfn{macros}. - -@node Formatting Control -@section Controlling Paragraph Formats - -Without any special options, @code{makeinfo} @dfn{fills} the paragraphs that -it outputs to an Info file. Filling is the process of breaking and connecting -lines so that lines are the same length as or shorter than the number -specified as the fill column. Lines are broken between words. With -@code{makeinfo}, you can control: - -@itemize @bullet -@item -The width of each paragraph (the @dfn{fill-column}). -@item -The amount of indentation that the first line of -each paragraph receives (the @dfn{paragraph-indentation}). -@end itemize - -@node Options -@section Command Line Options - -The following command line options are available for @code{makeinfo}. - -@need 100 -@table @code -@item -D @var{var} -Cause @var{var} to be defined. This is equivalent to -@code{@@set @var{var}} in the Texinfo file. - -@need 150 -@item --error-limit @var{limit} -Set the maximum number of errors that @code{makeinfo} will report -before exiting (on the assumption that continuing would be useless). -The default number of errors that can be reported before -@code{makeinfo} gives up is 100.@refill - -@need 150 -@item --fill-column @var{width} -Specify the maximum number of columns in a line; this is the right-hand -edge of a line. Paragraphs that are filled will be filled to this -width. The default value for @code{fill-column} is 72. -@refill - -@item --footnote-style @var{style} -Set the footnote style to @var{style}, either @samp{end} for the end -node style or @samp{separate} for the separate node style. The value -set by this option overrides the value set in a Texinfo file by an -@code{@@footnotestyle} command. When the footnote style is -@samp{separate}, @code{makeinfo} makes a new node containing the -footnotes found in the current node. When the footnote style is -@samp{end}, @code{makeinfo} places the footnote references at the end -of the current node.@refill - -@need 150 -@item -I @var{dir} -Add @code{dir} to the directory search list for finding files that are -included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. - -@need 150 -@item --no-headers -Do not include menus or node lines in the output. This results in an -@sc{ascii} file that you cannot read in Info since it does not contain -the requisite nodes or menus; but you can print such a file in a -single, typewriter-like font and produce acceptable output. - -@need 150 -@item --no-split -Suppress the splitting stage of @code{makeinfo}. Normally, large -output files (where the size is greater than 70k bytes) are split into -smaller subfiles, each one approximately 50k bytes. If you specify -@samp{--no-split}, @code{makeinfo} will not split up the output -file.@refill - -@need 100 -@item --no-pointer-validate -@item --no-validate -Suppress the pointer-validation phase of @code{makeinfo}. Normally, -after a Texinfo file is processed, some consistency checks are made to -ensure that cross references can be resolved, etc. -@xref{Pointer Validation}.@refill - -@need 150 -@item --no-warn -Suppress the output of warning messages. This does @emph{not} -suppress the output of error messages, only warnings. You might -want this if the file you are creating has examples of Texinfo cross -references within it, and the nodes that are referenced do not actually -exist.@refill - -@item --no-number-footnotes -Supress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@need 150 -@item --output @var{file} -@itemx -o @var{file} -Specify that the output should be directed to @var{file} and not to the -file name specified in the @code{@@setfilename} command found in the Texinfo -source. @var{file} can be the special token @samp{-}, which specifies -standard output. - -@need 150 -@item --paragraph-indent @var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command. The value of @var{indent} is -interpreted as follows:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, do not change the -existing indentation at the starts of paragraphs.@refill - -@item -If the value of @var{indent} is zero, delete any existing -indentation.@refill - -@item -If the value of @var{indent} is greater than zero, indent each -paragraph by that number of spaces.@refill -@end itemize - -@need 100 -@item --reference-limit @var{limit} -Set the value of the number of references to a node that -@code{makeinfo} will make without reporting a warning. If a node has more -than this number of references in it, @code{makeinfo} will make the -references but also report a warning.@refill - -@need 150 -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to -@code{@@clear @var{var}} in the Texinfo file. - -@need 100 -@item --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -Normally, @code{makeinfo} only outputs messages if there are errors or -warnings.@refill - -@need 100 -@item --version -Report the version number of this copy of @code{makeinfo}.@refill - -@item --help -Show a summary of the commend line arguments to @code{makeinfo}. -@end table - -@node Pointer Validation -@section Pointer Validation -@cindex Pointer validation with @code{makeinfo} -@cindex Validation of pointers - -If you do not suppress pointer-validation (by using the -@samp{--no-pointer-validation} option), @code{makeinfo} -will check the validity of the final Info file. Mostly, -this means ensuring that nodes you have referenced -really exist. Here is a complete list of what is -checked:@refill - -@enumerate -@item -If a `Next', `Previous', or `Up' node reference is a reference to a -node in the current file and is not an external reference such as to -@file{(dir)}, then the referenced node must exist.@refill - -@item -In every node, if the `Previous' node is different from the `Up' node, -then the `Previous' node must also be pointed to by a `Next' node.@refill - -@item -Every node except the `Top' node must have an `Up' pointer.@refill - -@item -The node referenced by an `Up' pointer must contain a reference to the -current node in some manner other than through a `Next' reference. -This includes menu entries and cross references.@refill - -@item -If the `Next' reference of a node is not the same as the `Next' reference -of the `Up' reference, then the node referenced by the `Next' pointer -must have a `Previous' pointer that points back to the current node. -This rule allows the last node in a section to point to the first node -of the next chapter.@refill -@end enumerate - -@c We don't want to advertise redefining commands. -@c lowersections -@c include macro.texi -@c raisesections - -@lowersections -@node Index -@appendix Index -@printindex cp -@raisesections - -@contents -@bye diff --git a/gnu/usr.bin/texinfo/makeinfo/multiformat.texi b/gnu/usr.bin/texinfo/makeinfo/multiformat.texi deleted file mode 100644 index 0c6c467dc0d..00000000000 --- a/gnu/usr.bin/texinfo/makeinfo/multiformat.texi +++ /dev/null @@ -1,40 +0,0 @@ -@c multiformat.texi: -*- Texinfo -*- \input texinfo.tex - -@c Copyright (c) 1995 Universal Access, Inc -@c Author: Brian J. Fox (bfox@ua.com) Sun Apr 2 07:56:23 1995. -@setfilename multiformat.info - -@include html.texi - -@ifset html -@html -@end ifset - -@node First Node, First Section, (dir), (dir) -@chapter First Chapter -Here is some text that belongs in the first chapter. Nothing very -exciting happens here, but this is enough text to span a couple of -lines, and we feel that is important. -@paragraph - -This is the second paragraph of the first chapter. Note that the -formatting commands in @code{HTML} seem to do the right thing, as do the -commands when invoked in @code{Texinfo} mode and in @TeX{}. - -@node First Section, , First Node, First Node -@isection First Section - -Here is some text in the first section of the first chapter. We are -trying very hard to examine the output here to see exactly how proper it -is. If I wasn't so tired, we could probably see it already. -@paragraph - -Here is a list of items: -@paragraph - -@itemize @bullet -@item Here is the first item. -@item Here is the second item. -@end itemize - -@bye diff --git a/gnu/usr.bin/texinfo/texinfo.tex b/gnu/usr.bin/texinfo/texinfo.tex deleted file mode 100644 index 806d28a2483..00000000000 --- a/gnu/usr.bin/texinfo/texinfo.tex +++ /dev/null @@ -1,4692 +0,0 @@ -%% TeX macros to handle texinfo files - -% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, -% 94, 95, 1996 Free Software Foundation, Inc. - -%This texinfo.tex file is free software; you can redistribute it and/or -%modify it under the terms of the GNU General Public License as -%published by the Free Software Foundation; either version 2, or (at -%your option) any later version. - -%This texinfo.tex file is distributed in the hope that it will be -%useful, but WITHOUT ANY WARRANTY; without even the implied warranty -%of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -%General Public License for more details. - -%You should have received a copy of the GNU General Public License -%along with this texinfo.tex file; see the file COPYING. If not, write -%to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, -%Boston, MA 02111-1307, USA. - - -%In other words, you are welcome to use, share and improve this program. -%You are forbidden to forbid anyone else to use, share and improve -%what you give them. Help stamp out software-hoarding! - - -% Send bug reports to bug-texinfo@prep.ai.mit.edu. -% Please include a *precise* test case in each bug report. - - -% Make it possible to create a .fmt file just by loading this file: -% if the underlying format is not loaded, start by loading it now. -% Added by gildea November 1993. -\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi - -% This automatically updates the version number based on RCS. -\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 1.3 $ -\message{Loading texinfo package [Version \texinfoversion]:} - -% If in a .fmt file, print the version number -% and turn on active characters that we couldn't do earlier because -% they might have appeared in the input file name. -\everyjob{\message{[Texinfo version \texinfoversion]}\message{} - \catcode`+=\active \catcode`\_=\active} - -% Save some parts of plain tex whose names we will redefine. - -\let\ptexb=\b -\let\ptexbullet=\bullet -\let\ptexc=\c -\let\ptexcomma=\, -\let\ptexdot=\. -\let\ptexdots=\dots -\let\ptexend=\end -\let\ptexequiv = \equiv -\let\ptexi=\i -\let\ptexlbrace=\{ -\let\ptexrbrace=\} -\let\ptexstar=\* -\let\ptext=\t -\let\ptextilde=\~ - -% Be sure we're in horizontal mode when doing a tie, since we make space -% equivalent to this in @example-like environments. Otherwise, a space -% at the beginning of a line will start with \penalty -- and -% since \penalty is valid in vertical mode, we'd end up putting the -% penalty on the vertical list instead of in the new paragraph. -{\catcode`@ = 11 - % Avoid using \@M directly, because that causes trouble - % if the definition is written into an index file. - \global\let\tiepenalty = \@M - \gdef\tie{\leavevmode\penalty\tiepenalty\ } -} -\let\~ = \tie % And make it available as @~. - - -\message{Basics,} -\chardef\other=12 - -% If this character appears in an error message or help string, it -% starts a new line in the output. -\newlinechar = `^^J - -% Set up fixed words for English. -\ifx\putwordChapter\undefined{\gdef\putwordChapter{Chapter}}\fi% -\def\putwordInfo{Info}% -\ifx\putwordSee\undefined{\gdef\putwordSee{See}}\fi% -\ifx\putwordsee\undefined{\gdef\putwordsee{see}}\fi% -\ifx\putwordfile\undefined{\gdef\putwordfile{file}}\fi% -\ifx\putwordpage\undefined{\gdef\putwordpage{page}}\fi% -\ifx\putwordsection\undefined{\gdef\putwordsection{section}}\fi% -\ifx\putwordSection\undefined{\gdef\putwordSection{Section}}\fi% -\ifx\putwordTableofContents\undefined{\gdef\putwordTableofContents{Table of Contents}}\fi% -\ifx\putwordShortContents\undefined{\gdef\putwordShortContents{Short Contents}}\fi% -\ifx\putwordAppendix\undefined{\gdef\putwordAppendix{Appendix}}\fi% - -% Ignore a token. -% -\def\gobble#1{} - -\hyphenation{ap-pen-dix} -\hyphenation{mini-buf-fer mini-buf-fers} -\hyphenation{eshell} - -% Margin to add to right of even pages, to left of odd pages. -\newdimen \bindingoffset -\newdimen \normaloffset -\newdimen\pagewidth \newdimen\pageheight - -% Sometimes it is convenient to have everything in the transcript file -% and nothing on the terminal. We don't just call \tracingall here, -% since that produces some useless output on the terminal. -% -\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% -\def\loggingall{\tracingcommands2 \tracingstats2 - \tracingpages1 \tracingoutput1 \tracinglostchars1 - \tracingmacros2 \tracingparagraphs1 \tracingrestores1 - \showboxbreadth\maxdimen\showboxdepth\maxdimen -}% - -%---------------------Begin change----------------------- -% -%%%% For @cropmarks command. -% Dimensions to add cropmarks at corners Added by P. A. MacKay, 12 Nov. 1986 -% -\newdimen\cornerlong \newdimen\cornerthick -\newdimen \topandbottommargin -\newdimen \outerhsize \newdimen \outervsize -\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks -\outerhsize=7in -%\outervsize=9.5in -% Alternative @smallbook page size is 9.25in -\outervsize=9.25in -\topandbottommargin=.75in -% -%---------------------End change----------------------- - -% \onepageout takes a vbox as an argument. Note that \pagecontents -% does insertions, but you have to call it yourself. -\chardef\PAGE=255 \output={\onepageout{\pagecontents\PAGE}} -\def\onepageout#1{% - \hoffset=\normaloffset - \ifodd\pageno \advance\hoffset by \bindingoffset - \else \advance\hoffset by -\bindingoffset\fi - {% - \escapechar = `\\ % use backslash in output files. - \indexdummies - \shipout\vbox{% - {\let\hsize=\pagewidth \makeheadline}% - \pagebody{#1}% - {\let\hsize=\pagewidth \makefootline}% - }% - }% - \advancepageno - \ifnum\outputpenalty>-20000 \else\dosupereject\fi -} - -%%%% For @cropmarks command %%%% - -% Here is a modification of the main output routine for Near East Publications -% This provides right-angle cropmarks at all four corners. -% The contents of the page are centerlined into the cropmarks, -% and any desired binding offset is added as an \hskip on either -% site of the centerlined box. (P. A. MacKay, 12 November, 1986) -% -\def\croppageout#1{\hoffset=0pt % make sure this doesn't mess things up -{\escapechar=`\\\relax % makes sure backslash is used in output files. - \shipout - \vbox to \outervsize{\hsize=\outerhsize - \vbox{\line{\ewtop\hfill\ewtop}} - \nointerlineskip - \line{\vbox{\moveleft\cornerthick\nstop} - \hfill - \vbox{\moveright\cornerthick\nstop}} - \vskip \topandbottommargin - \centerline{\ifodd\pageno\hskip\bindingoffset\fi - \vbox{ - {\let\hsize=\pagewidth \makeheadline} - \pagebody{#1} - {\let\hsize=\pagewidth \makefootline}} - \ifodd\pageno\else\hskip\bindingoffset\fi} - \vskip \topandbottommargin plus1fill minus1fill - \boxmaxdepth\cornerthick - \line{\vbox{\moveleft\cornerthick\nsbot} - \hfill - \vbox{\moveright\cornerthick\nsbot}} - \nointerlineskip - \vbox{\line{\ewbot\hfill\ewbot}} - }} - \advancepageno - \ifnum\outputpenalty>-20000 \else\dosupereject\fi} -% -% Do @cropmarks to get crop marks -\def\cropmarks{\let\onepageout=\croppageout } - -\newinsert\margin \dimen\margin=\maxdimen - -\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} -{\catcode`\@ =11 -\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi -% marginal hacks, juha@viisa.uucp (Juha Takala) -\ifvoid\margin\else % marginal info is present - \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi -\dimen@=\dp#1 \unvbox#1 -\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi -\ifr@ggedbottom \kern-\dimen@ \vfil \fi} -} - -% -% Here are the rules for the cropmarks. Note that they are -% offset so that the space between them is truly \outerhsize or \outervsize -% (P. A. MacKay, 12 November, 1986) -% -\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} -\def\nstop{\vbox - {\hrule height\cornerthick depth\cornerlong width\cornerthick}} -\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} -\def\nsbot{\vbox - {\hrule height\cornerlong depth\cornerthick width\cornerthick}} - -% Parse an argument, then pass it to #1. The argument is the rest of -% the input line (except we remove a trailing comment). #1 should be a -% macro which expects an ordinary undelimited TeX argument. -% -\def\parsearg#1{% - \let\next = #1% - \begingroup - \obeylines - \futurelet\temp\parseargx -} - -% If the next token is an obeyed space (from an @example environment or -% the like), remove it and recurse. Otherwise, we're done. -\def\parseargx{% - % \obeyedspace is defined far below, after the definition of \sepspaces. - \ifx\obeyedspace\temp - \expandafter\parseargdiscardspace - \else - \expandafter\parseargline - \fi -} - -% Remove a single space (as the delimiter token to the macro call). -{\obeyspaces % - \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} - -{\obeylines % - \gdef\parseargline#1^^M{% - \endgroup % End of the group started in \parsearg. - % - % First remove any @c comment, then any @comment. - % Result of each macro is put in \toks0. - \argremovec #1\c\relax % - \expandafter\argremovecomment \the\toks0 \comment\relax % - % - % Call the caller's macro, saved as \next in \parsearg. - \expandafter\next\expandafter{\the\toks0}% - }% -} - -% Since all \c{,omment} does is throw away the argument, we can let TeX -% do that for us. The \relax here is matched by the \relax in the call -% in \parseargline; it could be more or less anything, its purpose is -% just to delimit the argument to the \c. -\def\argremovec#1\c#2\relax{\toks0 = {#1}} -\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} - -% \argremovec{,omment} might leave us with trailing spaces, though; e.g., -% @end itemize @c foo -% will have two active spaces as part of the argument with the -% `itemize'. Here we remove all active spaces from #1, and assign the -% result to \toks0. -% -% This loses if there are any *other* active characters besides spaces -% in the argument -- _ ^ +, for example -- since they get expanded. -% Fortunately, Texinfo does not define any such commands. (If it ever -% does, the catcode of the characters in questionwill have to be changed -% here.) But this means we cannot call \removeactivespaces as part of -% \argremovec{,omment}, since @c uses \parsearg, and thus the argument -% that \parsearg gets might well have any character at all in it. -% -\def\removeactivespaces#1{% - \begingroup - \ignoreactivespaces - \edef\temp{#1}% - \global\toks0 = \expandafter{\temp}% - \endgroup -} - -% Change the active space to expand to nothing. -% -\begingroup - \obeyspaces - \gdef\ignoreactivespaces{\obeyspaces\let =\empty} -\endgroup - - -\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} - -%% These are used to keep @begin/@end levels from running away -%% Call \inENV within environments (after a \begingroup) -\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} -\def\ENVcheck{% -\ifENV\errmessage{Still within an environment. Type Return to continue.} -\endgroup\fi} % This is not perfect, but it should reduce lossage - -% @begin foo is the same as @foo, for now. -\newhelp\EMsimple{Type <Return> to continue.} - -\outer\def\begin{\parsearg\beginxxx} - -\def\beginxxx #1{% -\expandafter\ifx\csname #1\endcsname\relax -{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else -\csname #1\endcsname\fi} - -% @end foo executes the definition of \Efoo. -% -\def\end{\parsearg\endxxx} -\def\endxxx #1{% - \removeactivespaces{#1}% - \edef\endthing{\the\toks0}% - % - \expandafter\ifx\csname E\endthing\endcsname\relax - \expandafter\ifx\csname \endthing\endcsname\relax - % There's no \foo, i.e., no ``environment'' foo. - \errhelp = \EMsimple - \errmessage{Undefined command `@end \endthing'}% - \else - \unmatchedenderror\endthing - \fi - \else - % Everything's ok; the right environment has been started. - \csname E\endthing\endcsname - \fi -} - -% There is an environment #1, but it hasn't been started. Give an error. -% -\def\unmatchedenderror#1{% - \errhelp = \EMsimple - \errmessage{This `@end #1' doesn't have a matching `@#1'}% -} - -% Define the control sequence \E#1 to give an unmatched @end error. -% -\def\defineunmatchedend#1{% - \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% -} - - -% Single-spacing is done by various environments (specifically, in -% \nonfillstart and \quotations). -\newskip\singlespaceskip \singlespaceskip = 12.5pt -\def\singlespace{% - % Why was this kern here? It messes up equalizing space above and below - % environments. --karl, 6may93 - %{\advance \baselineskip by -\singlespaceskip - %\kern \baselineskip}% - \setleading \singlespaceskip -} - -%% Simple single-character @ commands - -% @@ prints an @ -% Kludge this until the fonts are right (grr). -\def\@{{\tt \char '100}} - -% This is turned off because it was never documented -% and you can use @w{...} around a quote to suppress ligatures. -%% Define @` and @' to be the same as ` and ' -%% but suppressing ligatures. -%\def\`{{`}} -%\def\'{{'}} - -% Used to generate quoted braces. -\def\mylbrace {{\tt \char '173}} -\def\myrbrace {{\tt \char '175}} -\let\{=\mylbrace -\let\}=\myrbrace -\begingroup - % Definitions to produce actual \{ & \} command in an index. - \catcode`\{ = 12 \catcode`\} = 12 - \catcode`\[ = 1 \catcode`\] = 2 - \catcode`\@ = 0 \catcode`\\ = 12 - @gdef@lbracecmd[\{]% - @gdef@rbracecmd[\}]% -@endgroup - -% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent -% Others are defined by plain TeX: @` @' @" @^ @~ @= @v @H. -\let\, = \c -\let\dotaccent = \. -\def\ringaccent#1{{\accent23 #1}} -\let\tieaccent = \t -\let\ubaraccent = \b -\let\udotaccent = \d - -% Other special characters: @questiondown @exclamdown -% Plain TeX defines: @AA @AE @O @OE @L (and lowercase versions) @ss. -\def\questiondown{?`} -\def\exclamdown{!`} - -% Dotless i and dotless j, used for accents. -\def\imacro{i} -\def\jmacro{j} -\def\dotless#1{% - \def\temp{#1}% - \ifx\temp\imacro \ptexi - \else\ifx\temp\jmacro \j - \else \errmessage{@dotless can be used only with i or j}% - \fi\fi -} - -% @: forces normal size whitespace following. -\def\:{\spacefactor=1000 } - -% @* forces a line break. -\def\*{\hfil\break\hbox{}\ignorespaces} - -% @. is an end-of-sentence period. -\def\.{.\spacefactor=3000 } - -% @enddots{} is an end-of-sentence ellipsis. -\gdef\enddots{$\mathinner{\ldotp\ldotp\ldotp\ldotp}$\spacefactor=3000} - -% @! is an end-of-sentence bang. -\gdef\!{!\spacefactor=3000 } - -% @? is an end-of-sentence query. -\gdef\?{?\spacefactor=3000 } - -% @w prevents a word break. Without the \leavevmode, @w at the -% beginning of a paragraph, when TeX is still in vertical mode, would -% produce a whole line of output instead of starting the paragraph. -\def\w#1{\leavevmode\hbox{#1}} - -% @group ... @end group forces ... to be all on one page, by enclosing -% it in a TeX vbox. We use \vtop instead of \vbox to construct the box -% to keep its height that of a normal line. According to the rules for -% \topskip (p.114 of the TeXbook), the glue inserted is -% max (\topskip - \ht (first item), 0). If that height is large, -% therefore, no glue is inserted, and the space between the headline and -% the text is small, which looks bad. -% -\def\group{\begingroup - \ifnum\catcode13=\active \else - \errhelp = \groupinvalidhelp - \errmessage{@group invalid in context where filling is enabled}% - \fi - % - % The \vtop we start below produces a box with normal height and large - % depth; thus, TeX puts \baselineskip glue before it, and (when the - % next line of text is done) \lineskip glue after it. (See p.82 of - % the TeXbook.) Thus, space below is not quite equal to space - % above. But it's pretty close. - \def\Egroup{% - \egroup % End the \vtop. - \endgroup % End the \group. - }% - % - \vtop\bgroup - % We have to put a strut on the last line in case the @group is in - % the midst of an example, rather than completely enclosing it. - % Otherwise, the interline space between the last line of the group - % and the first line afterwards is too small. But we can't put the - % strut in \Egroup, since there it would be on a line by itself. - % Hence this just inserts a strut at the beginning of each line. - \everypar = {\strut}% - % - % Since we have a strut on every line, we don't need any of TeX's - % normal interline spacing. - \offinterlineskip - % - % OK, but now we have to do something about blank - % lines in the input in @example-like environments, which normally - % just turn into \lisppar, which will insert no space now that we've - % turned off the interline space. Simplest is to make them be an - % empty paragraph. - \ifx\par\lisppar - \edef\par{\leavevmode \par}% - % - % Reset ^^M's definition to new definition of \par. - \obeylines - \fi - % - % Do @comment since we are called inside an environment such as - % @example, where each end-of-line in the input causes an - % end-of-line in the output. We don't want the end-of-line after - % the `@group' to put extra space in the output. Since @group - % should appear on a line by itself (according to the Texinfo - % manual), we don't worry about eating any user text. - \comment -} -% -% TeX puts in an \escapechar (i.e., `@') at the beginning of the help -% message, so this ends up printing `@group can only ...'. -% -\newhelp\groupinvalidhelp{% -group can only be used in environments such as @example,^^J% -where each line of input produces a line of output.} - -% @need space-in-mils -% forces a page break if there is not space-in-mils remaining. - -\newdimen\mil \mil=0.001in - -\def\need{\parsearg\needx} - -% Old definition--didn't work. -%\def\needx #1{\par % -%% This method tries to make TeX break the page naturally -%% if the depth of the box does not fit. -%{\baselineskip=0pt% -%\vtop to #1\mil{\vfil}\kern -#1\mil\penalty 10000 -%\prevdepth=-1000pt -%}} - -\def\needx#1{% - % Go into vertical mode, so we don't make a big box in the middle of a - % paragraph. - \par - % - % Don't add any leading before our big empty box, but allow a page - % break, since the best break might be right here. - \allowbreak - \nointerlineskip - \vtop to #1\mil{\vfil}% - % - % TeX does not even consider page breaks if a penalty added to the - % main vertical list is 10000 or more. But in order to see if the - % empty box we just added fits on the page, we must make it consider - % page breaks. On the other hand, we don't want to actually break the - % page after the empty box. So we use a penalty of 9999. - % - % There is an extremely small chance that TeX will actually break the - % page at this \penalty, if there are no other feasible breakpoints in - % sight. (If the user is using lots of big @group commands, which - % almost-but-not-quite fill up a page, TeX will have a hard time doing - % good page breaking, for example.) However, I could not construct an - % example where a page broke at this \penalty; if it happens in a real - % document, then we can reconsider our strategy. - \penalty9999 - % - % Back up by the size of the box, whether we did a page break or not. - \kern -#1\mil - % - % Do not allow a page break right after this kern. - \nobreak -} - -% @br forces paragraph break - -\let\br = \par - -% @dots{} output some dots - -\def\dots{$\ldots$} - -% @page forces the start of a new page - -\def\page{\par\vfill\supereject} - -% @exdent text.... -% outputs text on separate line in roman font, starting at standard page margin - -% This records the amount of indent in the innermost environment. -% That's how much \exdent should take out. -\newskip\exdentamount - -% This defn is used inside fill environments such as @defun. -\def\exdent{\parsearg\exdentyyy} -\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} - -% This defn is used inside nofill environments such as @example. -\def\nofillexdent{\parsearg\nofillexdentyyy} -\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount -\leftline{\hskip\leftskip{\rm#1}}}} - -% @inmargin{TEXT} puts TEXT in the margin next to the current paragraph. - -\def\inmargin#1{% -\strut\vadjust{\nobreak\kern-\strutdepth - \vtop to \strutdepth{\baselineskip\strutdepth\vss - \llap{\rightskip=\inmarginspacing \vbox{\noindent #1}}\null}}} -\newskip\inmarginspacing \inmarginspacing=1cm -\def\strutdepth{\dp\strutbox} - -%\hbox{{\rm#1}}\hfil\break}} - -% @include file insert text of that file as input. -% Allow normal characters that we make active in the argument (a file name). -\def\include{\begingroup - \catcode`\\=12 - \catcode`~=12 - \catcode`^=12 - \catcode`_=12 - \catcode`|=12 - \catcode`<=12 - \catcode`>=12 - \catcode`+=12 - \parsearg\includezzz} -% Restore active chars for included file. -\def\includezzz#1{\endgroup\begingroup - % Read the included file in a group so nested @include's work. - \def\thisfile{#1}% - \input\thisfile -\endgroup} - -\def\thisfile{} - -% @center line outputs that line, centered - -\def\center{\parsearg\centerzzz} -\def\centerzzz #1{{\advance\hsize by -\leftskip -\advance\hsize by -\rightskip -\centerline{#1}}} - -% @sp n outputs n lines of vertical space - -\def\sp{\parsearg\spxxx} -\def\spxxx #1{\vskip #1\baselineskip} - -% @comment ...line which is ignored... -% @c is the same as @comment -% @ignore ... @end ignore is another way to write a comment - -\def\comment{\catcode 64=\other \catcode 123=\other \catcode 125=\other% -\parsearg \commentxxx} - -\def\commentxxx #1{\catcode 64=0 \catcode 123=1 \catcode 125=2 } - -\let\c=\comment - -% @paragraphindent is defined for the Info formatting commands only. -\let\paragraphindent=\comment - -% Prevent errors for section commands. -% Used in @ignore and in failing conditionals. -\def\ignoresections{% -\let\chapter=\relax -\let\unnumbered=\relax -\let\top=\relax -\let\unnumberedsec=\relax -\let\unnumberedsection=\relax -\let\unnumberedsubsec=\relax -\let\unnumberedsubsection=\relax -\let\unnumberedsubsubsec=\relax -\let\unnumberedsubsubsection=\relax -\let\section=\relax -\let\subsec=\relax -\let\subsubsec=\relax -\let\subsection=\relax -\let\subsubsection=\relax -\let\appendix=\relax -\let\appendixsec=\relax -\let\appendixsection=\relax -\let\appendixsubsec=\relax -\let\appendixsubsection=\relax -\let\appendixsubsubsec=\relax -\let\appendixsubsubsection=\relax -\let\contents=\relax -\let\smallbook=\relax -\let\titlepage=\relax -} - -% Used in nested conditionals, where we have to parse the Texinfo source -% and so want to turn off most commands, in case they are used -% incorrectly. -% -\def\ignoremorecommands{% - \let\defcodeindex = \relax - \let\defcv = \relax - \let\deffn = \relax - \let\deffnx = \relax - \let\defindex = \relax - \let\defivar = \relax - \let\defmac = \relax - \let\defmethod = \relax - \let\defop = \relax - \let\defopt = \relax - \let\defspec = \relax - \let\deftp = \relax - \let\deftypefn = \relax - \let\deftypefun = \relax - \let\deftypevar = \relax - \let\deftypevr = \relax - \let\defun = \relax - \let\defvar = \relax - \let\defvr = \relax - \let\ref = \relax - \let\xref = \relax - \let\printindex = \relax - \let\pxref = \relax - \let\settitle = \relax - \let\setchapternewpage = \relax - \let\setchapterstyle = \relax - \let\everyheading = \relax - \let\evenheading = \relax - \let\oddheading = \relax - \let\everyfooting = \relax - \let\evenfooting = \relax - \let\oddfooting = \relax - \let\headings = \relax - \let\include = \relax - \let\lowersections = \relax - \let\down = \relax - \let\raisesections = \relax - \let\up = \relax - \let\set = \relax - \let\clear = \relax - \let\item = \relax -} - -% Ignore @ignore ... @end ignore. -% -\def\ignore{\doignore{ignore}} - -% Also ignore @ifinfo, @ifhtml, @html, @menu, and @direntry text. -% -\def\ifinfo{\doignore{ifinfo}} -\def\ifhtml{\doignore{ifhtml}} -\def\html{\doignore{html}} -\def\menu{\doignore{menu}} -\def\direntry{\doignore{direntry}} - -% Also ignore @macro ... @end macro. The user must run texi2dvi, -% which runs makeinfo to do macro expansion. Ignore @unmacro, too. -\def\macro{\doignore{macro}} -\let\unmacro = \comment - - -% @dircategory CATEGORY -- specify a category of the dir file -% which this file should belong to. Ignore this in TeX. -\let\dircategory = \comment - -% Ignore text until a line `@end #1'. -% -\def\doignore#1{\begingroup - % Don't complain about control sequences we have declared \outer. - \ignoresections - % - % Define a command to swallow text until we reach `@end #1'. - \long\def\doignoretext##1\end #1{\enddoignore}% - % - % Make sure that spaces turn into tokens that match what \doignoretext wants. - \catcode32 = 10 - % - % And now expand that command. - \doignoretext -} - -% What we do to finish off ignored text. -% -\def\enddoignore{\endgroup\ignorespaces}% - -\newif\ifwarnedobs\warnedobsfalse -\def\obstexwarn{% - \ifwarnedobs\relax\else - % We need to warn folks that they may have trouble with TeX 3.0. - % This uses \immediate\write16 rather than \message to get newlines. - \immediate\write16{} - \immediate\write16{***WARNING*** for users of Unix TeX 3.0!} - \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} - \immediate\write16{If you are running another version of TeX, relax.} - \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} - \immediate\write16{ Then upgrade your TeX installation if you can.} - \immediate\write16{ (See ftp://ftp.gnu.ai.mit.edu/pub/gnu/TeX.README.)} - \immediate\write16{If you are stuck with version 3.0, run the} - \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} - \immediate\write16{ to use a workaround.} - \immediate\write16{} - \global\warnedobstrue - \fi -} - -% **In TeX 3.0, setting text in \nullfont hangs tex. For a -% workaround (which requires the file ``dummy.tfm'' to be installed), -% uncomment the following line: -%%%%%\font\nullfont=dummy\let\obstexwarn=\relax - -% Ignore text, except that we keep track of conditional commands for -% purposes of nesting, up to an `@end #1' command. -% -\def\nestedignore#1{% - \obstexwarn - % We must actually expand the ignored text to look for the @end - % command, so that nested ignore constructs work. Thus, we put the - % text into a \vbox and then do nothing with the result. To minimize - % the change of memory overflow, we follow the approach outlined on - % page 401 of the TeXbook: make the current font be a dummy font. - % - \setbox0 = \vbox\bgroup - % Don't complain about control sequences we have declared \outer. - \ignoresections - % - % Define `@end #1' to end the box, which will in turn undefine the - % @end command again. - \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% - % - % We are going to be parsing Texinfo commands. Most cause no - % trouble when they are used incorrectly, but some commands do - % complicated argument parsing or otherwise get confused, so we - % undefine them. - % - % We can't do anything about stray @-signs, unfortunately; - % they'll produce `undefined control sequence' errors. - \ignoremorecommands - % - % Set the current font to be \nullfont, a TeX primitive, and define - % all the font commands to also use \nullfont. We don't use - % dummy.tfm, as suggested in the TeXbook, because not all sites - % might have that installed. Therefore, math mode will still - % produce output, but that should be an extremely small amount of - % stuff compared to the main input. - % - \nullfont - \let\tenrm = \nullfont \let\tenit = \nullfont \let\tensl = \nullfont - \let\tenbf = \nullfont \let\tentt = \nullfont \let\smallcaps = \nullfont - \let\tensf = \nullfont - % Similarly for index fonts (mostly for their use in - % smallexample) - \let\indrm = \nullfont \let\indit = \nullfont \let\indsl = \nullfont - \let\indbf = \nullfont \let\indtt = \nullfont \let\indsc = \nullfont - \let\indsf = \nullfont - % - % Don't complain when characters are missing from the fonts. - \tracinglostchars = 0 - % - % Don't bother to do space factor calculations. - \frenchspacing - % - % Don't report underfull hboxes. - \hbadness = 10000 - % - % Do minimal line-breaking. - \pretolerance = 10000 - % - % Do not execute instructions in @tex - \def\tex{\doignore{tex}} -} - -% @set VAR sets the variable VAR to an empty value. -% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. -% -% Since we want to separate VAR from REST-OF-LINE (which might be -% empty), we can't just use \parsearg; we have to insert a space of our -% own to delimit the rest of the line, and then take it out again if we -% didn't need it. Make sure the catcode of space is correct to avoid -% losing inside @example, for instance. -% -\def\set{\begingroup\catcode` =10 \parsearg\setxxx} -\def\setxxx#1{\setyyy#1 \endsetyyy} -\def\setyyy#1 #2\endsetyyy{% - \def\temp{#2}% - \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty - \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. - \fi - \endgroup -} -% Can't use \xdef to pre-expand #2 and save some time, since \temp or -% \next or other control sequences that we've defined might get us into -% an infinite loop. Consider `@set foo @cite{bar}'. -\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}} - -% @clear VAR clears (i.e., unsets) the variable VAR. -% -\def\clear{\parsearg\clearxxx} -\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} - -% @value{foo} gets the text saved in variable foo. -% -\def\value#1{\expandafter - \ifx\csname SET#1\endcsname\relax - {\{No value for ``#1''\}} - \else \csname SET#1\endcsname \fi} - -% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined -% with @set. -% -\def\ifset{\parsearg\ifsetxxx} -\def\ifsetxxx #1{% - \expandafter\ifx\csname SET#1\endcsname\relax - \expandafter\ifsetfail - \else - \expandafter\ifsetsucceed - \fi -} -\def\ifsetsucceed{\conditionalsucceed{ifset}} -\def\ifsetfail{\nestedignore{ifset}} -\defineunmatchedend{ifset} - -% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been -% defined with @set, or has been undefined with @clear. -% -\def\ifclear{\parsearg\ifclearxxx} -\def\ifclearxxx #1{% - \expandafter\ifx\csname SET#1\endcsname\relax - \expandafter\ifclearsucceed - \else - \expandafter\ifclearfail - \fi -} -\def\ifclearsucceed{\conditionalsucceed{ifclear}} -\def\ifclearfail{\nestedignore{ifclear}} -\defineunmatchedend{ifclear} - -% @iftex always succeeds; we read the text following, through @end -% iftex). But `@end iftex' should be valid only after an @iftex. -% -\def\iftex{\conditionalsucceed{iftex}} -\defineunmatchedend{iftex} - -% We can't just want to start a group at @iftex (for example) and end it -% at @end iftex, since then @set commands inside the conditional have no -% effect (they'd get reverted at the end of the group). So we must -% define \Eiftex to redefine itself to be its previous value. (We can't -% just define it to fail again with an ``unmatched end'' error, since -% the @ifset might be nested.) -% -\def\conditionalsucceed#1{% - \edef\temp{% - % Remember the current value of \E#1. - \let\nece{prevE#1} = \nece{E#1}% - % - % At the `@end #1', redefine \E#1 to be its previous value. - \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% - }% - \temp -} - -% We need to expand lots of \csname's, but we don't want to expand the -% control sequences after we've constructed them. -% -\def\nece#1{\expandafter\noexpand\csname#1\endcsname} - -% @asis just yields its argument. Used with @table, for example. -% -\def\asis#1{#1} - -% @math means output in math mode. -% We don't use $'s directly in the definition of \math because control -% sequences like \math are expanded when the toc file is written. Then, -% we read the toc file back, the $'s will be normal characters (as they -% should be, according to the definition of Texinfo). So we must use a -% control sequence to switch into and out of math mode. -% -% This isn't quite enough for @math to work properly in indices, but it -% seems unlikely it will ever be needed there. -% -\let\implicitmath = $ -\def\math#1{\implicitmath #1\implicitmath} - -% @bullet and @minus need the same treatment as @math, just above. -\def\bullet{\implicitmath\ptexbullet\implicitmath} -\def\minus{\implicitmath-\implicitmath} - -\def\node{\ENVcheck\parsearg\nodezzz} -\def\nodezzz#1{\nodexxx [#1,]} -\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} -\let\nwnode=\node -\let\lastnode=\relax - -\def\donoderef{\ifx\lastnode\relax\else -\expandafter\expandafter\expandafter\setref{\lastnode}\fi -\global\let\lastnode=\relax} - -\def\unnumbnoderef{\ifx\lastnode\relax\else -\expandafter\expandafter\expandafter\unnumbsetref{\lastnode}\fi -\global\let\lastnode=\relax} - -\def\appendixnoderef{\ifx\lastnode\relax\else -\expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi -\global\let\lastnode=\relax} - -% @refill is a no-op. -\let\refill=\relax - -% @setfilename is done at the beginning of every texinfo file. -% So open here the files we need to have open while reading the input. -% This makes it possible to make a .fmt file for texinfo. -\def\setfilename{% - \readauxfile - \opencontents - \openindices - \fixbackslash % Turn off hack to swallow `\input texinfo'. - \global\let\setfilename=\comment % Ignore extra @setfilename cmds. - \comment % Ignore the actual filename. -} - -% @bye. -\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} - -% \def\macro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\macroxxx} -% \def\macroxxx#1#2 \end macro{% -% \expandafter\gdef\macrotemp#1{#2}% -% \endgroup} - -%\def\linemacro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\linemacroxxx} -%\def\linemacroxxx#1#2 \end linemacro{% -%\let\parsearg=\relax -%\edef\macrotempx{\csname M\butfirst\expandafter\string\macrotemp\endcsname}% -%\expandafter\xdef\macrotemp{\parsearg\macrotempx}% -%\expandafter\gdef\macrotempx#1{#2}% -%\endgroup} - -%\def\butfirst#1{} - - -\message{fonts,} - -% Font-change commands. - -% Texinfo supports the sans serif font style, which plain TeX does not. -% So we set up a \sf analogous to plain's \rm, etc. -\newfam\sffam -\def\sf{\fam=\sffam \tensf} -\let\li = \sf % Sometimes we call it \li, not \sf. - -% We don't need math for this one. -\def\ttsl{\tenttsl} - -%% Try out Computer Modern fonts at \magstephalf -\let\mainmagstep=\magstephalf - -% Set the font macro #1 to the font named #2, adding on the -% specified font prefix (normally `cm'). -% #3 is the font's design size, #4 is a scale factor -\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} - -% Use cm as the default font prefix. -% To specify the font prefix, you must define \fontprefix -% before you read in texinfo.tex. -\ifx\fontprefix\undefined -\def\fontprefix{cm} -\fi -% Support font families that don't use the same naming scheme as CM. -\def\rmshape{r} -\def\rmbshape{bx} %where the normal face is bold -\def\bfshape{b} -\def\bxshape{bx} -\def\ttshape{tt} -\def\ttbshape{tt} -\def\ttslshape{sltt} -\def\itshape{ti} -\def\itbshape{bxti} -\def\slshape{sl} -\def\slbshape{bxsl} -\def\sfshape{ss} -\def\sfbshape{ss} -\def\scshape{csc} -\def\scbshape{csc} - -\ifx\bigger\relax -\let\mainmagstep=\magstep1 -\setfont\textrm\rmshape{12}{1000} -\setfont\texttt\ttshape{12}{1000} -\else -\setfont\textrm\rmshape{10}{\mainmagstep} -\setfont\texttt\ttshape{10}{\mainmagstep} -\fi -% Instead of cmb10, you many want to use cmbx10. -% cmbx10 is a prettier font on its own, but cmb10 -% looks better when embedded in a line with cmr10. -\setfont\textbf\bfshape{10}{\mainmagstep} -\setfont\textit\itshape{10}{\mainmagstep} -\setfont\textsl\slshape{10}{\mainmagstep} -\setfont\textsf\sfshape{10}{\mainmagstep} -\setfont\textsc\scshape{10}{\mainmagstep} -\setfont\textttsl\ttslshape{10}{\mainmagstep} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep - -% A few fonts for @defun, etc. -\setfont\defbf\bxshape{10}{\magstep1} %was 1314 -\setfont\deftt\ttshape{10}{\magstep1} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} - -% Fonts for indices and small examples (9pt). -% We actually use the slanted font rather than the italic, -% because texinfo normally uses the slanted fonts for that. -% Do not make many font distinctions in general in the index, since they -% aren't very useful. -\setfont\ninett\ttshape{9}{1000} -\setfont\indrm\rmshape{9}{1000} -\setfont\indit\slshape{9}{1000} -\let\indsl=\indit -\let\indtt=\ninett -\let\indttsl=\ninett -\let\indsf=\indrm -\let\indbf=\indrm -\setfont\indsc\scshape{10}{900} -\font\indi=cmmi9 -\font\indsy=cmsy9 - -% Chapter (and unnumbered) fonts (17.28pt). -\setfont\chaprm\rmbshape{12}{\magstep2} -\setfont\chapit\itbshape{10}{\magstep3} -\setfont\chapsl\slbshape{10}{\magstep3} -\setfont\chaptt\ttbshape{12}{\magstep2} -\setfont\chapttsl\ttslshape{10}{\magstep3} -\setfont\chapsf\sfbshape{12}{\magstep2} -\let\chapbf=\chaprm -\setfont\chapsc\scbshape{10}{\magstep3} -\font\chapi=cmmi12 scaled \magstep2 -\font\chapsy=cmsy10 scaled \magstep3 - -% Section fonts (14.4pt). -\setfont\secrm\rmbshape{12}{\magstep1} -\setfont\secit\itbshape{10}{\magstep2} -\setfont\secsl\slbshape{10}{\magstep2} -\setfont\sectt\ttbshape{12}{\magstep1} -\setfont\secttsl\ttslshape{10}{\magstep2} -\setfont\secsf\sfbshape{12}{\magstep1} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep2} -\font\seci=cmmi12 scaled \magstep1 -\font\secsy=cmsy10 scaled \magstep2 - -% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad. -% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded. -% \setfont\ssecsl\slshape{10}{\magstep1} -% \setfont\ssectt\ttshape{10}{\magstep1} -% \setfont\ssecsf\sfshape{10}{\magstep1} - -%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx. -%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than -%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1. -%\setfont\ssectt\ttshape{10}{1315} -%\setfont\ssecsf\sfshape{10}{1315} - -%\let\ssecbf=\ssecrm - -% Subsection fonts (13.15pt). -\setfont\ssecrm\rmbshape{12}{\magstephalf} -\setfont\ssecit\itbshape{10}{1315} -\setfont\ssecsl\slbshape{10}{1315} -\setfont\ssectt\ttbshape{12}{\magstephalf} -\setfont\ssecttsl\ttslshape{10}{\magstep1} -\setfont\ssecsf\sfbshape{12}{\magstephalf} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{\magstep1} -\font\sseci=cmmi12 scaled \magstephalf -\font\ssecsy=cmsy10 scaled \magstep1 -% The smallcaps and symbol fonts should actually be scaled \magstep1.5, -% but that is not a standard magnification. - -% Fonts for title page: -\setfont\titlerm\rmbshape{12}{\magstep3} -\let\authorrm = \secrm - -% In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. Since -% texinfo doesn't allow for producing subscripts and superscripts, we -% don't bother to reset \scriptfont and \scriptscriptfont (which would -% also require loading a lot more fonts). -% -\def\resetmathfonts{% - \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy - \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf - \textfont\ttfam = \tentt \textfont\sffam = \tensf -} - - -% The font-changing commands redefine the meanings of \tenSTYLE, instead -% of just \STYLE. We do this so that font changes will continue to work -% in math mode, where it is the current \fam that is relevant in most -% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam -% \tenbf}, for example. By redefining \tenbf, we obviate the need to -% redefine \bf itself. -\def\textfonts{% - \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl - \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl - \resetmathfonts} -\def\chapfonts{% - \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl - \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl - \resetmathfonts \setleading{19pt}} -\def\secfonts{% - \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl - \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl - \resetmathfonts \setleading{16pt}} -\def\subsecfonts{% - \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl - \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl - \resetmathfonts \setleading{15pt}} -\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf? -\def\indexfonts{% - \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl - \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc - \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy \let\tenttsl=\indttsl - \resetmathfonts \setleading{12pt}} - -% Set up the default fonts, so we can use them for creating boxes. -% -\textfonts - -% Count depth in font-changes, for error checks -\newcount\fontdepth \fontdepth=0 - -% Fonts for short table of contents. -\setfont\shortcontrm\rmshape{12}{1000} -\setfont\shortcontbf\bxshape{12}{1000} -\setfont\shortcontsl\slshape{12}{1000} - -%% Add scribe-like font environments, plus @l for inline lisp (usually sans -%% serif) and @ii for TeX italic - -% \smartitalic{ARG} outputs arg in italics, followed by an italic correction -% unless the following character is such as not to need one. -\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} -\def\smartitalic#1{{\sl #1}\futurelet\next\smartitalicx} - -\let\i=\smartitalic -\let\var=\smartitalic -\let\dfn=\smartitalic -\let\emph=\smartitalic -\let\cite=\smartitalic - -\def\b#1{{\bf #1}} -\let\strong=\b - -% We can't just use \exhyphenpenalty, because that only has effect at -% the end of a paragraph. Restore normal hyphenation at the end of the -% group within which \nohyphenation is presumably called. -% -\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} -\def\restorehyphenation{\hyphenchar\font = `- } - -\def\t#1{% - {\tt \rawbackslash \frenchspacing #1}% - \null -} -\let\ttfont=\t -\def\samp #1{`\tclose{#1}'\null} -\setfont\smallrm\rmshape{8}{1000} -\font\smallsy=cmsy9 -\def\key#1{{\smallrm\textfont2=\smallsy \leavevmode\hbox{% - \raise0.4pt\hbox{$\langle$}\kern-.08em\vtop{% - \vbox{\hrule\kern-0.4pt - \hbox{\raise0.4pt\hbox{\vphantom{$\langle$}}#1}}% - \kern-0.4pt\hrule}% - \kern-.06em\raise0.4pt\hbox{$\rangle$}}}} -% The old definition, with no lozenge: -%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} -\def\ctrl #1{{\tt \rawbackslash \hat}#1} - -\let\file=\samp -\let\url=\samp % perhaps include a hypertex \special eventually -\def\email#1{$\langle${\tt #1}$\rangle$} - -% @code is a modification of @t, -% which makes spaces the same size as normal in the surrounding text. -\def\tclose#1{% - {% - % Change normal interword space to be same as for the current font. - \spaceskip = \fontdimen2\font - % - % Switch to typewriter. - \tt - % - % But `\ ' produces the large typewriter interword space. - \def\ {{\spaceskip = 0pt{} }}% - % - % Turn off hyphenation. - \nohyphenation - % - \rawbackslash - \frenchspacing - #1% - }% - \null -} - -% We *must* turn on hyphenation at `-' and `_' in \code. -% Otherwise, it is too hard to avoid overfull hboxes -% in the Emacs manual, the Library manual, etc. - -% Unfortunately, TeX uses one parameter (\hyphenchar) to control -% both hyphenation at - and hyphenation within words. -% We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate at a dash. -% -- rms. -{ -\catcode`\-=\active -\catcode`\_=\active -\global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} -% The following is used by \doprintindex to insure that long function names -% wrap around. It is necessary for - and _ to be active before the index is -% read from the file, as \entry parses the arguments long before \code is -% ever called. -- mycroft -\global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} -} - -\def\realdash{-} -\def\realunder{_} -\def\codedash{-\discretionary{}{}{}} -\def\codeunder{\normalunderscore\discretionary{}{}{}} -\def\codex #1{\tclose{#1}\endgroup} - -%\let\exp=\tclose %Was temporary - -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. -% -\def\xkey{\key} -\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% -\ifx\one\xkey\ifx\threex\three \key{#2}% -\else{\tclose{\ttsl\look}}\fi -\else{\tclose{\ttsl\look}}\fi} - -% Check if we are currently using a typewriter font. Since all the -% Computer Modern typewriter fonts have zero interword stretch (and -% shrink), and it is reasonable to expect all typewriter fonts to have -% this property, we can check that font parameter. -% -\def\ifmonospace{\ifdim\fontdimen3\font=0pt } - -% Typeset a dimension, e.g., `in' or `pt'. The only reason for the -% argument is to make the input look right: @dmn{pt} instead of -% @dmn{}pt. -% -\def\dmn#1{\thinspace #1} - -\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} - -% @l was never documented to mean ``switch to the Lisp font'', -% and it is not used as such in any manual I can find. We need it for -% Polish suppressed-l. --karl, 22sep96. -%\def\l#1{{\li #1}\null} - -\def\r#1{{\rm #1}} % roman font -% Use of \lowercase was suggested. -\def\sc#1{{\smallcaps#1}} % smallcaps font -\def\ii#1{{\it #1}} % italic font - -% @pounds{} is a sterling sign. -\def\pounds{{\it\$}} - - -\message{page headings,} - -\newskip\titlepagetopglue \titlepagetopglue = 1.5in -\newskip\titlepagebottomglue \titlepagebottomglue = 2pc - -% First the title page. Must do @settitle before @titlepage. -\def\titlefont#1{{\titlerm #1}} - -\newif\ifseenauthor -\newif\iffinishedtitlepage - -\def\shorttitlepage{\parsearg\shorttitlepagezzz} -\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% - \endgroup\page\hbox{}\page} - -\def\titlepage{\begingroup \parindent=0pt \textfonts - \let\subtitlerm=\tenrm -% I deinstalled the following change because \cmr12 is undefined. -% This change was not in the ChangeLog anyway. --rms. -% \let\subtitlerm=\cmr12 - \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% - % - \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% - % - % Leave some space at the very top of the page. - \vglue\titlepagetopglue - % - % Now you can print the title using @title. - \def\title{\parsearg\titlezzz}% - \def\titlezzz##1{\leftline{\titlefont{##1}} - % print a rule at the page bottom also. - \finishedtitlepagefalse - \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% - % No rule at page bottom unless we print one at the top with @title. - \finishedtitlepagetrue - % - % Now you can put text using @subtitle. - \def\subtitle{\parsearg\subtitlezzz}% - \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% - % - % @author should come last, but may come many times. - \def\author{\parsearg\authorzzz}% - \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi - {\authorfont \leftline{##1}}}% - % - % Most title ``pages'' are actually two pages long, with space - % at the top of the second. We don't want the ragged left on the second. - \let\oldpage = \page - \def\page{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - \oldpage - \let\page = \oldpage - \hbox{}}% -% \def\page{\oldpage \hbox{}} -} - -\def\Etitlepage{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - % It is important to do the page break before ending the group, - % because the headline and footline are only empty inside the group. - % If we use the new definition of \page, we always get a blank page - % after the title page, which we certainly don't want. - \oldpage - \endgroup - \HEADINGSon -} - -\def\finishtitlepage{% - \vskip4pt \hrule height 2pt width \hsize - \vskip\titlepagebottomglue - \finishedtitlepagetrue -} - -%%% Set up page headings and footings. - -\let\thispage=\folio - -\newtoks \evenheadline % Token sequence for heading line of even pages -\newtoks \oddheadline % Token sequence for heading line of odd pages -\newtoks \evenfootline % Token sequence for footing line of even pages -\newtoks \oddfootline % Token sequence for footing line of odd pages - -% Now make Tex use those variables -\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline - \else \the\evenheadline \fi}} -\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline - \else \the\evenfootline \fi}\HEADINGShook} -\let\HEADINGShook=\relax - -% Commands to set those variables. -% For example, this is what @headings on does -% @evenheading @thistitle|@thispage|@thischapter -% @oddheading @thischapter|@thispage|@thistitle -% @evenfooting @thisfile|| -% @oddfooting ||@thisfile - -\def\evenheading{\parsearg\evenheadingxxx} -\def\oddheading{\parsearg\oddheadingxxx} -\def\everyheading{\parsearg\everyheadingxxx} - -\def\evenfooting{\parsearg\evenfootingxxx} -\def\oddfooting{\parsearg\oddfootingxxx} -\def\everyfooting{\parsearg\everyfootingxxx} - -{\catcode`\@=0 % - -\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} -\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} -\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\gdef\everyheadingxxx #1{\everyheadingyyy #1@|@|@|@|\finish} -\gdef\everyheadingyyy #1@|#2@|#3@|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} -\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% -\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} -\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% -\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\gdef\everyfootingxxx #1{\everyfootingyyy #1@|@|@|@|\finish} -\gdef\everyfootingyyy #1@|#2@|#3@|#4\finish{% -\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}} -\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} -% -}% unbind the catcode of @. - -% @headings double turns headings on for double-sided printing. -% @headings single turns headings on for single-sided printing. -% @headings off turns them off. -% @headings on same as @headings double, retained for compatibility. -% @headings after turns on double-sided headings after this page. -% @headings doubleafter turns on double-sided headings after this page. -% @headings singleafter turns on single-sided headings after this page. -% By default, they are off at the start of a document, -% and turned `on' after @end titlepage. - -\def\headings #1 {\csname HEADINGS#1\endcsname} - -\def\HEADINGSoff{ -\global\evenheadline={\hfil} \global\evenfootline={\hfil} -\global\oddheadline={\hfil} \global\oddfootline={\hfil}} -\HEADINGSoff -% When we turn headings on, set the page number to 1. -% For double-sided printing, put current file name in lower left corner, -% chapter name on inside top of right hand pages, document -% title on inside top of left hand pages, and page numbers on outside top -% edge of all pages. -\def\HEADINGSdouble{ -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} -\let\contentsalignmacro = \chappager - -% For single-sided printing, chapter title goes across top left of page, -% page number on top right. -\def\HEADINGSsingle{ -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} -\def\HEADINGSon{\HEADINGSdouble} - -\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} -\let\HEADINGSdoubleafter=\HEADINGSafter -\def\HEADINGSdoublex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} - -\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} -\def\HEADINGSsinglex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} - -% Subroutines used in generating headings -% Produces Day Month Year style of output. -\def\today{\number\day\space -\ifcase\month\or -January\or February\or March\or April\or May\or June\or -July\or August\or September\or October\or November\or December\fi -\space\number\year} - -% Use this if you want the Month Day, Year style of output. -%\def\today{\ifcase\month\or -%January\or February\or March\or April\or May\or June\or -%July\or August\or September\or October\or November\or December\fi -%\space\number\day, \number\year} - -% @settitle line... specifies the title of the document, for headings -% It generates no output of its own - -\def\thistitle{No Title} -\def\settitle{\parsearg\settitlezzz} -\def\settitlezzz #1{\gdef\thistitle{#1}} - - -\message{tables,} - -% @tabs -- simple alignment - -% These don't work. For one thing, \+ is defined as outer. -% So these macros cannot even be defined. - -%\def\tabs{\parsearg\tabszzz} -%\def\tabszzz #1{\settabs\+#1\cr} -%\def\tabline{\parsearg\tablinezzz} -%\def\tablinezzz #1{\+#1\cr} -%\def\&{&} - -% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x). - -% default indentation of table text -\newdimen\tableindent \tableindent=.8in -% default indentation of @itemize and @enumerate text -\newdimen\itemindent \itemindent=.3in -% margin between end of table item and start of table text. -\newdimen\itemmargin \itemmargin=.1in - -% used internally for \itemindent minus \itemmargin -\newdimen\itemmax - -% Note @table, @vtable, and @vtable define @item, @itemx, etc., with -% these defs. -% They also define \itemindex -% to index the item name in whatever manner is desired (perhaps none). - -\newif\ifitemxneedsnegativevskip - -\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} - -\def\internalBitem{\smallbreak \parsearg\itemzzz} -\def\internalBitemx{\itemxpar \parsearg\itemzzz} - -\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} -\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} - -\def\internalBkitem{\smallbreak \parsearg\kitemzzz} -\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} - -\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% - \itemzzz {#1}} - -\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% - \itemzzz {#1}} - -\def\itemzzz #1{\begingroup % - \advance\hsize by -\rightskip - \advance\hsize by -\tableindent - \setbox0=\hbox{\itemfont{#1}}% - \itemindex{#1}% - \nobreak % This prevents a break before @itemx. - % - % Be sure we are not still in the middle of a paragraph. - %{\parskip = 0in - %\par - %}% - % - % If the item text does not fit in the space we have, put it on a line - % by itself, and do not allow a page break either before or after that - % line. We do not start a paragraph here because then if the next - % command is, e.g., @kindex, the whatsit would get put into the - % horizontal list on a line by itself, resulting in extra blank space. - \ifdim \wd0>\itemmax - % - % Make this a paragraph so we get the \parskip glue and wrapping, - % but leave it ragged-right. - \begingroup - \advance\leftskip by-\tableindent - \advance\hsize by\tableindent - \advance\rightskip by0pt plus1fil - \leavevmode\unhbox0\par - \endgroup - % - % We're going to be starting a paragraph, but we don't want the - % \parskip glue -- logically it's part of the @item we just started. - \nobreak \vskip-\parskip - % - % Stop a page break at the \parskip glue coming up. Unfortunately - % we can't prevent a possible page break at the following - % \baselineskip glue. - \nobreak - \endgroup - \itemxneedsnegativevskipfalse - \else - % The item text fits into the space. Start a paragraph, so that the - % following text (if any) will end up on the same line. Since that - % text will be indented by \tableindent, we make the item text be in - % a zero-width box. - \noindent - \rlap{\hskip -\tableindent\box0}\ignorespaces% - \endgroup% - \itemxneedsnegativevskiptrue% - \fi -} - -\def\item{\errmessage{@item while not in a table}} -\def\itemx{\errmessage{@itemx while not in a table}} -\def\kitem{\errmessage{@kitem while not in a table}} -\def\kitemx{\errmessage{@kitemx while not in a table}} -\def\xitem{\errmessage{@xitem while not in a table}} -\def\xitemx{\errmessage{@xitemx while not in a table}} - -%% Contains a kludge to get @end[description] to work -\def\description{\tablez{\dontindex}{1}{}{}{}{}} - -\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} -{\obeylines\obeyspaces% -\gdef\tablex #1^^M{% -\tabley\dontindex#1 \endtabley}} - -\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} -{\obeylines\obeyspaces% -\gdef\ftablex #1^^M{% -\tabley\fnitemindex#1 \endtabley -\def\Eftable{\endgraf\afterenvbreak\endgroup}% -\let\Etable=\relax}} - -\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} -{\obeylines\obeyspaces% -\gdef\vtablex #1^^M{% -\tabley\vritemindex#1 \endtabley -\def\Evtable{\endgraf\afterenvbreak\endgroup}% -\let\Etable=\relax}} - -\def\dontindex #1{} -\def\fnitemindex #1{\doind {fn}{\code{#1}}}% -\def\vritemindex #1{\doind {vr}{\code{#1}}}% - -{\obeyspaces % -\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% -\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} - -\def\tablez #1#2#3#4#5#6{% -\aboveenvbreak % -\begingroup % -\def\Edescription{\Etable}% Necessary kludge. -\let\itemindex=#1% -\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % -\ifnum 0#4>0 \tableindent=#4\mil \fi % -\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % -\def\itemfont{#2}% -\itemmax=\tableindent % -\advance \itemmax by -\itemmargin % -\advance \leftskip by \tableindent % -\exdentamount=\tableindent -\parindent = 0pt -\parskip = \smallskipamount -\ifdim \parskip=0pt \parskip=2pt \fi% -\def\Etable{\endgraf\afterenvbreak\endgroup}% -\let\item = \internalBitem % -\let\itemx = \internalBitemx % -\let\kitem = \internalBkitem % -\let\kitemx = \internalBkitemx % -\let\xitem = \internalBxitem % -\let\xitemx = \internalBxitemx % -} - -% This is the counter used by @enumerate, which is really @itemize - -\newcount \itemno - -\def\itemize{\parsearg\itemizezzz} - -\def\itemizezzz #1{% - \begingroup % ended by the @end itemsize - \itemizey {#1}{\Eitemize} -} - -\def\itemizey #1#2{% -\aboveenvbreak % -\itemmax=\itemindent % -\advance \itemmax by -\itemmargin % -\advance \leftskip by \itemindent % -\exdentamount=\itemindent -\parindent = 0pt % -\parskip = \smallskipamount % -\ifdim \parskip=0pt \parskip=2pt \fi% -\def#2{\endgraf\afterenvbreak\endgroup}% -\def\itemcontents{#1}% -\let\item=\itemizeitem} - -% Set sfcode to normal for the chars that usually have another value. -% These are `.?!:;,' -\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 - \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } - -% \splitoff TOKENS\endmark defines \first to be the first token in -% TOKENS, and \rest to be the remainder. -% -\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% - -% Allow an optional argument of an uppercase letter, lowercase letter, -% or number, to specify the first label in the enumerated list. No -% argument is the same as `1'. -% -\def\enumerate{\parsearg\enumeratezzz} -\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} -\def\enumeratey #1 #2\endenumeratey{% - \begingroup % ended by the @end enumerate - % - % If we were given no argument, pretend we were given `1'. - \def\thearg{#1}% - \ifx\thearg\empty \def\thearg{1}\fi - % - % Detect if the argument is a single token. If so, it might be a - % letter. Otherwise, the only valid thing it can be is a number. - % (We will always have one token, because of the test we just made. - % This is a good thing, since \splitoff doesn't work given nothing at - % all -- the first parameter is undelimited.) - \expandafter\splitoff\thearg\endmark - \ifx\rest\empty - % Only one token in the argument. It could still be anything. - % A ``lowercase letter'' is one whose \lccode is nonzero. - % An ``uppercase letter'' is one whose \lccode is both nonzero, and - % not equal to itself. - % Otherwise, we assume it's a number. - % - % We need the \relax at the end of the \ifnum lines to stop TeX from - % continuing to look for a <number>. - % - \ifnum\lccode\expandafter`\thearg=0\relax - \numericenumerate % a number (we hope) - \else - % It's a letter. - \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax - \lowercaseenumerate % lowercase letter - \else - \uppercaseenumerate % uppercase letter - \fi - \fi - \else - % Multiple tokens in the argument. We hope it's a number. - \numericenumerate - \fi -} - -% An @enumerate whose labels are integers. The starting integer is -% given in \thearg. -% -\def\numericenumerate{% - \itemno = \thearg - \startenumeration{\the\itemno}% -} - -% The starting (lowercase) letter is in \thearg. -\def\lowercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more lowercase letters in @enumerate; get a bigger - alphabet}% - \fi - \char\lccode\itemno - }% -} - -% The starting (uppercase) letter is in \thearg. -\def\uppercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more uppercase letters in @enumerate; get a bigger - alphabet} - \fi - \char\uccode\itemno - }% -} - -% Call itemizey, adding a period to the first argument and supplying the -% common last two arguments. Also subtract one from the initial value in -% \itemno, since @item increments \itemno. -% -\def\startenumeration#1{% - \advance\itemno by -1 - \itemizey{#1.}\Eenumerate\flushcr -} - -% @alphaenumerate and @capsenumerate are abbreviations for giving an arg -% to @enumerate. -% -\def\alphaenumerate{\enumerate{a}} -\def\capsenumerate{\enumerate{A}} -\def\Ealphaenumerate{\Eenumerate} -\def\Ecapsenumerate{\Eenumerate} - -% Definition of @item while inside @itemize. - -\def\itemizeitem{% -\advance\itemno by 1 -{\let\par=\endgraf \smallbreak}% -\ifhmode \errmessage{\in hmode at itemizeitem}\fi -{\parskip=0in \hskip 0pt -\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% -\vadjust{\penalty 1200}}% -\flushcr} - -% @multitable macros -% Amy Hendrickson, 8/18/94, 3/6/96 -% -% @multitable ... @end multitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width -% can be specified either with sample text given in a template line, -% or in percent of \hsize, the current width of text on page. - -% Table can continue over pages but will only break between lines. - -% To make preamble: -% -% Either define widths of columns in terms of percent of \hsize: -% @multitable @columnfractions .25 .3 .45 -% @item ... -% -% Numbers following @columnfractions are the percent of the total -% current hsize to be used for each column. You may use as many -% columns as desired. - - -% Or use a template: -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item ... -% using the widest term desired in each column. -% -% For those who want to use more than one line's worth of words in -% the preamble, break the line within one argument and it -% will parse correctly, i.e., -% -% @multitable {Column 1 template} {Column 2 template} {Column 3 -% template} -% Not: -% @multitable {Column 1 template} {Column 2 template} -% {Column 3 template} - -% Each new table line starts with @item, each subsequent new column -% starts with @tab. Empty columns may be produced by supplying @tab's -% with nothing between them for as many times as empty columns are needed, -% ie, @tab@tab@tab will produce two empty columns. - -% @item, @tab, @multitable or @end multitable do not need to be on their -% own lines, but it will not hurt if they are. - -% Sample multitable: - -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff -% @tab Many paragraphs of text may be used in any column. -% -% They will wrap at the width determined by the template. -% @item@tab@tab This will be in third column. -% @end multitable - -% Default dimensions may be reset by user. -% @multitableparskip is vertical space between paragraphs in table. -% @multitableparindent is paragraph indent in table. -% @multitablecolmargin is horizontal space to be left between columns. -% @multitablelinespace is space to leave between table items, baseline -% to baseline. -% 0pt means it depends on current normal line spacing. - -%%%% -% Dimensions - -\newskip\multitableparskip -\newskip\multitableparindent -\newdimen\multitablecolspace -\newskip\multitablelinespace -\multitableparskip=0pt -\multitableparindent=6pt -\multitablecolspace=12pt -\multitablelinespace=0pt - -%%%% -% Macros used to set up halign preamble: -\let\endsetuptable\relax -\def\xendsetuptable{\endsetuptable} -\let\columnfractions\relax -\def\xcolumnfractions{\columnfractions} -\newif\ifsetpercent - -%% 2/1/96, to allow fractions to be given with more than one digit. -\def\pickupwholefraction#1 {\global\advance\colcount by1 % -\expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% -\setuptable} - -\newcount\colcount -\def\setuptable#1{\def\firstarg{#1}% -\ifx\firstarg\xendsetuptable\let\go\relax% -\else - \ifx\firstarg\xcolumnfractions\global\setpercenttrue% - \else - \ifsetpercent - \let\go\pickupwholefraction % In this case arg of setuptable - % is the decimal point before the - % number given in percent of hsize. - % We don't need this so we don't use it. - \else - \global\advance\colcount by1 - \setbox0=\hbox{#1 }% Add a normal word space as a separator; - % typically that is always in the input, anyway. - \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% - \fi% - \fi% -\ifx\go\pickupwholefraction\else\let\go\setuptable\fi% -\fi\go} - -%%%% -% multitable syntax -\def\tab{&\hskip1sp\relax} % 2/2/96 - % tiny skip here makes sure this column space is - % maintained, even if it is never used. - - -%%%% -% @multitable ... @end multitable definitions: - -\def\multitable{\parsearg\dotable} - -\def\dotable#1{\bgroup -\let\item\cr -\tolerance=9500 -\hbadness=9500 -\setmultitablespacing -\parskip=\multitableparskip -\parindent=\multitableparindent -\overfullrule=0pt -\global\colcount=0\relax% -\def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% - % To parse everything between @multitable and @item : -\setuptable#1 \endsetuptable - % Need to reset this to 0 after \setuptable. -\global\colcount=0\relax% - % - % This preamble sets up a generic column definition, which will - % be used as many times as user calls for columns. - % \vtop will set a single line and will also let text wrap and - % continue for many paragraphs if desired. -\halign\bgroup&\global\advance\colcount by 1\relax% -\multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % If user has set preamble in terms of percent of \hsize - % we will use that dimension as the width of the column, and - % the \leftskip will keep entries from bumping into each other. - % Table will start at left margin and final column will justify at - % right margin. -\ifnum\colcount=1 -\else - \ifsetpercent - \else - % If user has <not> set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: -\leftskip=\multitablecolspace -\fi -\noindent##\multistrut}\cr% - % \everycr will reset column counter, \colcount, at the end of - % each line. Every column entry will cause \colcount to advance by one. - % The table preamble - % looks at the current \colcount to find the correct column width. -\global\everycr{\noalign{% -\filbreak%% keeps underfull box messages off when table breaks over pages. -\global\colcount=0\relax}} -} - -\def\setmultitablespacing{% test to see if user has set \multitablelinespace. -% If so, do nothing. If not, give it an appropriate dimension based on -% current baselineskip. -\ifdim\multitablelinespace=0pt -%% strut to put in table in case some entry doesn't have descenders, -%% to keep lines equally spaced -\let\multistrut = \strut -%% Test to see if parskip is larger than space between lines of -%% table. If not, do nothing. -%% If so, set to same dimension as multitablelinespace. -\else -\gdef\multistrut{\vrule height\multitablelinespace depth\dp0 -width0pt\relax} \fi -\ifdim\multitableparskip>\multitablelinespace -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi% -\ifdim\multitableparskip=0pt -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi} - - -\message{indexing,} -% Index generation facilities - -% Define \newwrite to be identical to plain tex's \newwrite -% except not \outer, so it can be used within \newindex. -{\catcode`\@=11 -\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}} - -% \newindex {foo} defines an index named foo. -% It automatically defines \fooindex such that -% \fooindex ...rest of line... puts an entry in the index foo. -% It also defines \fooindfile to be the number of the output channel for -% the file that accumulates this index. The file's extension is foo. -% The name of an index should be no more than 2 characters long -% for the sake of vms. - -\def\newindex #1{ -\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file -\openout \csname#1indfile\endcsname \jobname.#1 % Open the file -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex -\noexpand\doindex {#1}} -} - -% @defindex foo == \newindex{foo} - -\def\defindex{\parsearg\newindex} - -% Define @defcodeindex, like @defindex except put all entries in @code. - -\def\newcodeindex #1{ -\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file -\openout \csname#1indfile\endcsname \jobname.#1 % Open the file -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex -\noexpand\docodeindex {#1}} -} - -\def\defcodeindex{\parsearg\newcodeindex} - -% @synindex foo bar makes index foo feed into index bar. -% Do this instead of @defindex foo if you don't want it as a separate index. -\def\synindex #1 #2 {% -\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname -\expandafter\let\csname#1indfile\endcsname=\synindexfoo -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex -\noexpand\doindex {#2}}% -} - -% @syncodeindex foo bar similar, but put all entries made for index foo -% inside @code. -\def\syncodeindex #1 #2 {% -\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname -\expandafter\let\csname#1indfile\endcsname=\synindexfoo -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex -\noexpand\docodeindex {#2}}% -} - -% Define \doindex, the driver for all \fooindex macros. -% Argument #1 is generated by the calling \fooindex macro, -% and it is "foo", the name of the index. - -% \doindex just uses \parsearg; it calls \doind for the actual work. -% This is because \doind is more useful to call from other macros. - -% There is also \dosubind {index}{topic}{subtopic} -% which makes an entry in a two-level index such as the operation index. - -\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} -\def\singleindexer #1{\doind{\indexname}{#1}} - -% like the previous two, but they put @code around the argument. -\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} -\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} - -\def\indexdummies{% -% Take care of the plain tex accent commands. -\def\"{\realbackslash "}% -\def\`{\realbackslash `}% -\def\'{\realbackslash '}% -\def\^{\realbackslash ^}% -\def\~{\realbackslash ~}% -\def\={\realbackslash =}% -\def\b{\realbackslash b}% -\def\c{\realbackslash c}% -\def\d{\realbackslash d}% -\def\u{\realbackslash u}% -\def\v{\realbackslash v}% -\def\H{\realbackslash H}% -% Take care of the plain tex special European modified letters. -\def\oe{\realbackslash oe}% -\def\ae{\realbackslash ae}% -\def\aa{\realbackslash aa}% -\def\OE{\realbackslash OE}% -\def\AE{\realbackslash AE}% -\def\AA{\realbackslash AA}% -\def\o{\realbackslash o}% -\def\O{\realbackslash O}% -\def\l{\realbackslash l}% -\def\L{\realbackslash L}% -\def\ss{\realbackslash ss}% -% Take care of texinfo commands likely to appear in an index entry. -% (Must be a way to avoid doing expansion at all, and thus not have to -% laboriously list every single command here.) -\def\@{@}% will be @@ when we switch to @ as escape char. -%\let\{ = \lbracecmd -%\let\} = \rbracecmd -\def\_{{\realbackslash _}}% -\def\w{\realbackslash w }% -\def\bf{\realbackslash bf }% -%\def\rm{\realbackslash rm }% -\def\sl{\realbackslash sl }% -\def\sf{\realbackslash sf}% -\def\tt{\realbackslash tt}% -\def\gtr{\realbackslash gtr}% -\def\less{\realbackslash less}% -\def\hat{\realbackslash hat}% -%\def\char{\realbackslash char}% -\def\TeX{\realbackslash TeX}% -\def\dots{\realbackslash dots }% -\def\copyright{\realbackslash copyright }% -\def\tclose##1{\realbackslash tclose {##1}}% -\def\code##1{\realbackslash code {##1}}% -\def\dotless##1{\realbackslash dotless {##1}}% -\def\samp##1{\realbackslash samp {##1}}% -\def\,##1{\realbackslash ,{##1}}% -\def\t##1{\realbackslash t {##1}}% -\def\r##1{\realbackslash r {##1}}% -\def\i##1{\realbackslash i {##1}}% -\def\b##1{\realbackslash b {##1}}% -\def\cite##1{\realbackslash cite {##1}}% -\def\key##1{\realbackslash key {##1}}% -\def\file##1{\realbackslash file {##1}}% -\def\var##1{\realbackslash var {##1}}% -\def\kbd##1{\realbackslash kbd {##1}}% -\def\dfn##1{\realbackslash dfn {##1}}% -\def\emph##1{\realbackslash emph {##1}}% -\unsepspaces -} - -% If an index command is used in an @example environment, any spaces -% therein should become regular spaces in the raw index file, not the -% expansion of \tie (\\leavevmode \penalty \@M \ ). -{\obeyspaces - \gdef\unsepspaces{\obeyspaces\let =\space}} - -% \indexnofonts no-ops all font-change commands. -% This is used when outputting the strings to sort the index by. -\def\indexdummyfont#1{#1} -\def\indexdummytex{TeX} -\def\indexdummydots{...} - -\def\indexnofonts{% -% Just ignore accents. -\let\,=\indexdummyfont -\let\"=\indexdummyfont -\let\`=\indexdummyfont -\let\'=\indexdummyfont -\let\^=\indexdummyfont -\let\~=\indexdummyfont -\let\==\indexdummyfont -\let\b=\indexdummyfont -\let\c=\indexdummyfont -\let\d=\indexdummyfont -\let\u=\indexdummyfont -\let\v=\indexdummyfont -\let\H=\indexdummyfont -\let\dotless=\indexdummyfont -% Take care of the plain tex special European modified letters. -\def\oe{oe}% -\def\ae{ae}% -\def\aa{aa}% -\def\OE{OE}% -\def\AE{AE}% -\def\AA{AA}% -\def\o{o}% -\def\O{O}% -\def\l{l}% -\def\L{L}% -\def\ss{ss}% -\let\w=\indexdummyfont -\let\t=\indexdummyfont -\let\r=\indexdummyfont -\let\i=\indexdummyfont -\let\b=\indexdummyfont -\let\emph=\indexdummyfont -\let\strong=\indexdummyfont -\let\cite=\indexdummyfont -\let\sc=\indexdummyfont -%Don't no-op \tt, since it isn't a user-level command -% and is used in the definitions of the active chars like <, >, |... -%\let\tt=\indexdummyfont -\let\tclose=\indexdummyfont -\let\code=\indexdummyfont -\let\file=\indexdummyfont -\let\samp=\indexdummyfont -\let\kbd=\indexdummyfont -\let\key=\indexdummyfont -\let\var=\indexdummyfont -\let\TeX=\indexdummytex -\let\dots=\indexdummydots -\def\@{@}% -} - -% To define \realbackslash, we must make \ not be an escape. -% We must first make another character (@) an escape -% so we do not become unable to do a definition. - -{\catcode`\@=0 \catcode`\\=\other -@gdef@realbackslash{\}} - -\let\indexbackslash=0 %overridden during \printindex. - -\let\SETmarginindex=\relax %initialize! -% workhorse for all \fooindexes -% #1 is name of index, #2 is stuff to put there -\def\doind #1#2{% - % Put the index entry in the margin if desired. - \ifx\SETmarginindex\relax\else - \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% - \fi - {% - \count255=\lastpenalty - {% - \indexdummies % Must do this here, since \bf, etc expand at this stage - \escapechar=`\\ - {% - \let\folio=0 % We will expand all macros now EXCEPT \folio. - \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now - % so it will be output as is; and it will print as backslash. - % - % First process the index-string with all font commands turned off - % to get the string to sort by. - {\indexnofonts \xdef\indexsorttmp{#2}}% - % - % Now produce the complete index entry, with both the sort key and the - % original text, including any font commands. - \toks0 = {#2}% - \edef\temp{% - \write\csname#1indfile\endcsname{% - \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}% - }% - \temp - }% - }% - \penalty\count255 - }% -} - -\def\dosubind #1#2#3{% -{\count10=\lastpenalty % -{\indexdummies % Must do this here, since \bf, etc expand at this stage -\escapechar=`\\% -{\let\folio=0% -\def\rawbackslashxx{\indexbackslash}% -% -% Now process the index-string once, with all font commands turned off, -% to get the string to sort the index by. -{\indexnofonts -\xdef\temp1{#2 #3}% -}% -% Now produce the complete index entry. We process the index-string again, -% this time with font commands expanded, to get what to print in the index. -\edef\temp{% -\write \csname#1indfile\endcsname{% -\realbackslash entry {\temp1}{\folio}{#2}{#3}}}% -\temp }% -}\penalty\count10}} - -% The index entry written in the file actually looks like -% \entry {sortstring}{page}{topic} -% or -% \entry {sortstring}{page}{topic}{subtopic} -% The texindex program reads in these files and writes files -% containing these kinds of lines: -% \initial {c} -% before the first topic whose initial is c -% \entry {topic}{pagelist} -% for a topic that is used without subtopics -% \primary {topic} -% for the beginning of a topic that is used with subtopics -% \secondary {subtopic}{pagelist} -% for each subtopic. - -% Define the user-accessible indexing commands -% @findex, @vindex, @kindex, @cindex. - -\def\findex {\fnindex} -\def\kindex {\kyindex} -\def\cindex {\cpindex} -\def\vindex {\vrindex} -\def\tindex {\tpindex} -\def\pindex {\pgindex} - -\def\cindexsub {\begingroup\obeylines\cindexsub} -{\obeylines % -\gdef\cindexsub "#1" #2^^M{\endgroup % -\dosubind{cp}{#2}{#1}}} - -% Define the macros used in formatting output of the sorted index material. - -% This is what you call to cause a particular index to get printed. -% Write -% @unnumbered Function Index -% @printindex fn - -\def\printindex{\parsearg\doprintindex} - -\def\doprintindex#1{\begingroup - \dobreak \chapheadingskip{10000}% - % - \indexfonts \rm - \tolerance = 9500 - \indexbreaks - \def\indexbackslash{\rawbackslashxx}% - % Index files are almost Texinfo source, but we use \ as the escape - % character. It would be better to use @, but that's too big a change - % to make right now. - \catcode`\\ = 0 - \catcode`\@ = 11 - \escapechar = `\\ - \begindoublecolumns - % - % See if the index file exists and is nonempty. - \openin 1 \jobname.#1s - \ifeof 1 - % \enddoublecolumns gets confused if there is no text in the index, - % and it loses the chapter title and the aux file entries for the - % index. The easiest way to prevent this problem is to make sure - % there is some text. - (Index is nonexistent) - \else - % - % If the index file exists but is empty, then \openin leaves \ifeof - % false. We have to make TeX try to read something from the file, so - % it can discover if there is anything in it. - \read 1 to \temp - \ifeof 1 - (Index is empty) - \else - \input \jobname.#1s - \fi - \fi - \closein 1 - \enddoublecolumns -\endgroup} - -% These macros are used by the sorted index file itself. -% Change them to control the appearance of the index. - -% Same as \bigskipamount except no shrink. -% \balancecolumns gets confused if there is any shrink. -\newskip\initialskipamount \initialskipamount 12pt plus4pt - -\def\initial #1{% -{\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt -\ifdim\lastskip<\initialskipamount -\removelastskip \penalty-200 \vskip \initialskipamount\fi -\line{\secbf#1\hfill}\kern 2pt\penalty10000}} - -% This typesets a paragraph consisting of #1, dot leaders, and then #2 -% flush to the right margin. It is used for index and table of contents -% entries. The paragraph is indented by \leftskip. -% -\def\entry #1#2{\begingroup - % - % Start a new paragraph if necessary, so our assignments below can't - % affect previous text. - \par - % - % Do not fill out the last line with white space. - \parfillskip = 0in - % - % No extra space above this paragraph. - \parskip = 0in - % - % Do not prefer a separate line ending with a hyphen to fewer lines. - \finalhyphendemerits = 0 - % - % \hangindent is only relevant when the entry text and page number - % don't both fit on one line. In that case, bob suggests starting the - % dots pretty far over on the line. Unfortunately, a large - % indentation looks wrong when the entry text itself is broken across - % lines. So we use a small indentation and put up with long leaders. - % - % \hangafter is reset to 1 (which is the value we want) at the start - % of each paragraph, so we need not do anything with that. - \hangindent=2em - % - % When the entry text needs to be broken, just fill out the first line - % with blank space. - \rightskip = 0pt plus1fil - % - % Start a ``paragraph'' for the index entry so the line breaking - % parameters we've set above will have an effect. - \noindent - % - % Insert the text of the index entry. TeX will do line-breaking on it. - #1% - % The following is kludged to not output a line of dots in the index if - % there are no page numbers. The next person who breaks this will be - % cursed by a Unix daemon. - \def\tempa{{\rm }}% - \def\tempb{#2}% - \edef\tempc{\tempa}% - \edef\tempd{\tempb}% - \ifx\tempc\tempd\ \else% - % - % If we must, put the page number on a line of its own, and fill out - % this line with blank space. (The \hfil is overwhelmed with the - % fill leaders glue in \indexdotfill if the page number does fit.) - \hfil\penalty50 - \null\nobreak\indexdotfill % Have leaders before the page number. - % - % The `\ ' here is removed by the implicit \unskip that TeX does as - % part of (the primitive) \par. Without it, a spurious underfull - % \hbox ensues. - \ #2% The page number ends the paragraph. - \fi% - \par -\endgroup} - -% Like \dotfill except takes at least 1 em. -\def\indexdotfill{\cleaders - \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill} - -\def\primary #1{\line{#1\hfil}} - -\newskip\secondaryindent \secondaryindent=0.5cm - -\def\secondary #1#2{ -{\parfillskip=0in \parskip=0in -\hangindent =1in \hangafter=1 -\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par -}} - -% Define two-column mode, which we use to typeset indexes. -% Adapted from the TeXbook, page 416, which is to say, -% the manmac.tex format used to print the TeXbook itself. -\catcode`\@=11 - -\newbox\partialpage -\newdimen\doublecolumnhsize - -\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns - % Grab any single-column material above us. - \output = {\global\setbox\partialpage - =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% - \eject - % - % Now switch to the double-column output routine. - \output={\doublecolumnout}% - % - % Change the page size parameters. We could do this once outside this - % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 - % format, but then we repeat the same computation. Repeating a couple - % of assignments once per index is clearly meaningless for the - % execution time, so we may as well do it once. - % - % First we halve the line length, less a little for the gutter between - % the columns. We compute the gutter based on the line length, so it - % changes automatically with the paper format. The magic constant - % below is chosen so that the gutter has the same value (well, +- < - % 1pt) as it did when we hard-coded it. - % - % We put the result in a separate register, \doublecolumhsize, so we - % can restore it in \pagesofar, after \hsize itself has (potentially) - % been clobbered. - % - \doublecolumnhsize = \hsize - \advance\doublecolumnhsize by -.04154\hsize - \divide\doublecolumnhsize by 2 - \hsize = \doublecolumnhsize - % - % Double the \vsize as well. (We don't need a separate register here, - % since nobody clobbers \vsize.) - \vsize = 2\vsize -} -\def\doublecolumnout{% - \splittopskip=\topskip \splitmaxdepth=\maxdepth - % Get the available space for the double columns -- the normal - % (undoubled) page height minus any material left over from the - % previous page. - \dimen@=\pageheight \advance\dimen@ by-\ht\partialpage - % box0 will be the left-hand column, box1 the right. - \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ - \onepageout\pagesofar - \unvbox255 \penalty\outputpenalty -} -\def\pagesofar{% - % The contents of the output page -- any previous material, - % followed by the two boxes we just split. - \unvbox\partialpage - \hsize = \doublecolumnhsize - \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}% -} -\def\enddoublecolumns{% - \output={\balancecolumns}\eject % split what we have - \endgroup - % Back to normal single-column typesetting, but take account of the - % fact that we just accumulated some stuff on the output page. - \pagegoal=\vsize -} -\def\balancecolumns{% - % Called on the last page of the double column material. - \setbox0=\vbox{\unvbox255}% - \dimen@ = \ht0 - \advance\dimen@ by \topskip - \advance\dimen@ by-\baselineskip - \divide\dimen@ by 2 - \splittopskip = \topskip - % Loop until we get a decent breakpoint. - {\vbadness=10000 \loop \global\setbox3=\copy0 - \global\setbox1=\vsplit3 to\dimen@ - \ifdim\ht3>\dimen@ \global\advance\dimen@ by1pt \repeat}% - \setbox0=\vbox to\dimen@{\unvbox1}% - \setbox2=\vbox to\dimen@{\unvbox3}% - \pagesofar -} -\catcode `\@=\other - - -\message{sectioning,} -% Define chapters, sections, etc. - -\newcount \chapno -\newcount \secno \secno=0 -\newcount \subsecno \subsecno=0 -\newcount \subsubsecno \subsubsecno=0 - -% This counter is funny since it counts through charcodes of letters A, B, ... -\newcount \appendixno \appendixno = `\@ -\def\appendixletter{\char\the\appendixno} - -\newwrite \contentsfile -% This is called from \setfilename. -\def\opencontents{\openout \contentsfile = \jobname.toc} - -% Each @chapter defines this as the name of the chapter. -% page headings and footings can use it. @section does likewise - -\def\thischapter{} \def\thissection{} -\def\seccheck#1{\if \pageno<0 % -\errmessage{@#1 not allowed after generating table of contents}\fi -% -} - -\def\chapternofonts{% -\let\rawbackslash=\relax% -\let\frenchspacing=\relax% -\def\result{\realbackslash result} -\def\equiv{\realbackslash equiv} -\def\expansion{\realbackslash expansion} -\def\print{\realbackslash print} -\def\TeX{\realbackslash TeX} -\def\dots{\realbackslash dots} -\def\copyright{\realbackslash copyright} -\def\tt{\realbackslash tt} -\def\bf{\realbackslash bf } -\def\w{\realbackslash w} -\def\less{\realbackslash less} -\def\gtr{\realbackslash gtr} -\def\hat{\realbackslash hat} -\def\char{\realbackslash char} -\def\tclose##1{\realbackslash tclose {##1}} -\def\code##1{\realbackslash code {##1}} -\def\samp##1{\realbackslash samp {##1}} -\def\r##1{\realbackslash r {##1}} -\def\b##1{\realbackslash b {##1}} -\def\key##1{\realbackslash key {##1}} -\def\file##1{\realbackslash file {##1}} -\def\kbd##1{\realbackslash kbd {##1}} -% These are redefined because @smartitalic wouldn't work inside xdef. -\def\i##1{\realbackslash i {##1}} -\def\cite##1{\realbackslash cite {##1}} -\def\var##1{\realbackslash var {##1}} -\def\emph##1{\realbackslash emph {##1}} -\def\dfn##1{\realbackslash dfn {##1}} -} - -\newcount\absseclevel % used to calculate proper heading level -\newcount\secbase\secbase=0 % @raise/lowersections modify this count - -% @raisesections: treat @section as chapter, @subsection as section, etc. -\def\raisesections{\global\advance\secbase by -1} -\let\up=\raisesections % original BFox name - -% @lowersections: treat @chapter as section, @section as subsection, etc. -\def\lowersections{\global\advance\secbase by 1} -\let\down=\lowersections % original BFox name - -% Choose a numbered-heading macro -% #1 is heading level if unmodified by @raisesections or @lowersections -% #2 is text for heading -\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 -\ifcase\absseclevel - \chapterzzz{#2} -\or - \seczzz{#2} -\or - \numberedsubseczzz{#2} -\or - \numberedsubsubseczzz{#2} -\else - \ifnum \absseclevel<0 - \chapterzzz{#2} - \else - \numberedsubsubseczzz{#2} - \fi -\fi -} - -% like \numhead, but chooses appendix heading levels -\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 -\ifcase\absseclevel - \appendixzzz{#2} -\or - \appendixsectionzzz{#2} -\or - \appendixsubseczzz{#2} -\or - \appendixsubsubseczzz{#2} -\else - \ifnum \absseclevel<0 - \appendixzzz{#2} - \else - \appendixsubsubseczzz{#2} - \fi -\fi -} - -% like \numhead, but chooses numberless heading levels -\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 -\ifcase\absseclevel - \unnumberedzzz{#2} -\or - \unnumberedseczzz{#2} -\or - \unnumberedsubseczzz{#2} -\or - \unnumberedsubsubseczzz{#2} -\else - \ifnum \absseclevel<0 - \unnumberedzzz{#2} - \else - \unnumberedsubsubseczzz{#2} - \fi -\fi -} - - -\def\thischaptername{No Chapter Title} -\outer\def\chapter{\parsearg\chapteryyy} -\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz -\def\chapterzzz #1{\seccheck{chapter}% -\secno=0 \subsecno=0 \subsubsecno=0 -\global\advance \chapno by 1 \message{\putwordChapter \the\chapno}% -\chapmacro {#1}{\the\chapno}% -\gdef\thissection{#1}% -\gdef\thischaptername{#1}% -% We don't substitute the actual chapter name into \thischapter -% because we don't want its macros evaluated now. -\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% -{\chapternofonts% -\edef\temp{{\realbackslash chapentry {#1}{\the\chapno}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\donoderef % -\global\let\section = \numberedsec -\global\let\subsection = \numberedsubsec -\global\let\subsubsection = \numberedsubsubsec -}} - -\outer\def\appendix{\parsearg\appendixyyy} -\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz -\def\appendixzzz #1{\seccheck{appendix}% -\secno=0 \subsecno=0 \subsubsecno=0 -\global\advance \appendixno by 1 \message{Appendix \appendixletter}% -\chapmacro {#1}{\putwordAppendix{} \appendixletter}% -\gdef\thissection{#1}% -\gdef\thischaptername{#1}% -\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% -{\chapternofonts% -\edef\temp{{\realbackslash chapentry - {#1}{\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\appendixnoderef % -\global\let\section = \appendixsec -\global\let\subsection = \appendixsubsec -\global\let\subsubsection = \appendixsubsubsec -}} - -% @centerchap is like @unnumbered, but the heading is centered. -\outer\def\centerchap{\parsearg\centerchapyyy} -\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}} - -\outer\def\top{\parsearg\unnumberedyyy} -\outer\def\unnumbered{\parsearg\unnumberedyyy} -\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz -\def\unnumberedzzz #1{\seccheck{unnumbered}% -\secno=0 \subsecno=0 \subsubsecno=0 -% -% This used to be simply \message{#1}, but TeX fully expands the -% argument to \message. Therefore, if #1 contained @-commands, TeX -% expanded them. For example, in `@unnumbered The @cite{Book}', TeX -% expanded @cite (which turns out to cause errors because \cite is meant -% to be executed, not expanded). -% -% Anyway, we don't want the fully-expanded definition of @cite to appear -% as a result of the \message, we just want `@cite' itself. We use -% \the<toks register> to achieve this: TeX expands \the<toks> only once, -% simply yielding the contents of the <toks register>. -\toks0 = {#1}\message{(\the\toks0)}% -% -\unnumbchapmacro {#1}% -\gdef\thischapter{#1}\gdef\thissection{#1}% -{\chapternofonts% -\edef\temp{{\realbackslash unnumbchapentry {#1}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\unnumbnoderef % -\global\let\section = \unnumberedsec -\global\let\subsection = \unnumberedsubsec -\global\let\subsubsection = \unnumberedsubsubsec -}} - -\outer\def\numberedsec{\parsearg\secyyy} -\def\secyyy #1{\numhead1{#1}} % normally calls seczzz -\def\seczzz #1{\seccheck{section}% -\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % -\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% -{\chapternofonts% -\edef\temp{{\realbackslash secentry % -{#1}{\the\chapno}{\the\secno}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\donoderef % -\penalty 10000 % -}} - -\outer\def\appendixsection{\parsearg\appendixsecyyy} -\outer\def\appendixsec{\parsearg\appendixsecyyy} -\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz -\def\appendixsectionzzz #1{\seccheck{appendixsection}% -\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % -\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% -{\chapternofonts% -\edef\temp{{\realbackslash secentry % -{#1}{\appendixletter}{\the\secno}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\appendixnoderef % -\penalty 10000 % -}} - -\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} -\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz -\def\unnumberedseczzz #1{\seccheck{unnumberedsec}% -\plainsecheading {#1}\gdef\thissection{#1}% -{\chapternofonts% -\edef\temp{{\realbackslash unnumbsecentry{#1}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\unnumbnoderef % -\penalty 10000 % -}} - -\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} -\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz -\def\numberedsubseczzz #1{\seccheck{subsection}% -\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % -\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% -{\chapternofonts% -\edef\temp{{\realbackslash subsecentry % -{#1}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\donoderef % -\penalty 10000 % -}} - -\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} -\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz -\def\appendixsubseczzz #1{\seccheck{appendixsubsec}% -\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % -\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% -{\chapternofonts% -\edef\temp{{\realbackslash subsecentry % -{#1}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\appendixnoderef % -\penalty 10000 % -}} - -\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} -\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz -\def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% -\plainsubsecheading {#1}\gdef\thissection{#1}% -{\chapternofonts% -\edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\unnumbnoderef % -\penalty 10000 % -}} - -\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} -\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz -\def\numberedsubsubseczzz #1{\seccheck{subsubsection}% -\gdef\thissection{#1}\global\advance \subsubsecno by 1 % -\subsubsecheading {#1} - {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% -{\chapternofonts% -\edef\temp{{\realbackslash subsubsecentry % - {#1} - {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} - {\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\donoderef % -\penalty 10000 % -}} - -\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} -\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz -\def\appendixsubsubseczzz #1{\seccheck{appendixsubsubsec}% -\gdef\thissection{#1}\global\advance \subsubsecno by 1 % -\subsubsecheading {#1} - {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% -{\chapternofonts% -\edef\temp{{\realbackslash subsubsecentry{#1}% - {\appendixletter} - {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\appendixnoderef % -\penalty 10000 % -}} - -\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} -\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz -\def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% -\plainsubsubsecheading {#1}\gdef\thissection{#1}% -{\chapternofonts% -\edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% -\escapechar=`\\% -\write \contentsfile \temp % -\unnumbnoderef % -\penalty 10000 % -}} - -% These are variants which are not "outer", so they can appear in @ifinfo. -% Actually, they should now be obsolete; ordinary section commands should work. -\def\infotop{\parsearg\unnumberedzzz} -\def\infounnumbered{\parsearg\unnumberedzzz} -\def\infounnumberedsec{\parsearg\unnumberedseczzz} -\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz} -\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz} - -\def\infoappendix{\parsearg\appendixzzz} -\def\infoappendixsec{\parsearg\appendixseczzz} -\def\infoappendixsubsec{\parsearg\appendixsubseczzz} -\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz} - -\def\infochapter{\parsearg\chapterzzz} -\def\infosection{\parsearg\sectionzzz} -\def\infosubsection{\parsearg\subsectionzzz} -\def\infosubsubsection{\parsearg\subsubsectionzzz} - -% These macros control what the section commands do, according -% to what kind of chapter we are in (ordinary, appendix, or unnumbered). -% Define them by default for a numbered chapter. -\global\let\section = \numberedsec -\global\let\subsection = \numberedsubsec -\global\let\subsubsection = \numberedsubsubsec - -% Define @majorheading, @heading and @subheading - -% NOTE on use of \vbox for chapter headings, section headings, and -% such: -% 1) We use \vbox rather than the earlier \line to permit -% overlong headings to fold. -% 2) \hyphenpenalty is set to 10000 because hyphenation in a -% heading is obnoxious; this forbids it. -% 3) Likewise, headings look best if no \parindent is used, and -% if justification is not attempted. Hence \raggedright. - - -\def\majorheading{\parsearg\majorheadingzzz} -\def\majorheadingzzz #1{% -{\advance\chapheadingskip by 10pt \chapbreak }% -{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 200} - -\def\chapheading{\parsearg\chapheadingzzz} -\def\chapheadingzzz #1{\chapbreak % -{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 200} - -% @heading, @subheading, @subsubheading. -\def\heading{\parsearg\plainsecheading} -\def\subheading{\parsearg\plainsubsecheading} -\def\subsubheading{\parsearg\plainsubsubsecheading} - -% These macros generate a chapter, section, etc. heading only -% (including whitespace, linebreaking, etc. around it), -% given all the information in convenient, parsed form. - -%%% Args are the skip and penalty (usually negative) -\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} - -\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} - -%%% Define plain chapter starts, and page on/off switching for it -% Parameter controlling skip before chapter headings (if needed) - -\newskip\chapheadingskip - -\def\chapbreak{\dobreak \chapheadingskip {-4000}} -\def\chappager{\par\vfill\supereject} -\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} - -\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} - -\def\CHAPPAGoff{ -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chapbreak -\global\let\pagealignmacro=\chappager} - -\def\CHAPPAGon{ -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chappager -\global\let\pagealignmacro=\chappager -\global\def\HEADINGSon{\HEADINGSsingle}} - -\def\CHAPPAGodd{ -\global\let\contentsalignmacro = \chapoddpage -\global\let\pchapsepmacro=\chapoddpage -\global\let\pagealignmacro=\chapoddpage -\global\def\HEADINGSon{\HEADINGSdouble}} - -\CHAPPAGon - -\def\CHAPFplain{ -\global\let\chapmacro=\chfplain -\global\let\unnumbchapmacro=\unnchfplain -\global\let\centerchapmacro=\centerchfplain} - -% Plain chapter opening. -% #1 is the text, #2 the chapter number or empty if unnumbered. -\def\chfplain#1#2{% - \pchapsepmacro - {% - \chapfonts \rm - \def\chapnum{#2}% - \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}% - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent = \wd0 \centerparametersmaybe - \unhbox0 #1\par}% - }% - \nobreak\bigskip % no page break after a chapter title - \nobreak -} - -% Plain opening for unnumbered. -\def\unnchfplain#1{\chfplain{#1}{}} - -% @centerchap -- centered and unnumbered. -\let\centerparametersmaybe = \relax -\def\centerchfplain#1{{% - \def\centerparametersmaybe{% - \advance\rightskip by 3\rightskip - \leftskip = \rightskip - \parfillskip = 0pt - }% - \chfplain{#1}{}% -}} - -\CHAPFplain % The default - -\def\unnchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 10000 % -} - -\def\chfopen #1#2{\chapoddpage {\chapfonts -\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% -\par\penalty 5000 % -} - -\def\centerchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt - \hfill {\rm #1}\hfill}}\bigskip \par\penalty 10000 % -} - -\def\CHAPFopen{ -\global\let\chapmacro=\chfopen -\global\let\unnumbchapmacro=\unnchfopen -\global\let\centerchapmacro=\centerchfopen} - - -% Section titles. -\newskip\secheadingskip -\def\secheadingbreak{\dobreak \secheadingskip {-1000}} -\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}} -\def\plainsecheading#1{\sectionheading{sec}{}{#1}} - -% Subsection titles. -\newskip \subsecheadingskip -\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} -\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}} -\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}} - -% Subsubsection titles. -\let\subsubsecheadingskip = \subsecheadingskip -\let\subsubsecheadingbreak = \subsecheadingbreak -\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}} -\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}} - - -% Print any size section title. -% -% #1 is the section type (sec/subsec/subsubsec), #2 is the section -% number (maybe empty), #3 the text. -\def\sectionheading#1#2#3{% - {% - \expandafter\advance\csname #1headingskip\endcsname by \parskip - \csname #1headingbreak\endcsname - }% - {% - % Switch to the right set of fonts. - \csname #1fonts\endcsname \rm - % - % Only insert the separating space if we have a section number. - \def\secnum{#2}% - \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}% - % - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent = \wd0 % zero if no section number - \unhbox0 #3}% - }% - \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak -} - - -\message{toc printing,} -% Finish up the main text and prepare to read what we've written -% to \contentsfile. - -\newskip\contentsrightmargin \contentsrightmargin=1in -\def\startcontents#1{% - % If @setchapternewpage on, and @headings double, the contents should - % start on an odd page, unlike chapters. Thus, we maintain - % \contentsalignmacro in parallel with \pagealignmacro. - % From: Torbjorn Granlund <tege@matematik.su.se> - \contentsalignmacro - \immediate\closeout \contentsfile - \ifnum \pageno>0 - \pageno = -1 % Request roman numbered pages. - \fi - % Don't need to put `Contents' or `Short Contents' in the headline. - % It is abundantly clear what they are. - \unnumbchapmacro{#1}\def\thischapter{}% - \begingroup % Set up to handle contents files properly. - \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 - \catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi - \raggedbottom % Worry more about breakpoints than the bottom. - \advance\hsize by -\contentsrightmargin % Don't use the full line length. -} - - -% Normal (long) toc. -\outer\def\contents{% - \startcontents{\putwordTableofContents}% - \input \jobname.toc - \endgroup - \vfill \eject -} - -% And just the chapters. -\outer\def\summarycontents{% - \startcontents{\putwordShortContents}% - % - \let\chapentry = \shortchapentry - \let\unnumbchapentry = \shortunnumberedentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl - \rm - \hyphenpenalty = 10000 - \advance\baselineskip by 1pt % Open it up a little. - \def\secentry ##1##2##3##4{} - \def\unnumbsecentry ##1##2{} - \def\subsecentry ##1##2##3##4##5{} - \def\unnumbsubsecentry ##1##2{} - \def\subsubsecentry ##1##2##3##4##5##6{} - \def\unnumbsubsubsecentry ##1##2{} - \input \jobname.toc - \endgroup - \vfill \eject -} -\let\shortcontents = \summarycontents - -% These macros generate individual entries in the table of contents. -% The first argument is the chapter or section name. -% The last argument is the page number. -% The arguments in between are the chapter number, section number, ... - -% Chapter-level things, for both the long and short contents. -\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} - -% See comments in \dochapentry re vbox and related settings -\def\shortchapentry#1#2#3{% - \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno{#3}}% -} - -% Typeset the label for a chapter or appendix for the short contents. -% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter. -% We could simplify the code here by writing out an \appendixentry -% command in the toc file for appendices, instead of using \chapentry -% for both, but it doesn't seem worth it. -\setbox0 = \hbox{\shortcontrm \putwordAppendix } -\newdimen\shortappendixwidth \shortappendixwidth = \wd0 - -\def\shortchaplabel#1{% - % We typeset #1 in a box of constant width, regardless of the text of - % #1, so the chapter titles will come out aligned. - \setbox0 = \hbox{#1}% - \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi - % - % This space should be plenty, since a single number is .5em, and the - % widest letter (M) is 1em, at least in the Computer Modern fonts. - % (This space doesn't include the extra space that gets added after - % the label; that gets put in by \shortchapentry above.) - \advance\dimen0 by 1.1em - \hbox to \dimen0{#1\hfil}% -} - -\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} -\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno{#2}}} - -% Sections. -\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} -\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} - -% Subsections. -\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} -\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} - -% And subsubsections. -\def\subsubsecentry#1#2#3#4#5#6{% - \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} -\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} - -% This parameter controls the indentation of the various levels. -\newdimen\tocindent \tocindent = 3pc - -% Now for the actual typesetting. In all these, #1 is the text and #2 is the -% page number. -% -% If the toc has to be broken over pages, we want it to be at chapters -% if at all possible; hence the \penalty. -\def\dochapentry#1#2{% - \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip - \begingroup - \chapentryfonts - \tocentry{#1}{\dopageno{#2}}% - \endgroup - \nobreak\vskip .25\baselineskip plus.1\baselineskip -} - -\def\dosecentry#1#2{\begingroup - \secentryfonts \leftskip=\tocindent - \tocentry{#1}{\dopageno{#2}}% -\endgroup} - -\def\dosubsecentry#1#2{\begingroup - \subsecentryfonts \leftskip=2\tocindent - \tocentry{#1}{\dopageno{#2}}% -\endgroup} - -\def\dosubsubsecentry#1#2{\begingroup - \subsubsecentryfonts \leftskip=3\tocindent - \tocentry{#1}{\dopageno{#2}}% -\endgroup} - -% Final typesetting of a toc entry; we use the same \entry macro as for -% the index entries, but we want to suppress hyphenation here. (We -% can't do that in the \entry macro, since index entries might consist -% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) -% -% \turnoffactive is for the sake of @" used for umlauts. -\def\tocentry#1#2{\begingroup - \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks - \entry{\turnoffactive #1}{\turnoffactive #2}% -\endgroup} - -% Space between chapter (or whatever) number and the title. -\def\labelspace{\hskip1em \relax} - -\def\dopageno#1{{\rm #1}} -\def\doshortpageno#1{{\rm #1}} - -\def\chapentryfonts{\secfonts \rm} -\def\secentryfonts{\textfonts} -\let\subsecentryfonts = \textfonts -\let\subsubsecentryfonts = \textfonts - - -\message{environments,} - -% Since these characters are used in examples, it should be an even number of -% \tt widths. Each \tt character is 1en, so two makes it 1em. -% Furthermore, these definitions must come after we define our fonts. -\newbox\dblarrowbox \newbox\longdblarrowbox -\newbox\pushcharbox \newbox\bullbox -\newbox\equivbox \newbox\errorbox - -%{\tentt -%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} -%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} -%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} -%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} -% Adapted from the manmac format (p.420 of TeXbook) -%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex -% depth .1ex\hfil} -%} - -% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. -\def\point{$\star$} -\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} -\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} -\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} -\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} - -% Adapted from the TeXbook's \boxit. -{\tentt \global\dimen0 = 3em}% Width of the box. -\dimen2 = .55pt % Thickness of rules -% The text. (`r' is open on the right, `e' somewhat less so on the left.) -\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} - -\global\setbox\errorbox=\hbox to \dimen0{\hfil - \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. - \advance\hsize by -2\dimen2 % Rules. - \vbox{ - \hrule height\dimen2 - \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. - \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. - \kern3pt\vrule width\dimen2}% Space to right. - \hrule height\dimen2} - \hfil} - -% The @error{} command. -\def\error{\leavevmode\lower.7ex\copy\errorbox} - -% @tex ... @end tex escapes into raw Tex temporarily. -% One exception: @ is still an escape character, so that @end tex works. -% But \@ or @@ will get a plain tex @ character. - -\def\tex{\begingroup -\catcode `\\=0 \catcode `\{=1 \catcode `\}=2 -\catcode `\$=3 \catcode `\&=4 \catcode `\#=6 -\catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie -\catcode `\%=14 -\catcode 43=12 % plus -\catcode`\"=12 -\catcode`\==12 -\catcode`\|=12 -\catcode`\<=12 -\catcode`\>=12 -\escapechar=`\\ -% -\let\,=\ptexcomma -\let\~=\ptextilde -\let\{=\ptexlbrace -\let\}=\ptexrbrace -\let\.=\ptexdot -\let\*=\ptexstar -\let\dots=\ptexdots -\def\endldots{\mathinner{\ldots\ldots\ldots\ldots}} -\def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi} -\def\@{@}% -\let\bullet=\ptexbullet -\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext -% -\let\Etex=\endgroup} - -% Define @lisp ... @endlisp. -% @lisp does a \begingroup so it can rebind things, -% including the definition of @endlisp (which normally is erroneous). - -% Amount to narrow the margins by for @lisp. -\newskip\lispnarrowing \lispnarrowing=0.4in - -% This is the definition that ^^M gets inside @lisp, @example, and other -% such environments. \null is better than a space, since it doesn't -% have any width. -\def\lisppar{\null\endgraf} - -% Make each space character in the input produce a normal interword -% space in the output. Don't allow a line break at this space, as this -% is used only in environments like @example, where each line of input -% should produce a line of output anyway. -% -{\obeyspaces % -\gdef\sepspaces{\obeyspaces\let =\tie}} - -% Define \obeyedspace to be our active space, whatever it is. This is -% for use in \parsearg. -{\sepspaces% -\global\let\obeyedspace= } - -% This space is always present above and below environments. -\newskip\envskipamount \envskipamount = 0pt - -% Make spacing and below environment symmetrical. We use \parskip here -% to help in doing that, since in @example-like environments \parskip -% is reset to zero; thus the \afterenvbreak inserts no space -- but the -% start of the next paragraph will insert \parskip -% -\def\aboveenvbreak{{\advance\envskipamount by \parskip -\endgraf \ifdim\lastskip<\envskipamount -\removelastskip \penalty-50 \vskip\envskipamount \fi}} - -\let\afterenvbreak = \aboveenvbreak - -% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. -\let\nonarrowing=\relax - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% \cartouche: draw rectangle w/rounded corners around argument -\font\circle=lcircle10 -\newdimen\circthick -\newdimen\cartouter\newdimen\cartinner -\newskip\normbskip\newskip\normpskip\newskip\normlskip -\circthick=\fontdimen8\circle -% -\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth -\def\ctr{{\hskip 6pt\circle\char'010}} -\def\cbl{{\circle\char'012\hskip -6pt}} -\def\cbr{{\hskip 6pt\circle\char'011}} -\def\carttop{\hbox to \cartouter{\hskip\lskip - \ctl\leaders\hrule height\circthick\hfil\ctr - \hskip\rskip}} -\def\cartbot{\hbox to \cartouter{\hskip\lskip - \cbl\leaders\hrule height\circthick\hfil\cbr - \hskip\rskip}} -% -\newskip\lskip\newskip\rskip - -\long\def\cartouche{% -\begingroup - \lskip=\leftskip \rskip=\rightskip - \leftskip=0pt\rightskip=0pt %we want these *outside*. - \cartinner=\hsize \advance\cartinner by-\lskip - \advance\cartinner by-\rskip - \cartouter=\hsize - \advance\cartouter by 18pt % allow for 3pt kerns on either -% side, and for 6pt waste from -% each corner char - \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing=\comment - \vbox\bgroup - \baselineskip=0pt\parskip=0pt\lineskip=0pt - \carttop - \hbox\bgroup - \hskip\lskip - \vrule\kern3pt - \vbox\bgroup - \hsize=\cartinner - \kern3pt - \begingroup - \baselineskip=\normbskip - \lineskip=\normlskip - \parskip=\normpskip - \vskip -\parskip -\def\Ecartouche{% - \endgroup - \kern3pt - \egroup - \kern3pt\vrule - \hskip\rskip - \egroup - \cartbot - \egroup -\endgroup -}} - - -% This macro is called at the beginning of all the @example variants, -% inside a group. -\def\nonfillstart{% - \aboveenvbreak - \inENV % This group ends at the end of the body - \hfuzz = 12pt % Don't be fussy - \sepspaces % Make spaces be word-separators rather than space tokens. - \singlespace - \let\par = \lisppar % don't ignore blank lines - \obeylines % each line of input is a line of output - \parskip = 0pt - \parindent = 0pt - \emergencystretch = 0pt % don't try to avoid overfull boxes - % @cartouche defines \nonarrowing to inhibit narrowing - % at next level down. - \ifx\nonarrowing\relax - \advance \leftskip by \lispnarrowing - \exdentamount=\lispnarrowing - \let\exdent=\nofillexdent - \let\nonarrowing=\relax - \fi -} - -% To ending an @example-like environment, we first end the paragraph -% (via \afterenvbreak's vertical glue), and then the group. That way we -% keep the zero \parskip that the environments set -- \parskip glue -% will be inserted at the beginning of the next paragraph in the -% document, after the environment. -% -\def\nonfillfinish{\afterenvbreak\endgroup}% - -% This macro is -\def\lisp{\begingroup - \nonfillstart - \let\Elisp = \nonfillfinish - \tt - \rawbackslash % have \ input char produce \ char from current font - \gobble -} - -% Define the \E... control sequence only if we are inside the -% environment, so the error checking in \end will work. -% -% We must call \lisp last in the definition, since it reads the -% return following the @example (or whatever) command. -% -\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} -\def\smallexample{\begingroup \def\Esmallexample{\nonfillfinish\endgroup}\lisp} -\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}\lisp} - -% @smallexample and @smalllisp. This is not used unless the @smallbook -% command is given. Originally contributed by Pavel@xerox. -% -\def\smalllispx{\begingroup - \nonfillstart - \let\Esmalllisp = \nonfillfinish - \let\Esmallexample = \nonfillfinish - % - % Smaller fonts for small examples. - \indexfonts \tt - \rawbackslash % make \ output the \ character from the current font (tt) - \gobble -} - -% This is @display; same as @lisp except use roman font. -% -\def\display{\begingroup - \nonfillstart - \let\Edisplay = \nonfillfinish - \gobble -} - -% This is @format; same as @display except don't narrow margins. -% -\def\format{\begingroup - \let\nonarrowing = t - \nonfillstart - \let\Eformat = \nonfillfinish - \gobble -} - -% @flushleft (same as @format) and @flushright. -% -\def\flushleft{\begingroup - \let\nonarrowing = t - \nonfillstart - \let\Eflushleft = \nonfillfinish - \gobble -} -\def\flushright{\begingroup - \let\nonarrowing = t - \nonfillstart - \let\Eflushright = \nonfillfinish - \advance\leftskip by 0pt plus 1fill - \gobble} - -% @quotation does normal linebreaking (hence we can't use \nonfillstart) -% and narrows the margins. -% -\def\quotation{% - \begingroup\inENV %This group ends at the end of the @quotation body - {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \singlespace - \parindent=0pt - % We have retained a nonzero parskip for the environment, since we're - % doing normal filling. So to avoid extra space below the environment... - \def\Equotation{\parskip = 0pt \nonfillfinish}% - % - % @cartouche defines \nonarrowing to inhibit narrowing at next level down. - \ifx\nonarrowing\relax - \advance\leftskip by \lispnarrowing - \advance\rightskip by \lispnarrowing - \exdentamount = \lispnarrowing - \let\nonarrowing = \relax - \fi -} - -\message{defuns,} -% Define formatter for defuns -% First, allow user to change definition object font (\df) internally -\def\setdeffont #1 {\csname DEF#1\endcsname} - -\newskip\defbodyindent \defbodyindent=.4in -\newskip\defargsindent \defargsindent=50pt -\newskip\deftypemargin \deftypemargin=12pt -\newskip\deflastargmargin \deflastargmargin=18pt - -\newcount\parencount -% define \functionparens, which makes ( and ) and & do special things. -% \functionparens affects the group it is contained in. -\def\activeparens{% -\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active -\catcode`\[=\active \catcode`\]=\active} - -% Make control sequences which act like normal parenthesis chars. -\let\lparen = ( \let\rparen = ) - -{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) - -% Be sure that we always have a definition for `(', etc. For example, -% if the fn name has parens in it, \boldbrax will not be in effect yet, -% so TeX would otherwise complain about undefined control sequence. -\global\let(=\lparen \global\let)=\rparen -\global\let[=\lbrack \global\let]=\rbrack - -\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } -\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} -% This is used to turn on special parens -% but make & act ordinary (given that it's active). -\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr} - -% Definitions of (, ) and & used in args for functions. -% This is the definition of ( outside of all parentheses. -\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested % -\global\advance\parencount by 1 } -% -% This is the definition of ( when already inside a level of parens. -\gdef\opnested{\char`\(\global\advance\parencount by 1 } -% -\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. -% also in that case restore the outer-level definition of (. -\ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi -\global\advance \parencount by -1 } -% If we encounter &foo, then turn on ()-hacking afterwards -\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } -% -\gdef\normalparens{\boldbrax\let&=\ampnr} -} % End of definition inside \activeparens -%% These parens (in \boldbrax) actually are a little bolder than the -%% contained text. This is especially needed for [ and ] -\def\opnr{{\sf\char`\(}} \def\clnr{{\sf\char`\)}} \def\ampnr{\&} -\def\lbrb{{\bf\char`\[}} \def\rbrb{{\bf\char`\]}} - -% First, defname, which formats the header line itself. -% #1 should be the function name. -% #2 should be the type of definition, such as "Function". - -\def\defname #1#2{% -% Get the values of \leftskip and \rightskip as they were -% outside the @def... -\dimen2=\leftskip -\advance\dimen2 by -\defbodyindent -\dimen3=\rightskip -\advance\dimen3 by -\defbodyindent -\noindent % -\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% -\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line -\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations -\parshape 2 0in \dimen0 \defargsindent \dimen1 % -% Now output arg 2 ("Function" or some such) -% ending at \deftypemargin from the right margin, -% but stuck inside a box of width 0 so it does not interfere with linebreaking -{% Adjust \hsize to exclude the ambient margins, -% so that \rightline will obey them. -\advance \hsize by -\dimen2 \advance \hsize by -\dimen3 -\rlap{\rightline{{\rm #2}\hskip \deftypemargin}}}% -% Make all lines underfull and no complaints: -\tolerance=10000 \hbadness=10000 -\advance\leftskip by -\defbodyindent -\exdentamount=\defbodyindent -{\df #1}\enskip % Generate function name -} - -% Actually process the body of a definition -% #1 should be the terminating control sequence, such as \Edefun. -% #2 should be the "another name" control sequence, such as \defunx. -% #3 should be the control sequence that actually processes the header, -% such as \defunheader. - -\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% -\parindent=0in -\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup % -\catcode 61=\active % 61 is `=' -\obeylines\activeparens\spacesplit#3} - -\def\defmethparsebody #1#2#3#4 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% -\parindent=0in -\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} - -\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 ##2 {\def#4{##1}% -\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% -\parindent=0in -\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} - -% These parsing functions are similar to the preceding ones -% except that they do not make parens into active characters. -% These are used for "variables" since they have no arguments. - -\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2{\begingroup\obeylines\spacesplit#3}% -\parindent=0in -\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup % -\catcode 61=\active % -\obeylines\spacesplit#3} - -% This is used for \def{tp,vr}parsebody. It could probably be used for -% some of the others, too, with some judicious conditionals. -% -\def\parsebodycommon#1#2#3{% - \begingroup\inENV % - \medbreak % - % Define the end token that this defining construct specifies - % so that it will exit this group. - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% - \parindent=0in - \advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent - \exdentamount=\defbodyindent - \begingroup\obeylines -} - -\def\defvrparsebody#1#2#3#4 {% - \parsebodycommon{#1}{#2}{#3}% - \spacesplit{#3{#4}}% -} - -% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the -% type is just `struct', because we lose the braces in `{struct -% termios}' when \spacesplit reads its undelimited argument. Sigh. -% \let\deftpparsebody=\defvrparsebody -% -% So, to get around this, we put \empty in with the type name. That -% way, TeX won't find exactly `{...}' as an undelimited argument, and -% won't strip off the braces. -% -\def\deftpparsebody #1#2#3#4 {% - \parsebodycommon{#1}{#2}{#3}% - \spacesplit{\parsetpheaderline{#3{#4}}}\empty -} - -% Fine, but then we have to eventually remove the \empty *and* the -% braces (if any). That's what this does, putting the result in \tptemp. -% -\def\removeemptybraces\empty#1\relax{\def\tptemp{#1}}% - -% After \spacesplit has done its work, this is called -- #1 is the final -% thing to call, #2 the type name (which starts with \empty), and #3 -% (which might be empty) the arguments. -% -\def\parsetpheaderline#1#2#3{% - \removeemptybraces#2\relax - #1{\tptemp}{#3}% -}% - -\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 ##2 {\def#4{##1}% -\begingroup\obeylines\spacesplit{#3{##2}}}% -\parindent=0in -\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\spacesplit{#3{#5}}} - -% Split up #2 at the first space token. -% call #1 with two arguments: -% the first is all of #2 before the space token, -% the second is all of #2 after that space token. -% If #2 contains no space token, all of it is passed as the first arg -% and the second is passed as empty. - -{\obeylines -\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% -\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% -\ifx\relax #3% -#1{#2}{}\else #1{#2}{#3#4}\fi}} - -% So much for the things common to all kinds of definitions. - -% Define @defun. - -% First, define the processing that is wanted for arguments of \defun -% Use this to expand the args and terminate the paragraph they make up - -\def\defunargs #1{\functionparens \sl -% Expand, preventing hyphenation at `-' chars. -% Note that groups don't affect changes in \hyphenchar. -\hyphenchar\tensl=0 -#1% -\hyphenchar\tensl=45 -\ifnum\parencount=0 \else \errmessage{unbalanced parens in @def arguments}\fi% -\interlinepenalty=10000 -\advance\rightskip by 0pt plus 1fil -\endgraf\penalty 10000\vskip -\parskip\penalty 10000% -} - -\def\deftypefunargs #1{% -% Expand, preventing hyphenation at `-' chars. -% Note that groups don't affect changes in \hyphenchar. -% Use \boldbraxnoamp, not \functionparens, so that & is not special. -\boldbraxnoamp -\tclose{#1}% avoid \code because of side effects on active chars -\interlinepenalty=10000 -\advance\rightskip by 0pt plus 1fil -\endgraf\penalty 10000\vskip -\parskip\penalty 10000% -} - -% Do complete processing of one @defun or @defunx line already parsed. - -% @deffn Command forward-char nchars - -\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} - -\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% -\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody -} - -% @defun == @deffn Function - -\def\defun{\defparsebody\Edefun\defunx\defunheader} - -\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index -\begingroup\defname {#1}{Function}% -\defunargs {#2}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody -} - -% @deftypefun int foobar (int @var{foo}, float @var{bar}) - -\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} - -% #1 is the data type. #2 is the name and args. -\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} -% #1 is the data type, #2 the name, #3 the args. -\def\deftypefunheaderx #1#2 #3\relax{% -\doind {fn}{\code{#2}}% Make entry in function index -\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Function}% -\deftypefunargs {#3}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody -} - -% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) - -\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} - -% \defheaderxcond#1\relax$$$ -% puts #1 in @code, followed by a space, but does nothing if #1 is null. -\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi} - -% #1 is the classification. #2 is the data type. #3 is the name and args. -\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} -% #1 is the classification, #2 the data type, #3 the name, #4 the args. -\def\deftypefnheaderx #1#2#3 #4\relax{% -\doind {fn}{\code{#3}}% Make entry in function index -\begingroup -\normalparens % notably, turn off `&' magic, which prevents -% at least some C++ text from working -\defname {\defheaderxcond#2\relax$$$#3}{#1}% -\deftypefunargs {#4}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody -} - -% @defmac == @deffn Macro - -\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} - -\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index -\begingroup\defname {#1}{Macro}% -\defunargs {#2}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody -} - -% @defspec == @deffn Special Form - -\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} - -\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index -\begingroup\defname {#1}{Special Form}% -\defunargs {#2}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody -} - -% This definition is run if you use @defunx -% anywhere other than immediately after a @defun or @defunx. - -\def\deffnx #1 {\errmessage{@deffnx in invalid context}} -\def\defunx #1 {\errmessage{@defunx in invalid context}} -\def\defmacx #1 {\errmessage{@defmacx in invalid context}} -\def\defspecx #1 {\errmessage{@defspecx in invalid context}} -\def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} -\def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} - -% @defmethod, and so on - -% @defop {Funny Method} foo-class frobnicate argument - -\def\defop #1 {\def\defoptype{#1}% -\defopparsebody\Edefop\defopx\defopheader\defoptype} - -\def\defopheader #1#2#3{% -\dosubind {fn}{\code{#2}}{on #1}% Make entry in function index -\begingroup\defname {#2}{\defoptype{} on #1}% -\defunargs {#3}\endgroup % -} - -% @defmethod == @defop Method - -\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} - -\def\defmethodheader #1#2#3{% -\dosubind {fn}{\code{#2}}{on #1}% entry in function index -\begingroup\defname {#2}{Method on #1}% -\defunargs {#3}\endgroup % -} - -% @defcv {Class Option} foo-class foo-flag - -\def\defcv #1 {\def\defcvtype{#1}% -\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} - -\def\defcvarheader #1#2#3{% -\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index -\begingroup\defname {#2}{\defcvtype{} of #1}% -\defvarargs {#3}\endgroup % -} - -% @defivar == @defcv {Instance Variable} - -\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} - -\def\defivarheader #1#2#3{% -\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index -\begingroup\defname {#2}{Instance Variable of #1}% -\defvarargs {#3}\endgroup % -} - -% These definitions are run if you use @defmethodx, etc., -% anywhere other than immediately after a @defmethod, etc. - -\def\defopx #1 {\errmessage{@defopx in invalid context}} -\def\defmethodx #1 {\errmessage{@defmethodx in invalid context}} -\def\defcvx #1 {\errmessage{@defcvx in invalid context}} -\def\defivarx #1 {\errmessage{@defivarx in invalid context}} - -% Now @defvar - -% First, define the processing that is wanted for arguments of @defvar. -% This is actually simple: just print them in roman. -% This must expand the args and terminate the paragraph they make up -\def\defvarargs #1{\normalparens #1% -\interlinepenalty=10000 -\endgraf\penalty 10000\vskip -\parskip\penalty 10000} - -% @defvr Counter foo-count - -\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} - -\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% -\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} - -% @defvar == @defvr Variable - -\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} - -\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index -\begingroup\defname {#1}{Variable}% -\defvarargs {#2}\endgroup % -} - -% @defopt == @defvr {User Option} - -\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} - -\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index -\begingroup\defname {#1}{User Option}% -\defvarargs {#2}\endgroup % -} - -% @deftypevar int foobar - -\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} - -% #1 is the data type. #2 is the name. -\def\deftypevarheader #1#2{% -\doind {vr}{\code{#2}}% Make entry in variables index -\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% -\interlinepenalty=10000 -\endgraf\penalty 10000\vskip -\parskip\penalty 10000 -\endgroup} - -% @deftypevr {Global Flag} int enable - -\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} - -\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% -\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} -\interlinepenalty=10000 -\endgraf\penalty 10000\vskip -\parskip\penalty 10000 -\endgroup} - -% This definition is run if you use @defvarx -% anywhere other than immediately after a @defvar or @defvarx. - -\def\defvrx #1 {\errmessage{@defvrx in invalid context}} -\def\defvarx #1 {\errmessage{@defvarx in invalid context}} -\def\defoptx #1 {\errmessage{@defoptx in invalid context}} -\def\deftypevarx #1 {\errmessage{@deftypevarx in invalid context}} -\def\deftypevrx #1 {\errmessage{@deftypevrx in invalid context}} - -% Now define @deftp -% Args are printed in bold, a slight difference from @defvar. - -\def\deftpargs #1{\bf \defvarargs{#1}} - -% @deftp Class window height width ... - -\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} - -\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% -\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} - -% This definition is run if you use @deftpx, etc -% anywhere other than immediately after a @deftp, etc. - -\def\deftpx #1 {\errmessage{@deftpx in invalid context}} - - -\message{cross reference,} -% Define cross-reference macros -\newwrite \auxfile - -\newif\ifhavexrefs % True if xref values are known. -\newif\ifwarnedxrefs % True if we warned once that they aren't known. - -% @inforef is simple. -\def\inforef #1{\inforefzzz #1,,,,**} -\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, - node \samp{\ignorespaces#1{}}} - -% \setref{foo} defines a cross-reference point named foo. - -\def\setref#1{% -\dosetq{#1-title}{Ytitle}% -\dosetq{#1-pg}{Ypagenumber}% -\dosetq{#1-snt}{Ysectionnumberandtype}} - -\def\unnumbsetref#1{% -\dosetq{#1-title}{Ytitle}% -\dosetq{#1-pg}{Ypagenumber}% -\dosetq{#1-snt}{Ynothing}} - -\def\appendixsetref#1{% -\dosetq{#1-title}{Ytitle}% -\dosetq{#1-pg}{Ypagenumber}% -\dosetq{#1-snt}{Yappendixletterandtype}} - -% \xref, \pxref, and \ref generate cross-references to specified points. -% For \xrefX, #1 is the node name, #2 the name of the Info -% cross-reference, #3 the printed node name, #4 the name of the Info -% file, #5 the name of the printed manual. All but the node name can be -% omitted. -% -\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} -\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} -\def\ref#1{\xrefX[#1,,,,,,,]} -\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup - \def\printedmanual{\ignorespaces #5}% - \def\printednodename{\ignorespaces #3}% - \setbox1=\hbox{\printedmanual}% - \setbox0=\hbox{\printednodename}% - \ifdim \wd0 = 0pt - % No printed node name was explicitly given. - \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax - % Use the node name inside the square brackets. - \def\printednodename{\ignorespaces #1}% - \else - % Use the actual chapter/section title appear inside - % the square brackets. Use the real section title if we have it. - \ifdim \wd1>0pt% - % It is in another manual, so we don't have it. - \def\printednodename{\ignorespaces #1}% - \else - \ifhavexrefs - % We know the real title if we have the xref values. - \def\printednodename{\refx{#1-title}{}}% - \else - % Otherwise just copy the Info node name. - \def\printednodename{\ignorespaces #1}% - \fi% - \fi - \fi - \fi - % - % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not - % insert empty discretionaries after hyphens, which means that it will - % not find a line break at a hyphen in a node names. Since some manuals - % are best written with fairly long node names, containing hyphens, this - % is a loss. Therefore, we give the text of the node name again, so it - % is as if TeX is seeing it for the first time. - \ifdim \wd1 > 0pt - \putwordsection{} ``\printednodename'' in \cite{\printedmanual}% - \else - % _ (for example) has to be the character _ for the purposes of the - % control sequence corresponding to the node, but it has to expand - % into the usual \leavevmode...\vrule stuff for purposes of - % printing. So we \turnoffactive for the \refx-snt, back on for the - % printing, back off for the \refx-pg. - {\turnoffactive \refx{#1-snt}{}}% - \space [\printednodename],\space - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% - \fi -\endgroup} - -% \dosetq is the interface for calls from other macros - -% Use \turnoffactive so that punctuation chars such as underscore -% work in node names. -\def\dosetq #1#2{{\let\folio=0 \turnoffactive \auxhat% -\edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% -\next}} - -% \internalsetq {foo}{page} expands into -% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} -% When the aux file is read, ' is the escape character - -\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} - -% Things to be expanded by \internalsetq - -\def\Ypagenumber{\folio} - -\def\Ytitle{\thissection} - -\def\Ynothing{} - -\def\Ysectionnumberandtype{% -\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % -\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % -\else \ifnum \subsubsecno=0 % -\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % -\else % -\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % -\fi \fi \fi } - -\def\Yappendixletterandtype{% -\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% -\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % -\else \ifnum \subsubsecno=0 % -\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % -\else % -\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % -\fi \fi \fi } - -\gdef\xreftie{'tie} - -% Use TeX 3.0's \inputlineno to get the line number, for better error -% messages, but if we're using an old version of TeX, don't do anything. -% -\ifx\inputlineno\thisisundefined - \let\linenumber = \empty % Non-3.0. -\else - \def\linenumber{\the\inputlineno:\space} -\fi - -% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. -% If its value is nonempty, SUFFIX is output afterward. - -\def\refx#1#2{% - \expandafter\ifx\csname X#1\endcsname\relax - % If not defined, say something at least. - $\langle$un\-de\-fined$\rangle$% - \ifhavexrefs - \message{\linenumber Undefined cross reference `#1'.}% - \else - \ifwarnedxrefs\else - \global\warnedxrefstrue - \message{Cross reference values unknown; you must run TeX again.}% - \fi - \fi - \else - % It's defined, so just use it. - \csname X#1\endcsname - \fi - #2% Output the suffix in any case. -} - -% Read the last existing aux file, if any. No error if none exists. - -% This is the macro invoked by entries in the aux file. -\def\xrdef #1#2{ -{\catcode`\'=\other\expandafter \gdef \csname X#1\endcsname {#2}}} - -\def\readauxfile{% -\begingroup -\catcode `\^^@=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\^^C=\other -\catcode `\^^D=\other -\catcode `\^^E=\other -\catcode `\^^F=\other -\catcode `\^^G=\other -\catcode `\^^H=\other -\catcode `\ =\other -\catcode `\^^L=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\=\other -\catcode 26=\other -\catcode `\^^[=\other -\catcode `\^^\=\other -\catcode `\^^]=\other -\catcode `\^^^=\other -\catcode `\^^_=\other -\catcode `\@=\other -\catcode `\^=\other -\catcode `\~=\other -\catcode `\[=\other -\catcode `\]=\other -\catcode`\"=\other -\catcode`\_=\other -\catcode`\|=\other -\catcode`\<=\other -\catcode`\>=\other -\catcode `\$=\other -\catcode `\#=\other -\catcode `\&=\other -% `\+ does not work, so use 43. -\catcode 43=\other -% Make the characters 128-255 be printing characters -{% - \count 1=128 - \def\loop{% - \catcode\count 1=\other - \advance\count 1 by 1 - \ifnum \count 1<256 \loop \fi - }% -}% -% the aux file uses ' as the escape. -% Turn off \ as an escape so we do not lose on -% entries which were dumped with control sequences in their names. -% For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ -% Reference to such entries still does not work the way one would wish, -% but at least they do not bomb out when the aux file is read in. -\catcode `\{=1 \catcode `\}=2 -\catcode `\%=\other -\catcode `\'=0 -\catcode`\^=7 % to make ^^e4 etc usable in xref tags -\catcode `\\=\other -\openin 1 \jobname.aux -\ifeof 1 \else \closein 1 \input \jobname.aux \global\havexrefstrue -\global\warnedobstrue -\fi -% Open the new aux file. Tex will close it automatically at exit. -\openout \auxfile=\jobname.aux -\endgroup} - - -% Footnotes. - -\newcount \footnoteno - -% The trailing space in the following definition for supereject is -% vital for proper filling; pages come out unaligned when you do a -% pagealignmacro call if that space before the closing brace is -% removed. (Generally, numeric constants should always be followed by a -% space to prevent strange expansion errors.) -\def\supereject{\par\penalty -20000\footnoteno =0 } - -% @footnotestyle is meaningful for info output only.. -\let\footnotestyle=\comment - -\let\ptexfootnote=\footnote - -{\catcode `\@=11 -% -% Auto-number footnotes. Otherwise like plain. -\gdef\footnote{% - \global\advance\footnoteno by \@ne - \edef\thisfootno{$^{\the\footnoteno}$}% - % - % In case the footnote comes at the end of a sentence, preserve the - % extra spacing after we do the footnote number. - \let\@sf\empty - \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi - % - % Remove inadvertent blank space before typesetting the footnote number. - \unskip - \thisfootno\@sf - \footnotezzz -}% - -% Don't bother with the trickery in plain.tex to not require the -% footnote text as a parameter. Our footnotes don't need to be so general. -% -\long\gdef\footnotezzz#1{\insert\footins{% - % We want to typeset this text as a normal paragraph, even if the - % footnote reference occurs in (for example) a display environment. - % So reset some parameters. - \interlinepenalty\interfootnotelinepenalty - \splittopskip\ht\strutbox % top baseline for broken footnotes - \splitmaxdepth\dp\strutbox - \floatingpenalty\@MM - \leftskip\z@skip - \rightskip\z@skip - \spaceskip\z@skip - \xspaceskip\z@skip - \parindent\defaultparindent - % - % Hang the footnote text off the number. - \hang - \textindent{\thisfootno}% - % - % Don't crash into the line above the footnote text. Since this - % expands into a box, it must come within the paragraph, lest it - % provide a place where TeX can split the footnote. - \footstrut - #1\strut}% -} - -}%end \catcode `\@=11 - -% Set the baselineskip to #1, and the lineskip and strut size -% correspondingly. There is no deep meaning behind these magic numbers -% used as factors; they just match (closely enough) what Knuth defined. -% -\def\lineskipfactor{.08333} -\def\strutheightpercent{.70833} -\def\strutdepthpercent {.29167} -% -\def\setleading#1{% - \normalbaselineskip = #1\relax - \normallineskip = \lineskipfactor\normalbaselineskip - \normalbaselines - \setbox\strutbox =\hbox{% - \vrule width0pt height\strutheightpercent\baselineskip - depth \strutdepthpercent \baselineskip - }% -} - -% @| inserts a changebar to the left of the current line. It should -% surround any changed text. This approach does *not* work if the -% change spans more than two lines of output. To handle that, we would -% have adopt a much more difficult approach (putting marks into the main -% vertical list for the beginning and end of each change). -% -\def\|{% - % \vadjust can only be used in horizontal mode. - \leavevmode - % - % Append this vertical mode material after the current line in the output. - \vadjust{% - % We want to insert a rule with the height and depth of the current - % leading; that is exactly what \strutbox is supposed to record. - \vskip-\baselineskip - % - % \vadjust-items are inserted at the left edge of the type. So - % the \llap here moves out into the left-hand margin. - \llap{% - % - % For a thicker or thinner bar, change the `1pt'. - \vrule height\baselineskip width1pt - % - % This is the space between the bar and the text. - \hskip 12pt - }% - }% -} - -% For a final copy, take out the rectangles -% that mark overfull boxes (in case you have decided -% that the text looks ok even though it passes the margin). -% -\def\finalout{\overfullrule=0pt} - - -% End of control word definitions. - -\message{and turning on texinfo input format.} - -\def\openindices{% - \newindex{cp}% - \newcodeindex{fn}% - \newcodeindex{vr}% - \newcodeindex{tp}% - \newcodeindex{ky}% - \newcodeindex{pg}% -} - -% Set some numeric style parameters, for 8.5 x 11 format. - -\hsize = 6in -\hoffset = .25in -\newdimen\defaultparindent \defaultparindent = 15pt -\parindent = \defaultparindent -\parskip 3pt plus 2pt minus 1pt -\setleading{13.2pt} -\advance\topskip by 1.2cm - -\chapheadingskip = 15pt plus 4pt minus 2pt -\secheadingskip = 12pt plus 3pt minus 2pt -\subsecheadingskip = 9pt plus 2pt minus 2pt - -% Prevent underfull vbox error messages. -\vbadness=10000 - -% Following George Bush, just get rid of widows and orphans. -\widowpenalty=10000 -\clubpenalty=10000 - -% Use TeX 3.0's \emergencystretch to help line breaking, but if we're -% using an old version of TeX, don't do anything. We want the amount of -% stretch added to depend on the line length, hence the dependence on -% \hsize. This makes it come to about 9pt for the 8.5x11 format. -% -\ifx\emergencystretch\thisisundefined - % Allow us to assign to \emergencystretch anyway. - \def\emergencystretch{\dimen0}% -\else - \emergencystretch = \hsize - \divide\emergencystretch by 45 -\fi - -% Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) -\def\smallbook{ - \global\chapheadingskip = 15pt plus 4pt minus 2pt - \global\secheadingskip = 12pt plus 3pt minus 2pt - \global\subsecheadingskip = 9pt plus 2pt minus 2pt - % - \global\lispnarrowing = 0.3in - \setleading{12pt} - \advance\topskip by -1cm - \global\parskip 2pt plus 1pt - \global\hsize = 5in - \global\vsize=7.5in - \global\tolerance=700 - \global\hfuzz=1pt - \global\contentsrightmargin=0pt - \global\deftypemargin=0pt - \global\defbodyindent=.5cm - % - \global\pagewidth=\hsize - \global\pageheight=\vsize - % - \global\let\smalllisp=\smalllispx - \global\let\smallexample=\smalllispx - \global\def\Esmallexample{\Esmalllisp} -} - -% Use @afourpaper to print on European A4 paper. -\def\afourpaper{ -\global\tolerance=700 -\global\hfuzz=1pt -\setleading{12pt} -\global\parskip 15pt plus 1pt - -\global\vsize= 53\baselineskip -\advance\vsize by \topskip -%\global\hsize= 5.85in % A4 wide 10pt -\global\hsize= 6.5in -\global\outerhsize=\hsize -\global\advance\outerhsize by 0.5in -\global\outervsize=\vsize -\global\advance\outervsize by 0.6in - -\global\pagewidth=\hsize -\global\pageheight=\vsize -} - -\bindingoffset=0pt -\normaloffset=\hoffset -\pagewidth=\hsize -\pageheight=\vsize - -% Allow control of the text dimensions. Parameters in order: textheight; -% textwidth; voffset; hoffset; binding offset; topskip. -% All require a dimension; -% header is additional; added length extends the bottom of the page. - -\def\changepagesizes#1#2#3#4#5#6{ - \global\vsize= #1 - \global\topskip= #6 - \advance\vsize by \topskip - \global\voffset= #3 - \global\hsize= #2 - \global\outerhsize=\hsize - \global\advance\outerhsize by 0.5in - \global\outervsize=\vsize - \global\advance\outervsize by 0.6in - \global\pagewidth=\hsize - \global\pageheight=\vsize - \global\normaloffset= #4 - \global\bindingoffset= #5} - -% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin -% 29mm, hence bottom margin 28mm, nominal side margin 3cm. -\def\afourlatex - {\global\tolerance=700 - \global\hfuzz=1pt - \setleading{12pt} - \global\parskip 15pt plus 1pt - \advance\baselineskip by 1.6pt - \changepagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm} - } - -% Use @afourwide to print on European A4 paper in wide format. -\def\afourwide{\afourpaper -\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}} - -% Define macros to output various characters with catcode for normal text. -\catcode`\"=\other -\catcode`\~=\other -\catcode`\^=\other -\catcode`\_=\other -\catcode`\|=\other -\catcode`\<=\other -\catcode`\>=\other -\catcode`\+=\other -\def\normaldoublequote{"} -\def\normaltilde{~} -\def\normalcaret{^} -\def\normalunderscore{_} -\def\normalverticalbar{|} -\def\normalless{<} -\def\normalgreater{>} -\def\normalplus{+} - -% This macro is used to make a character print one way in ttfont -% where it can probably just be output, and another way in other fonts, -% where something hairier probably needs to be done. -% -% #1 is what to print if we are indeed using \tt; #2 is what to print -% otherwise. Since all the Computer Modern typewriter fonts have zero -% interword stretch (and shrink), and it is reasonable to expect all -% typewriter fonts to have this, we can check that font parameter. -% -\def\ifusingtt#1#2{\ifdim \fontdimen3\the\font=0pt #1\else #2\fi} - -% Turn off all special characters except @ -% (and those which the user can use as if they were ordinary). -% Most of these we simply print from the \tt font, but for some, we can -% use math or other variants that look better in normal text. - -\catcode`\"=\active -\def\activedoublequote{{\tt \char '042}} -\let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt \char '176}} -\chardef\hat=`\^ -\catcode`\^=\active -\def\auxhat{\def^{'hat}} -\def^{{\tt \hat}} - -\catcode`\_=\active -\def_{\ifusingtt\normalunderscore\_} -% Subroutine for the previous macro. -\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}} - -\catcode`\|=\active -\def|{{\tt \char '174}} -\chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} -\chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -%\catcode 27=\active -%\def^^[{$\diamondsuit$} - -% Set up an active definition for =, but don't enable it most of the time. -{\catcode`\==\active -\global\def={{\tt \char 61}}} - -\catcode`+=\active -\catcode`\_=\active - -% If a .fmt file is being used, characters that might appear in a file -% name cannot be active until we have parsed the command line. -% So turn them off again, and have \everyjob (or @setfilename) turn them on. -% \otherifyactive is called near the end of this file. -\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} - -\catcode`\@=0 - -% \rawbackslashxx output one backslash character in current font -\global\chardef\rawbackslashxx=`\\ -%{\catcode`\\=\other -%@gdef@rawbackslashxx{\}} - -% \rawbackslash redefines \ as input to do \rawbackslashxx. -{\catcode`\\=\active -@gdef@rawbackslash{@let\=@rawbackslashxx }} - -% \normalbackslash outputs one backslash in fixed width font. -\def\normalbackslash{{\tt\rawbackslashxx}} - -% Say @foo, not \foo, in error messages. -\escapechar=`\@ - -% \catcode 17=0 % Define control-q -\catcode`\\=\active - -% Used sometimes to turn off (effectively) the active characters -% even after parsing them. -@def@turnoffactive{@let"=@normaldoublequote -@let\=@realbackslash -@let~=@normaltilde -@let^=@normalcaret -@let_=@normalunderscore -@let|=@normalverticalbar -@let<=@normalless -@let>=@normalgreater -@let+=@normalplus} - -@def@normalturnoffactive{@let"=@normaldoublequote -@let\=@normalbackslash -@let~=@normaltilde -@let^=@normalcaret -@let_=@normalunderscore -@let|=@normalverticalbar -@let<=@normalless -@let>=@normalgreater -@let+=@normalplus} - -% Make _ and + \other characters, temporarily. -% This is canceled by @fixbackslash. -@otherifyactive - -% If a .fmt file is being used, we don't want the `\input texinfo' to show up. -% That is what \eatinput is for; after that, the `\' should revert to printing -% a backslash. -% -@gdef@eatinput input texinfo{@fixbackslash} -@global@let\ = @eatinput - -% On the other hand, perhaps the file did not have a `\input texinfo'. Then -% the first `\{ in the file would cause an error. This macro tries to fix -% that, assuming it is called before the first `\' could plausibly occur. -% Also back turn on active characters that might appear in the input -% file name, in case not using a pre-dumped format. -% -@gdef@fixbackslash{@ifx\@eatinput @let\ = @normalbackslash @fi - @catcode`+=@active @catcode`@_=@active} - -%% These look ok in all fonts, so just make them not special. The @rm below -%% makes sure that the current font starts out as the newly loaded cmr10 -@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other - -@textfonts -@rm - -@c Local variables: -@c page-delimiter: "^\\\\message" -@c End: diff --git a/gnu/usr.bin/texinfo/texinfo.texi b/gnu/usr.bin/texinfo/texinfo.texi deleted file mode 100644 index bb9569b545a..00000000000 --- a/gnu/usr.bin/texinfo/texinfo.texi +++ /dev/null @@ -1,16886 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@comment %**start of header -@setfilename texinfo -@settitle Texinfo @value{edition} -@c Define a new index for options. -@defcodeindex op -@c Put everything except function (command, in this case) names in one -index (arbitrarily chosen to be the concept index). -@syncodeindex op cp -@syncodeindex vr cp -@syncodeindex pg cp -@footnotestyle separate -@paragraphindent 2 -@finalout -@comment %**end of header -@comment $Id: texinfo.texi,v 1.3 2002/06/10 13:51:01 espie Exp $ - -@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a -@c prefix arg). This updates the node pointers, which texinfmt.el needs. - -@dircategory Texinfo documentation system -@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Updating info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. -* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. -@end direntry - -@c Set smallbook if printing in smallbook format so the example of the -@c smallbook font is actually written using smallbook; in bigbook, a kludge -@c is used for TeX output. -@smallbook -@set smallbook -@c @@clear smallbook - -@set edition 2.23 -@set update-month October 1996 -@set update-date 1 @value{update-month} - -@c Currently undocumented command, 5 December 1993: -@c -@c nwnode (Same as node, but no warnings; for `makeinfo'.) - -@ifinfo -This file documents Texinfo, a documentation system that can produce -both on-line information and a printed manual from a single source file. - -Copyright (C) 1988, 90, 91, 92, 93, 95, 1996 Free Software Foundation, Inc. - -This is the second edition of the Texinfo documentation,@* -and is consistent with version 2 of @file{texinfo.tex}. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@end ifinfo - -@setchapternewpage odd - -@shorttitlepage Texinfo - -@titlepage -@c use the new format for titles -@title Texinfo -@subtitle The GNU Documentation Format -@subtitle Edition @value{edition}, for Texinfo Version Three -@subtitle @value{update-month} - -@author Robert J.@: Chassell -@author Richard M.@: Stallman - -@c Include the Distribution inside the titlepage so -@c that headings are turned off. - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996 Free Software Foundation, Inc. - -@sp 2 -This is the second edition of the Texinfo documentation,@* -and is consistent with version 2 of @file{texinfo.tex}. -@sp 2 - -Published by the Free Software Foundation @* -59 Temple Place Suite 330, @* -Boston, MA 02111-1307 USA @* -Printed copies are available for $15 each.@* -ISBN 1-882114-64-7 -@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 -@c ISBN 1-882114-64-7 is for edition 2.23 of 1 October 1996. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - -@ifinfo -@node Top, Copying, (dir), (dir) -@top Texinfo - -Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output.@refill - -The first part of this master menu lists the major nodes in this Info -document, including the @@-command and concept indices. The rest of -the menu lists all the lower level nodes in the document.@refill - -This is Edition @value{edition} of the Texinfo documentation, -@w{@value{update-date},} for Texinfo Version Three. -@end ifinfo - -@c Here is a spare copy of the chapter menu entry descriptions, -@c in case they are accidently deleted -@ignore -Your rights. -Texinfo in brief. -How to use Texinfo mode. -What is at the beginning of a Texinfo file? -What is at the end of a Texinfo file? -How to create chapters, sections, subsections, - appendices, and other parts. -How to provide structure for a document. -How to write nodes. -How to write menus. -How to write cross references. -How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -How to write quotations, examples, etc. -How to write lists and tables. -How to create indices. -How to insert @@-signs, braces, etc. -How to indicate results of evaluation, - expansion of macros, errors, etc. -How to force and prevent line and page breaks. -How to describe functions and the like in a uniform manner. -How to write footnotes. -How to specify text for either @TeX{} or Info. -How to print hardcopy. -How to create an Info file. -How to install an Info file -A list of all the Texinfo @@-commands. -Hints on how to write a Texinfo document. -A sample Texinfo file to look at. -Tell readers they have the right to copy - and distribute. -How to incorporate other Texinfo files. -How to write page headings and footings. -How to find formatting mistakes. -All about paragraph refilling. -A description of @@-Command syntax. -Texinfo second edition features. -A menu containing commands and variables. -A menu covering many topics. -@end ignore - -@menu -* Copying:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: How to use Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* Structuring:: How to create chapters, sections, subsections, - appendices, and other parts. -* Nodes:: How to write nodes. -* Menus:: How to write menus. -* Cross References:: How to write cross references. -* Marking Text:: How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: How to write quotations, examples, etc. -* Lists and Tables:: How to write lists and tables. -* Indices:: How to create indices. -* Insertions:: How to insert @@-signs, braces, etc. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -* Breaks:: How to force and prevent line and page breaks. -* Definition Commands:: How to describe functions and the like - in a uniform manner. -* Footnotes:: How to write footnotes. -* Conditionals:: How to specify text for either @TeX{} or Info. -* Macros:: Defining new Texinfo commands. -* Format/Print Hardcopy:: How to convert a Texinfo file to a file - for printing and how to print that file. -* Create an Info File:: Convert a Texinfo file into an Info file. -* Install an Info File:: Make an Info file accessible to users. -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo File:: A sample Texinfo file to look at. -* Sample Permissions:: Tell readers they have the right to copy - and distribute. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* Refilling Paragraphs:: All about paragraph refilling. -* Command Syntax:: A description of @@-Command syntax. -* Obtaining TeX:: How to Obtain @TeX{}. -* New Features:: Texinfo second edition features. -* Command and Variable Index:: A menu containing commands and variables. -* Concept Index:: A menu covering many topics. - -@detailmenu - - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Using Texinfo:: Create a conventional printed book - or an Info file. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: - -Using Texinfo Mode - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - -Updating Nodes and Menus - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - -Beginning a Texinfo File - -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -The Texinfo File Header - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. - -The Title and Copyright Pages - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright & Permissions:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. - -The `Top' Node and Master Menu - -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. - -Chapter Structuring - -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. - -Nodes - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. - -The @code{@@node} Command - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. -* Top Node Summary:: Write a brief description for readers. - -Menus - -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. - -Cross References - -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. - -@code{@@xref} - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. - -Marking Words and Phrases - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - -Indicating Definitions, Commands, etc. - -* Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -* url:: How to indicate a world wide web reference. -* email:: How to indicate an electronic mail address. - -Emphasizing Text - -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -* Customized Highlighting:: How to define highlighting commands. - -Quotations and Examples - -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. - -Making Lists and Tables - -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. - -Making a Two-column Table - -* table:: How to construct a two-column table. -* ftable vtable:: How to construct a two-column table - with automatic indexing. -* itemx:: How to put more entries in the first column. - -Multi-column Tables - -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. - -Creating Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - -Combining Indices - -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - -Special Insertions - -* Braces Atsigns:: How to insert braces, @samp{@@}. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* pounds:: How to insert the pounds currency symbol. -* minus:: How to insert a minus sign. -* math:: How to format a mathematical expression. - -Inserting @@ and Braces - -* Inserting An Atsign:: How to insert @samp{@@}. -* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. - -Inserting Space - -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* dmn:: How to format a dimension. - -Inserting Ellipsis, Dots, and Bullets - -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. - -Inserting @TeX{} and the Copyright Symbol - -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright}@{@}. - -Glyphs for Examples - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - -Making and Preventing Breaks - -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: - -The Definition Commands - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. - -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - -Conditionally Visible Text - -* Conditional Commands:: How to specify text for HTML, Info, or @TeX{}. -* Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. -* set clear value:: How to designate which text to format (for - both Info and @TeX{}); and how to set a - flag to a string that you can insert. - -@code{@@set}, @code{@@clear}, and @code{@@value} - -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. - -Macros: Defining New Texinfo Commands - -* Defining Macros:: Both defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. - -Format and Print Hardcopy - -* Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format in a shell. -* Format with texi2dvi:: A simpler way to use the shell. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What you need to do to use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. - -Creating an Info File - -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - -Installing an Info File - -* Directory file:: The top level menu for all Info files. -* New Info File:: Listing a new info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: @code{install-info} options. - -Sample Permissions - -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. - -Include Files - -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. - -Page Headings - -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. - -Formatting Mistakes - -* makeinfo preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with @TeX{} formatting. -* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. - -Finding Badly Referenced Nodes - -* Using Info-validate:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. - -Second Edition Features - -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@end detailmenu -@end menu - -@node Copying, Overview, Top, Top -@comment node-name, next, previous, up -@unnumbered Texinfo Copying Conditions -@cindex Copying conditions -@cindex Conditions for copying Texinfo - -The programs currently being distributed that relate to Texinfo include -portions of GNU Emacs, plus other separate programs (including -@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). -These programs are @dfn{free}; this means that everyone is free to use -them and free to redistribute them on a free basis. The Texinfo-related -programs are not in the public domain; they are copyrighted and there -are restrictions on their distribution, but these restrictions are -designed to permit everything that a good cooperating citizen would want -to do. What is not allowed is to try to prevent others from further -sharing any version of these programs that they might get from -you.@refill - - Specifically, we want to make sure that you have the right to give -away copies of the programs that relate to Texinfo, that you receive -source code or else can get it if you want it, that you can change these -programs or use pieces of them in new free programs, and that you know -you can do these things.@refill - - To make sure that everyone has such rights, we have to forbid you to -deprive anyone else of these rights. For example, if you distribute -copies of the Texinfo related programs, you must give the recipients all -the rights that you have. You must make sure that they, too, receive or -can get the source code. And you must tell them their rights.@refill - - Also, for our own protection, we must make certain that everyone finds -out that there is no warranty for the programs that relate to Texinfo. -If these programs are modified by someone else and passed on, we want -their recipients to know that what they have is not what we distributed, -so that any problems introduced by others will not reflect on our -reputation.@refill - - The precise conditions of the licenses for the programs currently -being distributed that relate to Texinfo are found in the General Public -Licenses that accompany them.@refill - -@node Overview, Texinfo Mode, Copying, Top -@comment node-name, next, previous, up -@chapter Overview of Texinfo -@cindex Overview of Texinfo -@cindex Texinfo overview - -@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is -pronounced like ``speck'', not ``hex''. This odd pronunciation is -derived from, but is not the same as, the pronunciation of @TeX{}. In -the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' -rather than the English letter ``ex''. Pronounce @TeX{} as if the -@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo -as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' -and write the other letters in lower case.} -is a documentation system that uses a single source file to produce both -on-line information and printed output. This means that instead of -writing two different documents, one for the on-line help or other on-line -information and the other for a typeset manual or other printed work, you -need write only one document. When the work is revised, you need revise -only one document. (You can read the on-line information, known as an -@dfn{Info file}, with an Info documentation-reading program.)@refill - -@menu -* Using Texinfo:: Create a conventional printed book - or an Info file. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: How to write comments and mark regions that - the formatting commands will ignore. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* Acknowledgements:: -@end menu - -@node Using Texinfo, Info Files, Overview, Overview -@ifinfo -@heading Using Texinfo -@end ifinfo - -Using Texinfo, you can create a printed document with the normal -features of a book, including chapters, sections, cross references, -and indices. From the same Texinfo source file, you can create a -menu-driven, on-line Info file with nodes, menus, cross references, -and indices. You can, if you wish, make the chapters and sections of -the printed document correspond to the nodes of the on-line -information; and you use the same cross references and indices for -both the Info file and the printed work. @cite{The GNU -Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill - -To make a printed document, you process a Texinfo source file with the -@TeX{} typesetting program. This creates a @sc{dvi} file that you can -typeset and print as a book or report. (Note that the Texinfo language -is completely different from @TeX{}'s usual language, plain @TeX{}.) If -you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you -can use the @code{texi2roff} program instead.@refill - -To make an Info file, you process a Texinfo source file with the -@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; -this creates an Info file that you can install on-line.@refill - -@TeX{} and @code{texi2roff} work with many types of printer; similarly, -Info works with almost every type of computer terminal. This power -makes Texinfo a general purpose system, but brings with it a constraint, -which is that a Texinfo file may contain only the customary -``typewriter'' characters (letters, numbers, spaces, and punctuation -marks) but no special graphics.@refill - -A Texinfo file is a plain @sc{ascii} file containing text and -@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the -typesetting and formatting programs what to do. You may edit a -Texinfo file with any text editor; but it is especially convenient to -use GNU Emacs since that editor has a special mode, called Texinfo -mode, that provides various Texinfo-related features. (@xref{Texinfo -Mode}.)@refill - -Before writing a Texinfo source file, you should become familiar with -the Info documentation reading program and learn about nodes, -menus, cross references, and the rest. (@inforef{Top, info, info}, -for more information.)@refill - -You can use Texinfo to create both on-line help and printed manuals; -moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the format in which documentation for GNU utilities and libraries is -written.@refill - -@node Info Files, Printed Books, Using Texinfo, Overview -@comment node-name, next, previous, up -@section Info files -@cindex Info files - -An Info file is a Texinfo file formatted so that the Info documentation -reading program can operate on it. (@code{makeinfo} -and @code{texinfo-format-buffer} are two commands that convert a Texinfo file -into an Info file.)@refill - -Info files are divided into pieces called @dfn{nodes}, each of which -contains the discussion of one topic. Each node has a name, and -contains both text for the user to read and pointers to other nodes, -which are identified by their names. The Info program displays one node -at a time, and provides commands with which the user can move to other -related nodes.@refill - -@ifinfo -@inforef{Top, info, info}, for more information about using Info.@refill -@end ifinfo - -Each node of an Info file may have any number of child nodes that -describe subtopics of the node's topic. The names of child -nodes are listed in a @dfn{menu} within the parent node; this -allows you to use certain Info commands to move to one of the child -nodes. Generally, an Info file is organized like a book. If a node -is at the logical level of a chapter, its child nodes are at the level -of sections; likewise, the child nodes of sections are at the level -of subsections.@refill - -All the children of any one parent are linked together in a -bidirectional chain of `Next' and `Previous' pointers. The `Next' -pointer provides a link to the next section, and the `Previous' pointer -provides a link to the previous section. This means that all the nodes -that are at the level of sections within a chapter are linked together. -Normally the order in this chain is the same as the order of the -children in the parent's menu. Each child node records the parent node -name as its `Up' pointer. The last child has no `Next' pointer, and the -first child has the parent both as its `Previous' and as its `Up' -pointer.@footnote{In some documents, the first child has no `Previous' -pointer. Occasionally, the last child has the node name of the next -following higher level node as its `Next' pointer.}@refill - -The book-like structuring of an Info file into nodes that correspond -to chapters, sections, and the like is a matter of convention, not a -requirement. The `Up', `Previous', and `Next' pointers of a node can -point to any other nodes, and a menu can contain any other nodes. -Thus, the node structure can be any directed graph. But it is usually -more comprehensible to follow a structure that corresponds to the -structure of chapters and sections in a printed book or report.@refill - -In addition to menus and to `Next', `Previous', and `Up' pointers, Info -provides pointers of another kind, called references, that can be -sprinkled throughout the text. This is usually the best way to -represent links that do not fit a hierarchical structure.@refill - -Usually, you will design a document so that its nodes match the -structure of chapters and sections in the printed output. But there -are times when this is not right for the material being discussed. -Therefore, Texinfo uses separate commands to specify the node -structure for the Info file and the section structure for the printed -output.@refill - -Generally, you enter an Info file through a node that by convention is -called @samp{Top}. This node normally contains just a brief summary -of the file's purpose, and a large menu through which the rest of the -file is reached. From this node, you can either traverse the file -systematically by going from node to node, or you can go to a specific -node listed in the main menu, or you can search the index menus and -then go directly to the node that has the information you want.@refill -@c !!! With the standalone Info system you may go to specific nodes -@c directly.. - -If you want to read through an Info file in sequence, as if it were a -printed manual, you can get the whole file with the advanced Info -command @kbd{g* @key{RET}}. (@inforef{Expert, Advanced Info commands, -info}.)@refill - -@c !!! dir file may be located in one of many places: -@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/info -@c /usr/local/lib/info -The @file{dir} file in the @file{info} directory serves as the -departure point for the whole Info system. From it, you can reach the -`Top' nodes of each of the documents in a complete Info system.@refill - -@node Printed Books, Formatting Commands, Info Files, Overview -@comment node-name, next, previous, up -@section Printed Books -@cindex Printed book and manual characteristics -@cindex Manual characteristics, printed -@cindex Book characteristics, printed -@cindex Texinfo printed book characteristics -@cindex Characteristics, printed books or manuals - -@cindex Knuth, Donald -A Texinfo file can be formatted and typeset as a printed book or manual. -To do this, you need @TeX{}, a powerful, sophisticated typesetting -program written by Donald Knuth.@footnote{You can also use the -@code{texi2roff} program if you do not have @TeX{}; since Texinfo is -designed for use with @TeX{}, @code{texi2roff} is not described here. -@code{texi2roff} is part of the standard GNU distribution.}@refill - -A Texinfo-based book is similar to any other typeset, printed work: it -can have a title page, copyright page, table of contents, and preface, -as well as chapters, numbered or unnumbered sections and subsections, -page headers, cross references, footnotes, and indices.@refill - -You can use Texinfo to write a book without ever having the intention -of converting it into on-line information. You can use Texinfo for -writing a printed novel, and even to write a printed memo, although -this latter application is not recommended since electronic mail is so -much easier.@refill - -@TeX{} is a general purpose typesetting program. Texinfo provides a -file called @file{texinfo.tex} that contains information (definitions or -@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. -(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands -to @TeX{} commands, which @TeX{} can then process to create the typeset -document.) @file{texinfo.tex} contains the specifications for printing -a document.@refill - -Most often, documents are printed on 8.5 inch by 11 inch -pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you -can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by -235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper -(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}. -Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill - -By changing the parameters in @file{texinfo.tex}, you can change the -size of the printed document. In addition, you can change the style in -which the printed document is formatted; for example, you can change the -sizes and fonts used, the amount of indentation for each paragraph, the -degree to which words are hyphenated, and the like. By changing the -specifications, you can make a book look dignified, old and serious, or -light-hearted, young and cheery.@refill - -@TeX{} is freely distributable. It is written in a dialect of Pascal -called WEB and can be compiled either in Pascal or (by using a -conversion program that comes with the @TeX{} distribution) in C. -(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information -about @TeX{}.)@refill - -@TeX{} is very powerful and has a great many features. Because a -Texinfo file must be able to present information both on a -character-only terminal in Info form and in a typeset book, the -formatting commands that Texinfo supports are necessarily -limited.@refill - -@xref{Obtaining TeX, , How to Obtain @TeX{}}. - - -@node Formatting Commands, Conventions, Printed Books, Overview -@comment node-name, next, previous, up -@section @@-commands -@cindex @@-commands -@cindex Formatting commands - -In a Texinfo file, the commands that tell @TeX{} how to typeset the -printed manual and tell @code{makeinfo} and -@code{texinfo-format-buffer} how to create an Info file are preceded -by @samp{@@}; they are called @dfn{@@-commands}. For example, -@code{@@node} is the command to indicate a node and @code{@@chapter} -is the command to indicate the start of a chapter.@refill - -@quotation -@strong{Please note:} All the @@-commands, with the exception of the -@code{@@TeX@{@}} command, must be written entirely in lower -case.@refill -@end quotation - -The Texinfo @@-commands are a strictly limited set of constructs. The -strict limits make it possible for Texinfo files to be understood both -by @TeX{} and by the code that converts them into Info files. You can -display Info files on any terminal that displays alphabetic and -numeric characters. Similarly, you can print the output generated by -@TeX{} on a wide variety of printers.@refill - -Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does -not refer to a disputation between two people; it refers to the -information presented to the command. According to the @cite{Oxford -English Dictionary}, the word derives from the Latin for @dfn{to make -clear, prove}; thus it came to mean `the evidence offered as proof', -which is to say, `the information offered', which led to its -mathematical meaning. In its other thread of derivation, the word -came to mean `to assert in a manner against which others may make -counter assertions', which led to the meaning of `argument' as a -disputation.} they take, you need to write @@-commands on lines of -their own or as part of sentences:@refill - -@itemize @bullet -@item -Write a command such as @code{@@noindent} at the beginning of a line as -the only text on the line. (@code{@@noindent} prevents the beginning of -the next line from being indented as the beginning of a -paragraph.)@refill - -@item -Write a command such as @code{@@chapter} at the beginning of a line -followed by the command's arguments, in this case the chapter title, on -the rest of the line. (@code{@@chapter} creates chapter titles.)@refill - -@item -Write a command such as @code{@@dots@{@}} wherever you wish but usually -within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill - -@item -Write a command such as @code{@@code@{@var{sample-code}@}} wherever you -wish (but usually within a sentence) with its argument, -@var{sample-code} in this example, between the braces. (@code{@@code} -marks text as being code.)@refill - -@item -Write a command such as @code{@@example} at the beginning of a line of -its own; write the body-text on following lines; and write the matching -@code{@@end} command, @code{@@end example} in this case, at the -beginning of a line of its own after the body-text. (@code{@@example} -@dots{} @code{@@end example} indents and typesets body-text as an -example.)@refill -@end itemize - -@noindent -@cindex Braces, when to use -As a general rule, a command requires braces if it mingles among other -text; but it does not need braces if it starts a line of its own. The -non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; -they do not need braces.@refill - -As you gain experience with Texinfo, you will rapidly learn how to -write the different commands: the different ways to write commands -make it easier to write and read Texinfo files than if all commands -followed exactly the same syntax. (For details about @@-command -syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill - -@node Conventions, Comments, Formatting Commands, Overview -@comment node-name, next, previous, up -@section General Syntactic Conventions -@cindex General syntactic conventions -@cindex Syntactic conventions -@cindex Conventions, syntactic - -All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and -@samp{@}} can appear in a Texinfo file and stand for themselves. -@samp{@@} is the escape character which introduces commands. -@samp{@{} and @samp{@}} should be used only to surround arguments to -certain commands. To put one of these special characters into the -document, put an @samp{@@} character in front of it, like this: -@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill - -@ifinfo -It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: ` ` and ' ' (but without a space between the -two single-quote characters). This convention should be followed in -Texinfo files. @TeX{} converts doubled single-quote characters to -left- and right-hand doubled quotation marks and Info converts doubled -single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill -@end ifinfo -@iftex -It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This -convention should be followed in Texinfo files. @TeX{} converts -doubled single-quote characters to left- and right-hand doubled -quotation marks, ``like this'', and Info converts doubled single-quote -characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and -@w{@tt{ '' }} to @w{@tt{ " }}.@refill -@end iftex - -Use three hyphens in a row, @samp{---}, for a dash---like this. In -@TeX{}, a single or even a double hyphen produces a printed dash that -is shorter than the usual typeset dash. Info reduces three hyphens to two for -display on the screen.@refill - -To prevent a paragraph from being indented in the printed manual, put -the command @code{@@noindent} on a line by itself before the -paragraph.@refill - -If you mark off a region of the Texinfo file with the @code{@@iftex} -and @w{@code{@@end iftex}} commands, that region will appear only in -the printed copy; in that region, you can use certain commands -borrowed from plain @TeX{} that you cannot use in Info. Likewise, if -you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo} -commands, that region will appear only in the Info file; in that -region, you can use Info commands that you cannot use in @TeX{}. -Similarly for @code{@@ifhtml} and @code{@@end ifhtml}. -@xref{Conditionals}. - -@cindex Tabs; don't use! -@quotation -@strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses -variable-width fonts, which means that it cannot predefine a tab to work -in all circumstances. Consequently, @TeX{} treats tabs like single -spaces, and that is not what they look like.@refill - -@noindent -To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple -spaces when you press the @key{TAB} key.@refill - -@noindent -Also, you can run @code{untabify} in Emacs to convert tabs in a region -to multiple spaces.@refill -@end quotation - -@node Comments, Minimum, Conventions, Overview -@comment node-name, next, previous, up -@section Comments - -You can write comments in a Texinfo file that will not appear in -either the Info file or the printed manual by using the -@code{@@comment} command (which may be abbreviated to @code{@@c}). -Such comments are for the person who reads the Texinfo file. All the -text on a line that follows either @code{@@comment} or @code{@@c} is a -comment; the rest of the line does not appear in either the Info file -or the printed manual. (Often, you can write the @code{@@comment} or -@code{@@c} in the middle of a line, and only the text that follows after -the @code{@@comment} or @code{@@c} command does not appear; but some -commands, such as @code{@@settitle} and @code{@@setfilename}, work on a -whole line. You cannot use @code{@@comment} or @code{@@c} in a line -beginning with such a command.)@refill -@cindex Comments -@findex comment -@findex c @r{(comment)} - -You can write long stretches of text that will not appear in either -the Info file or the printed manual by using the @code{@@ignore} and -@code{@@end ignore} commands. Write each of these commands on a line -of its own, starting each command at the beginning of the line. Text -between these two commands does not appear in the processed output. -You can use @code{@@ignore} and @code{@@end ignore} for writing -comments. Often, @code{@@ignore} and @code{@@end ignore} is used -to enclose a part of the copying permissions that applies to the -Texinfo source file of a document, but not to the Info or printed -version of the document.@refill -@cindex Ignored text -@cindex Unprocessed text -@findex ignore -@c !!! Perhaps include this comment about ignore and ifset: -@ignore -Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or -@code{@@ifclear} conditions is ignored in the sense that it will not -contribute to the formatted output. However, TeX and makeinfo must -still parse the ignored text, in order to understand when to -@emph{stop} ignoring text from the source file; that means that you -will still get error messages if you have invalid Texinfo markup -within ignored text. -@end ignore - -@node Minimum, Six Parts, Comments, Overview -@comment node-name, next, previous, up -@section What a Texinfo File Must Have -@cindex Minimal Texinfo file (requirements) -@cindex Must have in Texinfo file -@cindex Required in Texinfo file -@cindex Texinfo file minimum - -By convention, the names of Texinfo files end with one of the -extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer -extension is preferred since it describes more clearly to a human -reader the nature of the file. The shorter extensions are for -operating systems that cannot handle long file names.@refill - -In order to be made into a printed manual and an Info file, a Texinfo -file @strong{must} begin with lines like this:@refill - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -@noindent -The contents of the file follow this beginning, and then you @strong{must} end -a Texinfo file with a line like this:@refill - -@example -@@bye -@end example - -@findex input @r{(@TeX{} command)} -@noindent -The @samp{\input texinfo} line tells @TeX{} to use the -@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo -@@-commands into @TeX{} typesetting commands. (Note the use of the -backslash, @samp{\}; this is correct for @TeX{}.) The -@samp{@@setfilename} line provides a name for the Info file and tells -@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a -title for the page headers (or footers) of the printed manual.@refill - -The @code{@@bye} line at the end of the file on a line of its own tells -the formatters that the file is ended and to stop formatting.@refill - -Usually, you will not use quite such a spare format, but will include -mode setting and start-of-header and end-of-header lines at the -beginning of a Texinfo file, like this:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@@c %**end of header -@end group -@end example - -@noindent -In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into -Texinfo mode when you edit the file. - -The @code{@@c} lines which surround the @samp{@@setfilename} and -@samp{@@settitle} lines are optional, but you need them in order to -run @TeX{} or Info on just part of the file. (@xref{Start of Header}, -for more information.)@refill - -Furthermore, you will usually provide a Texinfo file with a title -page, indices, and the like. But the minimum, which can be useful -for short documents, is just the three lines at the beginning and the -one line at the end.@refill - -@node Six Parts, Short Sample, Minimum, Overview -@comment node-name, next, previous, up -@section Six Parts of a Texinfo File - -Generally, a Texinfo file contains more than the minimal -beginning and end---it usually contains six parts:@refill - -@table @r -@item 1. Header -The @dfn{Header} names the file, tells @TeX{} which definitions' file to -use, and performs other ``housekeeping'' tasks.@refill - -@item 2. Summary Description and Copyright -The @dfn{Summary Description and Copyright} segment describes the document -and contains the copyright notice and copying permissions for the Info -file. The segment must be enclosed between @code{@@ifinfo} and -@code{@@end ifinfo} commands so that the formatters place it only in the Info -file.@refill - -@item 3. Title and Copyright -The @dfn{Title and Copyright} segment contains the title and copyright pages -and copying permissions for the printed manual. The segment must be -enclosed between @code{@@titlepage} and @code{@@end titlepage} commands. -The title and copyright page appear only in the printed @w{manual}.@refill - -@item 4. `Top' Node and Master Menu -The @dfn{Master Menu} contains a complete menu of all the nodes in the whole -Info file. It appears only in the Info file, in the `Top' node.@refill - -@item 5. Body -The @dfn{Body} of the document may be structured like a traditional book or -encyclopedia or it may be free form.@refill - -@item 6. End -The @dfn{End} contains commands for printing indices and generating -the table of contents, and the @code{@@bye} command on a line of its -own.@refill -@end table - -@node Short Sample, Acknowledgements, Six Parts, Overview -@comment node-name, next, previous, up -@section A Short Sample Texinfo File -@cindex Sample Texinfo file - -Here is a complete but very short Texinfo file, in 6 parts. The first -three parts of the file, from @samp{\input texinfo} through to -@samp{@@end titlepage}, look more intimidating than they are. Most of -the material is standard boilerplate; when you write a manual, simply -insert the names for your own manual in this segment. (@xref{Beginning a -File}.)@refill - -@noindent -In the following, the sample text is @emph{indented}; comments on it are -not. The complete file, without any comments, is shown in -@ref{Sample Texinfo File}. - -@subheading Part 1: Header - -@noindent -The header does not appear in either the Info file or the@* -printed output. It sets various parameters, including the@* -name of the Info file and the title used in the header. - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header - -@@setchapternewpage odd -@end group -@end example - -@subheading Part 2: Summary Description and Copyright - -@noindent -The summary description and copyright segment does not@* -appear in the printed document. - -@example -@group -@@ifinfo -This is a short example of a complete Texinfo file. - -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end ifinfo -@end group -@end example - -@subheading Part 3: Titlepage and Copyright - -@noindent -The titlepage segment does not appear in the Info file. - -@example -@group -@@titlepage -@@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} -@end group - -@group -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage -@end group -@end example - -@subheading Part 4: `Top' Node and Master Menu - -@noindent -The `Top' node contains the master menu for the Info file.@* -Since a printed manual uses a table of contents rather than@* -a menu, the master menu appears only in the Info file. - -@example -@group -@@node Top, First Chapter, (dir), (dir) -@@comment node-name, next, previous, up -@end group -@end example - -@example -@group -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Concept Index:: This index has two entries. -@@end menu -@end group -@end example - -@subheading Part 5: The Body of the Document - -@noindent -The body segment contains all the text of the document, but not the -indices or table of contents. This example illustrates a node and a -chapter containing an enumerated list.@refill - -@example -@group -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Sample index entry -@end group - -@group -This is the contents of the first chapter. -@@cindex Another sample index entry -@end group - -@group -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate -@end group - -@group -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. -@end group -@end example - -@subheading Part 6: The End of the Document - -@noindent -The end segment contains commands both for generating an index in a node -and unnumbered chapter of its own and for generating the table of -contents; and it contains the @code{@@bye} command that marks the end of -the document.@refill - -@example -@group -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index -@end group - -@group -@@printindex cp - -@@contents -@@bye -@end group -@end example - -@subheading The Results - -Here is what the contents of the first chapter of the sample look like: - -@sp 1 -@need 700 -@quotation -This is the contents of the first chapter. - -Here is a numbered list. - -@enumerate -@item -This is the first item. - -@item -This is the second item. -@end enumerate - -The @code{makeinfo} and @code{texinfo-format-buffer} -commands transform a Texinfo file such as this into -an Info file; and @TeX{} typesets it for a printed -manual. -@end quotation - -@node Acknowledgements, , Short Sample, Overview -@comment node-name, next, previous, up -@section Acknowledgements - -@cindex Stallman, Richard M. -@cindex Chassell, Robert J. -@cindex Berry, Karl -Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@: -Chassell} revised and extended it, starting with Edition 1.1. Karl -Berry made updates for the Texinfo 3.8 and subsequent releases, starting -with Edition 2.22. - -@cindex Pinard, Fran@,{c}ois -@cindex Zuhn, David D. -@cindex Weisshaus, Melissa -Our thanks go out to all who helped improve this work, particularly to -Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and -reported mistakes and obscurities; our special thanks go to Melissa -Weisshaus for her frequent and often tedious reviews of nearly similar -editions. Our mistakes are our own. - -Please send suggestions and corrections to: - -@example -@group -@r{Internet address:} - bug-texinfo@@prep.ai.mit.edu -@end group -@end example - -@noindent -Please include the manual's edition number and update date in your messages. - -@node Texinfo Mode, Beginning a File, Overview, Top -@comment node-name, next, previous, up -@chapter Using Texinfo Mode -@cindex Texinfo mode -@cindex Mode, using Texinfo -@cindex GNU Emacs -@cindex Emacs - -You may edit a Texinfo file with any text editor you choose. A Texinfo -file is no different from any other @sc{ascii} file. However, GNU Emacs -comes with a special mode, called Texinfo -mode, that provides Emacs commands and tools to help ease your work.@refill - -This chapter describes features of GNU Emacs' Texinfo mode but not any -features of the Texinfo formatting language. If you are reading this -manual straight through from the beginning, you may want to skim through -this chapter briefly and come back to it after reading succeeding -chapters which describe the Texinfo formatting language in -detail.@refill - -@menu -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. -@end menu - -@node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode -@ifinfo -@heading Texinfo Mode Overview -@end ifinfo - -Texinfo mode provides special features for working with Texinfo -files:@refill - -@itemize @bullet -@item -Insert frequently used @@-commands. @refill - -@item -Automatically create @code{@@node} lines. - -@item -Show the structure of a Texinfo source file.@refill - -@item -Automatically create or update the `Next',@* -`Previous', and `Up' pointers of a node. - -@item -Automatically create or update menus.@refill - -@item -Automatically create a master menu.@refill - -@item -Format a part or all of a file for Info.@refill - -@item -Typeset and print part or all of a file.@refill -@end itemize - -Perhaps the two most helpful features are those for inserting frequently -used @@-commands and for creating node pointers and menus.@refill - -@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode -@section The Usual GNU Emacs Editing Commands - -In most cases, the usual Text mode commands work the same in Texinfo -mode as they do in Text mode. Texinfo mode adds new editing commands -and tools to GNU Emacs' general purpose editing features. The major -difference concerns filling. In Texinfo mode, the paragraph -separation variable and syntax table are redefined so that Texinfo -commands that should be on lines of their own are not inadvertently -included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) -command will refill a paragraph but not mix an indexing command on a -line adjacent to it into the paragraph.@refill - -In addition, Texinfo mode sets the @code{page-delimiter} variable to -the value of @code{texinfo-chapter-level-regexp}; by default, this is -a regular expression matching the commands for chapters and their -equivalents, such as appendices. With this value for the page -delimiter, you can jump from chapter title to chapter title with the -@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} -(@code{backward-page}) commands and narrow to a chapter with the -@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, -The GNU Emacs Manual}, for details about the page commands.)@refill - -You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the three extensions -@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is -preferred, since it is explicit, but a shorter extension may be -necessary for operating systems that limit the length of file names. -GNU Emacs automatically enters Texinfo mode when you visit a file with -a @file{.texinfo} or @file{.texi} -extension. Also, Emacs switches to Texinfo mode -when you visit a -file that has @samp{-*-texinfo-*-} in its first line. If ever you are -in another mode and wish to switch to Texinfo mode, type @code{M-x -texinfo-mode}.@refill - -Like all other Emacs features, you can customize or enhance Texinfo -mode as you wish. In particular, the keybindings are very easy to -change. The keybindings described here are the default or standard -ones.@refill - -@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode -@comment node-name, next, previous, up -@section Inserting Frequently Used Commands -@cindex Inserting frequently used commands -@cindex Frequently used commands, inserting -@cindex Commands, inserting them - -Texinfo mode provides commands to insert various frequently used -@@-commands into the buffer. You can use these commands to save -keystrokes.@refill - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command:@refill - -@table @kbd -@item C-c C-c c -@itemx M-x texinfo-insert-@@code -@findex texinfo-insert-@@code -Insert @code{@@code@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c d -@itemx M-x texinfo-insert-@@dfn -@findex texinfo-insert-@@dfn -Insert @code{@@dfn@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c e -@itemx M-x texinfo-insert-@@end -@findex texinfo-insert-@@end -Insert @code{@@end} and attempt to insert the correct following word, -such as @samp{example} or @samp{table}. (This command does not handle -nested lists correctly, but inserts the word appropriate to the -immediately preceding list.)@refill - -@item C-c C-c i -@itemx M-x texinfo-insert-@@item -@findex texinfo-insert-@@item -Insert @code{@@item} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c k -@itemx M-x texinfo-insert-@@kbd -@findex texinfo-insert-@@kbd -Insert @code{@@kbd@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c n -@itemx M-x texinfo-insert-@@node -@findex texinfo-insert-@@node -Insert @code{@@node} and a comment line -listing the sequence for the `Next', -`Previous', and `Up' nodes. -Leave point after the @code{@@node}.@refill - -@item C-c C-c o -@itemx M-x texinfo-insert-@@noindent -@findex texinfo-insert-@@noindent -Insert @code{@@noindent} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c s -@itemx M-x texinfo-insert-@@samp -@findex texinfo-insert-@@samp -Insert @code{@@samp@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c t -@itemx M-x texinfo-insert-@@table -@findex texinfo-insert-@@table -Insert @code{@@table} followed by a @key{SPC} -and leave the cursor after the @key{SPC}.@refill - -@item C-c C-c v -@itemx M-x texinfo-insert-@@var -@findex texinfo-insert-@@var -Insert @code{@@var@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c x -@itemx M-x texinfo-insert-@@example -@findex texinfo-insert-@@example -Insert @code{@@example} and put the -cursor at the beginning of the next line.@refill - -@c M-@{ was the binding for texinfo-insert-braces; -@c in Emacs 19, backward-paragraph will take this binding. -@item C-c C-c @{ -@itemx M-x texinfo-insert-braces -@findex texinfo-insert-braces -Insert @code{@{@}} and put the cursor between the braces.@refill - -@item C-c C-c @} -@itemx C-c C-c ] -@itemx M-x up-list -@findex up-list -Move from between a pair of braces forward past the closing brace. -Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which -is, however, more mnemonic; hence the two keybindings. (Also, you can -move out from between braces by typing @kbd{C-f}.)@refill -@end table - -To put a command such as @w{@code{@@code@{@dots{}@}}} around an -@emph{existing} word, position the cursor in front of the word and type -@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. -The value of the prefix argument tells Emacs how many words following -point to include between braces---1 for one word, 2 for two words, and -so on. Use a negative argument to enclose the previous word or words. -If you do not specify a prefix argument, Emacs inserts the @@-command -string and positions the cursor between the braces. This feature works -only for those @@-commands that operate on a word or words within one -line, such as @code{@@kbd} and @code{@@var}.@refill - -This set of insert commands was created after analyzing the frequency -with which different @@-commands are used in the @cite{GNU Emacs -Manual} and the @cite{GDB Manual}. If you wish to add your own insert -commands, you can bind a keyboard macro to a key, use abbreviations, -or extend the code in @file{texinfo.el}.@refill - -@findex texinfo-start-menu-description -@cindex Menu description, start -@cindex Description for menu, start -@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert -command that works differently from the other insert commands. It -inserts a node's section or chapter title in the space for the -description in a menu entry line. (A menu entry has three parts, the -entry name, the node name, and the description. Only the node name is -required, but a description helps explain what the node is about. -@xref{Menu Parts, , The Parts of a Menu}.)@refill - -To use @code{texinfo-start-menu-description}, position point in a menu -entry line and type @kbd{C-c C-c C-d}. The command looks for and copies -the title that goes with the node name, and inserts the title as a -description; it positions point at beginning of the inserted text so you -can edit it. The function does not insert the title if the menu entry -line already contains a description.@refill - -This command is only an aid to writing descriptions; it does not do the -whole job. You must edit the inserted text since a title tends to use -the same words as a node name but a useful description uses different -words.@refill - -@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode -@comment node-name, next, previous, up -@section Showing the Section Structure of a File -@cindex Showing the section structure of a file -@cindex Section structure of a file, showing it -@cindex Structure of a file, showing it -@cindex Outline of file structure, showing it -@cindex Contents-like outline of file structure -@cindex File section structure, showing it -@cindex Texinfo file section structure, showing it - -You can show the section structure of a Texinfo file by using the -@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command -shows the section structure of a Texinfo file by listing the lines -that begin with the @@-commands for @code{@@chapter}, -@code{@@section}, and the like. It constructs what amounts -to a table of contents. These lines are displayed in another buffer -called the @samp{*Occur*} buffer. In that buffer, you can position -the cursor over one of the lines and use the @kbd{C-c C-c} command -(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot -in the Texinfo file.@refill - -@table @kbd -@item C-c C-s -@itemx M-x texinfo-show-structure -@findex texinfo-show-structure -Show the @code{@@chapter}, @code{@@section}, and such lines of a -Texinfo file.@refill - -@item C-c C-c -@itemx M-x occur-mode-goto-occurrence -@findex occur-mode-goto-occurrence -Go to the line in the Texinfo file corresponding to the line under the -cursor in the @file{*Occur*} buffer.@refill -@end table - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the -@@-commands for @code{@@chapter}, @code{@@section}, and the like, -but also the @code{@@node} lines. (This is how the -@code{texinfo-show-structure} command worked without an argument in -the first version of Texinfo. It was changed because @code{@@node} -lines clutter up the @samp{*Occur*} buffer and are usually not -needed.) You can use @code{texinfo-show-structure} with a prefix -argument to check whether the `Next', `Previous', and `Up' pointers of -an @code{@@node} line are correct.@refill - -Often, when you are working on a manual, you will be interested only -in the structure of the current chapter. In this case, you can mark -off the region of the buffer that you are interested in by using the -@kbd{C-x n n} (@code{narrow-to-region}) command and -@code{texinfo-show-structure} will work on only that region. To see -the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). -(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more -information about the narrowing commands.)@refill - -@vindex page-delimiter -@cindex Page delimiter in Texinfo mode -In addition to providing the @code{texinfo-show-structure} command, -Texinfo mode sets the value of the page delimiter variable to match -the chapter-level @@-commands. This enables you to use the @kbd{C-x -]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) -commands to move forward and backward by chapter, and to use the -@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter. -@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information -about the page commands.@refill - -@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode -@comment node-name, next, previous, up -@section Updating Nodes and Menus -@cindex Updating nodes and menus -@cindex Create nodes, menus automatically -@cindex Insert nodes, menus automatically -@cindex Automatically insert nodes, menus - -Texinfo mode provides commands for automatically creating or updating -menus and node pointers. The commands are called ``update'' commands -because their most frequent use is for updating a Texinfo file after -you have worked on it; but you can use them to insert the `Next', -`Previous', and `Up' pointers into an @code{@@node} line that has none and to -create menus in a file that has none.@refill - -If you do not use the updating commands, you need to write menus and -node pointers by hand, which is a tedious task.@refill - -@menu -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. -@end menu - -@node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus -@ifinfo -@subheading The Updating Commands -@end ifinfo - -You can use the updating commands@refill - -@itemize @bullet -@item -to insert or update the `Next', `Previous', and `Up' pointers of a -node,@refill - -@item -to insert or update the menu for a section, and@refill - -@item -to create a master menu for a Texinfo source file.@refill -@end itemize - -You can also use the commands to update all the nodes and menus in a -region or in a whole Texinfo file.@refill - -The updating commands work only with conventional Texinfo files, which -are structured hierarchically like books. In such files, a structuring -command line must follow closely after each @code{@@node} line, except -for the `Top' @code{@@node} line. (A @dfn{structuring command line} is -a line beginning with @code{@@chapter}, @code{@@section}, or other -similar command.) - -You can write the structuring command line on the line that follows -immediately after an @code{@@node} line or else on the line that -follows after a single @code{@@comment} line or a single -@code{@@ifinfo} line. You cannot interpose more than one line between -the @code{@@node} line and the structuring command line; and you may -interpose only an @code{@@comment} line or an @code{@@ifinfo} line. - -Commands which work on a whole buffer require that the `Top' node be -followed by a node with an @code{@@chapter} or equivalent-level command. -Note that the menu updating commands will not create a main or master -menu for a Texinfo file that has only @code{@@chapter}-level nodes! The -menu updating commands only create menus @emph{within} nodes for lower level -nodes. To create a menu of chapters, you must provide a `Top' -node.@refill - -The menu updating commands remove menu entries that refer to other Info -files since they do not refer to nodes within the current buffer. This -is a deficiency. Rather than use menu entries, you can use cross -references to refer to other Info files. None of the updating commands -affect cross references.@refill - -Texinfo mode has five updating commands that are used most often: two -are for updating the node pointers or menu of a single node (or a -region); two are for updating every node pointer and menu in a file; -and one, the @code{texinfo-master-menu} command, is for creating a -master menu for a complete file, and optionally, for updating every -node and menu in the whole Texinfo file.@refill - -The @code{texinfo-master-menu} command is the primary command:@refill - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -@findex texinfo-master-menu -Create or update a master menu that includes all the other menus -(incorporating the descriptions from pre-existing menus, if -any).@refill - -With an argument (prefix argument, @kbd{C-u,} if interactive), first create or -update all the nodes and all the regular menus in the buffer before -constructing the master menu. (@xref{The Top Node, , The Top Node and -Master Menu}, for more about a master menu.)@refill - -For @code{texinfo-master-menu} to work, the Texinfo file must have a -`Top' node and at least one subsequent node.@refill - -After extensively editing a Texinfo file, you can type the following: - -@example -C-u M-x texinfo-master-menu -@exdent or -C-u C-c C-u m -@end example - -@noindent -This updates all the nodes and menus completely and all at once.@refill -@end table - -The other major updating commands do smaller jobs and are designed for -the person who updates nodes and menus as he or she writes a Texinfo -file.@refill - -@need 1000 -The commands are:@refill - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -@findex texinfo-update-node -Insert the `Next', `Previous', and `Up' pointers for the node that point is -within (i.e., for the @code{@@node} line preceding point). If the -@code{@@node} line has pre-existing `Next', `Previous', or `Up' -pointers in it, the old pointers are removed and new ones inserted. -With an argument (prefix argument, @kbd{C-u}, if interactive), this command -updates all @code{@@node} lines in the region (which is the text -between point and mark).@refill - -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -@findex texinfo-make-menu -Create or update the menu in the node that point is within. -With an argument (@kbd{C-u} as prefix argument, if -interactive), the command makes or updates menus for the -nodes which are either within or a part of the -region.@refill - -Whenever @code{texinfo-make-menu} updates an existing menu, the -descriptions from that menu are incorporated into the new menu. This -is done by copying descriptions from the existing menu to the entries -in the new menu that have the same node names. If the node names are -different, the descriptions are not copied to the new menu.@refill - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -@findex texinfo-every-node-update -Insert or update the `Next', `Previous', and `Up' pointers for every -node in the buffer.@refill - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -@findex texinfo-all-menus-update -Create or update all the menus in the buffer. With an argument -(@kbd{C-u} as prefix argument, if interactive), first insert -or update all the node -pointers before working on the menus.@refill - -If a master menu exists, the @code{texinfo-all-menus-update} command -updates it; but the command does not create a new master menu if none -already exists. (Use the @code{texinfo-master-menu} command for -that.)@refill - -When working on a document that does not merit a master menu, you can -type the following: - -@example -C-u C-c C-u C-a -@exdent or -C-u M-x texinfo-all-menus-update -@end example - -@noindent -This updates all the nodes and menus.@refill -@end table - -The @code{texinfo-column-for-description} variable specifies the -column to which menu descriptions are indented. By default, the value -is 32 although it is often useful to reduce it to as low as 24. You -can set the variable with the @kbd{M-x edit-options} command -(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs -Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, -, Examining and Setting Variables, emacs, The GNU Emacs -Manual}).@refill - -Also, the @code{texinfo-indent-menu-description} command may be used to -indent existing menu descriptions to a specified column. Finally, if -you wish, you can use the @code{texinfo-insert-node-lines} command to -insert missing @code{@@node} lines into a file. (@xref{Other Updating -Commands}, for more information.)@refill - -@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus -@comment node-name, next, previous, up -@subsection Updating Requirements -@cindex Updating requirements -@cindex Requirements for updating commands - -To use the updating commands, you must organize the Texinfo file -hierarchically with chapters, sections, subsections, and the like. -When you construct the hierarchy of the manual, do not `jump down' -more than one level at a time: you can follow the `Top' node with a -chapter, but not with a section; you can follow a chapter with a -section, but not with a subsection. However, you may `jump up' any -number of levels at one time---for example, from a subsection to a -chapter.@refill - -Each @code{@@node} line, with the exception of the line for the `Top' -node, must be followed by a line with a structuring command such as -@code{@@chapter}, @code{@@section}, or -@code{@@unnumberedsubsec}.@refill - -Each @code{@@node} line/structuring-command line combination -must look either like this:@refill - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@comment node-name, next, previous, up -@@section Comments -@end group -@end example - -or like this (without the @code{@@comment} line): - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@section Comments -@end group -@end example - -@noindent -In this example, `Comments' is the name of both the node and the -section. The next node is called `Minimum' and the previous node is -called `Conventions'. The `Comments' section is within the `Overview' -node, which is specified by the `Up' pointer. (Instead of an -@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill - -If a file has a `Top' node, it must be called @samp{top} or @samp{Top} -and be the first node in the file.@refill - -The menu updating commands create a menu of sections within a chapter, -a menu of subsections within a section, and so on. This means that -you must have a `Top' node if you want a menu of chapters.@refill - -Incidentally, the @code{makeinfo} command will create an Info file for -a hierarchically organized Texinfo file that lacks `Next', `Previous' -and `Up' pointers. Thus, if you can be sure that your Texinfo file -will be formatted with @code{makeinfo}, you have no need for the -`update node' commands. (@xref{Create an Info File, , Creating an -Info File}, for more information about @code{makeinfo}.) However, -both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands -require that you insert menus in the file.@refill - -@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus -@comment node-name, next, previous, up -@subsection Other Updating Commands - -In addition to the five major updating commands, Texinfo mode -possesses several less frequently used updating commands:@refill - -@table @kbd -@item M-x texinfo-insert-node-lines -@findex texinfo-insert-node-lines -Insert @code{@@node} lines before the @code{@@chapter}, -@code{@@section}, and other sectioning commands wherever they are -missing throughout a region in a Texinfo file.@refill - -With an argument (@kbd{C-u} as prefix argument, if interactive), the -@code{texinfo-insert-node-lines} command not only inserts -@code{@@node} lines but also inserts the chapter or section titles as -the names of the corresponding nodes. In addition, it inserts the -titles as node names in pre-existing @code{@@node} lines that lack -names. Since node names should be more concise than section or -chapter titles, you must manually edit node names so inserted.@refill - -For example, the following marks a whole buffer as a region and inserts -@code{@@node} lines and titles throughout:@refill - -@example -C-x h C-u M-x texinfo-insert-node-lines -@end example - -(Note that this command inserts titles as node names in @code{@@node} -lines; the @code{texinfo-start-menu-description} command -(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles -as descriptions in menu entries, a different action. However, in both -cases, you need to edit the inserted text.)@refill - -@item M-x texinfo-multiple-files-update -@findex texinfo-multiple-files-update @r{(in brief)} -Update nodes and menus in a document built from several separate files. -With @kbd{C-u} as a prefix argument, create and insert a master menu in -the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first -update all the menus and all the `Next', `Previous', and `Up' pointers -of all the included files before creating and inserting a master menu in -the outer file. The @code{texinfo-multiple-files-update} command is -described in the appendix on @code{@@include} files. -@ifinfo -@xref{texinfo-multiple-files-update}.@refill -@end ifinfo -@iftex -@xref{texinfo-multiple-files-update, , -@code{texinfo-multiple-files-update}}.@refill -@end iftex - -@item M-x texinfo-indent-menu-description -@findex texinfo-indent-menu-description -Indent every description in the menu following point to the specified -column. You can use this command to give yourself more space for -descriptions. With an argument (@kbd{C-u} as prefix argument, if -interactive), the @code{texinfo-indent-menu-description} command indents -every description in every menu in the region. However, this command -does not indent the second and subsequent lines of a multi-line -description.@refill - -@item M-x texinfo-sequential-node-update -@findex texinfo-sequential-node-update -Insert the names of the nodes immediately following and preceding the -current node as the `Next' or `Previous' pointers regardless of those -nodes' hierarchical level. This means that the `Next' node of a -subsection may well be the next chapter. Sequentially ordered nodes are -useful for novels and other documents that you read through -sequentially. (However, in Info, the @code{g* @key{RET}} command lets -you look through the file sequentially, so sequentially ordered nodes -are not strictly necessary.) With an argument (prefix argument, if -interactive), the @code{texinfo-sequential-node-update} command -sequentially updates all the nodes in the region.@refill -@end table - -@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode -@comment node-name, next, previous, up -@section Formatting for Info -@cindex Formatting for Info -@cindex Running an Info formatter -@cindex Info formatting - -Texinfo mode provides several commands for formatting part or all of a -Texinfo file for Info. Often, when you are writing a document, you -want to format only part of a file---that is, a region.@refill - -You can use either the @code{texinfo-format-region} or the -@code{makeinfo-region} command to format a region:@refill - -@table @kbd -@findex texinfo-format-region -@item C-c C-e C-r -@itemx M-x texinfo-format-region -@itemx C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@end table - -You can use either the @code{texinfo-format-buffer} or the -@code{makeinfo-buffer} command to format a whole buffer:@refill - -@table @kbd -@findex texinfo-format-buffer -@item C-c C-e C-b -@itemx M-x texinfo-format-buffer -@itemx C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@end table - -@need 1000 -For example, after writing a Texinfo file, you can type the following: - -@example -C-u C-c C-u m -@exdent or -C-u M-x texinfo-master-menu -@end example - -@noindent -This updates all the nodes and menus. Then type the following to create -an Info file: - -@example -C-c C-m C-b -@exdent or -M-x makeinfo-buffer -@end example - -For @TeX{} or the Info formatting commands to work, the file @emph{must} -include a line that has @code{@@setfilename} in its header.@refill - -@xref{Create an Info File}, for details about Info formatting.@refill - -@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode -@comment node-name, next, previous, up -@section Formatting and Printing -@cindex Formatting for printing -@cindex Printing a region or buffer -@cindex Region formatting and printing -@cindex Buffer formatting and printing -@cindex Part of file formatting and printing - -Typesetting and printing a Texinfo file is a multi-step process in which -you first create a file for printing (called a @sc{dvi} file), and then -print the file. Optionally, you may also create indices. To do this, -you must run the @code{texindex} command after first running the -@code{tex} typesetting command; and then you must run the @code{tex} -command again. Or else run the @code{texi2dvi} command which -automatically creates indices as needed.@refill - -Often, when you are writing a document, you want to typeset and print -only part of a file to see what it will look like. You can use the -@code{texinfo-tex-region} and related commands for this purpose. Use -the @code{texinfo-tex-buffer} command to format all of a -buffer.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -@findex texinfo-tex-buffer -Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the -buffer, this command automatically creates or updates indices as -needed.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -@findex texinfo-tex-region -Run @TeX{} on the region.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Run @code{texindex} to sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does -not run @code{texindex} automatically; it only runs the @code{tex} -typesetting command. You must run the @code{texinfo-tex-region} command -a second time after sorting the raw index files with the @code{texindex} -command. (Usually, you do not format an index when you format a region, -only when you format a buffer. Now that the @code{texi2dvi} command -exists, there is no little need for this command.)@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -@findex texinfo-tex-print -Print the file (or the part of the file) previously formatted with -@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill -@end table - -For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the -file @emph{must} start with a @samp{\input texinfo} line and must -include an @code{@@settitle} line. The file must end with @code{@@bye} -on a line by itself. (When you use @code{texinfo-tex-region}, you must -surround the @code{@@settitle} line with start-of-header and -end-of-header lines.)@refill - -@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related -commands, such as @code{tex-show-print-queue}.@refill - -@node Texinfo Mode Summary, , Printing, Texinfo Mode -@comment node-name, next, previous, up -@section Texinfo Mode Summary - -In Texinfo mode, each set of commands has default keybindings that -begin with the same keys. All the commands that are custom-created -for Texinfo mode begin with @kbd{C-c}. The keys are somewhat -mnemonic.@refill - -@subheading Insert Commands - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command to be inserted. (It might make more -sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but -@kbd{C-c C-c} is quick to type.)@refill - -@example -C-c C-c c @r{Insert} @samp{@@code}. -C-c C-c d @r{Insert} @samp{@@dfn}. -C-c C-c e @r{Insert} @samp{@@end}. -C-c C-c i @r{Insert} @samp{@@item}. -C-c C-c n @r{Insert} @samp{@@node}. -C-c C-c s @r{Insert} @samp{@@samp}. -C-c C-c v @r{Insert} @samp{@@var}. -C-c C-c @{ @r{Insert braces.} -C-c C-c ] -C-c C-c @} @r{Move out of enclosing braces.} - -@group -C-c C-c C-d @r{Insert a node's section title} - @r{in the space for the description} - @r{in a menu entry line.} -@end group -@end example - -@subheading Show Structure - -The @code{texinfo-show-structure} command is often used within a -narrowed region.@refill - -@example -C-c C-s @r{List all the headings.} -@end example - -@subheading The Master Update Command - -The @code{texinfo-master-menu} command creates a master menu; and can -be used to update every node and menu in a file as well.@refill - -@example -@group -C-c C-u m -M-x texinfo-master-menu - @r{Create or update a master menu.} -@end group - -@group -C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} - @r{create or update all nodes and regular} - @r{menus, and then create a master menu.} -@end group -@end example - -@subheading Update Pointers - -The update pointer commands are invoked by typing @kbd{C-c C-u} and -then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for -@code{texinfo-every-node-update}.@refill - -@example -C-c C-u C-n @r{Update a node.} -C-c C-u C-e @r{Update every node in the buffer.} -@end example - -@subheading Update Menus - -Invoke the update menu commands by typing @kbd{C-c C-u} -and then either @kbd{C-m} for @code{texinfo-make-menu} or -@kbd{C-a} for @code{texinfo-all-menus-update}. To update -both nodes and menus at the same time, precede @kbd{C-c C-u -C-a} with @kbd{C-u}.@refill - -@example -C-c C-u C-m @r{Make or update a menu.} - -@group -C-c C-u C-a @r{Make or update all} - @r{menus in a buffer.} -@end group - -@group -C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} - @r{first create or update all nodes and} - @r{then create or update all menus.} -@end group -@end example - -@subheading Format for Info - -The Info formatting commands that are written in Emacs Lisp are -invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region -or @kbd{C-b} for the whole buffer.@refill - -The Info formatting commands that are written in C and based on the -@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then -either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill - -@need 800 -@noindent -Use the @code{texinfo-format@dots{}} commands: - -@example -@group -C-c C-e C-r @r{Format the region.} -C-c C-e C-b @r{Format the buffer.} -@end group -@end example - -@need 750 -@noindent -Use @code{makeinfo}: - -@example -C-c C-m C-r @r{Format the region.} -C-c C-m C-b @r{Format the buffer.} -C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} -C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} -@end example - -@subheading Typeset and Print - -The @TeX{} typesetting and printing commands are invoked by typing -@kbd{C-c C-t} and then another control command: @kbd{C-r} for -@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, -and so on.@refill - -@example -C-c C-t C-r @r{Run @TeX{} on the region.} -C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} -C-c C-t C-i @r{Run} @code{texindex}. -C-c C-t C-p @r{Print the @sc{dvi} file.} -C-c C-t C-q @r{Show the print queue.} -C-c C-t C-d @r{Delete a job from the print queue.} -C-c C-t C-k @r{Kill the current @TeX{} formatting job.} -C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} -C-c C-t C-l @r{Recenter the output buffer.} -@end example - -@subheading Other Updating Commands - -The `other updating commands' do not have standard keybindings because -they are rarely used. - -@example -@group -M-x texinfo-insert-node-lines - @r{Insert missing @code{@@node} lines in region.} - @r{With @kbd{C-u} as a prefix argument,} - @r{use section titles as node names.} -@end group - -@group -M-x texinfo-multiple-files-update - @r{Update a multi-file document.} - @r{With @kbd{C-u 2} as a prefix argument,} - @r{create or update all nodes and menus} - @r{in all included files first.} -@end group - -@group -M-x texinfo-indent-menu-description - @r{Indent descriptions.} -@end group - -@group -M-x texinfo-sequential-node-update - @r{Insert node pointers in strict sequence.} -@end group -@end example - -@node Beginning a File, Ending a File, Texinfo Mode, Top -@comment node-name, next, previous, up -@chapter Beginning a Texinfo File -@cindex Beginning a Texinfo file -@cindex Texinfo file beginning -@cindex File beginning - -Certain pieces of information must be provided at the beginning of a -Texinfo file, such as the name of the file and the title of the -document.@refill - -@menu -* Four Parts:: Four parts begin a Texinfo file. -* Sample Beginning:: Here is a sample beginning for a Texinfo file. -* Header:: The very beginning of a Texinfo file. -* Info Summary and Permissions:: Summary and copying permissions for Info. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* The Top Node:: Creating the `Top' node and master menu. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. -@end menu - -@node Four Parts, Sample Beginning, Beginning a File, Beginning a File -@ifinfo -@heading Four Parts Begin a File -@end ifinfo - -Generally, the beginning of a Texinfo file has four parts:@refill - -@enumerate -@item -The header, delimited by special comment lines, that includes the -commands for naming the Texinfo file and telling @TeX{} what -definitions' file to use when processing the Texinfo file.@refill - -@item -A short statement of what the file is about, with a copyright notice -and copying permissions. This is enclosed in @code{@@ifinfo} and -@code{@@end ifinfo} commands so that the formatters place it only -in the Info file.@refill - -@item -A title page and copyright page, with a copyright notice and copying -permissions. This is enclosed between @code{@@titlepage} and -@code{@@end titlepage} commands. The title and copyright page appear -only in the printed @w{manual}.@refill - -@item -The `Top' node that contains a menu for the whole Info file. The -contents of this node appear only in the Info file.@refill -@end enumerate - -Also, optionally, you may include the copying conditions for a program -and a warranty disclaimer. The copying section will be followed by an -introduction or else by the first chapter of the manual.@refill - -Since the copyright notice and copying permissions for the Texinfo -document (in contrast to the copying permissions for a program) are in -parts that appear only in the Info file or only in the printed manual, -this information must be given twice.@refill - -@node Sample Beginning, Header, Four Parts, Beginning a File -@comment node-name, next, previous, up -@section Sample Texinfo File Beginning - -The following sample shows what is needed.@refill - -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{name-of-info-file} -@@settitle @var{name-of-manual} -@@setchapternewpage odd -@@c %**end of header - -@@ifinfo -This file documents @dots{} - -Copyright @var{year} @var{copyright-owner} - -@group -Permission is granted to @dots{} -@@end ifinfo -@end group - -@group -@@c This title page illustrates only one of the -@@c two methods of forming a title page. -@end group - -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@end group - -@group -@@c The following two commands -@@c start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} @var{year} @var{copyright-owner} -@end group - -Published by @dots{} - -Permission is granted to @dots{} -@@end titlepage - -@@node Top, Overview, (dir), (dir) - -@@ifinfo -This document describes @dots{} - -This document applies to version @dots{} -of the program named @dots{} -@@end ifinfo - -@group -@@menu -* Copying:: Your rights and freedoms. -* First Chapter:: Getting started @dots{} -* Second Chapter:: @dots{} - @dots{} - @dots{} -@@end menu -@end group - -@group -@@node First Chapter, Second Chapter, top, top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Index entry for First Chapter -@end group -@end example - -@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File -@comment node-name, next, previous, up -@section The Texinfo File Header -@cindex Header for Texinfo files -@cindex Texinfo file header - -Texinfo files start with at least three lines that provide Info and -@TeX{} with necessary information. These are the @code{\input -texinfo} line, the @code{@@settitle} line, and the -@code{@@setfilename} line. If you want to run @TeX{} on just a part -of the Texinfo File, you must write the @code{@@settitle} -and @code{@@setfilename} lines between start-of-header and end-of-header -lines.@refill - -Thus, the beginning of a Texinfo file looks like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@setfilename sample.info -@@settitle Sample Document -@end group -@end example - -@noindent -or else like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header -@end group -@end example - -@menu -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. -* End of Header:: Formatting a region requires this. -@end menu - -@node First Line, Start of Header, Header, Header -@comment node-name, next, previous, up -@subsection The First Line of a Texinfo File -@cindex First line of a Texinfo file -@cindex Beginning line of a Texinfo file -@cindex Header of a Texinfo file - -Every Texinfo file that is to be the top-level input to @TeX{} must begin -with a line that looks like this:@refill - -@example -\input texinfo @@c -*-texinfo-*- -@end example - -@noindent -This line serves two functions: - -@enumerate -@item -When the file is processed by @TeX{}, the @code{\input texinfo} command -tells @TeX{} to load the macros needed for processing a Texinfo file. -These are in a file called @file{texinfo.tex}, which is usually located -in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash, -@samp{\}, to mark the beginning of a command, just as Texinfo uses -@code{@@}. The @file{texinfo.tex} file causes the switch from @samp{\} -to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which -is why it appears at the beginning of the file.@refill - -@item -When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode -specification tells Emacs to use Texinfo mode.@refill -@end enumerate - -@node Start of Header, setfilename, First Line, Header -@comment node-name, next, previous, up -@subsection Start of Header -@cindex Start of header line - -Write a start-of-header line on the second line of a Texinfo file. -Follow the start-of-header line with @code{@@setfilename} and -@code{@@settitle} lines and, optionally, with other command lines, such -as @code{@@smallbook} or @code{@@footnotestyle}; and then by an -end-of-header line (@pxref{End of Header}).@refill - -With these lines, you can format part of a Texinfo file for Info or -typeset part for printing.@refill - -A start-of-header line looks like this:@refill - -@example -@@c %**start of header -@end example - -The odd string of characters, @samp{%**}, is to ensure that no other -comment is accidentally taken for a start-of-header line.@refill - -@node setfilename, settitle, Start of Header, Header -@comment node-name, next, previous, up -@subsection @code{@@setfilename} -@cindex Info file requires @code{@@setfilename} -@findex setfilename - -In order to serve as the primary input file for either @code{makeinfo} -or @TeX{}, a Texinfo file must contain a line that looks like this: - -@example -@@setfilename @var{info-file-name} -@end example - -Write the @code{@@setfilename} command at the beginning of a line and -follow it on the same line by the Info file name. Do not write -anything else on the line; anything on the line after the command is -considered part of the file name, including a comment.@refill - -The @code{@@setfilename} line specifies the name of the Info file to be -generated. This name should be different from the name of the Texinfo -file. There are two conventions for choosing the name: you can either -remove the @samp{.tex} extension from the input file name, or replace it -with the @samp{.info} extension. - -Some operating systems cannot handle long file names. You can run into -a problem even when the file name you specify is itself short enough. -This occurs because the Info formatters split a long Info file into -short indirect subfiles, and name them by appending `-1', `-2', @dots{}, -`-10', `-11', and so on, to the original file name. (@xref{Tag and -Split Files, , Tag Files and Split Files}.) The subfile name -@file{texinfo.info-10}, for example, is too long for some systems; so -the Info file name for this document is @file{texinfo} rather than -@file{texinfo.info}.@refill - -The Info formatting commands ignore everything written before the -@code{@@setfilename} line, which is why the very first line of -the file (the @code{\input} line) does not need to be commented out. - -The @code{@@setfilename} line produces no output when you typeset a -printed manual, but is does an essential job: it opens the index, -cross-reference, and other auxiliary files used by Texinfo. - -@node settitle, setchapternewpage, setfilename, Header -@comment node-name, next, previous, up -@subsection @code{@@settitle} -@findex settitle - -In order to be made into a printed manual, a Texinfo file must contain -a line that looks like this:@refill - -@example -@@settitle @var{title} -@end example - -Write the @code{@@settitle} command at the beginning of a line and -follow it on the same line by the title. This tells @TeX{} the title -to use in a header or footer. Do not write anything else on the line; -anything on the line after the command is considered part of the -title, including a comment.@refill - -Conventionally, when @TeX{} formats a Texinfo file for double-sided -output, the title is printed in the left-hand (even-numbered) page -headings and the current chapter title is printed in the right-hand -(odd-numbered) page headings. (@TeX{} learns the title of each chapter -from each @code{@@chapter} command.) Page footers are not -printed.@refill - -Even if you are printing in a single-sided style, @TeX{} looks for an -@code{@@settitle} command line, in case you include the manual title -in the heading. @refill - -The @code{@@settitle} command should precede everything that generates -actual output in @TeX{}.@refill - -Although the title in the @code{@@settitle} command is usually the -same as the title on the title page, it does not affect the title as -it appears on the title page. Thus, the two do not need not match -exactly; and the title in the @code{@@settitle} command can be a -shortened or expanded version of the title as it appears on the title -page. (@xref{titlepage, , @code{@@titlepage}}.)@refill - -@TeX{} prints page headings only for that text that comes after the -@code{@@end titlepage} command in the Texinfo file, or that comes -after an @code{@@headings} command that turns on headings. -(@xref{headings on off, , The @code{@@headings} Command}, for more -information.)@refill - -You may, if you wish, create your own, customized headings and -footings. @xref{Headings, , Page Headings}, for a detailed discussion -of this process.@refill - -@node setchapternewpage, paragraphindent, settitle, Header -@comment node-name, next, previous, up -@subsection @code{@@setchapternewpage} -@cindex Starting chapters -@cindex Pages, starting odd -@findex setchapternewpage - -In a book or a manual, text is usually printed on both sides of the -paper, chapters start on right-hand pages, and right-hand pages have -odd numbers. But in short reports, text often is printed only on one -side of the paper. Also in short reports, chapters sometimes do not -start on new pages, but are printed on the same page as the end of the -preceding chapter, after a small amount of vertical whitespace.@refill - -You can use the @code{@@setchapternewpage} command with various -arguments to specify how @TeX{} should start chapters and whether it -should typeset pages for printing on one or both sides of the paper -(single-sided or double-sided printing).@refill - -Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument.@refill - -For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page:@refill - -@example -@@setchapternewpage odd -@end example - -You can specify one of three alternatives with the -@code{@@setchapternewpage} command:@refill - -@table @asis -@ignore -@item No @code{@@setchapternewpage} command -If the Texinfo file does not contain an @code{@@setchapternewpage} -command before the @code{@@titlepage} command, @TeX{} automatically -begins chapters on new pages and prints headings in the standard -format for single-sided printing. This is the conventional format for -single-sided printing.@refill - -The result is exactly the same as when you write -@code{@@setchapternewpage on}.@refill -@end ignore -@item @code{@@setchapternewpage off} -Cause @TeX{} to typeset a new chapter on the same page as the last -chapter, after skipping some vertical whitespace. Also, cause @TeX{} to -format page headers for single-sided printing. (You can override the -headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to typeset page -headers for single-sided printing. This is the form most often -used for short reports.@refill - -This alternative is the default.@refill - -@item @code{@@setchapternewpage odd} -Cause @TeX{} to start new chapters on new, odd-numbered pages -(right-handed pages) and to typeset for double-sided printing. This is -the form most often used for books and manuals.@refill -@end table - -@noindent -Texinfo does not have an @code{@@setchapternewpage even} command.@refill - -@noindent -(You can countermand or modify an @code{@@setchapternewpage} command -with an @code{@@headings} command. @xref{headings on off, , The -@code{@@headings} Command}.)@refill - -At the beginning of a manual or book, pages are not numbered---for -example, the title and copyright pages of a book are not numbered. -By convention, table of contents pages are numbered with roman -numerals and not in sequence with the rest of the document.@refill - -Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it.@refill - -Usually, you do not write an @code{@@setchapternewpage} command for -single-sided printing, but accept the default which is to typeset for -single-sided printing and to start new chapters on new pages. Usually, -you write an @code{@@setchapternewpage odd} command for double-sided -printing.@refill - -@node paragraphindent, End of Header, setchapternewpage, Header -@comment node-name, next, previous, up -@subsection Paragraph Indenting -@cindex Indenting paragraphs -@cindex Paragraph indentation -@findex paragraphindent - -The Info formatting commands may insert spaces at the beginning of the -first line of each paragraph, thereby indenting that paragraph. You -can use the @code{@@paragraphindent} command to specify the -indentation. Write an @code{@@paragraphindent} command at the -beginning of a line followed by either @samp{asis} or a number. The -template is:@refill - -@example -@@paragraphindent @var{indent} -@end example - -The Info formatting commands indent according to the value of -@var{indent}:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, the Info formatting -commands do not change the existing indentation.@refill - -@item -If the value of @var{indent} is 0, the Info formatting commands delete -existing indentation.@refill - -@item -If the value of @var{indent} is greater than 0, the Info formatting -commands indent the paragraph by that number of spaces.@refill -@end itemize - -The default value of @var{indent} is @samp{asis}.@refill - -Write the @code{@@paragraphindent} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you write -the command between the start-of-header and end-of-header lines, the -region formatting commands indent paragraphs as specified.)@refill - -A peculiarity of the @code{texinfo-format-buffer} and -@code{texinfo-format-region} commands is that they do not indent (nor -fill) paragraphs that contain @code{@@w} or @code{@@*} commands. -@xref{Refilling Paragraphs}, for a detailed description of what goes -on.@refill - -@node End of Header, , paragraphindent, Header -@comment node-name, next, previous, up -@subsection End of Header -@cindex End of header line - -Follow the header lines with an @w{end-of-header} line. -An end-of-header line looks like this:@refill - -@example -@@c %**end of header -@end example - -If you include the @code{@@setchapternewpage} command between the -start-of-header and end-of-header lines, @TeX{} will typeset a region as -that command specifies. Similarly, if you include an @code{@@smallbook} -command between the start-of-header and end-of-header lines, @TeX{} will -typeset a region in the ``small'' book format.@refill - -@ifinfo -The reason for the odd string of characters (@samp{%**}) is so that the -@code{texinfo-tex-region} command does not accidentally find -something that it should not when it is looking for the header.@refill - -The start-of-header line and the end-of-header line are Texinfo mode -variables that you can change.@refill -@end ifinfo - -@iftex -@xref{Start of Header}. -@end iftex - -@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File -@comment node-name, next, previous, up -@section Summary and Copying Permissions for Info - -The title page and the copyright page appear only in the printed copy of -the manual; therefore, the same information must be inserted in a -section that appears only in the Info file. This section usually -contains a brief description of the contents of the Info file, a -copyright notice, and copying permissions.@refill - -The copyright notice should read:@refill - -@example -Copyright @var{year} @var{copyright-owner} -@end example - -@noindent -and be put on a line by itself.@refill - -Standard text for the copyright permissions is contained in an appendix -to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying -Permissions}, for the complete text.@refill - -The permissions text appears in an Info file @emph{before} the first -node. This mean that a reader does @emph{not} see this text when -reading the file using Info, except when using the advanced Info command -@kbd{g *}. - -@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File -@comment node-name, next, previous, up -@section The Title and Copyright Pages - -A manual's name and author are usually printed on a title page. -Sometimes copyright information is printed on the title page as well; -more often, copyright information is printed on the back of the title -page. - -The title and copyright pages appear in the printed manual, but not in the -Info file. Because of this, it is possible to use several slightly -obscure @TeX{} typesetting commands that cannot be used in an Info file. -In addition, this part of the beginning of a Texinfo file contains the text -of the copying permissions that will appear in the printed manual.@refill - -@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the -standard text for the copyright permissions.@refill - -@menu -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright & Permissions:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. -@end menu - -@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@titlepage} -@cindex Title page -@findex titlepage - -Start the material for the title page and following copyright page -with @code{@@titlepage} on a line by itself and end it with -@code{@@end titlepage} on a line by itself.@refill - -The @code{@@end titlepage} command starts a new page and turns on page -numbering. (@xref{Headings, , Page Headings}, for details about how to -generate page headings.) All the material that you want to -appear on unnumbered pages should be put between the -@code{@@titlepage} and @code{@@end titlepage} commands. By using the -@code{@@page} command you can force a page break within the region -delineated by the @code{@@titlepage} and @code{@@end titlepage} -commands and thereby create more than one unnumbered page. This is -how the copyright page is produced. (The @code{@@titlepage} command -might perhaps have been better named the -@code{@@titleandadditionalpages} command, but that would have been -rather long!)@refill - -@c !!! append refill to footnote when makeinfo can handle it. -When you write a manual about a computer program, you should write the -version of the program to which the manual applies on the title -page. If the manual changes more frequently than the program or is -independent of it, you should also include an edition -number@footnote{We have found that it is helpful to refer to versions -of manuals as `editions' and versions of programs as `versions'; -otherwise, we find we are liable to confuse each other in conversation -by referring to both the documentation and the software with the same -words.} for the manual. This helps readers keep track of which manual -is for which version of the program. (The `Top' node -should also contain this information; see @ref{makeinfo top, , -@code{@@top}}.)@refill - -Texinfo provides two main methods for creating a title page. One method -uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands -to generate a title page in which the words on the page are -centered.@refill - -The second method uses the @code{@@title}, @code{@@subtitle}, and -@code{@@author} commands to create a title page with black rules under -the title and author lines and the subtitle text set flush to the -right hand side of the page. With this method, you do not specify any -of the actual formatting of the title page. You specify the text -you want, and Texinfo does the formatting. You may use either -method.@refill - -@findex shorttitlepage -For extremely simple applications, Texinfo also provides a command -@code{@@shorttitlepage} which takes a single argument as the title. -The argument is typeset on a page by itself and followed by a blank -page. - - -@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} -@findex titlefont -@findex center -@findex sp @r{(titlepage line spacing)} - -You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} -commands to create a title page for a printed document. (This is the -first of the two methods for creating a title page in Texinfo.)@refill - -Use the @code{@@titlefont} command to select a large font suitable for -the title itself.@refill - -@need 700 -For example: - -@example -@@titlefont@{Texinfo@} -@end example - -Use the @code{@@center} command at the beginning of a line to center -the remaining text on that line. Thus,@refill - -@example -@@center @@titlefont@{Texinfo@} -@end example - -@noindent -centers the title, which in this example is ``Texinfo'' printed -in the title font.@refill - -Use the @code{@@sp} command to insert vertical space. For example:@refill - -@example -@@sp 2 -@end example - -@noindent -This inserts two blank lines on the printed page. (@xref{sp, , -@code{@@sp}}, for more information about the @code{@@sp} -command.)@refill - -A template for this method looks like this:@refill - -@example -@group -@@titlepage -@@sp 10 -@@center @@titlefont@{@var{name-of-manual-when-printed}@} -@@sp 2 -@@center @var{subtitle-if-any} -@@sp 2 -@@center @var{author} -@dots{} -@@end titlepage -@end group -@end example - -The spacing of the example fits an 8 1/2 by 11 inch manual.@refill - -@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} -@findex title -@findex subtitle -@findex author - -You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} -commands to create a title page in which the vertical and horizontal -spacing is done for you automatically. This contrasts with the method -described in -the previous section, in which the @code{@@sp} command is needed to -adjust vertical spacing.@refill - -Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} -commands at the beginning of a line followed by the title, subtitle, -or author.@refill - -The @code{@@title} command produces a line in which the title is set -flush to the left-hand side of the page in a larger than normal font. -The title is underlined with a black rule.@refill - -The @code{@@subtitle} command sets subtitles in a normal-sized font -flush to the right-hand side of the page.@refill - -The @code{@@author} command sets the names of the author or authors in -a middle-sized font flush to the left-hand side of the page on a line -near the bottom of the title page. The names are underlined with a -black rule that is thinner than the rule that underlines the title. -(The black rule only occurs if the @code{@@author} command line is -followed by an @code{@@page} command line.)@refill - -There are two ways to use the @code{@@author} command: you can write -the name or names on the remaining part of the line that starts with -an @code{@@author} command:@refill - -@example -@@author by Jane Smith and John Doe -@end example - -@noindent -or you can write the names one above each other by using two (or more) -@code{@@author} commands:@refill - -@example -@group -@@author Jane Smith -@@author John Doe -@end group -@end example - -@noindent -(Only the bottom name is underlined with a black rule.)@refill - -@need 950 -A template for this method looks like this:@refill - -@example -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@@page -@dots{} -@@end titlepage -@end group -@end example - -@ifinfo -@noindent -Contrast this form with the form of a title page written using the -@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill - -@example -@@titlepage -@@sp 10 -@@center @@titlefont@{Name of Manual When Printed@} -@@sp 2 -@@center Subtitle, If Any -@@sp 1 -@@center Second subtitle -@@sp 2 -@@center Author -@@page -@dots{} -@@end titlepage -@end example -@end ifinfo - -@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection Copyright Page and Permissions -@cindex Copyright page -@cindex Printed permissions -@cindex Permissions, printed - -By international treaty, the copyright notice for a book should be -either on the title page or on the back of the title page. The -copyright notice should include the year followed by the name of the -organization or person who owns the copyright.@refill - -When the copyright notice is on the back of the title page, that page -is customarily not numbered. Therefore, in Texinfo, the information -on the copyright page should be within @code{@@titlepage} and -@code{@@end titlepage} commands.@refill - -@findex vskip -@findex filll -@cindex Vertical whitespace (@samp{vskip}) -Use the @code{@@page} command to cause a page break. To push the -copyright notice and the other text on the copyright page towards the -bottom of the page, you can write a somewhat mysterious line after the -@code{@@page} command that reads like this:@refill - -@example -@@vskip 0pt plus 1filll -@end example - -@noindent -This is a @TeX{} command that is not supported by the Info formatting -commands. The @code{@@vskip} command inserts whitespace. The -@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace, -and as much optional whitespace as needed to push the -following text to the bottom of the page. Note the use of three -@samp{l}s in the word @samp{filll}; this is the correct usage in -@TeX{}.@refill - -@findex copyright -In a printed manual, the @code{@@copyright@{@}} command generates a -@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The -copyright notice itself has the following legally defined sequence:@refill - -@example -Copyright @copyright{} @var{year} @var{copyright-owner} -@end example - -It is customary to put information on how to get a manual after the -copyright notice, followed by the copying permissions for the -manual.@refill - -Note that permissions must be given here as well as in the summary -segment within @code{@@ifinfo} and @code{@@end ifinfo} that -immediately follows the header since this text appears only in the -printed manual and the @samp{ifinfo} text appears only in the Info -file.@refill - -@xref{Sample Permissions}, for the standard text.@refill - -@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection Heading Generation -@findex end titlepage -@cindex Headings, page, begin to appear -@cindex Titlepage end starts headings -@cindex End titlepage starts headings - -An @code{@@end titlepage} command on a line by itself not only marks -the end of the title and copyright pages, but also causes @TeX{} to start -generating page headings and page numbers. - -To repeat what is said elsewhere, Texinfo has two standard page heading -formats, one for documents which are printed on one side of each sheet of paper -(single-sided printing), and the other for documents which are printed on both -sides of each sheet (double-sided printing). -(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.) -You can specify these formats in different ways:@refill - -@itemize @bullet -@item -The conventional way is to write an @code{@@setchapternewpage} command -before the title page commands, and then have the @code{@@end -titlepage} command start generating page headings in the manner desired. -(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill - -@item -Alternatively, you can use the @code{@@headings} command to prevent page -headings from being generated or to start them for either single or -double-sided printing. (Write an @code{@@headings} command immediately -after the @code{@@end titlepage} command. @xref{headings on off, , The -@code{@@headings} Command}, for more information.)@refill - -@item -Or, you may specify your own page heading and footing format. -@xref{Headings, , Page Headings}, for detailed -information about page headings and footings.@refill -@end itemize - -Most documents are formatted with the standard single-sided or -double-sided format, using @code{@@setchapternewpage odd} for -double-sided printing and no @code{@@setchapternewpage} command for -single-sided printing.@refill - -@node headings on off, , end titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up -@subsection The @code{@@headings} Command -@findex headings - -The @code{@@headings} command is rarely used. It specifies what kind of -page headings and footings to print on each page. Usually, this is -controlled by the @code{@@setchapternewpage} command. You need the -@code{@@headings} command only if the @code{@@setchapternewpage} command -does not do what you want, or if you want to turn off pre-defined page -headings prior to defining your own. Write an @code{@@headings} command -immediately after the @code{@@end titlepage} command.@refill - -You can use @code{@@headings} as follows:@refill - -@table @code -@item @@headings off -Turn off printing of page headings.@refill - -@item @@headings single -Turn on page headings appropriate for single-sided printing. -@refill - -@item @@headings double -Turn on page headings appropriate for double-sided printing. The two -commands, @code{@@headings on} and @code{@@headings double}, are -synonymous.@refill - -@item @@headings singleafter -@itemx @@headings doubleafter -Turn on @code{single} or @code{double} headings, respectively, after the -current page is output. - -@item @@headings on -Turn on page headings: @code{single} if @samp{@@setchapternewpage -on}, @code{double} otherwise. -@end table - -For example, suppose you write @code{@@setchapternewpage off} before the -@code{@@titlepage} command to tell @TeX{} to start a new chapter on the -same page as the end of the last chapter. This command also causes -@TeX{} to typeset page headers for single-sided printing. To cause -@TeX{} to typeset for double sided printing, write @code{@@headings -double} after the @code{@@end titlepage} command. - -You can stop @TeX{} from generating any page headings at all by -writing @code{@@headings off} on a line of its own immediately after the -line containing the @code{@@end titlepage} command, like this:@refill - -@example -@@end titlepage -@@headings off -@end example - -@noindent -The @code{@@headings off} command overrides the @code{@@end titlepage} -command, which would otherwise cause @TeX{} to print page -headings.@refill - -You can also specify your own style of page heading and footing. -@xref{Headings, , Page Headings}, for more information.@refill - -@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File -@comment node-name, next, previous, up -@section The `Top' Node and Master Menu -@cindex @samp{@r{Top}} node -@cindex Master menu -@cindex Node, `Top' - -The `Top' node is the node from which you enter an Info file.@refill - -A `Top' node should contain a brief description of the Info file and an -extensive, master menu for the whole Info file. -This helps the reader understand what the Info file is -about. Also, you should write the version number of the program to -which the Info file applies; or, at least, the edition number.@refill - -The contents of the `Top' node should appear only in the Info file; none -of it should appear in printed output, so enclose it between -@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not -print either an @code{@@node} line or a menu; they appear only in Info; -strictly speaking, you are not required to enclose these parts between -@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so. -@xref{Conditionals, , Conditionally Visible Text}.)@refill - -@menu -* Title of Top Node:: Sketch what the file is about. -* Master Menu Parts:: A master menu has three or more parts. -@end menu - -@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node -@ifinfo -@subheading `Top' Node Title -@end ifinfo - -Sometimes, you will want to place an @code{@@top} sectioning command -line containing the title of the document immediately after the -@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top} -Sectioning Command}, for more information).@refill - -For example, the beginning of the Top node of this manual contains an -@code{@@top} sectioning command, a short description, and edition and -version information. It looks like this:@refill - -@example -@group -@dots{} -@@end titlepage - -@@ifinfo -@@node Top, Copying, (dir), (dir) -@@top Texinfo - -Texinfo is a documentation system@dots{} -@end group - -@group -This is edition@dots{} -@dots{} -@@end ifinfo -@end group - -@group -@@menu -* Copying:: Texinfo is freely - redistributable. -* Overview:: What is Texinfo? -@dots{} -@end group -@@end menu -@end example - -In a `Top' node, the `Previous', and `Up' nodes usually refer to the top -level directory of the whole Info system, which is called @samp{(dir)}. -The `Next' node refers to the first node that follows the main or master -menu, which is usually the copying permissions, introduction, or first -chapter.@refill - -@node Master Menu Parts, , Title of Top Node, The Top Node -@subsection Parts of a Master Menu -@cindex Master menu parts -@cindex Parts of a master menu - -A @dfn{master menu} is a detailed main menu listing all the nodes in a -file. - -A master menu is enclosed in @code{@@menu} and @code{@@end menu} -commands and does not appear in the printed document.@refill - -Generally, a master menu is divided into parts.@refill - -@itemize @bullet -@item -The first part contains the major nodes in the Texinfo file: the nodes -for the chapters, chapter-like sections, and the appendices.@refill - -@item -The second part contains nodes for the indices.@refill - -@item -The third and subsequent parts contain a listing of the other, lower -level nodes, often ordered by chapter. This way, rather than go -through an intermediary menu, an inquirer can go directly to a -particular node when searching for specific information. These menu -items are not required; add them if you think they are a -convenience. If you do use them, put @code{@@detailmenu} before the -first one, and @code{@@end detailmenu} after the last; otherwise, -@code{makeinfo} will get confused. -@end itemize - -Each section in the menu can be introduced by a descriptive line. So -long as the line does not begin with an asterisk, it will not be -treated as a menu entry. (@xref{Writing a Menu}, for more -information.)@refill - -For example, the master menu for this manual looks like the following -(but has many more entries):@refill - -@example -@group -@@menu -* Copying:: Texinfo is freely - redistributable. -* Overview:: What is Texinfo? -* Texinfo Mode:: Special features in GNU Emacs. -@dots{} -@dots{} -@end group -@group -* Command and Variable Index:: - An entry for each @@-command. -* Concept Index:: An entry for each concept. -@end group - -@group -@@detailmenu - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Info Files:: What is an Info file? -* Printed Manuals:: Characteristics of - a printed manual. -@dots{} -@dots{} -@end group - -@group -Using Texinfo Mode - -* Info on a Region:: Formatting part of a file - for Info. -@dots{} -@dots{} -@@end detailmenu -@@end menu -@end group -@end example - -@node Software Copying Permissions, , The Top Node, Beginning a File -@comment node-name, next, previous, up -@section Software Copying Permissions -@cindex Software copying permissions -@cindex Copying software -@cindex Distribution -@cindex License agreement - -If the Texinfo file has a section containing the ``General Public -License'' and the distribution information and a warranty disclaimer -for the software that is documented, this section usually follows the -`Top' node. The General Public License is very important to Project -GNU software. It ensures that you and others will continue to have a -right to use and share the software.@refill - -The copying and distribution information and the disclaimer are -followed by an introduction or else by the first chapter of the -manual.@refill - -@cindex Introduction, as part of file -Although an introduction is not a required part of a Texinfo file, it -is very helpful. Ideally, it should state clearly and concisely what -the file is about and who would be interested in reading it. In -general, an introduction would follow the licensing and distribution -information, although sometimes people put it earlier in the document. -Usually, an introduction is put in an @code{@@unnumbered} section. -(@xref{unnumbered & appendix, , The @code{@@unnumbered} and -@code{@@appendix} Commands}.)@refill - -@node Ending a File, Structuring, Beginning a File, Top -@comment node-name, next, previous, up -@chapter Ending a Texinfo File -@cindex Ending a Texinfo file -@cindex Texinfo file ending -@cindex File ending -@findex bye - -The end of a Texinfo file should include the commands that create -indices and generate detailed and summary tables of contents. -And it must include the @code{@@bye} command that marks the last line -processed by @TeX{}.@refill - -@need 700 -For example: - -@example -@@node Concept Index, , Variables Index, Top -@@c node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp - -@@contents -@@bye -@end example - -@menu -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* Contents:: How to create a table of contents. -* File End:: How to mark the end of a file. -@end menu - -@node Printing Indices & Menus, Contents, Ending a File, Ending a File -@comment node-name, next, previous, up -@section Index Menus and Printing an Index -@findex printindex -@cindex Printing an index -@cindex Indices, printing and menus -@cindex Generating menus with indices -@cindex Menus generated with indices - -To print an index means to include it as part of a manual or Info -file. This does not happen automatically just because you use -@code{@@cindex} or other index-entry generating commands in the -Texinfo file; those just cause the raw data for the index to be -accumulated. To generate an index, you must include the -@code{@@printindex} command at the place in the document where you -want the index to appear. Also, as part of the process of creating a -printed manual, you must run a program called @code{texindex} -(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted -index file. The sorted index file is what is actually used to -print the index.@refill - -Texinfo offers six different types of predefined index: the concept -index, the function index, the variables index, the keystroke index, the -program index, and the data type index (@pxref{Predefined Indices}). Each -index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr}, -@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them -into separate sections (@pxref{Combining Indices}); or you may define -your own indices (@pxref{New Indices, , Defining New Indices}).@refill - -The @code{@@printindex} command takes a two-letter index name, reads -the corresponding sorted index file and formats it appropriately into -an index.@refill - -@ignore -The two-letter index names are: - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table -@end ignore -The @code{@@printindex} command does not generate a chapter heading -for the index. Consequently, you should precede the -@code{@@printindex} command with a suitable section or chapter command -(usually @code{@@unnumbered}) to supply the chapter heading and put -the index into the table of contents. Precede the @code{@@unnumbered} -command with an @code{@@node} line.@refill - -@need 1200 -For example: - -@smallexample -@group -@@node Variable Index, Concept Index, Function Index, Top -@@comment node-name, next, previous, up -@@unnumbered Variable Index - -@@printindex vr -@end group - -@group -@@node Concept Index, , Variable Index, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp -@end group - -@group -@@summarycontents -@@contents -@@bye -@end group -@end smallexample - -@noindent -(Readers often prefer that the concept index come last in a book, -since that makes it easiest to find.)@refill - -@ignore -In @TeX{}, the @code{@@printindex} command needs a sorted index file -to work from. @TeX{} does not know how to do sorting; this is a -deficiency. @TeX{} writes output files of raw index data; use the -@code{texindex} program to convert these files to sorted index files. -(@xref{Format/Print Hardcopy}, for more information.)@refill -@end ignore -@node Contents, File End, Printing Indices & Menus, Ending a File -@comment node-name, next, previous, up -@section Generating a Table of Contents -@cindex Table of contents -@cindex Contents, Table of -@findex contents -@findex summarycontents -@findex shortcontents - -The @code{@@chapter}, @code{@@section}, and other structuring commands -supply the information to make up a table of contents, but they do not -cause an actual table to appear in the manual. To do this, you must -use the @code{@@contents} and @code{@@summarycontents} -commands:@refill - -@table @code -@item @@contents -Generate a table of contents in a printed manual, including all -chapters, sections, subsections, etc., as well as appendices and -unnumbered chapters. (Headings generated by the @code{@@heading} -series of commands do not appear in the table of contents.) The -@code{@@contents} command should be written on a line by -itself.@refill - -@item @@shortcontents -@itemx @@summarycontents -(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the -two commands are exactly the same.)@refill - -Generate a short or summary table of contents that lists only the -chapters (and appendices and unnumbered chapters). Omit sections, subsections -and subsubsections. Only a long manual needs a short table -of contents in addition to the full table of contents.@refill - -Write the @code{@@shortcontents} command on a line by itself right -@emph{before} the @code{@@contents} command.@refill -@end table - -The table of contents commands automatically generate a chapter-like -heading at the top of the first table of contents page. Write the table -of contents commands at the very end of a Texinfo file, just before the -@code{@@bye} command, following any index sections---anything in the -Texinfo file after the table of contents commands will be omitted from -the table of contents.@refill - -When you print a manual with a table of contents, the table of -contents are printed last and numbered with roman numerals. You need -to place those pages in their proper place, after the title page, -yourself. (This is the only collating you need to do for a printed -manual. The table of contents is printed last because it is generated -after the rest of the manual is typeset.)@refill - -@need 700 -Here is an example of where to write table of contents commands:@refill - -@example -@group -@var{indices}@dots{} -@@shortcontents -@@contents -@@bye -@end group -@end example - -Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the @code{@@contents} and -@code{@@shortcontents} commands.@refill - -@node File End, , Contents, Ending a File -@comment node-name, next, previous, up -@section @code{@@bye} File Ending -@findex bye - -An @code{@@bye} command terminates @TeX{} or Info formatting. None of -the formatting commands see any of the file following @code{@@bye}. -The @code{@@bye} command should be on a line by itself.@refill - -If you wish, you may follow the @code{@@bye} line with notes. These notes -will not be formatted and will not appear in either Info or a printed -manual; it is as if text after @code{@@bye} were within @code{@@ignore} -@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line -with a local variables list. @xref{Compile-Command, , Using Local -Variables and the Compile Command}, for more information.@refill - -@node Structuring, Nodes, Ending a File, Top -@comment node-name, next, previous, up -@chapter Chapter Structuring -@cindex Chapter structuring -@cindex Structuring of chapters - -The @dfn{chapter structuring} commands divide a document into a hierarchy of -chapters, sections, subsections, and subsubsections. These commands -generate large headings; they also provide information for the table -of contents of a printed manual (@pxref{Contents, , Generating a Table -of Contents}).@refill - -The chapter structuring commands do not create an Info node structure, -so normally you should put an @code{@@node} command immediately before -each chapter structuring command (@pxref{Nodes}). The only time you -are likely to use the chapter structuring commands without using the -node structuring commands is if you are writing a document that -contains no cross references and will never be transformed into Info -format.@refill - -It is unlikely that you will ever write a Texinfo file that is -intended only as an Info file and not as a printable document. If you -do, you might still use chapter structuring commands to create a -heading at the top of each node---but you don't need to.@refill - -@menu -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. -@end menu - -@node Tree Structuring, Structuring Command Types, Structuring, Structuring -@comment node-name, next, previous, up -@section Tree Structure of Sections -@cindex Tree structuring - -A Texinfo file is usually structured like a book with chapters, -sections, subsections, and the like. This structure can be visualized -as a tree (or rather as an upside-down tree) with the root at the top -and the levels corresponding to chapters, sections, subsection, and -subsubsections.@refill - -Here is a diagram that shows a Texinfo file with three chapters, -each of which has two sections.@refill - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | - Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - -@end group -@end example - -In a Texinfo file that has this structure, the beginning of Chapter 2 -looks like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@chapter Chapter 2 -@end group -@end example - -The chapter structuring commands are described in the sections that -follow; the @code{@@node} and @code{@@menu} commands are described in -following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill - -@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring -@comment node-name, next, previous, up -@section Types of Structuring Command - -The chapter structuring commands fall into four groups or series, each -of which contains structuring commands corresponding to the -hierarchical levels of chapters, sections, subsections, and -subsubsections.@refill - -The four groups are the @code{@@chapter} series, the -@code{@@unnumbered} series, the @code{@@appendix} series, and the -@code{@@heading} series.@refill - -Each command produces titles that have a different appearance on the -printed page or Info file; only some of the commands produce -titles that are listed in the table of contents of a printed book or -manual.@refill - -@itemize @bullet -@item -The @code{@@chapter} and @code{@@appendix} series of commands produce -numbered or lettered entries both in the body of a printed work and in -its table of contents.@refill - -@item -The @code{@@unnumbered} series of commands produce unnumbered entries -both in the body of a printed work and in its table of contents. The -@code{@@top} command, which has a special use, is a member of this -series (@pxref{makeinfo top, , @code{@@top}}).@refill - -@item -The @code{@@heading} series of commands produce unnumbered headings -that do not appear in a table of contents. The heading commands never -start a new page.@refill - -@item -The @code{@@majorheading} command produces results similar to using -the @code{@@chapheading} command but generates a larger vertical -whitespace before the heading.@refill - -@item -When an @code{@@setchapternewpage} command says to do so, the -@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands -start new pages in the printed manual; the @code{@@heading} commands -do not.@refill -@end itemize - -@need 1000 -Here are the four groups of chapter structuring commands:@refill - -@c Slightly different formatting for regular sized books and smallbooks. -@ifset smallbook -@sp 1 -@tex -{\let\rm=\indrm \let\tt=\indtt -\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil\cr - -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifset -@ifclear smallbook -@sp 1 -@tex -\vbox{ -\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil& \hskip.5em #\hfil\cr - -& & & \cr -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifclear -@ifinfo -@example -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end example -@end ifinfo - -@c Cannot line up columns properly inside of an example because of roman -@c proportional fonts. -@ignore -@ifset smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ifset -@ifclear smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ignore - -@node makeinfo top, chapter, Structuring Command Types, Structuring -@comment node-name, next, previous, up -@section @code{@@top} - -The @code{@@top} command is a special sectioning command that you use -only after an @code{@@node Top} line at the beginning of a Texinfo file. -The @code{@@top} command tells the @code{makeinfo} formatter -which node is the `Top' -node. It has the same typesetting effect as @code{@@unnumbered} -(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). -For detailed information, see -@ref{makeinfo top command, , The @code{@@top} Command}.@refill - -@node chapter, unnumbered & appendix, makeinfo top, Structuring -@comment node-name, next, previous, up -@section @code{@@chapter} -@findex chapter - -@code{@@chapter} identifies a chapter in the document. Write the -command at the beginning of a line and follow it on the same line by -the title of the chapter.@refill - -For example, this chapter in this manual is entitled ``Chapter -Structuring''; the @code{@@chapter} line looks like this:@refill - -@example -@@chapter Chapter Structuring -@end example - -In @TeX{}, the @code{@@chapter} command creates a chapter in the -document, specifying the chapter title. The chapter is numbered -automatically.@refill - -In Info, the @code{@@chapter} command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath. Thus, -in Info, the above example produces the following output:@refill - -@example -Chapter Structuring -******************* -@end example - -@findex centerchap -Texinfo also provides a command @code{@@centerchap}, which is analogous -to @code{@@unnumbered}, but centers its argument in the printed output. -This kind of stylistic choice is not usually offered by Texinfo. -@c but the Hacker's Dictionary wanted it ... - - -@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumbered}, @code{@@appendix} -@findex unnumbered -@findex appendix - -Use the @code{@@unnumbered} command to create a chapter that appears -in a printed manual without chapter numbers of any kind. Use the -@code{@@appendix} command to create an appendix in a printed manual -that is labelled by letter instead of by number.@refill - -For Info file output, the @code{@@unnumbered} and @code{@@appendix} -commands are equivalent to @code{@@chapter}: the title is printed on a -line by itself with a line of asterisks underneath. (@xref{chapter, , -@code{@@chapter}}.)@refill - -To create an appendix or an unnumbered chapter, write an -@code{@@appendix} or @code{@@unnumbered} command at the beginning of a -line and follow it on the same line by the title, as you would if you -were creating a chapter.@refill - - -@node majorheading & chapheading, section, unnumbered & appendix, Structuring -@section @code{@@majorheading}, @code{@@chapheading} -@findex majorheading -@findex chapheading - -The @code{@@majorheading} and @code{@@chapheading} commands put -chapter-like headings in the body of a document.@refill - -However, neither command causes @TeX{} to produce a numbered heading -or an entry in the table of contents; and neither command causes -@TeX{} to start a new page in a printed manual.@refill - -In @TeX{}, an @code{@@majorheading} command generates a larger vertical -whitespace before the heading than an @code{@@chapheading} command but -is otherwise the same.@refill - -In Info, -the @code{@@majorheading} and -@code{@@chapheading} commands are equivalent to -@code{@@chapter}: the title is printed on a line by itself with a line -of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill - -@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring -@comment node-name, next, previous, up -@section @code{@@section} -@findex section - -In a printed manual, an @code{@@section} command identifies a -numbered section within a chapter. The section title appears in the -table of contents. In Info, an @code{@@section} command provides a -title for a segment of text, underlined with @samp{=}.@refill - -This section is headed with an @code{@@section} command and looks like -this in the Texinfo file:@refill - -@example -@@section @@code@{@@@@section@} -@end example - -To create a section, write the @code{@@section} command at the -beginning of a line and follow it on the same line by the section -title.@refill - -Thus, - -@example -@@section This is a section -@end example - -@noindent -produces - -@example -@group -This is a section -================= -@end group -@end example - -@noindent -in Info. - -@node unnumberedsec appendixsec heading, subsection, section, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} -@findex unnumberedsec -@findex appendixsec -@findex heading - -The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} -commands are, respectively, the unnumbered, appendix-like, and -heading-like equivalents of the @code{@@section} command. -(@xref{section, , @code{@@section}}.)@refill - -@table @code -@item @@unnumberedsec -The @code{@@unnumberedsec} command may be used within an -unnumbered chapter or within a regular chapter or appendix to -provide an unnumbered section.@refill - -@item @@appendixsec -@itemx @@appendixsection -@code{@@appendixsection} is a longer spelling of the -@code{@@appendixsec} command; the two are synonymous.@refill -@findex appendixsection - -Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} -command is used only within appendices.@refill - -@item @@heading -You may use the @code{@@heading} command anywhere you wish for a -section-style heading that will not appear in the table of contents.@refill -@end table - -@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring -@comment node-name, next, previous, up -@section The @code{@@subsection} Command -@findex subsection - -Subsections are to sections as sections are to chapters. -(@xref{section, , @code{@@section}}.) In Info, subsection titles are -underlined with @samp{-}. For example,@refill - -@example -@@subsection This is a subsection -@end example - -@noindent -produces - -@example -@group -This is a subsection --------------------- -@end group -@end example - -In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep.@refill - -@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring -@comment node-name, next, previous, up -@section The @code{@@subsection}-like Commands -@cindex Subsection-like commands -@findex unnumberedsubsec -@findex appendixsubsec -@findex subheading - -The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and -@code{@@subheading} commands are, respectively, the unnumbered, -appendix-like, and heading-like equivalents of the @code{@@subsection} -command. (@xref{subsection, , @code{@@subsection}}.)@refill - -In Info, the @code{@@subsection}-like commands generate a title -underlined with hyphens. In a printed manual, an @code{@@subheading} -command produces a heading like that of a subsection except that it is -not numbered and does not appear in the table of contents. Similarly, -an @code{@@unnumberedsubsec} command produces an unnumbered heading like -that of a subsection and an @code{@@appendixsubsec} command produces a -subsection-like heading labelled with a letter and numbers; both of -these commands produce headings that appear in the table of -contents.@refill - -@node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring -@comment node-name, next, previous, up -@section The `subsub' Commands -@cindex Subsub commands -@findex subsubsection -@findex unnumberedsubsubsec -@findex appendixsubsubsec -@findex subsubheading - -The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are:@refill - -@table @code -@item @@subsubsection -Subsubsections are to subsections as subsections are to sections. -(@xref{subsection, , @code{@@subsection}}.) In a printed manual, -subsubsection titles appear in the table of contents and are numbered -four levels deep.@refill - -@item @@unnumberedsubsubsec -Unnumbered subsubsection titles appear in the table of contents of a -printed manual, but lack numbers. Otherwise, unnumbered -subsubsections are the same as subsubsections. In Info, unnumbered -subsubsections look exactly like ordinary subsubsections.@refill - -@item @@appendixsubsubsec -Conventionally, appendix commands are used only for appendices and are -lettered and numbered appropriately in a printed manual. They also -appear in the table of contents. In Info, appendix subsubsections look -exactly like ordinary subsubsections.@refill - -@item @@subsubheading -The @code{@@subsubheading} command may be used anywhere that you need -a small heading that will not appear in the table of contents. In -Info, subsubheadings look exactly like ordinary subsubsection -headings.@refill -@end table - -In Info, `subsub' titles are underlined with periods. -For example,@refill - -@example -@@subsubsection This is a subsubsection -@end example - -@noindent -produces - -@example -@group -This is a subsubsection -....................... -@end group -@end example - -@node Raise/lower sections, , subsubsection, Structuring -@comment node-name, next, previous, up -@section @code{@@raisesections} and @code{@@lowersections} -@findex raisesections -@findex lowersections -@cindex Raising and lowering sections -@cindex Sections, raising and lowering - -The @code{@@raisesections} and @code{@@lowersections} commands raise and -lower the hierarchical level of chapters, sections, subsections and the -like. The @code{@@raisesections} command changes sections to chapters, -subsections to sections, and so on. The @code{@@lowersections} command -changes chapters to sections, sections to subsections, and so on. - -An @code{@@lowersections} command is useful if you wish to include text -that is written as an outer or standalone Texinfo file in another -Texinfo file as an inner, included file. If you write the command at -the beginning of the file, all your @code{@@chapter} commands are -formatted as if they were @code{@@section} commands, all your -@code{@@section} command are formatted as if they were -@code{@@subsection} commands, and so on. - -@need 1000 -@code{@@raisesections} raises a command one level in the chapter -structuring hierarchy:@refill - -@example -@group - @r{Change} @r{To} - -@@subsection @@section, -@@section @@chapter, -@@heading @@chapheading, - @r{etc.} -@end group -@end example - -@need 1000 -@code{@@lowersections} lowers a command one level in the chapter -structuring hierarchy:@refill - -@example -@group - @r{Change} @r{To} - -@@chapter @@section, -@@subsection @@subsubsection, -@@heading @@subheading, - @r{etc.} -@end group -@end example - -An @code{@@raisesections} or @code{@@lowersections} command changes only -those structuring commands that follow the command in the Texinfo file. -Write an @code{@@raisesections} or @code{@@lowersections} command on a -line of its own. - -An @code{@@lowersections} command cancels an @code{@@raisesections} -command, and vice versa. - -Repeated use of the commands continue to raise or lower the hierarchical -level a step at a time. - -An attempt to raise above `chapters' reproduces chapter commands; an -attempt to lower below `subsubsections' reproduces subsubsection -commands. - -@node Nodes, Menus, Structuring, Top -@comment node-name, next, previous, up -@chapter Nodes - -@dfn{Nodes} are the primary segments of a Texinfo file. They do not -themselves impose a hierarchic or any other kind of structure on a file. -Nodes contain @dfn{node pointers} that name other nodes, and can contain -@dfn{menus} which are lists of nodes. In Info, the movement commands -can carry you to a pointed-to node or to a node listed in a menu. Node -pointers and menus provide structure for Info files just as chapters, -sections, subsections, and the like, provide structure for printed -books.@refill - -@menu -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. -@end menu - -@node Two Paths, Node Menu Illustration, Nodes, Nodes -@ifinfo -@heading Two Paths -@end ifinfo - -The node and menu commands and the chapter structuring commands are -independent of each other: - -@itemize @bullet -@item -In Info, node and menu commands provide structure. The chapter -structuring commands generate headings with different kinds of -underlining---asterisks for chapters, hyphens for sections, and so on; -they do nothing else.@refill - -@item -In @TeX{}, the chapter structuring commands generate chapter and section -numbers and tables of contents. The node and menu commands provide -information for cross references; they do nothing else.@refill -@end itemize - -You can use node pointers and menus to structure an Info file any way -you want; and you can write a Texinfo file so that its Info output has a -different structure than its printed output. However, most Texinfo -files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is not -convenient to do otherwise.@refill - -Generally, printed output is structured in a tree-like hierarchy in -which the chapters are the major limbs from which the sections branch -out. Similarly, node pointers and menus are organized to create a -matching structure in the Info output.@refill - -@node Node Menu Illustration, node, Two Paths, Nodes -@comment node-name, next, previous, up -@section Node and Menu Illustration - -Here is a copy of the diagram shown earlier that illustrates a Texinfo -file with three chapters, each of which contains two sections.@refill - -Note that the ``root'' is at the top of the diagram and the ``leaves'' -are at the bottom. This is how such a diagram is drawn conventionally; -it illustrates an upside-down tree. For this reason, the root node is -called the `Top' node, and `Up' node pointers carry you closer to the -root.@refill - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | - Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - -@end group -@end example - -Write the beginning of the node for Chapter 2 like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@comment node-name, next, previous, up -@end group -@end example - -@noindent -This @code{@@node} line says that the name of this node is ``Chapter 2'', the -name of the `Next' node is ``Chapter 3'', the name of the `Previous' -node is ``Chapter 1'', and the name of the `Up' node is ``Top''. - -@quotation -@strong{Please Note:} `Next' refers to the next node at the same -hierarchical level in the manual, not necessarily to the next node -within the Texinfo file. In the Texinfo file, the subsequent node may -be at a lower level---a section-level node may follow a chapter-level -node, and a subsection-level node may follow a section-level node. -`Next' and `Previous' refer to nodes at the @emph{same} hierarchical -level. (The `Top' node contains the exception to this rule. Since the -`Top' node is the only node at that level, `Next' refers to the first -following node, which is almost always a chapter or chapter-level -node.)@refill -@end quotation - -To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter -2. (@xref{Menus}.) You would write the menu just -before the beginning of Section 2.1, like this:@refill - -@example -@group - @@menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: - @@end menu -@end group -@end example - -Write the node for Sect. 2.1 like this:@refill - -@example -@group - @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 - @@comment node-name, next, previous, up -@end group -@end example - -In Info format, the `Next' and `Previous' pointers of a node usually -lead to other nodes at the same level---from chapter to chapter or from -section to section (sometimes, as shown, the `Previous' pointer points -up); an `Up' pointer usually leads to a node at the level above (closer -to the `Top' node); and a `Menu' leads to nodes at a level below (closer -to `leaves'). (A cross reference can point to a node at any level; -see @ref{Cross References}.)@refill - -Usually, an @code{@@node} command and a chapter structuring command are -used in sequence, along with indexing commands. (You may follow the -@code{@@node} line with a comment line that reminds you which pointer is -which.)@refill - -Here is the beginning of the chapter in this manual called ``Ending a -Texinfo File''. This shows an @code{@@node} line followed by a comment -line, an @code{@@chapter} line, and then by indexing lines.@refill - -@example -@group -@@node Ending a File, Structuring, Beginning a File, Top -@@comment node-name, next, previous, up -@@chapter Ending a Texinfo File -@@cindex Ending a Texinfo file -@@cindex Texinfo file ending -@@cindex File ending -@end group -@end example - -@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes -@comment node-name, next, previous, up -@section The @code{@@node} Command - -@cindex Node, defined -A @dfn{node} is a segment of text that begins at an @code{@@node} -command and continues until the next @code{@@node} command. The -definition of node is different from that for chapter or section. A -chapter may contain sections and a section may contain subsections; -but a node cannot contain subnodes; the text of a node continues only -until the next @code{@@node} command in the file. A node usually -contains only one chapter structuring command, the one that follows -the @code{@@node} line. On the other hand, in printed output nodes -are used only for cross references, so a chapter or section may -contain any number of nodes. Indeed, a chapter usually contains -several nodes, one for each section, subsection, and -subsubsection.@refill - -To create a node, write an @code{@@node} command at the beginning of a -line, and follow it with four arguments, separated by commas, on the -rest of the same line. These arguments are the name of the node, and -the names of the `Next', `Previous', and `Up' pointers, in that order. -You may insert spaces before each pointer if you wish; the spaces are -ignored. You must write the name of the node, and the names of the -`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, -the formatters fail. (@inforef{Top, info, info}, for more information -about nodes in Info.)@refill - -Usually, you write one of the chapter-structuring command lines -immediately after an @code{@@node} line---for example, an -@code{@@section} or @code{@@subsection} line. (@xref{Structuring -Command Types, , Types of Structuring Command}.)@refill - -@quotation -@strong{Please note:} The GNU Emacs Texinfo mode updating commands work -only with Texinfo files in which @code{@@node} lines are followed by chapter -structuring lines. @xref{Updating Requirements}.@refill -@end quotation - -@TeX{} uses @code{@@node} lines to identify the names to use for cross -references. For this reason, you must write @code{@@node} lines in a -Texinfo file that you intend to format for printing, even if you do not -intend to format it for Info. (Cross references, such as the one at the -end of this sentence, are made with @code{@@xref} and its related -commands; see @ref{Cross References}.)@refill - -@menu -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. -* Top Node Summary:: Write a brief description for readers. -@end menu - -@node Node Names, Writing a Node, node, node -@ifinfo -@subheading Choosing Node and Pointer Names -@end ifinfo - -The name of a node identifies the node. The pointers enable -you to reach other nodes and consist of the names of those nodes.@refill - -Normally, a node's `Up' pointer contains the name of the node whose menu -mentions that node. The node's `Next' pointer contains the name of the -node that follows that node in that menu and its `Previous' pointer -contains the name of the node that precedes it in that menu. When a -node's `Previous' node is the same as its `Up' node, both node pointers -name the same node.@refill - -Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the @file{dir} file, which -contains the main menu for all of Info.@refill - -The `Top' node itself contains the main or master menu for the manual. -Also, it is helpful to include a brief description of the manual in the -`Top' node. @xref{First Node}, for information on how to write the -first node of a Texinfo file.@refill - -@node Writing a Node, Node Line Tips, Node Names, node -@comment node-name, next, previous, up -@subsection How to Write an @code{@@node} Line -@cindex Writing an @code{@@node} line -@cindex @code{@@node} line writing -@cindex Node line writing - -The easiest way to write an @code{@@node} line is to write @code{@@node} -at the beginning of a line and then the name of the node, like -this:@refill - -@example -@@node @var{node-name} -@end example - -If you are using GNU Emacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or you -can leave the pointers out of the Texinfo file and let @code{makeinfo} -insert node pointers into the Info file it creates. (@xref{Texinfo -Mode}, and @ref{makeinfo Pointer Creation}.)@refill - -Alternatively, you can insert the `Next', `Previous', and `Up' -pointers yourself. If you do this, you may find it helpful to use the -Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts -@samp{@@node} and a comment line listing the names of the pointers in -their proper order. The comment line helps you keep track of which -arguments are for which pointers. This comment line is especially useful -if you are not familiar with Texinfo.@refill - -The template for a node line with `Next', `Previous', and `Up' pointers -looks like this:@refill - -@example -@@node @var{node-name}, @var{next}, @var{previous}, @var{up} -@end example - -If you wish, you can ignore @code{@@node} lines altogether in your first -draft and then use the @code{texinfo-insert-node-lines} command to -create @code{@@node} lines for you. However, we do not -recommend this practice. It is better to name the node itself -at the same time that you -write a segment so you can easily make cross references. A large number -of cross references are an especially important feature of a good Info -file.@refill - -After you have inserted an @code{@@node} line, you should immediately -write an @@-command for the chapter or section and insert its name. -Next (and this is important!), put in several index entries. Usually, -you will find at least two and often as many as four or five ways of -referring to the node in the index. Use them all. This will make it -much easier for people to find the node.@refill - -@node Node Line Tips, Node Line Requirements, Writing a Node, node -@comment node-name, next, previous, up -@subsection @code{@@node} Line Tips - -Here are three suggestions: - -@itemize @bullet -@item -Try to pick node names that are informative but short.@refill - -In the Info file, the file name, node name, and pointer names are all -inserted on one line, which may run into the right edge of the window. -(This does not cause a problem with Info, but is ugly.)@refill - -@item -Try to pick node names that differ from each other near the beginnings -of their names. This way, it is easy to use automatic name completion in -Info.@refill - -@item -By convention, node names are capitalized just as they would be for -section or chapter titles---initial and significant words are -capitalized; others are not.@refill -@end itemize - -@node Node Line Requirements, First Node, Node Line Tips, node -@comment node-name, next, previous, up -@subsection @code{@@node} Line Requirements - -@cindex Node line requirements -Here are several requirements for @code{@@node} lines: - -@itemize @bullet -@cindex Unique nodename requirement -@cindex Nodename must be unique -@item -All the node names for a single Info file must be unique.@refill - -Duplicates confuse the Info movement commands. This means, for -example, that if you end every chapter with a summary, you must name -each summary node differently. You cannot just call each one -``Summary''. You may, however, duplicate the titles of chapters, sections, -and the like. Thus you can end each chapter in a book with a section -called ``Summary'', so long as the node names for those sections are all -different.@refill - -@item -A pointer name must be the name of a node.@refill - -The node to which a pointer points may come before or after the -node containing the pointer.@refill - -@cindex @@-command in nodename -@cindex Nodename, cannot contain -@item -You cannot use any of the Texinfo @@-commands in a node name; -@w{@@-commands} confuse Info.@refill - -@need 750 -Thus, the beginning of the section called @code{@@chapter} looks like -this:@refill - -@smallexample -@group -@@node chapter, unnumbered & appendix, makeinfo top, Structuring -@@comment node-name, next, previous, up -@@section @@code@{@@@@chapter@} -@@findex chapter -@end group -@end smallexample - -@cindex Comma in nodename -@cindex Colon in nodename -@cindex Apostrophe in nodename -@item -You cannot use commas, colons, or apostrophes within a node name; these -confuse @TeX{} or the Info formatters.@refill - -@need 700 -For example, the following is a section title: - -@smallexample -@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} -@end smallexample - -@noindent -The corresponding node name is: - -@smallexample -unnumberedsec appendixsec heading -@end smallexample - -@cindex Case in nodename -@item -Case is significant. -@end itemize - -@node First Node, makeinfo top command, Node Line Requirements, node -@comment node-name, next, previous, up -@subsection The First Node -@cindex @samp{@r{Top}} node is first -@cindex First node - -The first node of a Texinfo file is the `Top' node, except in an -included file (@pxref{Include Files}). - -The `Top' node (which must be named @samp{top} or @samp{Top}) should -have as its `Up' and `Previous' nodes the name of a node in another -file, where there is a menu that leads to this file. Specify the file -name in parentheses. If the file is to be installed directly in the -Info directory file, use @samp{(dir)} as the parent of the `Top' node; -this is short for @samp{(dir)top}, and specifies the `Top' node in the -@file{dir} file, which contains the main menu for Info. For example, -the @code{@@node Top} line of this manual looks like this:@refill - -@example -@@node Top, Overview, (dir), (dir) -@end example - -@noindent -(You may use the Texinfo updating commands or the @code{makeinfo} -utility to insert these `Next' and @samp{(dir)} pointers -automatically.)@refill - -@xref{Install an Info File}, for more information about installing -an Info file in the @file{info} directory.@refill - -The `Top' node contains the main or master menu for the document. - -@node makeinfo top command, Top Node Summary, First Node, node -@comment node-name, next, previous, up -@subsection The @code{@@top} Sectioning Command -@findex top @r{(@@-command)} - -A special sectioning command, @code{@@top}, has been created for use -with the @code{@@node Top} line. The @code{@@top} sectioning command tells -@code{makeinfo} that it marks the `Top' node in the file. It provides -the information that @code{makeinfo} needs to insert node -pointers automatically. Write the @code{@@top} command at the -beginning of the line immediately following the @code{@@node Top} -line. Write the title on the remaining part of the same line as the -@code{@@top} command.@refill - -In Info, the @code{@@top} sectioning command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath.@refill - -In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -sectioning command is merely a synonym for @code{@@unnumbered}. -Neither of these formatters require an @code{@@top} command, and do -nothing special with it. You can use @code{@@chapter} or -@code{@@unnumbered} after the @code{@@node Top} line when you use -these formatters. Also, you can use @code{@@chapter} or -@code{@@unnumbered} when you use the Texinfo updating commands to -create or update pointers and menus.@refill - -@node Top Node Summary, , makeinfo top command, node -@subsection The `Top' Node Summary -@cindex @samp{@r{Top}} node summary - -You can help readers by writing a summary in the `Top' node, after the -@code{@@top} line, before the main or master menu. The summary should -briefly describe the document. In Info, this summary will appear just -before the master menu. In a printed manual, this summary will appear -on a page of its own.@refill - -If you do not want the summary to appear on a page of its own in a -printed manual, you can enclose the whole of the `Top' node, including -the @code{@@node Top} line and the @code{@@top} sectioning command line -or other sectioning command line between @code{@@ifinfo} and @code{@@end -ifinfo}. This prevents any of the text from appearing in the printed -output. (@pxref{Conditionals, , Conditionally Visible Text}). You can -repeat the brief description from the `Top' node within @code{@@iftex} -@dots{} @code{@@end iftex} at the beginning of the first chapter, for -those who read the printed manual. This saves paper and may look -neater.@refill - -You should write the version number of the program to which the manual -applies in the summary. This helps the reader keep track of which -manual is for which version of the program. If the manual changes more -frequently than the program or is independent of it, you should also -include an edition number for the manual. (The title page should also -contain this information: see @ref{titlepage, , -@code{@@titlepage}}.)@refill - -@node makeinfo Pointer Creation, , node, Nodes -@section Creating Pointers with @code{makeinfo} -@cindex Creating pointers with @code{makeinfo} -@cindex Pointer creation with @code{makeinfo} -@cindex Automatic pointer creation with @code{makeinfo} - -The @code{makeinfo} program has a feature for automatically creating -node pointers for a hierarchically organized file that lacks -them.@refill - -When you take advantage of this feature, you do not need to write the -`Next', `Previous', and `Up' pointers after the name of a node. -However, you must write a sectioning command, such as @code{@@chapter} -or @code{@@section}, on the line immediately following each truncated -@code{@@node} line. You cannot write a comment line after a node -line; the section line must follow it immediately.@refill - -In addition, you must follow the `Top' @code{@@node} line with a line beginning -with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo -top, , @code{@@top}}. - -Finally, you must write the name of each node (except for the `Top' -node) in a menu that is one or more hierarchical levels above the -node's hierarchical level.@refill - -This node pointer insertion feature in @code{makeinfo} is an -alternative to the menu and pointer creation and update commands in -Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially -helpful to people who do not use GNU Emacs for writing Texinfo -documents.@refill - -@node Menus, Cross References, Nodes, Top -@comment node-name, next, previous, up -@chapter Menus -@cindex Menus -@findex menu - -@dfn{Menus} contain pointers to subordinate -nodes.@footnote{Menus can carry you to any node, regardless -of the hierarchical structure; even to nodes in a different -Info file. However, the GNU Emacs Texinfo mode updating -commands work only to create menus of subordinate nodes. -Conventionally, cross references are used to refer to other -nodes.} In Info, you use menus to go to such nodes. Menus -have no effect in printed manuals and do not appear in -them.@refill - -By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it.@refill - -@ifinfo -A node that has a menu should @emph{not} contain much text. If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines.@refill -@end ifinfo -@iftex -@emph{A node that has a menu should not contain much text.} If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines. Otherwise, a reader with a terminal -that displays only a few lines may miss the menu and its associated -text. As a practical matter, you should locate a menu within 20 lines -of the beginning of the node.@refill -@end iftex - -@menu -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. -@end menu - -@node Menu Location, Writing a Menu, Menus, Menus -@ifinfo -@heading Menus Need Short Nodes -@end ifinfo -@cindex Menu location -@cindex Location of menus -@cindex Nodes for menus are short -@cindex Short nodes for menus - -@ifinfo -A reader can easily see a menu that is close to the beginning of the -node. The node should be short. As a practical matter, you should -locate a menu within 20 lines of the beginning of the node. -Otherwise, a reader with a terminal that displays only a few lines may -miss the menu and its associated text.@refill -@end ifinfo - -The short text before a menu may look awkward in a printed manual. To -avoid this, you can write a menu near the beginning of its node and -follow the menu by an @code{@@node} line, and then an @code{@@heading} -line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, -the menu, @code{@@node} line, and title appear only in the Info file, -not the printed document.@refill - -For example, the preceding two paragraphs follow an Info-only menu, -@code{@@node} line, and heading, and look like this:@refill - -@example -@group -@@menu -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part entries. -* Other Info Files:: How to refer to a different - Info file. -@@end menu - -@@node Menu Location, Writing a Menu, , Menus -@@ifinfo -@@heading Menus Need Short Nodes -@@end ifinfo -@end group -@end example - -The Texinfo file for this document contains more than a dozen -examples of this procedure. One is at the beginning of this chapter; -another is at the beginning of the ``Cross References'' chapter.@refill - -@node Writing a Menu, Menu Parts, Menu Location, Menus -@section Writing a Menu -@cindex Writing a menu -@cindex Menu writing - -A menu consists of an @code{@@menu} command on a line by -itself followed by menu entry lines or menu comment lines -and then by an @code{@@end menu} command on a line by -itself.@refill - -A menu looks like this:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -In a menu, every line that begins with an @w{@samp{* }} is a -@dfn{menu entry}. (Note the space after the asterisk.) A -line that does not start with an @w{@samp{* }} may also -appear in a menu. Such a line is not a menu entry but is a -menu comment line that appears in the Info file. In -the example above, the line @samp{Larger Units of Text} is a -menu comment line; the two lines starting with @w{@samp{* }} -are menu entries. - -@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus -@section The Parts of a Menu -@cindex Parts of a menu -@cindex Menu parts -@cindex @code{@@menu} parts - -A menu entry has three parts, only the second of which is -required:@refill - -@enumerate -@item -The menu entry name. - -@item -The name of the node (required). - -@item -A description of the item. -@end enumerate - -The template for a menu entry looks like this:@refill - -@example -* @var{menu-entry-name}: @var{node-name}. @var{description} -@end example - -Follow the menu entry name with a single colon and follow the node name -with tab, comma, period, or newline.@refill - -In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) -command. The menu entry name is what the user types after the @kbd{m} -command.@refill - -The third part of a menu entry is a descriptive phrase or -sentence. Menu entry names and node names are often short; the -description explains to the reader what the node is about. The -description, which is optional, can spread over two or more lines. A -useful description complements the node name rather than repeats -it.@refill - -@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus -@comment node-name, next, previous, up -@section Less Cluttered Menu Entry -@cindex Two part menu entry -@cindex Double-colon menu entries -@cindex Menu entries with two colons -@cindex Less cluttered menu entry -@cindex Uncluttered menu entry - -When the menu entry name and node name are the same, you can write -the name immediately after the asterisk and space at the beginning of -the line and follow the name with two colons.@refill - -@need 800 -For example, write - -@example -* Name:: @var{description} -@end example - -@need 800 -@noindent -instead of - -@example -* Name: Name. @var{description} -@end example - -You should use the node name for the menu entry name whenever possible, -since it reduces visual clutter in the menu.@refill - -@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus -@comment node-name, next, previous, up -@section A Menu Example -@cindex Menu example -@cindex Example menu - -A menu looks like this in Texinfo:@refill - -@example -@group -@@menu -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: - -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@end group -@end example - -@need 700 -Here is an example as you might see it in a Texinfo file:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@end group -@end example - -In this example, the menu has two entries. @samp{Files} is both a menu -entry name and the name of the node referred to by that name. -@samp{Multiples} is the menu entry name; it refers to the node named -@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it -appears in the menu, but is not an entry.@refill - -Since no file name is specified with either @samp{Files} or -@samp{Buffers}, they must be the names of nodes in the same Info file -(@pxref{Other Info Files, , Referring to Other Info Files}).@refill - -@node Other Info Files, , Menu Example, Menus -@comment node-name, next, previous, up -@section Referring to Other Info Files -@cindex Referring to other Info files -@cindex Nodes in other Info files -@cindex Other Info files' nodes -@cindex Going to other Info files' nodes -@cindex Info; other files' nodes - -You can create a menu entry that enables a reader in Info to go to a -node in another Info file by writing the file name in parentheses just -before the node name. In this case, you should use the three-part menu -entry format, which saves the reader from having to type the file -name.@refill - -@need 800 -The format looks like this:@refill - -@example -@group -@@menu -* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} -* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} -@@end menu -@end group -@end example - -For example, to refer directly to the @samp{Outlining} and -@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a -menu like this:@refill - -@example -@group -@@menu -* Outlining: (emacs)Outline Mode. The major mode for - editing outlines. -* Rebinding: (emacs)Rebinding. How to redefine the - meaning of a key. -@@end menu -@end group -@end example - -If you do not list the node name, but only name the file, then Info -presumes that you are referring to the `Top' node.@refill - -The @file{dir} file that contains the main menu for Info has menu -entries that list only file names. These take you directly to the `Top' -nodes of each Info document. (@xref{Install an Info File}.)@refill - -@need 700 -For example: - -@example -@group -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -@end group -@end example - -@noindent -(The @file{dir} top level directory for the Info system is an Info file, -not a Texinfo file, but a menu entry looks the same in both types of -file.)@refill - -Note that the GNU Emacs Texinfo mode menu updating commands only work -with nodes within the current buffer, so you cannot use them to create -menus that refer to other files. You must write such menus by hand.@refill - -@node Cross References, Marking Text, Menus, Top -@comment node-name, next, previous, up -@chapter Cross References -@cindex Making cross references -@cindex Cross references -@cindex References - -@dfn{Cross references} are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes are the -places to which cross references can refer.@refill - -@menu -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -@end menu - -@node References, Cross Reference Commands, Cross References, Cross References -@ifinfo -@heading What References Are For -@end ifinfo - -Often, but not always, a printed document should be designed so that -it can be read sequentially. People tire of flipping back and forth -to find information that should be presented to them as they need -it.@refill - -However, in any document, some information will be too detailed for -the current context, or incidental to it; use cross references to -provide access to such information. Also, an on-line help system or a -reference manual is not like a novel; few read such documents in -sequence from beginning to end. Instead, people look up what they -need. For this reason, such creations should contain many cross -references to help readers find other information that they may not -have read.@refill - -In a printed manual, a cross reference results in a page reference, -unless it is to another manual altogether, in which case the cross -reference names that manual.@refill - -In Info, a cross reference results in an entry that you can follow using -the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info -commands, info}.)@refill - -The various cross reference commands use nodes to define cross -reference locations. This is evident in Info, in which a cross -reference takes you to the specified node. @TeX{} also uses nodes to -define cross reference locations, but the action is less obvious. When -@TeX{} generates a @sc{dvi} file, it records nodes' page numbers and -uses the page numbers in making references. Thus, if you are writing -a manual that will only be printed, and will not be used on-line, you -must nonetheless write @code{@@node} lines to name the places to which -you make cross references.@refill - -@need 800 -@node Cross Reference Commands, Cross Reference Parts, References, Cross References -@comment node-name, next, previous, up -@section Different Cross Reference Commands -@cindex Different cross reference commands - -There are four different cross reference commands:@refill - -@table @code -@item @@xref -Used to start a sentence in the printed manual saying @w{`See @dots{}'} -or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}. - -@item @@ref -Used within or, more often, at the end of a sentence; same as -@code{@@xref} for Info; produces just the reference in the printed -manual without a preceding `See'.@refill - -@item @@pxref -Used within parentheses to make a reference that suits both an Info -file and a printed book. Starts with a lower case `see' within the -printed manual. (@samp{p} is for `parenthesis'.)@refill - -@item @@inforef -Used to make a reference to an Info file for which there is no printed -manual.@refill -@end table - -@noindent -(The @code{@@cite} command is used to make references to books and -manuals for which there is no corresponding Info file and, therefore, -no node to which to point. @xref{cite, , @code{@@cite}}.)@refill - -@node Cross Reference Parts, xref, Cross Reference Commands, Cross References -@comment node-name, next, previous, up -@section Parts of a Cross Reference -@cindex Cross reference parts -@cindex Parts of a cross reference - -A cross reference command requires only one argument, which is the -name of the node to which it refers. But a cross reference command -may contain up to four additional arguments. By using these -arguments, you can provide a cross reference name for Info, a topic -description or section title for the printed output, the name of a -different Info file, and the name of a different printed -manual.@refill - -Here is a simple cross reference example:@refill - -@example -@@xref@{Node name@}. -@end example - -@noindent -which produces - -@example -*Note Node name::. -@end example - -@noindent -and - -@quotation -See Section @var{nnn} [Node name], page @var{ppp}. -@end quotation - -@need 700 -Here is an example of a full five-part cross reference:@refill - -@example -@group -@@xref@{Node name, Cross Reference Name, Particular Topic, -info-file-name, A Printed Manual@}, for details. -@end group -@end example - -@noindent -which produces - -@example -*Note Cross Reference Name: (info-file-name)Node name, -for details. -@end example - -@noindent -in Info and - -@quotation -See section ``Particular Topic'' in @i{A Printed Manual}, for details. -@end quotation - -@noindent -in a printed book. - -The five possible arguments for a cross reference are:@refill - -@enumerate -@item -The node name (required). This is the node to which the -cross reference takes you. In a printed document, the location of the -node provides the page reference only for references within the same -document.@refill - -@item -The cross reference name for the Info reference, if it is to be different -from the node name. If you include this argument, it argument becomes -the first part of the cross reference. It is usually omitted.@refill - -@item -A topic description or section name. Often, this is the title of the -section. This is used as the name of the reference in the printed -manual. If omitted, the node name is used.@refill - -@item -The name of the Info file in which the reference is located, if it is -different from the current file.@refill - -@item -The name of a printed manual from a different Texinfo file.@refill -@end enumerate - -The template for a full five argument cross reference looks like -this:@refill - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -Cross references with one, two, three, four, and five arguments are -described separately following the description of @code{@@xref}.@refill - -Write a node name in a cross reference in exactly the same way as in -the @code{@@node} line, including the same capitalization; otherwise, the -formatters may not find the reference.@refill - -You can write cross reference commands within a paragraph, but note -how Info and @TeX{} format the output of each of the various commands: -write @code{@@xref} at the beginning of a sentence; write -@code{@@pxref} only within parentheses, and so on.@refill - -@node xref, Top Node Naming, Cross Reference Parts, Cross References -@comment node-name, next, previous, up -@section @code{@@xref} -@findex xref -@cindex Cross references using @code{@@xref} -@cindex References using @code{@@xref} - -The @code{@@xref} command generates a cross reference for the -beginning of a sentence. The Info formatting commands convert it into -an Info cross reference, which the Info @samp{f} command can use to -bring you directly to another node. The @TeX{} typesetting commands -convert it into a page reference, or a reference to another book or -manual.@refill - -@menu -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. -@end menu - -@node Reference Syntax, One Argument, xref, xref -@ifinfo -@subheading What a Reference Looks Like and Requires -@end ifinfo - -Most often, an Info cross reference looks like this:@refill - -@example -*Note @var{node-name}::. -@end example - -@noindent -or like this - -@example -*Note @var{cross-reference-name}: @var{node-name}. -@end example - -@noindent -In @TeX{}, a cross reference looks like this: - -@example -See Section @var{section-number} [@var{node-name}], page @var{page}. -@end example - -@noindent -or like this - -@example -See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end example - -The @code{@@xref} command does not generate a period or comma to end -the cross reference in either the Info file or the printed output. -You must write that period or comma yourself; otherwise, Info will not -recognize the end of the reference. (The @code{@@pxref} command works -differently. @xref{pxref, , @code{@@pxref}}.)@refill - -@quotation -@strong{Please note:} A period or comma @strong{must} follow the closing -brace of an @code{@@xref}. It is required to terminate the cross -reference. This period or comma will appear in the output, both in -the Info file and in the printed manual.@refill -@end quotation - -@code{@@xref} must refer to an Info node by name. Use @code{@@node} -to define the node (@pxref{Writing a Node}).@refill - -@code{@@xref} is followed by several arguments inside braces, separated by -commas. Whitespace before and after these commas is ignored.@refill - -A cross reference requires only the name of a node; but it may contain -up to four additional arguments. Each of these variations produces a -cross reference that looks somewhat different.@refill - -@quotation -@strong{Please note:} Commas separate arguments in a cross reference; -avoid including them in the title or other part lest the formatters -mistake them for separators.@refill -@end quotation - -@node One Argument, Two Arguments, Reference Syntax, xref -@subsection @code{@@xref} with One Argument - -The simplest form of @code{@@xref} takes one argument, the name of -another node in the same Info file. The Info formatters produce -output that the Info readers can use to jump to the reference; @TeX{} -produces output that specifies the page and section number for you.@refill - -@need 700 -@noindent -For example, - -@example -@@xref@{Tropical Storms@}. -@end example - -@noindent -produces - -@example -*Note Tropical Storms::. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Tropical Storms@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Tropical Storms::, for more info. -@end example - -@quotation -See Section 3.1 [Tropical Storms], page 24, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Two Arguments, Three Arguments, One Argument, xref -@subsection @code{@@xref} with Two Arguments - -With two arguments, the second is used as the name of the Info cross -reference, while the first is still the name of the node to which the -cross reference points.@refill - -@need 750 -@noindent -The template is like this: - -@example -@@xref@{@var{node-name}, @var{cross-reference-name}@}. -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning@}. -@end example - -@noindent -produces: - -@example -*Note Lightning: Electrical Effects. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Electrical Effects, Lightning@}, for more info. -@end example - -@noindent -which produces -@example -*Note Lightning: Electrical Effects, for more info. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Three Arguments, Four and Five Arguments, Two Arguments, xref -@subsection @code{@@xref} with Three Arguments - -A third argument replaces the node name in the @TeX{} output. The third -argument should be the name of the section in the printed output, or -else state the topic discussed by that section. Often, you will want to -use initial upper case letters so it will be easier to read when the -reference is printed. Use a third argument when the node name is -unsuitable because of syntax or meaning.@refill - -Remember to avoid placing a comma within the title or topic section of -a cross reference, or within any other section. The formatters divide -cross references into arguments according to the commas; a comma -within a title or other section will divide it into two arguments. In -a reference, you need to write a title such as ``Clouds, Mist, and -Fog'' without the commas.@refill - -Also, remember to write a comma or period after the closing brace of a -@code{@@xref} to terminate the cross reference. In the following -examples, a clause follows a terminating comma.@refill - - -@need 750 -@noindent -The template is like this: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -If a third argument is given and the second one is empty, then the -third argument serves both. (Note how two commas, side by side, mark -the empty second argument.)@refill - -@example -@group -@@xref@{Electrical Effects, , Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Thunder and Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -As a practical matter, it is often best to write cross references with -just the first argument if the node name and the section title are the -same, and with the first and third arguments if the node name and title -are different.@refill - -Here are several examples from @cite{The GAWK Manual}:@refill - -@smallexample -@@xref@{Sample Program@}. -@@xref@{Glossary@}. -@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. -@@xref@{Close Output, , Closing Output Files and Pipes@}, - for more information. -@@xref@{Regexp, , Regular Expressions as Patterns@}. -@end smallexample - -@node Four and Five Arguments, , Three Arguments, xref -@subsection @code{@@xref} with Four and Five Arguments - -In a cross reference, a fourth argument specifies the name of another -Info file, different from the file in which the reference appears, and -a fifth argument specifies its title as a printed manual.@refill - -Remember that a comma or period must follow the closing brace of an -@code{@@xref} command to terminate the cross reference. In the -following examples, a clause follows a terminating comma.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning, Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -*Note Lightning: (weather)Electrical Effects, for details. -@end example - -@noindent -The name of the Info file is enclosed in parentheses and precedes -the name of the node. - -@noindent -In a printed manual, the reference looks like this:@refill - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -@noindent -The title of the printed manual is typeset in italics; and the -reference lacks a page number since @TeX{} cannot know to which page a -reference refers when that reference is to another manual.@refill - -Often, you will leave out the second argument when you use the long -version of @code{@@xref}. In this case, the third argument, the topic -description, will be used as the cross reference name in Info.@refill - -@noindent -The template looks like this: - -@example -@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, -@var{printed-manual-title}@}, for details. -@end example - -@noindent -which produces - -@example -*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. -@end example - -@noindent -and - -@quotation -See section @var{title-or-topic} in @var{printed-manual-title}, for details. -@end quotation - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, , Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -@group -*Note Thunder and Lightning: (weather)Electrical Effects, -for details. -@end group -@end example - -@noindent -and - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -On rare occasions, you may want to refer to another Info file that -is within a single printed manual---when multiple Texinfo files are -incorporated into the same @TeX{} run but make separate Info files. -In this case, you need to specify only the fourth argument, and not -the fifth.@refill - -@node Top Node Naming, ref, xref, Cross References -@section Naming a `Top' Node -@cindex Naming a `Top' Node in references -@cindex @samp{@r{Top}} node naming for references - -In a cross reference, you must always name a node. This means that in -order to refer to a whole manual, you must identify the `Top' node by -writing it as the first argument to the @code{@@xref} command. (This -is different from the way you write a menu entry; see @ref{Other Info -Files, , Referring to Other Info Files}.) At the same time, to -provide a meaningful section topic or title in the printed cross -reference (instead of the word `Top'), you must write an appropriate -entry for the third argument to the @code{@@xref} command. -@refill - -@noindent -Thus, to make a cross reference to @cite{The GNU Make Manual}, -write:@refill - -@example -@@xref@{Top, , Overview, make, The GNU Make Manual@}. -@end example - -@noindent -which produces - -@example -*Note Overview: (make)Top. -@end example - -@noindent -and - -@quotation -See section ``Overview'' in @i{The GNU Make Manual}. -@end quotation - -@noindent -In this example, @samp{Top} is the name of the first node, and -@samp{Overview} is the name of the first section of the manual.@refill -@node ref, pxref, Top Node Naming, Cross References -@comment node-name, next, previous, up -@section @code{@@ref} -@cindex Cross references using @code{@@ref} -@cindex References using @code{@@ref} -@findex ref - -@code{@@ref} is nearly the same as @code{@@xref} except that it does -not generate a `See' in the printed output, just the reference itself. -This makes it useful as the last part of a sentence.@refill - -@need 700 -@noindent -For example, - -@example -For more information, see @@ref@{Hurricanes@}. -@end example - -@noindent -produces - -@example -For more information, see *Note Hurricanes. -@end example - -@noindent -and - -@quotation -For more information, see Section 8.2 [Hurricanes], page 123. -@end quotation - -The @code{@@ref} command sometimes leads writers to express themselves -in a manner that is suitable for a printed manual but looks awkward -in the Info format. Bear in mind that your audience will be using -both the printed and the Info format.@refill - -@need 800 -@noindent -For example, - -@example -@group -Sea surges are described in @@ref@{Hurricanes@}. -@end group -@end example - -@need 800 -@noindent -produces - -@quotation -Sea surges are described in Section 6.7 [Hurricanes], page 72. -@end quotation - -@need 800 -@noindent -in a printed document, and the following in Info: - -@example -Sea surges are described in *Note Hurricanes::. -@end example - -@quotation -@strong{Caution:} You @emph{must} write a period or comma immediately -after an @code{@@ref} command with two or more arguments. Otherwise, -Info will not find the end of the cross reference entry and its -attempt to follow the cross reference will fail. As a general rule, -you should write a period or comma after every @code{@@ref} command. -This looks best in both the printed and the Info output.@refill -@end quotation - -@node pxref, inforef, ref, Cross References -@comment node-name, next, previous, up -@section @code{@@pxref} -@cindex Cross references using @code{@@pxref} -@cindex References using @code{@@pxref} -@findex pxref - -The parenthetical reference command, @code{@@pxref}, is nearly the -same as @code{@@xref}, but you use it @emph{only} inside parentheses -and you do @emph{not} type a comma or period after the command's -closing brace. The command differs from @code{@@xref} in two -ways:@refill - -@enumerate -@item -@TeX{} typesets the reference for the printed manual with a lower case -`see' rather than an upper case `See'.@refill - -@item -The Info formatting commands automatically end the reference with a -closing colon or period.@refill -@end enumerate - -Because one type of formatting automatically inserts closing -punctuation and the other does not, you should use @code{@@pxref} -@emph{only} inside parentheses as part of another sentence. Also, you -yourself should not insert punctuation after the reference, as you do -with @code{@@xref}.@refill - -@code{@@pxref} is designed so that the output looks right and works -right between parentheses both in printed output and in an Info file. -In a printed manual, a closing comma or period should not follow a -cross reference within parentheses; such punctuation is wrong. But in -an Info file, suitable closing punctuation must follow the cross -reference so Info can recognize its end. @code{@@pxref} spares you -the need to use complicated methods to put a terminator into one form -of the output and not the other.@refill - -@noindent -With one argument, a parenthetical cross reference looks like -this:@refill - -@example -@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} -@end example - -@need 800 -@noindent -which produces - -@example -@group -@dots{} storms cause flooding (*Note Hurricanes::) @dots{} -@end group -@end example - -@noindent -and - -@quotation -@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} -@end quotation - -With two arguments, a parenthetical cross reference has this -template:@refill - -@example -@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} -@end example - -@noindent -which produces - -@example -@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{} -@end example - -@noindent -and - -@need 1500 -@quotation -@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} -@end quotation - -@code{@@pxref} can be used with up to five arguments just like -@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill - -@quotation -@strong{Please note:} Use @code{@@pxref} only as a parenthetical -reference. Do not try to use @code{@@pxref} as a clause in a sentence. -It will look bad in either the Info file, the printed output, or -both.@refill - -Also, parenthetical cross references look best at the ends of sentences. -Although you may write them in the middle of a sentence, that location -breaks up the flow of text.@refill -@end quotation - -@node inforef, , pxref, Cross References -@comment node-name, next, previous, up -@section @code{@@inforef} -@cindex Cross references using @code{@@inforef} -@cindex References using @code{@@inforef} -@findex inforef - -@code{@@inforef} is used for cross references to Info files for which -there are no printed manuals. Even in a printed manual, -@code{@@inforef} generates a reference directing the user to look in -an Info file.@refill - -The command takes either two or three arguments, in the following -order:@refill - -@enumerate -@item -The node name. - -@item -The cross reference name (optional). - -@item -The Info file name. -@end enumerate - -@noindent -Separate the arguments with commas, as with @code{@@xref}. Also, you -must terminate the reference with a comma or period after the -@samp{@}}, as you do with @code{@@xref}.@refill - -@noindent -The template is: - -@example -@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, -@end example - -@need 800 -@noindent -Thus, - -@example -@group -@@inforef@{Expert, Advanced Info commands, info@}, -for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -@group -*Note Advanced Info commands: (info)Expert, -for more information. -@end group -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation - -@need 800 -@noindent -Similarly, - -@example -@group -@@inforef@{Expert, , info@}, for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -*Note (info)Expert::, for more information. -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation - -The converse of @code{@@inforef} is @code{@@cite}, which is used to -refer to printed works for which no Info form exists. @xref{cite, , -@code{@@cite}}.@refill - -@node Marking Text, Quotations and Examples, Cross References, Top -@comment node-name, next, previous, up -@chapter Marking Words and Phrases -@cindex Paragraph, marking text within -@cindex Marking words and phrases -@cindex Words and phrases, marking them -@cindex Marking text within a paragraph - -In Texinfo, you can mark words and phrases in a variety of ways. -The Texinfo formatters use this information to determine how to -highlight the text. -You can specify, for example, whether a word or phrase is a -defining occurrence, a metasyntactic variable, or a symbol used in a -program. Also, you can emphasize text.@refill - -@menu -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. -@end menu - -@node Indicating, Emphasis, Marking Text, Marking Text -@comment node-name, next, previous, up -@section Indicating Definitions, Commands, etc. -@cindex Highlighting text -@cindex Indicating commands, definitions, etc. - -Texinfo has commands for indicating just what kind of object a piece of -text refers to. For example, metasyntactic variables are marked by -@code{@@var}, and code by @code{@@code}. Since the pieces of text are -labelled by commands that tell what kind of object they are, it is easy -to change the way the Texinfo formatters prepare such text. (Texinfo is -an @emph{intentional} formatting language rather than a @emph{typesetting} -formatting language.)@refill - -For example, in a printed manual, -code is usually illustrated in a typewriter font; -@code{@@code} tells @TeX{} to typeset this text in this font. But it -would be easy to change the way @TeX{} highlights code to use another -font, and this change would not effect how keystroke examples are -highlighted. If straight typesetting commands were used in the body -of the file and you wanted to make a change, you would need to check -every single occurrence to make sure that you were changing code and -not something else that should not be changed.@refill - -@menu -* Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -* url:: How to indicate a world wide web reference. -* email:: How to indicate an electronic mail address. -@end menu - -@node Useful Highlighting, code, Indicating, Indicating -@ifinfo -@subheading Highlighting Commands are Useful -@end ifinfo - -The highlighting commands can be used to generate useful information -from the file, such as lists of functions or file names. It is -possible, for example, to write a program in Emacs Lisp (or a keyboard -macro) to insert an index entry after every paragraph that contains -words or phrases marked by a specified command. You could do this to -construct an index of functions if you had not already made the -entries.@refill - -The commands serve a variety of purposes:@refill - -@table @code -@item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input.@refill - -@item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard.@refill - -@item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable.@refill - -@item @@url@{@var{uniform-resource-locator}@} -Indicate a uniform resource locator for the World Wide Web. - -@item @@file@{@var{file-name}@} -Indicate the name of a file.@refill - -@item @@email@{@var{email-address}@} -Indicate an electronic mail address. - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term.@refill - -@item @@cite@{@var{reference}@} -Indicate the name of a book.@refill - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Use for an @sc{ascii} control character.@refill -@end ignore -@end table - -@node code, kbd, Useful Highlighting, Indicating -@comment node-name, next, previous, up -@subsection @code{@@code}@{@var{sample-code}@} -@findex code - -Use the @code{@@code} command to indicate text that is a piece of a -program and which consists of entire syntactic tokens. Enclose the -text in braces.@refill - -Thus, you should use @code{@@code} for an expression in a program, for -the name of a variable or function used in a program, or for a -keyword. Also, you should use @code{@@code} for the name of a -program, such as @code{diff}, that is a name used in the machine. (You -should write the name of a program in the ordinary text font if you -regard it as a new English word, such as `Emacs' or `Bison'.)@refill - -Use @code{@@code} for environment variables such as @code{TEXINPUTS}, -and other variables.@refill - -Use @code{@@code} for command names in command languages that -resemble programming languages, such as Texinfo or the shell. -For example, @code{@@code} and @code{@@samp} are produced by writing -@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo -source, respectively.@refill - -Note, however, that you should not use @code{@@code} for shell options -such as @samp{-c} when such options stand alone. (Use @code{@@samp}.) -Also, an entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format.@refill - -It is incorrect to alter the case of a word inside an @code{@@code} -command when it appears at the beginning of a sentence. Most computer -languages are case sensitive. In C, for example, @code{Printf} is -different from the identifier @code{printf}, and most likely is a -misspelling of it. Even in languages which are not case sensitive, it -is confusing to a human reader to see identifiers spelled in different -ways. Pick one spelling and always use that. If you do not want to -start a sentence with a command written all in lower case, you should -rearrange the sentence.@refill - -Do not use the @code{@@code} command for a string of characters shorter -than a syntactic token. If you are writing about @samp{TEXINPU}, which -is just a part of the name for the @code{TEXINPUTS} environment -variable, you should use @code{@@samp}.@refill - -In particular, you should not use the @code{@@code} command when writing -about the characters used in a token; do not, for example, use -@code{@@code} when you are explaining what letters or printable symbols -can be used in the names of functions. (Use @code{@@samp}.) Also, you -should not use @code{@@code} to mark text that is considered input to -programs unless the input is written in a language that is like a -programming language. For example, you should not use @code{@@code} for -the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although -you may use @code{@@code} for the names of the Emacs Lisp functions that -the keystroke commands invoke.@refill - -In the printed manual, @code{@@code} causes @TeX{} to typeset the -argument in a typewriter face. In the Info file, it causes the Info -formatting commands to use single quotation marks around the text. - -@need 700 -For example, - -@example -Use @@code@{diff@} to compare two files. -@end example - -@noindent -produces this in the printed manual:@refill - -@quotation -Use @code{diff} to compare two files. -@end quotation -@iftex - -@noindent -and this in the Info file:@refill - -@example -Use `diff' to compare two files. -@end example -@end iftex - -@node kbd, key, code, Indicating -@comment node-name, next, previous, up -@subsection @code{@@kbd}@{@var{keyboard-characters}@} -@findex kbd - -Use the @code{@@kbd} command for characters of input to be typed by -users. For example, to refer to the characters @kbd{M-a}, -write@refill - -@example -@@kbd@{M-a@} -@end example - -@noindent -and to refer to the characters @kbd{M-x shell}, write@refill - -@example -@@kbd@{M-x shell@} -@end example - -The @code{@@kbd} command has the same effect as @code{@@code} in Info, -but may produce a different font in a printed manual.@refill - -You can embed another @@-command inside the braces of an @code{@@kbd} -command. Here, for example, is the way to describe a command that -would be described more verbosely as ``press an @samp{r} and then -press the @key{RET} key'':@refill - -@example -@@kbd@{r @@key@{RET@}@} -@end example - -@noindent -This produces: @kbd{r @key{RET}} - -You also use the @code{@@kbd} command if you are spelling out the letters -you type; for example:@refill - -@example -To give the @@code@{logout@} command, -type the characters @@kbd@{l o g o u t @@key@{RET@}@}. -@end example - -@noindent -This produces: - -@quotation -To give the @code{logout} command, -type the characters @kbd{l o g o u t @key{RET}}. -@end quotation - -(Also, this example shows that you can add spaces for clarity. If you -really want to mention a space character as one of the characters of -input, write @kbd{@@key@{SPC@}} for it.)@refill - -@node key, samp, kbd, Indicating -@comment node-name, next, previous, up -@subsection @code{@@key}@{@var{key-name}@} -@findex key - -Use the @code{@@key} command for the conventional name for a key on a -keyboard, as in:@refill - -@example -@@key@{RET@} -@end example - -You can use the @code{@@key} command within the argument of an -@code{@@kbd} command when the sequence of characters to be typed -includes one or more keys that are described by name.@refill - -@need 700 -For example, to produce @kbd{C-x @key{ESC}} you would type:@refill - -@example -@@kbd@{C-x @@key@{ESC@}@} -@end example - -Here is a list of the recommended names for keys: -@cindex Recommended names for keys -@cindex Keys, recommended names -@cindex Names recommended for keys -@cindex Abbreviations for keys - -@quotation -@table @t -@item SPC -Space -@item RET -Return -@item LFD -Linefeed (however, since most keyboards nowadays do not have a Linefeed key, -it might be better to call this character @kbd{C-j}. -@item TAB -Tab -@item BS -Backspace -@item ESC -Escape -@item DEL -Delete -@item SHIFT -Shift -@item CTRL -Control -@item META -Meta -@end table -@end quotation - -@cindex META key -There are subtleties to handling words like `meta' or `ctrl' that are -names of shift keys. When mentioning a character in which the shift key -is used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone; do -not use the @code{@@key} command; but when you are referring to the -shift key in isolation, use the @code{@@key} command. For example, -write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and -@samp{@@key@{META@}} to produce @key{META}. - -@c I don't think this is a good explanation. -@c I think it will puzzle readers more than it clarifies matters. -- rms. -@c In other words, use @code{@@kbd} for what you do, and use @code{@@key} -@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to -@c the beginning of the sentence. The @code{@@key@{META@}} key is often in -@c the lower left of the keyboard.''@refill - -@node samp, var, key, Indicating -@comment node-name, next, previous, up -@subsection @code{@@samp}@{@var{text}@} -@findex samp - -Use the @code{@@samp} command to indicate text that is a literal example -or `sample' of a sequence of characters in a file, string, pattern, etc. -Enclose the text in braces. The argument appears within single -quotation marks in both the Info file and the printed manual; in -addition, it is printed in a fixed-width font.@refill - -@example -To match @@samp@{foo@} at the end of the line, -use the regexp @@samp@{foo$@}. -@end example - -@noindent -produces - -@quotation -To match @samp{foo} at the end of the line, use the regexp -@samp{foo$}.@refill -@end quotation - -Any time you are referring to single characters, you should use -@code{@@samp} unless @code{@@kbd} is more appropriate. Use -@code{@@samp} for the names of command-line options. Also, you may use -@code{@@samp} for entire statements in C and for entire shell -commands---in this case, @code{@@samp} often looks better than -@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is -not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill - -Only include punctuation marks within braces if they are part of the -string you are specifying. Write punctuation marks outside the braces -if those punctuation marks are part of the English text that surrounds -the string. In the following sentence, for example, the commas and -period are outside of the braces:@refill - -@example -@group -In English, the vowels are @@samp@{a@}, @@samp@{e@}, -@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes -@@samp@{y@}. -@end group -@end example - -@noindent -This produces: - -@quotation -In English, the vowels are @samp{a}, @samp{e}, -@samp{i}, @samp{o}, @samp{u}, and sometimes -@samp{y}. -@end quotation - -@node var, file, samp, Indicating -@comment node-name, next, previous, up -@subsection @code{@@var}@{@var{metasyntactic-variable}@} -@findex var - -Use the @code{@@var} command to indicate metasyntactic variables. A -@dfn{metasyntactic variable} is something that stands for another piece of -text. For example, you should use a metasyntactic variable in the -documentation of a function to describe the arguments that are passed -to that function.@refill - -Do not use @code{@@var} for the names of particular variables in -programming languages. These are specific names from a program, so -@code{@@code} is correct for them. For example, the Lisp variable -@code{texinfo-tex-command} is not a metasyntactic variable; it is -properly formatted using @code{@@code}.@refill - -The effect of @code{@@var} in the Info file is to change the case of -the argument to all upper case; in the printed manual, to italicize it. - -@need 700 -For example, - -@example -To delete file @@var@{filename@}, -type @@code@{rm @@var@{filename@}@}. -@end example - -@noindent -produces - -@quotation -To delete file @var{filename}, type @code{rm @var{filename}}. -@end quotation - -@noindent -(Note that @code{@@var} may appear inside @code{@@code}, -@code{@@samp}, @code{@@file}, etc.)@refill - -Write a metasyntactic variable all in lower case without spaces, and -use hyphens to make it more readable. Thus, the Texinfo source for -the illustration of how to begin a Texinfo manual looks like -this:@refill - -@example -@group -\input texinfo -@@@@setfilename @@var@{info-file-name@} -@@@@settitle @@var@{name-of-manual@} -@end group -@end example - -@noindent -This produces: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -In some documentation styles, metasyntactic variables are shown with -angle brackets, for example:@refill - -@example -@dots{}, type rm <filename> -@end example - -@noindent -However, that is not the style that Texinfo uses. (You can, of -course, modify the sources to @TeX{} and the Info formatting commands -to output the @code{<@dots{}>} format if you wish.)@refill - -@node file, dfn, var, Indicating -@comment node-name, next, previous, up -@subsection @code{@@file}@{@var{file-name}@} -@findex file - -Use the @code{@@file} command to indicate text that is the name of a -file, buffer, or directory, or is the name of a node in Info. You can -also use the command for file name suffixes. Do not use @code{@@file} -for symbols in a programming language; use @code{@@code}. - -Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. -For example,@refill - -@example -The @@file@{.el@} files are in -the @@file@{/usr/local/emacs/lisp@} directory. -@end example - -@noindent -produces - -@quotation -The @file{.el} files are in -the @file{/usr/local/emacs/lisp} directory. -@end quotation - -@node dfn, cite, file, Indicating -@comment node-name, next, previous, up -@subsection @code{@@dfn}@{@var{term}@} -@findex dfn - -Use the @code{@@dfn} command to identify the introductory or defining -use of a technical term. Use the command only in passages whose -purpose is to introduce a term which will be used again or which the -reader ought to know. Mere passing mention of a term for the first -time does not deserve @code{@@dfn}. The command generates italics in -the printed manual, and double quotation marks in the Info file. For -example:@refill - -@example -Getting rid of a file is called @@dfn@{deleting@} it. -@end example - -@noindent -produces - -@quotation -Getting rid of a file is called @dfn{deleting} it. -@end quotation - -As a general rule, a sentence containing the defining occurrence of a -term should be a definition of the term. The sentence does not need -to say explicitly that it is a definition, but it should contain the -information of a definition---it should make the meaning clear. - -@node cite, url, dfn, Indicating -@comment node-name, next, previous, up -@subsection @code{@@cite}@{@var{reference}@} -@findex cite - -Use the @code{@@cite} command for the name of a book that lacks a -companion Info file. The command produces italics in the printed -manual, and quotation marks in the Info file.@refill - -(If a book is written in Texinfo, it is better to use a cross reference -command since a reader can easily follow such a reference in Info. -@xref{xref, , @code{@@xref}}.)@refill - -@ignore -@c node ctrl, , cite, Indicating -@comment node-name, next, previous, up -@c subsection @code{@@ctrl}@{@var{ctrl-char}@} -@findex ctrl - -The @code{@@ctrl} command is seldom used. It describes an @sc{ascii} -control character by inserting the actual character into the Info -file. - -Usually, in Texinfo, you talk what you type as keyboard entry by -describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for -@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control -character that is typed on the keyboard by the user. When talking -about a control character appearing in a file or a string, do not use -@code{@@kbd} since the control character is not typed. Also, do not -use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, -to make it easier for a reader to understand.@refill - -@code{@@ctrl} is an idea from the beginnings of Texinfo which may not -really fit in to the scheme of things. But there may be times when -you want to use the command. The pattern is -@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character -whose control-equivalent is wanted. For example, to specify -@samp{control-f}, you would enter@refill - -@example -@@ctrl@{f@} -@end example - -@noindent -produces - -@quotation -@ctrl{f} -@end quotation - -In the Info file, this generates the specified control character, output -literally into the file. This is done so a user can copy the specified -control character (along with whatever else he or she wants) into another -Emacs buffer and use it. Since the `control-h',`control-i', and -`control-j' characters are formatting characters, they should not be -indicated with @code{@@ctrl}.@refill - -In a printed manual, @code{@@ctrl} generates text to describe or -identify that control character: an uparrow followed by the character -@var{ch}.@refill -@end ignore - -@node url, email, cite, Indicating -@subsection @code{@@url}@{@var{uniform-resource-locator}@} -@findex url - -Use the @code{@@url} command to indicate a uniform resource locator on -the World Wide Web. For example: - -@c Two lines because one is too long for smallbook format. -@example -The official GNU ftp site is -@@url@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@}. -@end example - -In Info and @TeX{}, this acts like @code{@@samp}. When -Texinfo is converted to HTML, this produces a link you can follow. - -@node email, , url, Indicating -@subsection @code{@@email}@{@var{email-address}@} -@findex email - -Use the @code{@@email} command to indicate an electronic mail address. -For example: - -@example -Send bug reports to @email{bug-texinfo@@prep.ai.mit.edu}. -@end example - -In Info and @TeX{}, this acts like @code{@@samp}. When we have support -for conversion of Texinfo to HTML, this will produce a link you can -follow to bring up a mail composition window initialized with -@var{email-address}. - -@node Emphasis, , Indicating, Marking Text -@comment node-name, next, previous, up -@section Emphasizing Text -@cindex Emphasizing text - -Usually, Texinfo changes the font to mark words in the text according to -what category the words belong to; an example is the @code{@@code} command. -Most often, this is the best way to mark words. -However, sometimes you will want to emphasize text without indicating a -category. Texinfo has two commands to do this. Also, Texinfo has -several commands that specify the font in which @TeX{} will typeset -text. These commands have no affect on Info and only one of them, -the @code{@@r} command, has any regular use.@refill - -@menu -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -* Customized Highlighting:: How to define highlighting commands. -@end menu - -@node emph & strong, Smallcaps, Emphasis, Emphasis -@comment node-name, next, previous, up -@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} -@cindex Emphasizing text, font for -@findex emph -@findex strong - -The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} -produces @emph{italics} and @code{@@strong} produces -@strong{bold}.@refill - -@need 800 -For example, - -@example -@group -@@quotation -@@strong@{Caution:@} @@code@{rm * .[^.]*@} removes @@emph@{all@} -files in the directory. -@@end quotation -@end group -@end example - -@iftex -@noindent -produces the following in printed output: - -@quotation -@strong{Caution}: @code{rm * .[^.]*} removes @emph{all} -files in the directory. -@end quotation - -@noindent -and the following in Info: -@end iftex -@ifinfo -@noindent -produces: -@end ifinfo - -@example - *Caution*: `rm * .[^.]*' removes *all* - files in the directory. -@end example - -The @code{@@strong} command is seldom used except to mark what is, in -effect, a typographical element, such as the word `Caution' in the -preceding example. - -In the Info file, both @code{@@emph} and @code{@@strong} put asterisks -around the text.@refill - -@quotation -@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the -word @samp{Note}; Info will mistake the combination for a cross -reference. Use a phrase such as @strong{Please note} or -@strong{Caution} instead.@refill -@end quotation - -@node Smallcaps, Fonts, emph & strong, Emphasis -@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font -@cindex Small caps font -@findex sc @r{(small caps font)} - -@iftex -Use the @samp{@@sc} command to set text in the printed output in @sc{a -small caps font} and set text in the Info file in upper case letters.@refill -@end iftex -@ifinfo -Use the @samp{@@sc} command to set text in the printed output in a -small caps font and set text in the Info file in upper case letters.@refill -@end ifinfo - -Write the text between braces in lower case, like this:@refill - -@example -The @@sc@{acm@} and @@sc@{ieee@} are technical societies. -@end example - -@noindent -This produces: - -@display -The @sc{acm} and @sc{ieee} are technical societies. -@end display - -@TeX{} typesets the small caps font in a manner that prevents the -letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case. The Info formatting -commands set all small caps text in upper case.@refill - -@ifinfo -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in full-size capitals. Use full-size capitals -sparingly.@refill -@end ifinfo -@iftex -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals -sparingly.@refill -@end iftex - -You may also use the small caps font for a jargon word such as -@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill - -There are subtleties to using the small caps font with a jargon word -such as @sc{cdr}, a word used in Lisp programming. In this case, you -should use the small caps font when the word refers to the second and -subsequent elements of a list (the @sc{cdr} of the list), but you -should use @samp{@@code} when the word refers to the Lisp function of -the same spelling.@refill - -@node Fonts, Customized Highlighting, Smallcaps, Emphasis -@comment node-name, next, previous, up -@subsection Fonts for Printing, Not Info -@cindex Fonts for printing, not for Info -@findex i @r{(italic font)} -@findex b @r{(bold font)} -@findex t @r{(typewriter font)} -@findex r @r{(Roman font)} - -Texinfo provides four font commands that specify font changes in the -printed manual but have no effect in the Info file. @code{@@i} -requests @i{italic} font (in some versions of @TeX{}, a slanted font -is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the -@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a -@r{roman} font, which is the usual font in which text is printed. All -four commands apply to an argument that follows, surrounded by -braces.@refill - -Only the @code{@@r} command has much use: in example programs, you -can use the @code{@@r} command to convert code comments from the -fixed-width font to a roman font. This looks better in printed -output.@refill - -@need 700 -For example, - -@example -@group -@@lisp -(+ 2 2) ; @@r@{Add two plus two.@} -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -(+ 2 2) ; @r{Add two plus two.} -@end lisp - -If possible, you should avoid using the other three font commands. If -you need to use one, it probably indicates a gap in the Texinfo -language.@refill - -@node Customized Highlighting, , Fonts, Emphasis -@comment node-name, next, previous, up -@subsection Customized Highlighting -@cindex Highlighting, customized -@cindex Customized highlighting - -@c I think this whole section is obsolete with the advent of macros -@c --karl, 15sep96. -You can use regular @TeX{} commands inside of @code{@@iftex} @dots{} -@code{@@end iftex} to create your own customized highlighting commands -for Texinfo. The easiest way to do this is to equate your customized -commands with pre-existing commands, such as those for italics. Such -new commands work only with @TeX{}.@refill - -@findex definfoenclose -@cindex Enclosure command for Info -You can use the @code{@@definfoenclose} command inside of -@code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info -with the same names as new commands for @TeX{}. -@code{@@definfoenclose} creates new commands for Info that mark text by -enclosing it in strings that precede and follow the text. -@footnote{Currently, @code{@@definfoenclose} works only with -@code{texinfo-format-buffer} and @code{texinfo-format-region}, not with -@code{makeinfo}.}@refill - -Here is how to create a new @@-command called @code{@@phoo} that causes -@TeX{} to typeset its argument in italics and causes Info to display the -argument between @samp{//} and @samp{\\}.@refill - -@need 1300 -For @TeX{}, write the following to equate the @code{@@phoo} command with -the existing @code{@@i} italics command:@refill - -@example -@group -@@iftex -@@global@@let@@phoo=@@i -@@end iftex -@end group -@end example - -@noindent -This defines @code{@@phoo} as a command that causes @TeX{} to typeset -the argument to @code{@@phoo} in italics. @code{@@global@@let} tells -@TeX{} to equate the next argument with the argument that follows the -equals sign. - -@need 1300 -For Info, write the following to tell the Info formatters to enclose the -argument between @samp{//} and @samp{\\}: - -@example -@group -@@ifinfo -@@definfoenclose phoo, //, \\ -@@end ifinfo -@end group -@end example - -@noindent -Write the @code{@@definfoenclose} command on a line and follow it with -three arguments separated by commas (commas are used as separators in an -@code{@@node} line in the same way).@refill - -@itemize @bullet -@item -The first argument to @code{@@definfoenclose} is the @@-command name -@strong{without} the @samp{@@}; - -@item -the second argument is the Info start delimiter string; and, - -@item -the third argument is the Info end delimiter string. -@end itemize - -@noindent -The latter two arguments enclose the highlighted text in the Info file. -A delimiter string may contain spaces. Neither the start nor end -delimiter is required. However, if you do not provide a start -delimiter, you must follow the command name with two commas in a row; -otherwise, the Info formatting commands will misinterpret the end -delimiter string as a start delimiter string.@refill - -After you have defined @code{@@phoo} both for @TeX{} and for Info, you -can then write @code{@@phoo@{bar@}} to see @samp{//bar\\} -in Info and see -@ifinfo -@samp{bar} in italics in printed output. -@end ifinfo -@iftex -@i{bar} in italics in printed output. -@end iftex - -Note that each definition applies to its own formatter: one for @TeX{}, -the other for Info. - -@need 1200 -Here is another example: - -@example -@group -@@ifinfo -@@definfoenclose headword, , : -@@end ifinfo -@@iftex -@@global@@let@@headword=@@b -@@end iftex -@end group -@end example - -@noindent -This defines @code{@@headword} as an Info formatting command that -inserts nothing before and a colon after the argument and as a @TeX{} -formatting command to typeset its argument in bold. - -@node Quotations and Examples, Lists and Tables, Marking Text, Top -@comment node-name, next, previous, up -@chapter Quotations and Examples - -Quotations and examples are blocks of text consisting of one or more -whole paragraphs that are set off from the bulk of the text and -treated differently. They are usually indented.@refill - -In Texinfo, you always begin a quotation or example by writing an -@@-command at the beginning of a line by itself, and end it by writing -an @code{@@end} command that is also at the beginning of a line by -itself. For instance, you begin an example by writing @code{@@example} -by itself at the beginning of a line and end the example by writing -@code{@@end example} on a line by itself, at the beginning of that -line.@refill -@findex end - -@menu -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. -@end menu - -@node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples -@section The Block Enclosing Commands - -Here are commands for quotations and examples:@refill - -@table @code -@item @@quotation -Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default.@refill - -@item @@example -Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled.@refill - -@item @@lisp -Illustrate Lisp code. The text is printed in a fixed-width font, -and indented but not filled.@refill - -@item @@smallexample -Illustrate code, commands, and the like. Similar to -@code{@@example}, except that in @TeX{} this command typesets text in -a smaller font for the smaller @code{@@smallbook} format than for the -8.5 by 11 inch format.@refill - -@item @@smalllisp -Illustrate Lisp code. Similar to @code{@@lisp}, except that -in @TeX{} this command typesets text in a smaller font for the smaller -@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill - -@item @@display -Display illustrative text. The text is indented but not filled, and -no font is specified (so, by default, the font is roman).@refill - -@item @@format -Print illustrative text. The text is not indented and not filled -and no font is specified (so, by default, the font is roman).@refill -@end table - -The @code{@@exdent} command is used within the above constructs to -undo the indentation of a line. - -The @code{@@flushleft} and @code{@@flushright} commands are used to line -up the left or right margins of unfilled text.@refill - -The @code{@@noindent} command may be used after one of the above -constructs to prevent the following text from being indented as a new -paragraph.@refill - -You can use the @code{@@cartouche} command within one of the above -constructs to highlight the example or quotation by drawing a box with -rounded corners around it. (The @code{@@cartouche} command affects -only the printed manual; it has no effect in the Info file; see -@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@node quotation, example, Block Enclosing Commands, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@quotation} -@cindex Quotations -@findex quotation - -The text of a quotation is -processed normally except that:@refill - -@itemize @bullet -@item -the margins are closer to the center of the page, so the whole of the -quotation is indented;@refill - -@item -the first lines of paragraphs are indented no more than other -lines;@refill - -@item -in the printed output, interparagraph spacing is reduced.@refill -@end itemize - -@quotation -This is an example of text written between an @code{@@quotation} -command and an @code{@@end quotation} command. An @code{@@quotation} -command is most often used to indicate text that is excerpted from -another (real or hypothetical) printed work.@refill -@end quotation - -Write an @code{@@quotation} command as text on a line by itself. This -line will disappear from the output. Mark the end of the quotation -with a line beginning with and containing only @code{@@end quotation}. -The @code{@@end quotation} line will likewise disappear from the -output. Thus, the following,@refill - -@example -@@quotation -This is -a foo. -@@end quotation -@end example - -@noindent -produces - -@quotation -This is a foo. -@end quotation - -@node example, noindent, quotation, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@example} -@cindex Examples, formatting them -@cindex Formatting examples -@findex example - -The @code{@@example} command is used to indicate an example that is -not part of the running text, such as computer input or output.@refill - -@example -@group -This is an example of text written between an -@code{@@example} command -and an @code{@@end example} command. -The text is indented but not filled. -@end group - -@group -In the printed manual, the text is typeset in a -fixed-width font, and extra spaces and blank lines are -significant. In the Info file, an analogous result is -obtained by indenting each line with five spaces. -@end group -@end example - -Write an @code{@@example} command at the beginning of a line by itself. -This line will disappear from the output. Mark the end of the example -with an @code{@@end example} command, also written at the beginning of a -line by itself. The @code{@@end example} will disappear from the -output.@refill - -@need 700 -For example, - -@example -@@example -mv foo bar -@@end example -@end example - -@noindent -produces - -@example -mv foo bar -@end example - -Since the lines containing @code{@@example} and @code{@@end example} -will disappear, you should put a blank line before the -@code{@@example} and another blank line after the @code{@@end -example}. (Remember that blank lines between the beginning -@code{@@example} and the ending @code{@@end example} will appear in -the output.)@refill - -@quotation -@strong{Caution:} Do not use tabs in the lines of an example (or anywhere -else in Texinfo, for that matter)! @TeX{} treats tabs as single -spaces, and that is not what they look like. This is a problem with -@TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to -convert tabs in a region to multiple spaces.)@refill -@end quotation - -Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text continues after an example should not be -indented. The @code{@@noindent} command prevents a piece of text from -being indented as if it were a new paragraph. -@ifinfo -(@xref{noindent}.) -@end ifinfo - -(The @code{@@code} command is used for examples of code that are -embedded within sentences, not set off from preceding and following -text. @xref{code, , @code{@@code}}.) - -@node noindent, Lisp Example, example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@noindent} -@findex noindent - -An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. However, you can prevent this by writing @code{@@noindent} -at the beginning of a line by itself preceding the continuation -text.@refill - -@need 1500 -For example: - -@example -@group -@@example -This is an example -@@end example - -@@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@@code@{@@@@display@} and @@code@{@@@@end display@}.) -@end group -@end example - -@noindent -produces - -@display -@example -This is an example -@end example -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3.5\baselineskip -@end tex - -@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@code{@@display} and @code{@@end display}.) -@end display - -To adjust the number of blank lines properly in the Info file output, -remember that the line containing @code{@@noindent} does not generate a -blank line, and neither does the @code{@@end example} line.@refill - -In the Texinfo source file for this manual, each line that says -`produces' is preceded by a line containing @code{@@noindent}.@refill - -Do not put braces after an @code{@@noindent} command; they are not -necessary, since @code{@@noindent} is a command used outside of -paragraphs (@pxref{Command Syntax}).@refill - -@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@lisp} -@cindex Lisp example -@findex lisp - -The @code{@@lisp} command is used for Lisp code. It is synonymous -with the @code{@@example} command. - -@lisp -This is an example of text written between an -@code{@@lisp} command and an @code{@@end lisp} command. -@end lisp - -Use @code{@@lisp} instead of @code{@@example} so as to preserve -information regarding the nature of the example. This is useful, for -example, if you write a function that evaluates only and all the Lisp -code in a Texinfo file. Then you can use the Texinfo file as a Lisp -library.@footnote{It would be straightforward to extend Texinfo to -work in a similar fashion for C, @sc{fortran}, or other languages.}@refill - -Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by -itself.@refill - -@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@smallexample} and @code{@@smalllisp} -@cindex Small book example -@cindex Example for a small book -@cindex Lisp example for a small book -@findex smallexample -@findex smalllisp - -In addition to the regular @code{@@example} and @code{@@lisp} commands, -Texinfo has two other ``example-style'' commands. These are the -@code{@@smallexample} and @code{@@smalllisp} commands. Both these -commands are designed for use with the @code{@@smallbook} command that -causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format.@refill - -In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands -typeset text in a smaller font for the smaller @code{@@smallbook} -format than for the 8.5 by 11 inch format. Consequently, many examples -containing long lines fit in a narrower, @code{@@smallbook} page -without needing to be shortened. Both commands typeset in the normal -font size when you format for the 8.5 by 11 inch size; indeed, -in this situation, the @code{@@smallexample} and @code{@@smalllisp} -commands are defined to be the @code{@@example} and @code{@@lisp} -commands.@refill - -In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are -equivalent to the @code{@@example} and @code{@@lisp} commands, and work -exactly the same.@refill - -Mark the end of @code{@@smallexample} or @code{@@smalllisp} with -@code{@@end smallexample} or @code{@@end smalllisp}, -respectively.@refill - -@iftex -Here is an example written in the small font used by the -@code{@@smallexample} and @code{@@smalllisp} commands: - -@ifclear smallbook -@display -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3\baselineskip -{\ninett -\dots{} to make sure that you have the freedom to -distribute copies of free software (and charge for -this service if you wish), that you receive source -code or can get it if you want it, that you can -change the software or use pieces of it in new free -programs; and that you know you can do these things.} -@end tex -@end display -@end ifclear -@end iftex -@ifset smallbook -@iftex -@smallexample -This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. -@end smallexample -@end iftex -@end ifset -@ifinfo -@smallexample -This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. -@end smallexample -@end ifinfo - -The @code{@@smallexample} and @code{@@smalllisp} commands make it -easier to prepare smaller format manuals without forcing you to edit -examples by hand to fit them onto narrower pages.@refill - -As a general rule, a printed document looks better if you write all the -examples in a chapter consistently in @code{@@example} or in -@code{@@smallexample}. Only occasionally should you mix the two -formats.@refill - -@xref{smallbook, , Printing ``Small'' Books}, for more information -about the @code{@@smallbook} command.@refill - -@node display, format, smallexample & smalllisp, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@display} -@cindex Display formatting -@findex display - -The @code{@@display} command begins a kind of example. It is like the -@code{@@example} command -except that, in -a printed manual, @code{@@display} does not select the fixed-width -font. In fact, it does not specify the font at all, so that the text -appears in the same font it would have appeared in without the -@code{@@display} command.@refill - -@display -This is an example of text written between an @code{@@display} command -and an @code{@@end display} command. The @code{@@display} command -indents the text, but does not fill it. -@end display - -@node format, exdent, display, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@format} -@findex format - -The @code{@@format} command is similar to @code{@@example} except -that, in the printed manual, @code{@@format} does not select the -fixed-width font and does not narrow the margins.@refill - -@format -This is an example of text written between an @code{@@format} command -and an @code{@@end format} command. As you can see -from this example, -the @code{@@format} command does not fill the text. -@end format - -@node exdent, flushleft & flushright, format, Quotations and Examples -@section @code{@@exdent}: Undoing a Line's Indentation -@cindex Indentation undoing -@findex exdent - -The @code{@@exdent} command removes any indentation a line might have. -The command is written at the beginning of a line and applies only to -the text that follows the command that is on the same line. Do not use -braces around the text. In a printed manual, the text on an -@code{@@exdent} line is printed in the roman font.@refill - -@code{@@exdent} is usually used within examples. Thus,@refill - -@example -@group -@@example -This line follows an @@@@example command. -@@exdent This line is exdented. -This line follows the exdented line. -The @@@@end example comes on the next line. -@@end group -@end group -@end example - -@noindent -produces - -@example -@group -This line follows an @@example command. -@exdent This line is exdented. -This line follows the exdented line. -The @@end example comes on the next line. -@end group -@end example - -In practice, the @code{@@exdent} command is rarely used. -Usually, you un-indent text by ending the example and -returning the page to its normal width.@refill - -@node flushleft & flushright, cartouche, exdent, Quotations and Examples -@section @code{@@flushleft} and @code{@@flushright} -@findex flushleft -@findex flushright - -The @code{@@flushleft} and @code{@@flushright} commands line up the -ends of lines on the left and right margins of a page, -but do not fill the text. The commands are written on lines of their -own, without braces. The @code{@@flushleft} and @code{@@flushright} -commands are ended by @code{@@end flushleft} and @code{@@end -flushright} commands on lines of their own.@refill - -@need 1500 -For example, - -@example -@group -@@flushleft -This text is -written flushleft. -@@end flushleft -@end group -@end example - -@noindent -produces - -@quotation -@flushleft -This text is -written flushleft. -@end flushleft -@end quotation - - -Flushright produces the type of indentation often used in the return -address of letters.@refill - -@need 1500 -@noindent -For example, - -@example -@group -@@flushright -Here is an example of text written -flushright. The @@code@{@@flushright@} command -right justifies every line but leaves the -left end ragged. -@@end flushright -@end group -@end example - -@noindent -produces - -@flushright -Here is an example of text written -flushright. The @code{@@flushright} command -right justifies every line but leaves the -left end ragged. -@end flushright - -@node cartouche, , flushleft & flushright, Quotations and Examples -@section Drawing Cartouches Around Examples -@findex cartouche -@cindex Box with rounded corners - -In a printed manual, the @code{@@cartouche} command draws a box with -rounded corners around its contents. You can use this command to -further highlight an example or quotation. For instance, you could -write a manual in which one type of example is surrounded by a cartouche -for emphasis.@refill - -The @code{@@cartouche} command affects only the printed manual; it has -no effect in the Info file.@refill - -@need 1500 -For example, - -@example -@group -@@example -@@cartouche -% pwd -/usr/local/lib/emacs/info -@@end cartouche -@@end example -@end group -@end example - -@noindent -surrounds the two-line example with a box with rounded corners, in the -printed manual. - -@iftex -In a printed manual, the example looks like this:@refill - -@example -@group -@cartouche -% pwd -/usr/local/lib/emacs/info -@end cartouche -@end group -@end example -@end iftex - -@node Lists and Tables, Indices, Quotations and Examples, Top -@comment node-name, next, previous, up -@chapter Making Lists and Tables -@cindex Making lists and tables -@cindex Lists and tables, making them -@cindex Tables and lists, making them - -Texinfo has several ways of making lists and two-column tables. Lists can -be bulleted or numbered, while two-column tables can highlight the items in -the first column.@refill - -@menu -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. -@end menu - -@ifinfo -@node Introducing Lists, itemize, Lists and Tables, Lists and Tables -@heading Introducing Lists -@end ifinfo - -Texinfo automatically indents the text in lists or tables, and numbers -an enumerated list. This last feature is useful if you modify the -list, since you do not need to renumber it yourself.@refill - -Numbered lists and tables begin with the appropriate @@-command at the -beginning of a line, and end with the corresponding @code{@@end} -command on a line by itself. The table and itemized-list commands -also require that you write formatting information on the same line as -the beginning @@-command.@refill - -Begin an enumerated list, for example, with an @code{@@enumerate} -command and end the list with an @code{@@end enumerate} command. -Begin an itemized list with an @code{@@itemize} command, followed on -the same line by a formatting command such as @code{@@bullet}, and end -the list with an @code{@@end itemize} command.@refill -@findex end - -Precede each element of a list with an @code{@@item} or @code{@@itemx} -command.@refill - -@sp 1 -@noindent -Here is an itemized list of the different kinds of table and lists:@refill - -@itemize @bullet -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end itemize - -@sp 1 -@noindent -Here is an enumerated list with the same items:@refill - -@enumerate -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end enumerate - -@sp 1 -@noindent -And here is a two-column table with the same items and their -@w{@@-commands}:@refill - -@table @code -@item @@itemize -Itemized lists with and without bullets. - -@item @@enumerate -Enumerated lists, using numbers or letters. - -@item @@table -@itemx @@ftable -@itemx @@vtable -Two-column tables with indexing. -@end table - -@node itemize, enumerate, Introducing Lists, Lists and Tables -@comment node-name, next, previous, up -@section Making an Itemized List -@cindex Itemization -@findex itemize - -The @code{@@itemize} command produces sequences of indented -paragraphs, with a bullet or other mark inside the left margin -at the beginning of each paragraph for which such a mark is desired.@refill - -Begin an itemized list by writing @code{@@itemize} at the beginning of -a line. Follow the command, on the same line, with a character or a -Texinfo command that generates a mark. Usually, you will write -@code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any character or any special symbol that results in -a single character in the Info file. (When you write @code{@@bullet} -or @code{@@minus} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.)@refill - -Write the text of the indented paragraphs themselves after the -@code{@@itemize}, up to another line that says @code{@@end -itemize}.@refill - -Before each paragraph for which a mark in the margin is desired, write -a line that says just @code{@@item}. Do not write any other text on this -line.@refill -@findex item - -Usually, you should put a blank line before an @code{@@item}. This -puts a blank line in the Info file. (@TeX{} inserts the proper -interline whitespace in either case.) Except when the entries are -very brief, these blank lines make the list look better.@refill - -Here is an example of the use of @code{@@itemize}, followed by the -output it produces. Note that @code{@@bullet} produces an @samp{*} in -Info and a round dot in @TeX{}.@refill - -@example -@group -@@itemize @@bullet -@@item -Some text for foo. - -@@item -Some text -for bar. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -Some text for foo. - -@item -Some text -for bar. -@end itemize -@end quotation - -Itemized lists may be embedded within other itemized lists. Here is a -list marked with dashes embedded in a list marked with bullets:@refill - -@example -@group -@@itemize @@bullet -@@item -First item. - -@@itemize @@minus -@@item -Inner item. - -@@item -Second inner item. -@@end itemize - -@@item -Second outer item. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -First item. - -@itemize @minus -@item -Inner item. - -@item -Second inner item. -@end itemize - -@item -Second outer item. -@end itemize -@end quotation - -@node enumerate, Two-column Tables, itemize, Lists and Tables -@comment node-name, next, previous, up -@section Making a Numbered or Lettered List -@cindex Enumeration -@findex enumerate - -@code{@@enumerate} is like @code{@@itemize} except that the marks in -the left margin contain successive integers or letters. -(@xref{itemize, , @code{@@itemize}}.)@refill - -Write the @code{@@enumerate} command at the beginning of a line. -The command does not require an argument, but accepts either a number or -a letter as an option. -Without an argument, @code{@@enumerate} starts the list -with the number 1. With a numeric argument, such as 3, -the command starts the list with that number. -With an upper or lower case letter, such as @kbd{a} or @kbd{A}, -the command starts the list with that letter.@refill - -Write the text of the enumerated list in the same way you write an -itemized list: put @code{@@item} on a line of its own before the start of -each paragraph that you want enumerated. Do not write any other text on -the line beginning with @code{@@item}.@refill - -You should put a blank line between entries in the list. -This generally makes it easier to read the Info file.@refill - -@need 1500 -Here is an example of @code{@@enumerate} without an argument:@refill - -@example -@group -@@enumerate -@@item -Underlying causes. - -@@item -Proximate causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate -@item -Underlying causes. - -@item -Proximate causes. -@end enumerate -@sp 1 -Here is an example with an argument of @kbd{3}:@refill -@sp 1 -@example -@group -@@enumerate 3 -@@item -Predisposing causes. - -@@item -Precipitating causes. - -@@item -Perpetuating causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate 3 -@item -Predisposing causes. - -@item -Precipitating causes. - -@item -Perpetuating causes. -@end enumerate -@sp 1 -Here is a brief summary of the alternatives. The summary is constructed -using @code{@@enumerate} with an argument of @kbd{a}.@refill -@sp 1 -@enumerate a -@item -@code{@@enumerate} - -Without an argument, produce a numbered list, starting with the number -1.@refill - -@item -@code{@@enumerate @var{positive-integer}} - -With a (positive) numeric argument, start a numbered list with that -number. You can use this to continue a list that you interrupted with -other text.@refill - -@item -@code{@@enumerate @var{upper-case-letter}} - -With an upper case letter as argument, start a list -in which each item is marked -by a letter, beginning with that upper case letter.@refill - -@item -@code{@@enumerate @var{lower-case-letter}} - -With a lower case letter as argument, start a list -in which each item is marked by -a letter, beginning with that lower case letter.@refill -@end enumerate - -You can also nest enumerated lists, as in an outline.@refill - -@node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables -@section Making a Two-column Table -@cindex Tables, making two-column -@findex table - -@code{@@table} is similar to @code{@@itemize}, but the command allows -you to specify a name or heading line for each item. (@xref{itemize, -, @code{@@itemize}}.) The @code{@@table} command is used to produce -two-column tables, and is especially useful for glossaries and -explanatory exhibits.@refill - -@menu -* table:: How to construct a two-column table. -* ftable vtable:: How to construct a two-column table - with automatic indexing. -* itemx:: How to put more entries in the first column. -@end menu - -@ifinfo -@node table, ftable vtable, Two-column Tables, Two-column Tables -@subheading Using the @code{@@table} Command - -Use the @code{@@table} command to produce two-column tables.@refill -@end ifinfo - -Write the @code{@@table} command at the beginning of a line and follow -it on the same line with an argument that is a Texinfo command such as -@code{@@code}, @code{@@samp}, @code{@@var}, or @code{@@kbd}. -Although these commands are usually followed by arguments in braces, -in this case you use the command name without an argument because -@code{@@item} will supply the argument. This command will be applied -to the text that goes into the first column of each item and -determines how it will be highlighted. For example, @code{@@samp} -will cause the text in the first column to be highlighted with an -@code{@@samp} command.@refill - -You may also choose to use the @code{@@asis} command as an argument to -@code{@@table}. @code{@@asis} is a command that does nothing; if you use this -command after @code{@@table}, @TeX{} and the Info formatting commands -output the first column entries without added highlighting (`as -is').@refill - -(The @code{@@table} command may work with other commands besides those -listed here. However, you can only use commands -that normally take arguments in braces.)@refill - -Begin each table entry with an @code{@@item} command at the beginning -of a line. Write the first column text on the same line as the -@code{@@item} command. Write the second column text on the line -following the @code{@@item} line and on subsequent lines. (You do not -need to type anything for an empty second column entry.) You may -write as many lines of supporting text as you wish, even several -paragraphs. But only text on the same line as the @code{@@item} will -be placed in the first column.@refill -@findex item - -Normally, you should put a blank line before an @code{@@item} line. -This puts a blank like in the Info file. Except when the entries are -very brief, a blank line looks better.@refill - -@need 1500 -The following table, for example, highlights the text in the first -column with an @code{@@samp} command:@refill - -@example -@group -@@table @@samp -@@item foo -This is the text for -@@samp@{foo@}. - -@@item bar -Text for @@samp@{bar@}. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @samp -@item foo -This is the text for -@samp{foo}. -@item bar -Text for @samp{bar}. -@end table - -If you want to list two or more named items with a single block of -text, use the @code{@@itemx} command. (@xref{itemx, , -@code{@@itemx}}.)@refill - -@node ftable vtable, itemx, table, Two-column Tables -@comment node-name, next, previous, up -@subsection @code{@@ftable} and @code{@@vtable} -@cindex Tables with indexes -@cindex Indexing table entries automatically -@findex ftable -@findex vtable - -The @code{@@ftable} and @code{@@vtable} commands are the same as the -@code{@@table} command except that @code{@@ftable} automatically enters -each of the items in the first column of the table into the index of -functions and @code{@@vtable} automatically enters each of the items in -the first column of the table into the index of variables. This -simplifies the task of creating indices. Only the items on the same -line as the @code{@@item} commands are indexed, and they are indexed in -exactly the form that they appear on that line. @xref{Indices, , -Creating Indices}, for more information about indices.@refill - -Begin a two-column table using @code{@@ftable} or @code{@@vtable} by -writing the @@-command at the beginning of a line, followed on the same -line by an argument that is a Texinfo command such as @code{@@code}, -exactly as you would for an @code{@@table} command; and end the table -with an @code{@@end ftable} or @code{@@end vtable} command on a line by -itself. - -See the example for @code{@@table} in the previous section. - -@node itemx, , ftable vtable, Two-column Tables -@comment node-name, next, previous, up -@subsection @code{@@itemx} -@cindex Two named items for @code{@@table} -@findex itemx - -Use the @code{@@itemx} command inside a table when you have two or -more first column entries for the same item, each of which should -appear on a line of its own. Use @code{@@itemx} for all but the first -entry. The @code{@@itemx} command works exactly like @code{@@item} -except that it does not generate extra vertical space above the first -column text.@refill - -@need 1000 -For example, - -@example -@group -@@table @@code -@@item upcase -@@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding upper case (lower -case) character or string. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @code -@item upcase -@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding upper case (lower -case) character or string.@refill -@end table - -@noindent -(Note also that this example illustrates multi-line supporting text in -a two-column table.)@refill - - -@node Multi-column Tables, , Two-column Tables, Lists and Tables -@section Multi-column Tables -@cindex Tables, making multi-column -@findex multitable - -@code{@@multitable} allows you to construct tables with any number of -columns, with each column having any width you like. - -You define the column widths on the @code{@@multitable} line itself, and -write each row of the actual table following an @code{@@item} command, -with columns separated by an @code{@@tab} command. Finally, @code{@@end -multitable} completes the table. Details in the sections below. - -@menu -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. -@end menu - -@node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables -@subsection Multitable Column Widths -@cindex Multitable column widths -@cindex Column widths, defining for multitables -@cindex Widths, defining multitable column - -You can define the column widths for a multitable in two ways: as -fractions of the line length; or with a prototype row. Mixing the two -methods is not supported. In either case, the widths are defined -entirely on the same line as the @code{@@multitable} command. - -@enumerate -@item -@findex columnfractions -@cindex Line length, column widths as fraction of -To specify column widths as fractions of the line length, write -@code{@@columnfractions} and the decimal numbers (presumably less than -1) after the @code{@@multitable} command, as in: - -@example -@@multitable @@columnfractions .33 .33 .33 -@end example - -@noindent The fractions need not add up exactly to 1.0, as these do -not. This allows you to produce tables that do not need the full line -length. - -@item -@cindex Prototype row, column widths defined by -To specify a prototype row, write the longest entry for each column -enclosed in braces after the @code{@@multitable} command. For example: - -@example -@@multitable @{some text for column one@} @{for column two@} -@end example - -@noindent -The first column will then have the width of the typeset `some text for -column one', and the second column the width of `for column two'. - -The prototype entries need not appear in the table itself. - -Although we used simple text in this example, the prototype entries can -contain Texinfo commands; markup commands such as @code{@@code} are -particularly likely to be useful. - -@end enumerate - - -@node Multitable Rows, , Multitable Column Widths, Multi-column Tables -@subsection Multitable Rows -@cindex Multitable rows -@cindex Rows, of a multitable - -@findex item -@cindex tab -After the @code{@@multitable} command defining the column widths (see -the previous section), you begin each row in the body of a multitable -with @code{@@item}, and separate the column entries with @code{@@tab}. -Line breaks are not special within the table body, and you may break -input lines in your source file as necessary. - -Here is a complete example of a multi-column table (the text is from -the GNU Emacs manual): - -@example -@@multitable @@columnfractions .15 .45 .4 -@@item Key @@tab Command @@tab Description -@@item C-x 2 -@@tab @@code@{split-window-vertically@} -@@tab Split the selected window into two windows, -with one above the other. -@@item C-x 3 -@@tab @@code@{split-window-horizontally@} -@@tab Split the selected window into two windows -positioned side by side. -@@item C-Mouse-2 -@@tab -@@tab In the mode line or scroll bar of a window, -split that window. -@@end multitable -@end example - -@noindent produces: - -@multitable @columnfractions .15 .45 .4 -@item Key @tab Command @tab Description -@item C-x 2 -@tab @code{split-window-vertically} -@tab Split the selected window into two windows, -with one above the other. -@item C-x 3 -@tab @code{split-window-horizontally} -@tab Split the selected window into two windows -positioned side by side. -@item C-Mouse-2 -@tab -@tab In the mode line or scroll bar of a window, -split that window. -@end multitable - - -@node Indices, Insertions, Lists and Tables, Top -@comment node-name, next, previous, up -@chapter Creating Indices -@cindex Indices -@cindex Creating indices - -Using Texinfo, you can generate indices without having to sort and -collate entries manually. In an index, the entries are listed in -alphabetical order, together with information on how to find the -discussion of each entry. In a printed manual, this information -consists of page numbers. In an Info file, this information is a menu -entry leading to the first node referenced.@refill - -Texinfo provides several predefined kinds of index: an index -for functions, an index for variables, an index for concepts, and so -on. You can combine indices or use them for other than their -canonical purpose. If you wish, you can define your own indices.@refill - -@menu -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entry. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. -@end menu - -@node Index Entries, Predefined Indices, Indices, Indices -@comment node-name, next, previous, up -@section Making Index Entries -@cindex Index entries, making -@cindex Entries, making index - -When you are making index entries, it is good practice to think of the -different ways people may look for something. Different people -@emph{do not} think of the same words when they look something up. A -helpful index will have items indexed under all the different words -that people may use. For example, one reader may think it obvious that -the two-letter names for indices should be listed under ``Indices, -two-letter names'', since the word ``Index'' is the general concept. -But another reader may remember the specific concept of two-letter -names and search for the entry listed as ``Two letter names for -indices''. A good index will have both entries and will help both -readers.@refill - -Like typesetting, the construction of an index is a highly skilled, -professional art, the subtleties of which are not appreciated until you -need to do it yourself.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - -@node Predefined Indices, Indexing Commands, Index Entries, Indices -@comment node-name, next, previous, up -@section Predefined Indices - -Texinfo provides six predefined indices:@refill - -@itemize @bullet -@item -A @dfn{concept index} listing concepts that are discussed.@refill - -@item -A @dfn{function index} listing functions (such as entry points of -libraries).@refill - -@item -A @dfn{variables index} listing variables (such as global variables -of libraries).@refill - -@item -A @dfn{keystroke index} listing keyboard commands.@refill - -@item -A @dfn{program index} listing names of programs.@refill - -@item -A @dfn{data type index} listing data types (such as structures defined in -header files).@refill -@end itemize - -@noindent -Not every manual needs all of these, and most manuals use two or three -of them. This manual has two indices: a -concept index and an @@-command index (that is actually the function -index but is called a command index in the chapter heading). Two or -more indices can be combined into one using the @code{@@synindex} or -@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill - -@node Indexing Commands, Combining Indices, Predefined Indices, Indices -@comment node-name, next, previous, up -@section Defining the Entries of an Index -@cindex Defining indexing entries -@cindex Index entries -@cindex Entries for an index -@cindex Specifying index entries -@cindex Creating index entries - -The data to make an index come from many individual indexing commands -scattered throughout the Texinfo source file. Each command says to add -one entry to a particular index; after formatting, the index will give -the current page number or node name as the reference.@refill - -An index entry consists of an indexing command at the beginning of a -line followed, on the rest of the line, by the entry.@refill - -For example, this section begins with the following five entries for -the concept index:@refill - -@example -@@cindex Defining indexing entries -@@cindex Index entries -@@cindex Entries for an index -@@cindex Specifying index entries -@@cindex Creating index entries -@end example - -Each predefined index has its own indexing command---@code{@@cindex} -for the concept index, @code{@@findex} for the function index, and so -on.@refill - -@cindex Writing index entries -@cindex Index entry writing -Concept index entries consist of text. The best way to write an index -is to choose entries that are terse yet clear. If you can do this, -the index often looks better if the entries are not capitalized, but -written just as they would appear in the middle of a sentence. -(Capitalize proper names and acronyms that always call for upper case -letters.) This is the case convention we use in most GNU manuals' -indices. - -If you don't see how to make an entry terse yet clear, make it longer -and clear---not terse and confusing. If many of the entries are several -words long, the index may look better if you use a different convention: -to capitalize the first word of each entry. But do not capitalize a -case-sensitive name such as a C or Lisp function name or a shell -command; that would be a spelling error. - -Whichever case convention you use, please use it consistently! - -@ignore -Concept index entries consist of English text. The usual convention -is to capitalize the first word of each such index entry, unless that -word is the name of a function, variable, or other such entity that -should not be capitalized. However, if your concept index entries are -consistently short (one or two words each) it may look better for each -regular entry to start with a lower case letter, aside from proper -names and acronyms that always call for upper case letters. Whichever -convention you adapt, please be consistent! -@end ignore - -Entries in indices other than the concept index are symbol names in -programming languages, or program names; these names are usually -case-sensitive, so use upper and lower case as required for them. - -By default, entries for a concept index are printed in a small roman -font and entries for the other indices are printed in a small -@code{@@code} font. You may change the way part of an entry is -printed with the usual Texinfo commands, such as @code{@@file} for -file names and @code{@@emph} for emphasis (@pxref{Marking -Text}).@refill -@cindex Index font types - -@cindex Predefined indexing commands -@cindex Indexing commands, predefined -The six indexing commands for predefined indices are: - -@table @code -@item @@cindex @var{concept} -@findex cindex -Make an entry in the concept index for @var{concept}.@refill - -@item @@findex @var{function} -@findex findex -Make an entry in the function index for @var{function}.@refill - -@item @@vindex @var{variable} -@findex vindex -Make an entry in the variable index for @var{variable}.@refill - -@item @@kindex @var{keystroke} -@findex kindex -Make an entry in the key index for @var{keystroke}.@refill - -@item @@pindex @var{program} -@findex pindex -Make an entry in the program index for @var{program}.@refill - -@item @@tindex @var{data type} -@findex tindex -Make an entry in the data type index for @var{data type}.@refill -@end table - -@quotation -@strong{Caution:} Do not use a colon in an index entry. In Info, a -colon separates the menu entry name from the node name. An extra -colon confuses Info. -@xref{Menu Parts, , The Parts of a Menu}, -for more information about the structure of a menu entry.@refill -@end quotation - -If you write several identical index entries in different places in a -Texinfo file, the index in the printed manual will list all the pages to -which those entries refer. However, the index in the Info file will -list @strong{only} the node that references the @strong{first} of those -index entries. Therefore, it is best to write indices in which each -entry refers to only one place in the Texinfo file. Fortunately, this -constraint is a feature rather than a loss since it means that the index -will be easy to use. Otherwise, you could create an index that lists -several pages for one entry and your reader would not know to which page -to turn. If you have two identical entries for one topic, change the -topics slightly, or qualify them to indicate the difference.@refill - -You are not actually required to use the predefined indices for their -canonical purposes. For example, suppose you wish to index some C -preprocessor macros. You could put them in the function index along -with actual functions, just by writing @code{@@findex} commands for -them; then, when you print the ``Function Index'' as an unnumbered -chapter, you could give it the title `Function and Macro Index' and -all will be consistent for the reader. Or you could put the macros in -with the data types by writing @code{@@tindex} commands for them, and -give that index a suitable title so the reader will understand. -(@xref{Printing Indices & Menus}.)@refill - -@node Combining Indices, New Indices, Indexing Commands, Indices -@comment node-name, next, previous, up -@section Combining Indices -@cindex Combining indices -@cindex Indices, combining them - -Sometimes you will want to combine two disparate indices such as functions -and concepts, perhaps because you have few enough of one of them that -a separate index for them would look silly.@refill - -You could put functions into the concept index by writing -@code{@@cindex} commands for them instead of @code{@@findex} commands, -and produce a consistent manual by printing the concept index with the -title `Function and Concept Index' and not printing the `Function -Index' at all; but this is not a robust procedure. It works only if -your document is never included as part of another -document that is designed to have a separate function index; if your -document were to be included with such a document, the functions from -your document and those from the other would not end up together. -Also, to make your function names appear in the right font in the -concept index, you would need to enclose every one of them between -the braces of @code{@@code}.@refill - -@menu -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. -@end menu - -@node syncodeindex, synindex, Combining Indices, Combining Indices -@subsection @code{@@syncodeindex} -@findex syncodeindex - -When you want to combine functions and concepts into one index, you -should index the functions with @code{@@findex} and index the concepts -with @code{@@cindex}, and use the @code{@@syncodeindex} command to -redirect the function index entries into the concept index.@refill -@findex syncodeindex - -The @code{@@syncodeindex} command takes two arguments; they are the name -of the index to redirect, and the name of the index to redirect it to. -The template looks like this:@refill - -@example -@@syncodeindex @var{from} @var{to} -@end example - -@cindex Predefined names for indices -@cindex Two letter names for indices -@cindex Indices, two letter names -@cindex Names for indices -For this purpose, the indices are given two-letter names:@refill - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table - -Write an @code{@@syncodeindex} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. For example, -to merge a function index with a concept index, write the -following:@refill - -@example -@@syncodeindex fn cp -@end example - -@noindent -This will cause all entries designated for the function index to merge -in with the concept index instead.@refill - -To merge both a variables index and a function index into a concept -index, write the following:@refill - -@example -@group -@@syncodeindex vr cp -@@syncodeindex fn cp -@end group -@end example - -@cindex Fonts for indices -The @code{@@syncodeindex} command puts all the entries from the `from' -index (the redirected index) into the @code{@@code} font, overriding -whatever default font is used by the index to which the entries are -now directed. This way, if you direct function names from a function -index into a concept index, all the function names are printed in the -@code{@@code} font as you would expect.@refill - -@node synindex, , syncodeindex, Combining Indices -@subsection @code{@@synindex} -@findex synindex - -The @code{@@synindex} command is nearly the same as the -@code{@@syncodeindex} command, except that it does not put the -`from' index entries into the @code{@@code} font; rather it puts -them in the roman font. Thus, you use @code{@@synindex} when you -merge a concept index into a function index.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - -@node New Indices, , Combining Indices, Indices -@section Defining New Indices -@cindex Defining new indices -@cindex Indices, defining new -@cindex New index defining -@findex defindex -@findex defcodeindex - -In addition to the predefined indices, you may use the -@code{@@defindex} and @code{@@defcodeindex} commands to define new -indices. These commands create new indexing @@-commands with which -you mark index entries. The @code{@@defindex }command is used like -this:@refill - -@example -@@defindex @var{name} -@end example - -The name of an index should be a two letter word, such as @samp{au}. -For example:@refill - -@example -@@defindex au -@end example - -This defines a new index, called the @samp{au} index. At the same -time, it creates a new indexing command, @code{@@auindex}, that you -can use to make index entries. Use the new indexing command just as -you would use a predefined indexing command.@refill - -For example, here is a section heading followed by a concept index -entry and two @samp{au} index entries.@refill - -@example -@@section Cognitive Semantics -@@cindex kinesthetic image schemas -@@auindex Johnson, Mark -@@auindex Lakoff, George -@end example - -@noindent -(Evidently, @samp{au} serves here as an abbreviation for ``author''.) -Texinfo constructs the new indexing command by concatenating the name -of the index with @samp{index}; thus, defining an @samp{au} index -leads to the automatic creation of an @code{@@auindex} command.@refill - -Use the @code{@@printindex} command to print the index, as you do with -the predefined indices. For example:@refill - -@example -@group -@@node Author Index, Subject Index, , Top -@@unnumbered Author Index - -@@printindex au -@end group -@end example - -The @code{@@defcodeindex} is like the @code{@@defindex} command, except -that, in the printed output, it prints entries in an @code{@@code} font -instead of a roman font. Thus, it parallels the @code{@@findex} command -rather than the @code{@@cindex} command.@refill - -You should define new indices within or right after the end-of-header -line of a Texinfo file, before any @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Header}).@refill - -@node Insertions, Glyphs, Indices, Top -@comment node-name, next, previous, up -@chapter Special Insertions -@cindex Inserting special characters and symbols -@cindex Special insertions - -Texinfo provides several commands for formatting dimensions, for -inserting single characters that have special meaning in Texinfo, such -as braces, and for inserting special graphic symbols that do not -correspond to characters, such as dots and bullets.@refill - -@iftex -These are: - -@itemize @bullet -@item -Braces, @samp{@@} and periods. - -@item -Format a dimension, such as @samp{12@dmn{pt}}. - -@item -Dots and bullets. - -@item -The @TeX{} logo and the copyright symbol. - -@item -A minus sign. -@end itemize -@end iftex - -@menu -* Braces Atsigns:: How to insert braces, @samp{@@}. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* pounds:: How to insert the pounds currency symbol. -* minus:: How to insert a minus sign. -* math:: How to format a mathematical expression. -@end menu - - -@node Braces Atsigns, Inserting Space, Insertions, Insertions -@section Inserting @@ and Braces -@cindex Inserting @@, braces -@cindex Braces, inserting -@cindex Special characters, commands to insert -@cindex Commands to insert special characters - -@samp{@@} and curly braces are special characters in Texinfo. To insert -these characters so they appear in text, you must put an @samp{@@} in -front of these characters to prevent Texinfo from misinterpreting -them. - -Do not put braces after any of these commands; they are not -necessary. - -@menu -* Inserting An Atsign:: How to insert @samp{@@}. -* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. -@end menu - -@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns -@subsection Inserting @samp{@@} with @@@@ -@findex @@ @r{(single @samp{@@})} - -@code{@@@@} stands for a single @samp{@@} in either printed or Info -output. - -Do not put braces after an @code{@@@@} command. - -@node Inserting Braces, , Inserting An Atsign, Braces Atsigns -@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} -@findex @{ @r{(single @samp{@{})} -@findex @} @r{(single @samp{@}})} - -@code{@@@{} stands for a single @samp{@{} in either printed or Info -output. - -@code{@@@}} stands for a single @samp{@}} in either printed or Info -output. - -Do not put braces after either an @code{@@@{} or an @code{@@@}} -command. - - -@node Inserting Space, Inserting Accents, Braces Atsigns, Insertions -@section Inserting Space - -@cindex Inserting space -@cindex Spacing, inserting -@cindex Whitespace, inserting -The following sections describe commands that control spacing of various -kinds within and after sentences. - -@menu -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* dmn:: How to format a dimension. -@end menu - -@node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space -@subsection Not Ending a Sentence - -@cindex Not ending a sentence -@cindex Sentence non-ending punctuation -@cindex Periods, inserting -Depending on whether a period or exclamation point or question mark is -inside or at the end of a sentence, less or more space is inserted after -a period in a typeset manual. Since it is not always possible for -Texinfo to determine when a period ends a sentence and when it is used -in an abbreviation, special commands are needed in some circumstances. -(Usually, Texinfo can guess how to handle periods, so you do not need to -use the special commands; you just enter a period as you would if you -were using a typewriter, which means you put two spaces after the -period, question mark, or exclamation mark that ends a sentence.) - -@findex : @r{(suppress widening)} -Use the @code{@@:}@: command after a period, question mark, -exclamation mark, or colon that should not be followed by extra space. -For example, use @code{@@:}@: after periods that end abbreviations -which are not at the ends of sentences. @code{@@:}@: has no effect on -the Info file output. - -@need 700 -For example, - -@example -The s.o.p.@@: has three parts @dots{} -The s.o.p. has three parts @dots{} -@end example - -@noindent -@ifinfo -produces -@end ifinfo -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after @samp{s.o.p.} in the second -line.@refill -@end iftex - -@quotation -The s.o.p.@: has three parts @dots{}@* -The s.o.p. has three parts @dots{} -@end quotation - -@noindent -@kbd{@@:} has no effect on the Info output. (@samp{s.o.p.} is an -abbreviation for ``Standard Operating Procedure''.) - -Do not put braces after @code{@@:}. - - -@node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space -@subsection Ending a Sentence - -@cindex Ending a Sentence -@cindex Sentence ending punctuation - -@findex . @r{(end of sentence)} -@findex ! @r{(end of sentence)} -@findex ? @r{(end of sentence)} -Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an -exclamation point, and @code{@@?}@: instead of a question mark at the end -of a sentence that ends with a single capital letter. Otherwise, @TeX{} -will think the letter is an abbreviation and will not insert the correct -end-of-sentence spacing. Here is an example: - -@example -Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end example - -@noindent -@ifinfo -produces -@end ifinfo -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after the @samp{W} in the first -line. -@end iftex - -@quotation -Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end quotation - -In the Info file output, @code{@@.}@: is equivalent to a simple -@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. - -The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to -work well with the Emacs sentence motion commands (@pxref{Sentences,,, -emacs, GNU Emacs}). This made it necessary for them to be incompatible -with some other formatting systems that use @@-commands. - -Do not put braces after any of these commands. - - -@node Multiple Spaces, dmn, Ending a Sentence, Inserting Space -@subsection Multiple Spaces - -@cindex Multiple spaces -@cindex Whitespace, inserting -@findex (space) -@findex (tab) -@findex (newline) - -Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, -and newline) into a single space. (Info output, on the other hand, -preserves whitespace as you type it, except for changing a newline into -a space; this is why it is important to put two spaces at the end of -sentences in Texinfo documents.) - -Occasionally, you may want to actually insert several consecutive -spaces, either for purposes of example (what your program does with -multiple spaces as input), or merely for purposes of appearance in -headings or lists. Texinfo supports three commands: @code{@@ }, -@code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of which insert a single -space into the output. (Here, @kbd{TAB} and @kbd{NL} represent the tab -character and end-of-line, i.e., when @samp{@@} is the last character on -a line.) - -For example, -@example -Spacey@@ @@ @@ @@ -example. -@end example - -@noindent produces - -@example -Spacey@ @ @ @ -example. -@end example - -Other possible uses of @code{@@ } have been subsumed by @code{@@multitable} -(@pxref{Multi-column Tables}). - -Do not follow any of these commands with braces. - - -@node dmn, , Multiple Spaces, Inserting Space -@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension -@cindex Thin space between number, dimension -@cindex Dimension formatting -@cindex Format a dimension -@findex dmn - -At times, you may want to write @samp{12@dmn{pt}} or -@samp{8.5@dmn{in}} with little or no space between the number and the -abbreviation for the dimension. You can use the @code{@@dmn} command -to do this. On seeing the command, @TeX{} inserts just enough space -for proper typesetting; the Info formatting commands insert no space -at all, since the Info file does not require it.@refill - -To use the @code{@@dmn} command, write the number and then follow it -immediately, with no intervening space, by @code{@@dmn}, and then by -the dimension within braces.@refill - -@need 700 -@noindent -For example, - -@example -A4 paper is 8.27@@dmn@{in@} wide. -@end example - -@noindent -produces - -@quotation -A4 paper is 8.27@dmn{in} wide. -@end quotation - -Not everyone uses this style. Instead of writing -@w{@samp{8.27@@dmn@{in@}}} in the Texinfo file, you may write -@w{@samp{8.27 in.}} or @w{@samp{8.27 inches}}. (In these cases, the -formatters may insert a line break between the number and the -dimension. Also, if you write a period after an abbreviation within a -sentence, you should write @samp{@@:} after the period to prevent -@TeX{} from inserting extra whitespace. @xref{Inserting Space}. - - -@node Inserting Accents, Dots Bullets, Inserting Space, Insertions -@section Inserting Accents - -@cindex Inserting accents -@cindex Accents, inserting -@cindex Floating accents, inserting - -Here is a table with the commands Texinfo provides for inserting -floating accents. The commands with non-alphabetic names do not take -braces around their argument (which is taken to be the next character). -(Exception: @code{@@,} @emph{does} take braces around its argument.) -This is so as to make the source as convenient to type and read as -possible, since accented characters are very common in some languages. - -@findex " -@cindex Umlaut accent -@findex ' -@cindex Acute accent -@findex = -@cindex Macron accent -@findex ^ -@cindex Circumflex accent -@findex ` -@cindex Grave accent -@findex ~ -@cindex Tilde accent -@findex , -@cindex Cedilla accent -@findex dotaccent -@cindex Dot accent -@findex H -@cindex Hungariam umlaut accent -@findex ringaccent -@cindex Ring accent -@findex tieaccent -@cindex Tie-after accent -@findex u -@cindex Breve accent -@findex ubaraccent -@cindex Underbar accent -@findex udotaccent -@cindex Underdot accent -@findex v -@cindex Check accent -@multitable {@@questiondown@{@}} {Output} {macron/overbar accent} -@item Command @tab Output @tab What -@item @t{@@"o} @tab @"o @tab umlaut accent -@item @t{@@'o} @tab @'o @tab acute accent -@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent -@item @t{@@=o} @tab @=o @tab macron/overbar accent -@item @t{@@^o} @tab @^o @tab circumflex accent -@item @t{@@`o} @tab @`o @tab grave accent -@item @t{@@~o} @tab @~o @tab tilde accent -@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent -@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut -@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent -@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent -@item @t{@@u@{o@}} @tab @u{o} @tab breve accent -@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent -@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent -@item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent -@end multitable - -This table lists the Texinfo commands for inserting other characters -commonly used in languages other than English. - -@findex questiondown -@cindex @questiondown{} -@findex exclamdown -@cindex @exclamdown{} -@findex aa -@cindex @aa{} -@findex AA -@cindex @AA{} -@findex ae -@cindex @ae{} -@findex AE -@cindex @AE{} -@findex dotless -@cindex @dotless{i} -@cindex @dotless{j} -@cindex Dotless i, j -@findex l -@cindex @l{} -@findex L -@cindex @L{} -@findex o -@cindex @o{} -@findex O -@cindex @O{} -@findex oe -@cindex @oe{} -@findex OE -@cindex @OE{} -@findex ss -@cindex @ss{} -@cindex Es-zet -@cindex Sharp S -@cindex German S -@multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S} -@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! -@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? -@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle -@item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures -@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i -@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j -@item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l -@item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash -@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures -@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S -@end multitable - - -@node Dots Bullets, TeX and copyright, Inserting Accents, Insertions -@section Inserting Ellipsis, Dots, and Bullets -@cindex Dots, inserting -@cindex Bullets, inserting -@cindex Ellipsis, inserting -@cindex Inserting ellipsis -@cindex Inserting dots -@cindex Special typesetting commands -@cindex Typesetting commands for dots, etc. - -An @dfn{ellipsis} (a line of dots) is not typeset as a string of -periods, so a special command is used for ellipsis in Texinfo. The -@code{@@bullet} command is special, too. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. (You need to use braces -with these commands because you can use them next to other text; without -the braces, the formatters would be confused. @xref{Command Syntax, , -@@-Command Syntax}, for further information.)@refill - -@menu -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. -@end menu - -@node dots, bullet, Dots Bullets, Dots Bullets -@comment node-name, next, previous, up -@subsection @code{@@dots}@{@} -@findex dots -@cindex Inserting dots -@cindex Dots, inserting - -Use the @code{@@dots@{@}} command to generate an ellipsis, which is -three dots in a row, appropriately spaced, like this: `@dots{}'. Do -not simply write three periods in the input file; that would work for -the Info file output, but would produce the wrong amount of space -between the periods in the printed manual. - -Similarly, the @code{@@enddots@{@}} command generates an -end-of-sentence ellipsis (four dots) @enddots{} - -@iftex -Here is an ellipsis: @dots{} -Here are three periods in a row: ... - -In printed output, the three periods in a row are closer together than -the dots in the ellipsis. -@end iftex - -@node bullet, , dots, Dots Bullets -@comment node-name, next, previous, up -@subsection @code{@@bullet}@{@} -@findex bullet - -Use the @code{@@bullet@{@}} command to generate a large round dot, or -the closest possible thing to one. In Info, an asterisk is used.@refill - -Here is a bullet: @bullet{} - -When you use @code{@@bullet} in @code{@@itemize}, you do not need to -type the braces, because @code{@@itemize} supplies them. -(@xref{itemize, , @code{@@itemize}}.)@refill - -@node TeX and copyright, pounds, Dots Bullets, Insertions -@comment node-name, next, previous, up -@section Inserting @TeX{} and the Copyright Symbol - -The logo `@TeX{}' is typeset in a special fashion and it needs an -@@-command. The copyright symbol, `@copyright{}', is also special. -Each of these commands is followed by a pair of braces, @samp{@{@}}, -without any whitespace between the name of the command and the -braces.@refill - -@menu -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright}@{@}. -@end menu - -@node tex, copyright symbol, TeX and copyright, TeX and copyright -@comment node-name, next, previous, up -@subsection @code{@@TeX}@{@} -@findex tex (command) - -Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed -manual, this is a special logo that is different from three ordinary -letters. In Info, it just looks like @samp{TeX}. The -@code{@@TeX@{@}} command is unique among Texinfo commands in that the -@kbd{T} and the @kbd{X} are in upper case.@refill - -@node copyright symbol, , tex, TeX and copyright -@comment node-name, next, previous, up -@subsection @code{@@copyright}@{@} -@findex copyright - -Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In -a printed manual, this is a @samp{c} inside a circle, and in Info, -this is @samp{(C)}.@refill - -@node pounds, minus, TeX and copyright, Insertions -@section @code{@@pounds}@{@} -@findex pounds - -Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a -printed manual, this is the symbol for the currency pounds sterling. -In Info, it is a @samp{#}. Other currency symbols are unfortunately not -available. - -@node minus, math, pounds, Insertions -@section @code{@@minus}@{@}: Inserting a Minus Sign -@findex minus - -Use the @code{@@minus@{@}} command to generate a minus sign. In a -fixed-width font, this is a single hyphen, but in a proportional font, -the symbol is the customary length for a minus sign---a little longer -than a hyphen.@refill - -You can compare the two forms: - -@display -@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, - -`-' is a hyphen generated with the character @samp{-}. -@end display - -@noindent -In the fixed-width font used by Info, @code{@@minus@{@}} is the same -as a hyphen.@refill - -You should not use @code{@@minus@{@}} inside @code{@@code} or -@code{@@example} because the width distinction is not made in the -fixed-width font they use.@refill - -When you use @code{@@minus} to specify the mark beginning each entry in -an itemized list, you do not need to type the braces -(@pxref{itemize, , @code{@@itemize}}.)@refill - -@node math, , minus, Insertions -@comment node-name, next, previous, up -@section @code{@@math}: Inserting Mathematical Expressions -@findex math -@cindex Mathematical expressions - -You can write a short mathematical expression with the @code{@@math} -command. Write the mathematical expression between braces, like this: - -@example -@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} -@end example - -@iftex -@need 1000 -@noindent -This produces the following in @TeX{}: - -@display -@math{(a + b)(a + b) = a^2 + 2ab + b^2} -@end display - -@noindent -and the following in Info: -@end iftex -@ifinfo -@noindent -This produces the following in Info: -@end ifinfo - -@example -(a + b)(a + b) = a^2 + 2ab + b^2 -@end example - -The @code{@@math} command has no effect on the Info output. Currently, -it has limited effect on typeset output. However, this may change since -@TeX{} itself is designed for mathematical typesetting and does a -splendid job. - -Certainly, for complex mathematical expressions, you could use @TeX{} -directly. @xref{Using Ordinary TeX Commands, , Using Ordinary @TeX{} -Commands}. When you use @TeX{} directly, remember to write the -mathematical expression between one or two @samp{$} (dollar-signs) as -appropriate. - -@node Glyphs, Breaks, Insertions, Top -@comment node-name, next, previous, up -@chapter Glyphs for Examples -@cindex Glyphs - -In Texinfo, code is often illustrated in examples that are delimited -by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and -@code{@@end lisp}. In such examples, you can indicate the results of -evaluation or an expansion using @samp{@result{}} or -@samp{@expansion{}}. Likewise, there are commands to insert glyphs -to indicate -printed output, error messages, equivalence of expressions, and the -location of point.@refill - -The glyph-insertion commands do not need to be used within an example, but -most often they are. Every glyph-insertion command is followed by a pair of -left- and right-hand braces.@refill - -@menu -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. -@end menu - -@node Glyphs Summary, result, Glyphs, Glyphs -@ifinfo -@heading Glyphs Summary - -Here are the different glyph commands:@refill -@end ifinfo - -@table @asis -@item @result{} -@code{@@result@{@}} points to the result of an expression.@refill - -@item @expansion{} -@code{@@expansion@{@}} shows the results of a macro expansion.@refill - -@item @print{} -@code{@@print@{@}} indicates printed output.@refill - -@item @error{} -@code{@@error@{@}} indicates that the following text is an error -message.@refill - -@item @equiv{} -@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill - -@item @point{} -@code{@@point@{@}} shows the location of point.@refill -@end table - -@node result, expansion, Glyphs Summary, Glyphs -@section @result{}: Indicating Evaluation -@cindex Result of an expression -@cindex Indicating evaluation -@cindex Evaluation glyph -@cindex Value of an expression, indicating - -Use the @code{@@result@{@}} command to indicate the result of -evaluating an expression.@refill - -@iftex -The @code{@@result@{@}} command is displayed as @samp{=>} in Info and -as @samp{@result{}} in the printed output. -@end iftex -@ifinfo -The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info -and as a double stemmed arrow in the printed output.@refill -@end ifinfo - -Thus, the following, - -@lisp -(cdr '(1 2 3)) - @result{} (2 3) -@end lisp - -@noindent -may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. - -@node expansion, Print Glyph, result, Glyphs -@section @expansion{}: Indicating an Expansion -@cindex Expansion, indicating it - -When an expression is a macro call, it expands into a new expression. -You can indicate the result of the expansion with the -@code{@@expansion@{@}} command.@refill - -@iftex -The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and -as @samp{@expansion{}} in the printed output. -@end iftex -@ifinfo -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in Info and as a long arrow with a flat base in the printed output.@refill -@end ifinfo - -@need 700 -For example, the following - -@example -@group -@@lisp -(third '(a b c)) - @@expansion@{@} (car (cdr (cdr '(a b c)))) - @@result@{@} c -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -@group -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end group -@end lisp - -@noindent -which may be read as: - -@quotation -@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; -the result of evaluating the expression is @code{c}. -@end quotation - -@noindent -Often, as in this case, an example looks better if the -@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented -five spaces.@refill - -@node Print Glyph, Error Glyph, expansion, Glyphs -@section @print{}: Indicating Printed Output -@cindex Printed output, indicating it - -Sometimes an expression will print output during its execution. You -can indicate the printed output with the @code{@@print@{@}} command.@refill - -@iftex -The @code{@@print@{@}} command is displayed as @samp{-|} in Info and -as @samp{@print{}} in the printed output. -@end iftex -@ifinfo -The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info -and similarly, as a horizontal dash butting against a vertical bar, in -the printed output.@refill -@end ifinfo - -In the following example, the printed text is indicated with -@samp{@print{}}, and the value of the expression follows on the -last line.@refill - -@lisp -@group -(progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end lisp - -@noindent -In a Texinfo source file, this example is written as follows: - -@lisp -@group -@@lisp -(progn (print 'foo) (print 'bar)) - @@print@{@} foo - @@print@{@} bar - @@result@{@} bar -@@end lisp -@end group -@end lisp - -@node Error Glyph, Equivalence, Print Glyph, Glyphs -@section @error{}: Indicating an Error Message -@cindex Error message, indicating it - -A piece of code may cause an error when you evaluate it. You can -designate the error message with the @code{@@error@{@}} command.@refill - -@iftex -The @code{@@error@{@}} command is displayed as @samp{error-->} in Info -and as @samp{@error{}} in the printed output. -@end iftex -@ifinfo -The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info -and as the word `error' in a box in the printed output.@refill -@end ifinfo - -@need 700 -Thus, - -@example -@@lisp -(+ 23 'x) -@@error@{@} Wrong type argument: integer-or-marker-p, x -@@end lisp -@end example - -@noindent -produces - -@lisp -(+ 23 'x) -@error{} Wrong type argument: integer-or-marker-p, x -@end lisp - -@noindent -This indicates that the following error message is printed -when you evaluate the expression: - -@lisp -Wrong type argument: integer-or-marker-p, x -@end lisp - -Note that @samp{@error{}} itself is not part of the error -message. - -@node Equivalence, Point Glyph, Error Glyph, Glyphs -@section @equiv{}: Indicating Equivalence -@cindex Equivalence, indicating it - -Sometimes two expressions produce identical results. You can indicate the -exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill - -@iftex -The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and -as @samp{@equiv{}} in the printed output. -@end iftex -@ifinfo -The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info -and as a three parallel horizontal lines in the printed output.@refill -@end ifinfo - -Thus, - -@example -@@lisp -(make-sparse-keymap) @@equiv@{@} (list 'keymap) -@@end lisp -@end example - -@noindent -produces - -@lisp -(make-sparse-keymap) @equiv{} (list 'keymap) -@end lisp - -@noindent -This indicates that evaluating @code{(make-sparse-keymap)} produces -identical results to evaluating @code{(list 'keymap)}. - -@c Cannot write point command here because it causes trouble with TOC. -@node Point Glyph, , Equivalence, Glyphs -@section Indicating Point in a Buffer -@cindex Point, indicating it in a buffer - -Sometimes you need to show an example of text in an Emacs buffer. In -such examples, the convention is to include the entire contents of the -buffer in question between two lines of dashes containing the buffer -name.@refill - -You can use the @samp{@@point@{@}} command to show the location of point -in the text in the buffer. (The symbol for point, of course, is not -part of the text in the buffer; it indicates the place @emph{between} -two characters where point is located.)@refill - -@iftex -The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and -as @samp{@point{}} in the printed output. -@end iftex -@ifinfo -The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info -and as a small five pointed star in the printed output.@refill -@end ifinfo - -The following example shows the contents of buffer @file{foo} before -and after evaluating a Lisp command to insert the word @code{changed}.@refill - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -@example -@group -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -In a Texinfo source file, the example is written like this:@refill - -@example -@@example ----------- Buffer: foo ---------- -This is the @@point@{@}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @@result@{@} nil ----------- Buffer: foo ---------- -This is the changed @@point@{@}contents of foo. ----------- Buffer: foo ---------- -@@end example -@end example - -@node Breaks, Definition Commands, Glyphs, Top -@comment node-name, next, previous, up -@chapter Making and Preventing Breaks -@cindex Making line and page breaks -@cindex Preventing line and page breaks - -Usually, a Texinfo file is processed both by @TeX{} and by one of the -Info formatting commands. Line, paragraph, or page breaks sometimes -occur in the `wrong' place in one or other form of output. You must -ensure that text looks right both in the printed manual and in the -Info file.@refill - -For example, in a printed manual, page breaks may occur awkwardly in -the middle of an example; to prevent this, you can hold text together -using a grouping command that keeps the text from being split across -two pages. Conversely, you may want to force a page break where none -would occur normally. Fortunately, problems like these do not often -arise. When they do, use the break, break prevention, or pagination -commands.@refill - -@menu -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. -@end menu - -@ifinfo -@node Break Commands, Line Breaks, Breaks, Breaks -@heading The Break Commands -@end ifinfo -@iftex -@sp 1 -@end iftex - -The break commands create or allow line and paragraph breaks:@refill - -@table @code -@item @@* -Force a line break. - -@item @@sp @var{n} -Skip @var{n} blank lines.@refill - -@item @@- -Insert a discretionary hyphen. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Define hyphen points in @var{hy-phen-a-ted words}. -@end table - -The line-break-prevention command holds text together all on one -line:@refill - -@table @code -@item @@w@{@var{text}@} -Prevent @var{text} from being split and hyphenated across two lines.@refill -@end table -@iftex -@sp 1 -@end iftex - -The pagination commands apply only to printed output, since Info -files do not have pages.@refill - -@table @code -@item @@page -Start a new page in the printed manual.@refill - -@item @@group -Hold text together that must appear on one printed page.@refill - -@item @@need @var{mils} -Start a new printed page if not enough space on this one.@refill -@end table - -@node Line Breaks, - and hyphenation, Break Commands, Breaks -@comment node-name, next, previous, up -@section @code{@@*}: Generate Line Breaks -@findex * @r{(force line break)} -@cindex Line breaks -@cindex Breaks in a line - -The @code{@@*} command forces a line break in both the printed manual and -in Info.@refill - -@need 700 -For example, - -@example -This line @@* is broken @@*in two places. -@end example - -@noindent -produces - -@example -@group -This line - is broken -in two places. -@end group -@end example - -@noindent -(Note that the space after the first @code{@@*} command is faithfully -carried down to the next line.)@refill - -@need 800 -The @code{@@*} command is often used in a file's copyright page:@refill - -@example -@group -This is edition 2.0 of the Texinfo documentation,@@* -and is for @dots{} -@end group -@end example - -@noindent -In this case, the @code{@@*} command keeps @TeX{} from stretching the -line across the whole page in an ugly manner.@refill - -@quotation -@strong{Please note:} Do not write braces after an @code{@@*} command; -they are not needed.@refill - -Do not write an @code{@@refill} command at the end of a paragraph -containing an @code{@@*} command; it will cause the paragraph to be -refilled after the line break occurs, negating the effect of the line -break.@refill -@end quotation - -@node - and hyphenation, w, Line Breaks, Breaks -@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate - -@findex - -@findex hyphenation -@cindex Hyphenation, helping @TeX{} do -@cindex Fine-tuning, and hyphenation - -Although @TeX{}'s hyphenation algorithm is generally pretty good, it -does miss useful hyphenation points from time to time. (Or, far more -rarely, insert an incorrect hyphenation.) So, for documents with an -unusual vocabulary or when fine-tuning for a printed edition, you may -wish to help @TeX{} out. Texinfo supports two commands for this: - -@table @code -@item @@- -Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does -not have to) hyphenate. This is especially useful when you notice -an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull -hboxes}). @TeX{} will not insert any hyphenation points in a word -containing @code{@@-}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you -put a @samp{-} at each hyphenation point. For example: -@example -@@hyphenation@{man-u-script man-u-scripts@} -@end example -@noindent @TeX{} only uses the specified hyphenation points when the -words match exactly, so give all necessary variants. -@end table - -Info output is not hyphenated, so these commands have no effect there. - -@node w, sp, - and hyphenation, Breaks -@comment node-name, next, previous, up -@section @code{@@w}@{@var{text}@}: Prevent Line Breaks -@findex w @r{(prevent line break)} -@cindex Line breaks, preventing -@cindex Hyphenation, preventing - -@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks -within @var{text}.@refill - -You can use the @code{@@w} command to prevent @TeX{} from automatically -hyphenating a long name or phrase that accidentally falls near the end -of a line.@refill - -@example -You can copy GNU software from @@w@{@@file@{prep.ai.mit.edu@}@}. -@end example - -@noindent -produces - -@quotation -You can copy GNU software from @w{@file{prep.ai.mit.edu}}. -@end quotation - -@quotation -@strong{Caution:} Do not write an @code{@@refill} command at the end -of a paragraph containing an @code{@@w} command; it will cause the -paragraph to be refilled and may thereby negate the effect of the -@code{@@w} command.@refill -@end quotation - -@node sp, page, w, Breaks -@comment node-name, next, previous, up -@section @code{@@sp} @var{n}: Insert Blank Lines -@findex sp @r{(line spacing)} -@cindex Spaces (blank lines) -@cindex Blank lines -@cindex Line spacing - -A line beginning with and containing only @code{@@sp @var{n}} -generates @var{n} blank lines of space in both the printed manual and -the Info file. @code{@@sp} also forces a paragraph break. For -example,@refill - -@example -@@sp 2 -@end example - -@noindent -generates two blank lines. - -The @code{@@sp} command is most often used in the title page.@refill - -@ignore -@c node br, page, sp, Breaks -@comment node-name, next, previous, up -@c section @code{@@br}: Generate Paragraph Breaks -@findex br @r{(paragraph breaks)} -@cindex Paragraph breaks -@cindex Breaks in a paragraph - -The @code{@@br} command forces a paragraph break. It inserts a blank -line. You can use the command within or at the end of a line. If -used within a line, the @code{@@br@{@}} command must be followed by -left and right braces (as shown here) to mark the end of the -command.@refill - -@need 700 -For example, - -@example -@group -This line @@br@{@}contains and is ended by paragraph breaks@@br -and is followed by another line. -@end group -@end example - -@noindent -produces - -@example -@group -This line - -contains and is ended by paragraph breaks - -and is followed by another line. -@end group -@end example - -The @code{@@br} command is seldom used. -@end ignore - -@node page, group, sp, Breaks -@comment node-name, next, previous, up -@section @code{@@page}: Start a New Page -@cindex Page breaks -@findex page - -A line containing only @code{@@page} starts a new page in a printed -manual. The command has no effect on Info files since they are not -paginated. An @code{@@page} command is often used in the @code{@@titlepage} -section of a Texinfo file to start the copyright page.@refill - -@node group, need, page, Breaks -@comment node-name, next, previous, up -@section @code{@@group}: Prevent Page Breaks -@cindex Group (hold text together vertically) -@cindex Holding text together vertically -@cindex Vertically holding text together -@findex group - -The @code{@@group} command (on a line by itself) is used inside an -@code{@@example} or similar construct to begin an unsplittable vertical -group, which will appear entirely on one page in the printed output. -The group is terminated by a line containing only @code{@@end group}. -These two lines produce no output of their own, and in the Info file -output they have no effect at all.@refill - -@c Once said that these environments -@c turn off vertical spacing between ``paragraphs''. -@c Also, quotation used to work, but doesn't in texinfo-2.72 -Although @code{@@group} would make sense conceptually in a wide -variety of contexts, its current implementation works reliably only -within @code{@@example} and variants, and within @code{@@display}, -@code{@@format}, @code{@@flushleft} and @code{@@flushright}. -@xref{Quotations and Examples}. (What all these commands have in -common is that each line of input produces a line of output.) In -other contexts, @code{@@group} can cause anomalous vertical -spacing.@refill - -@need 750 -This formatting requirement means that you should write: - -@example -@group -@@example -@@group -@dots{} -@@end group -@@end example -@end group -@end example - -@noindent -with the @code{@@group} and @code{@@end group} commands inside the -@code{@@example} and @code{@@end example} commands. - -The @code{@@group} command is most often used to hold an example -together on one page. In this Texinfo manual, more than 100 examples -contain text that is enclosed between @code{@@group} and @code{@@end -group}. - -If you forget to end a group, you may get strange and unfathomable -error messages when you run @TeX{}. This is because @TeX{} keeps -trying to put the rest of the Texinfo file onto the one page and does -not start to generate error messages until it has processed -considerable text. It is a good rule of thumb to look for a missing -@code{@@end group} if you get incomprehensible error messages in -@TeX{}.@refill - -@node need, , group, Breaks -@comment node-name, next, previous, up -@section @code{@@need @var{mils}}: Prevent Page Breaks -@cindex Need space at page bottom -@findex need - -A line containing only @code{@@need @var{n}} starts -a new page in a printed manual if fewer than @var{n} mils (thousandths -of an inch) remain on the current page. Do not use -braces around the argument @var{n}. The @code{@@need} command has no -effect on Info files since they are not paginated.@refill - -@need 800 -This paragraph is preceded by an @code{@@need} command that tells -@TeX{} to start a new page if fewer than 800 mils (eight-tenths -inch) remain on the page. It looks like this:@refill - -@example -@group -@@need 800 -This paragraph is preceded by @dots{} -@end group -@end example - -The @code{@@need} command is useful for preventing orphans (single -lines at the bottoms of printed pages).@refill - -@node Definition Commands, Footnotes, Breaks, Top -@chapter Definition Commands -@cindex Definition commands - -The @code{@@deffn} command and the other @dfn{definition commands} -enable you to describe functions, variables, macros, commands, user -options, special forms and other such artifacts in a uniform -format.@refill - -In the Info file, a definition causes the entity -category---`Function', `Variable', or whatever---to appear at the -beginning of the first line of the definition, followed by the -entity's name and arguments. In the printed manual, the command -causes @TeX{} to print the entity's name and its arguments on the left -margin and print the category next to the right margin. In both -output formats, the body of the definition is indented. Also, the -name of the entity is entered into the appropriate index: -@code{@@deffn} enters the name into the index of functions, -@code{@@defvr} enters it into the index of variables, and so -on.@refill - -A manual need not and should not contain more than one definition for -a given name. An appendix containing a summary should use -@code{@@table} rather than the definition commands.@refill - -@menu -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: -@end menu - -@node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands -@section The Template for a Definition -@cindex Definition template -@cindex Template for a definition - -The @code{@@deffn} command is used for definitions of entities that -resemble functions. To write a definition using the @code{@@deffn} -command, write the @code{@@deffn} command at the beginning of a line -and follow it on the same line by the category of the entity, the name -of the entity itself, and its arguments (if any). Then write the body -of the definition on succeeding lines. (You may embed examples in the -body.) Finally, end the definition with an @code{@@end deffn} command -written on a line of its own. (The other definition commands follow -the same format.)@refill - -The template for a definition looks like this: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@deffn Command forward-word count -This command moves point forward @@var@{count@} words -(or backward if @@var@{count@} is negative). @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@quotation -@deffn Command forward-word count -This function moves point forward @var{count} words -(or backward if @var{count} is negative). @dots{} -@end deffn -@end quotation - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', -write braces around it. For example:@refill - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@dots{} -@@end deffn -@end group -@end example - -@noindent -Otherwise, the second word will be mistaken for the name of the -entity.@refill - -Some of the definition commands are more general than others. The -@code{@@deffn} command, for example, is the general definition command -for functions and the like---for entities that may take arguments. When -you use this command, you specify the category to which the entity -belongs. The @code{@@deffn} command possesses three predefined, -specialized variations, @code{@@defun}, @code{@@defmac}, and -@code{@@defspec}, that specify the category for you: ``Function'', -``Macro'', and ``Special Form'' respectively. The @code{@@defvr} -command also is accompanied by several predefined, specialized -variations for describing particular kinds of variables.@refill - -The template for a specialized definition, such as @code{@@defun}, is -similar to the template for a generalized definition, except that you -do not need to specify the category:@refill - -@example -@group -@@defun @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@noindent -Thus, - -@example -@group -@@defun buffer-end flag -This function returns @@code@{(point-min)@} if @@var@{flag@} -is less than 1, @@code@{(point-max)@} otherwise. -@dots{} -@@end defun -@end group -@end example - -@noindent -produces - -@quotation -@defun buffer-end flag -This function returns @code{(point-min)} if @var{flag} is less than 1, -@code{(point-max)} otherwise. @dots{} -@end defun -@end quotation - -@noindent -@xref{Sample Function Definition, Sample Function Definition, A Sample -Function Definition}, for a more detailed example of a function -definition, including the use of @code{@@example} inside the -definition.@refill - -The other specialized commands work like @code{@@defun}.@refill - -@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands -@section Optional and Repeated Arguments -@cindex Optional and repeated arguments -@cindex Repeated and optional arguments -@cindex Arguments, repeated and optional -@cindex Syntax, optional & repeated arguments -@cindex Meta-syntactic chars for arguments - -Some entities take optional or repeated arguments, which may be -specified by a distinctive glyph that uses square brackets and -ellipses. For @w{example}, a special form often breaks its argument list -into separate arguments in more complicated ways than a -straightforward function.@refill - -@iftex -An argument enclosed within square brackets is optional. -Thus, the phrase -@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that -@var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end iftex -@c The following looks better in Info (no `r', `samp' and `code'): -@ifinfo -An argument enclosed within square brackets is optional. -Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @var{repeated-args}@dots{} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end ifinfo - -Here is the @code{@@defspec} line of an example of an imaginary -special form:@refill - -@quotation -@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -@end defspec -@tex -\vskip \parskip -@end tex -@end quotation - -@noindent -In this example, the arguments @var{from} and @var{to} are optional, -but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the -form.@refill - -In a Texinfo source file, this @code{@@defspec} line is written like -this (except it would not be split over two lines, as it is in this -example).@refill - -@example -@group -@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} - [@@var@{inc@}]]) @@var@{body@}@@dots@{@} -@end group -@end example - -@noindent -The function is listed in the Command and Variable Index under -@samp{foobar}.@refill - -@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands -@section Two or More `First' Lines -@cindex Two `First' Lines for @code{@@deffn} -@cindex Grouping two definitions together -@cindex Definitions grouped together -@findex deffnx - -To create two or more `first' or header lines for a definition, follow -the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. -The @code{@@deffnx} command works exactly like @code{@@deffn} -except that it does not generate extra vertical white space between it -and the preceding line.@refill - -@need 1000 -For example, - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@@deffnx @{Interactive Command@} isearch-backward -These two search commands are similar except @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@deffn {Interactive Command} isearch-forward -@deffnx {Interactive Command} isearch-backward -These two search commands are similar except @dots{} -@end deffn - -Each of the other definition commands has an `x' form: @code{@@defunx}, -@code{@@defvrx}, @code{@@deftypefunx}, etc. - -The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. - -@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands -@section The Definition Commands - -Texinfo provides more than a dozen definition commands, all of which -are described in this section.@refill - -The definition commands automatically enter the name of the entity in -the appropriate index: for example, @code{@@deffn}, @code{@@defun}, -and @code{@@defmac} enter function names in the index of functions; -@code{@@defvr} and @code{@@defvar} enter variable names in the index -of variables.@refill - -Although the examples that follow mostly illustrate Lisp, the commands -can be used for other programming languages.@refill - -@menu -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. -@end menu - -@node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail -@subsection Functions and Similar Entities - -This section describes the commands for describing functions and similar -entities:@refill - -@table @code -@findex deffn -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -The @code{@@deffn} command is the general definition command for -functions, interactive commands, and similar entities that may take -arguments. You must choose a term to describe the category of entity -being defined; for example, ``Function'' could be used if the entity is -a function. The @code{@@deffn} command is written at the beginning of a -line and is followed on the same line by the category of entity being -described, the name of this particular entity, and its arguments, if -any. Terminate the definition with @code{@@end deffn} on a line of its -own.@refill - -@need 750 -For example, here is a definition: - -@example -@group -@@deffn Command forward-char nchars -Move point forward @@var@{nchars@} characters. -@@end deffn -@end group -@end example - -@noindent -This shows a rather terse definition for a ``command'' named -@code{forward-char} with one argument, @var{nchars}. - -@code{@@deffn} prints argument names such as @var{nchars} in italics or -upper case, as if @code{@@var} had been used, because we think of these -names as metasyntactic variables---they stand for the actual argument -values. Within the text of the description, write an argument name -explicitly with @code{@@var} to refer to the value of the argument. In -the example above, we used @samp{@@var@{nchars@}} in this way. - -The template for @code{@@deffn} is: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@findex defun -@item @@defun @var{name} @var{arguments}@dots{} -The @code{@@defun} command is the definition command for functions. -@code{@@defun} is equivalent to @samp{@@deffn Function -@dots{}}.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defun set symbol new-value -Change the value of the symbol @@var@{symbol@} -to @@var@{new-value@}. -@@end defun -@end group -@end example - -@noindent -shows a rather terse definition for a function @code{set} whose -arguments are @var{symbol} and @var{new-value}. The argument names on -the @code{@@defun} line automatically appear in italics or upper case as -if they were enclosed in @code{@@var}. Terminate the definition with -@code{@@end defun} on a line of its own.@refill - -The template is: - -@example -@group -@@defun @var{function-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@code{@@defun} creates an entry in the index of functions. - -@findex defmac -@item @@defmac @var{name} @var{arguments}@dots{} -The @code{@@defmac} command is the definition command for macros. -@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and -works like @code{@@defun}.@refill - -@findex defspec -@item @@defspec @var{name} @var{arguments}@dots{} -The @code{@@defspec} command is the definition command for special -forms. (In Lisp, a special form is an entity much like a function.) -@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} -@dots{}} and works like @code{@@defun}.@refill -@end table - -@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail -@subsection Variables and Similar Entities - -Here are the commands for defining variables and similar -entities:@refill - -@table @code -@findex defvr -@item @@defvr @var{category} @var{name} -The @code{@@defvr} command is a general definition command for -something like a variable---an entity that records a value. You must -choose a term to describe the category of entity being defined; for -example, ``Variable'' could be used if the entity is a variable. -Write the @code{@@defvr} command at the beginning of a line and -followed it on the same line by the category of the entity and the -name of the entity.@refill - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the name `User Option', write braces -around it. Otherwise, the second word will be mistaken for the name -of the entity, for example: - -@example -@group -@@defvr @{User Option@} fill-column -This buffer-local variable specifies -the maximum width of filled lines. -@dots{} -@@end defvr -@end group -@end example - -Terminate the definition with @code{@@end defvr} on a line of its -own.@refill - -The template is: - -@example -@group -@@defvr @var{category} @var{name} -@var{body-of-definition} -@@end defvr -@end group -@end example - -@code{@@defvr} creates an entry in the index of variables for @var{name}. - -@findex defvar -@item @@defvar @var{name} -The @code{@@defvar} command is the definition command for variables. -@code{@@defvar} is equivalent to @samp{@@defvr Variable -@dots{}}.@refill - -@need 750 -For example: - -@example -@group -@@defvar kill-ring -@dots{} -@@end defvar -@end group -@end example - -The template is: - -@example -@group -@@defvar @var{name} -@var{body-of-definition} -@@end defvar -@end group -@end example - -@code{@@defvar} creates an entry in the index of variables for -@var{name}.@refill - -@findex defopt -@item @@defopt @var{name} -The @code{@@defopt} command is the definition command for user -options. @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}.@refill -@end table - -@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail -@subsection Functions in Typed Languages - -The @code{@@deftypefn} command and its variations are for describing -functions in C or any other language in which you must declare types -of variables and functions.@refill - -@table @code -@findex deftypefn -@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefn} command is the general definition command for -functions and similar entities that may take arguments and that are -typed. The @code{@@deftypefn} command is written at the beginning of -a line and is followed on the same line by the category of entity -being described, the type of the returned value, the name of this -particular entity, and its arguments, if any.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@deftypefn @{Library Function@} int foobar - (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefn -@end group -@end example - -@need 1000 -@noindent -(where the text before the ``@dots{}'', shown above as two lines, would -actually be a single line in a real Texinfo file) produces the following -in Info: - -@smallexample -@group --- Library Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end smallexample -@iftex - -In a printed manual, it produces: - -@quotation -@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefn -@end quotation -@end iftex - -This means that @code{foobar} is a ``library function'' that returns an -@code{int}, and its arguments are @var{foo} (an @code{int}) and -@var{bar} (a @code{float}).@refill - -The argument names that you write in @code{@@deftypefn} are not subject -to an implicit @code{@@var}---since the actual names of the arguments in -@code{@@deftypefn} are typically scattered among data type names and -keywords, Texinfo cannot find them without help. Instead, you must write -@code{@@var} explicitly around the argument names. In the example -above, the argument names are @samp{foo} and @samp{bar}.@refill - -The template for @code{@@deftypefn} is:@refill - -@example -@group -@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} -@var{body-of-description} -@@end deftypefn -@end group -@end example - -@noindent -Note that if the @var{category} or @var{data type} is more than one -word then it must be enclosed in braces to make it a single argument.@refill - -If you are describing a procedure in a language that has packages, -such as Ada, you might consider using @code{@@deftypefn} in a manner -somewhat contrary to the convention described in the preceding -paragraphs.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypefn stacks private push - (@@var@{s@}:in out stack; - @@var@{n@}:in integer) -@dots{} -@@end deftypefn -@end group -@end example - -@noindent -(The @code{@@deftypefn} arguments are shown split into three lines, but -would be a single line in a real Texinfo file.) - -In this instance, the procedure is classified as belonging to the -package @code{stacks} rather than classified as a `procedure' and its -data type is described as @code{private}. (The name of the procedure -is @code{push}, and its arguments are @var{s} and @var{n}.)@refill - -@code{@@deftypefn} creates an entry in the index of functions for -@var{name}.@refill - -@findex deftypefun -@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefun} command is the specialized definition command -for functions in typed languages. The command is equivalent to -@samp{@@deftypefn Function @dots{}}.@refill - -@need 800 -@noindent -Thus, - -@smallexample -@group -@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefun -@end group -@end smallexample - -@noindent -produces the following in Info: - -@example -@group --- Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypefun int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefun -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@group -@@deftypefun @var{type} @var{name} @var{arguments}@dots{} -@var{body-of-description} -@@end deftypefun -@end group -@end example - -@code{@@deftypefun} creates an entry in the index of functions for -@var{name}.@refill -@end table - -@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail -@subsection Variables in Typed Languages - -Variables in typed languages are handled in a manner similar to -functions in typed languages. @xref{Typed Functions}. The general -definition command @code{@@deftypevr} corresponds to -@code{@@deftypefn} and the specialized definition command -@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill - -@table @code -@findex deftypevr -@item @@deftypevr @var{category} @var{data-type} @var{name} -The @code{@@deftypevr} command is the general definition command for -something like a variable in a typed language---an entity that records -a value. You must choose a term to describe the category of the -entity being defined; for example, ``Variable'' could be used if the -entity is a variable.@refill - -The @code{@@deftypevr} command is written at the beginning of a line -and is followed on the same line by the category of the entity -being described, the data type, and the name of this particular -entity.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevr @{Global Flag@} int enable -@dots{} -@@end deftypevr -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Global Flag: int enable -@dots{} -@end group -@end example -@iftex - -@noindent -and the following in a printed manual: - -@quotation -@deftypevr {Global Flag} int enable -@dots{} -@end deftypevr -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@@deftypevr @var{category} @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevr -@end example - -@code{@@deftypevr} creates an entry in the index of variables for -@var{name}.@refill - -@findex deftypevar -@item @@deftypevar @var{data-type} @var{name} -The @code{@@deftypevar} command is the specialized definition command -for variables in typed languages. @code{@@deftypevar} is equivalent -to @samp{@@deftypevr Variable @dots{}}.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevar int fubar -@dots{} -@@end deftypevar -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Variable: int fubar -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypevar int fubar -@dots{} -@end deftypevar -@end quotation -@end iftex - -@need 800 -@noindent -The template is: - -@example -@group -@@deftypevar @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevar -@end group -@end example - -@code{@@deftypevar} creates an entry in the index of variables for -@var{name}.@refill -@end table - -@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail -@subsection Object-Oriented Programming - -Here are the commands for formatting descriptions about abstract -objects, such as are used in object-oriented programming. A class is -a defined type of abstract object. An instance of a class is a -particular object that has the type of the class. An instance -variable is a variable that belongs to the class but for which each -instance has its own value.@refill - -In a definition, if the name of a class is truly a name defined in the -programming system for a class, then you should write an @code{@@code} -around it. Otherwise, it is printed in the usual text font.@refill - -@table @code -@findex defcv -@item @@defcv @var{category} @var{class} @var{name} -The @code{@@defcv} command is the general definition command for -variables associated with classes in object-oriented programming. The -@code{@@defcv} command is followed by three arguments: the category of -thing being defined, the class to which it belongs, and its -name. Thus,@refill - -@example -@group -@@defcv @{Class Option@} Window border-pattern -@dots{} -@@end defcv -@end group -@end example - -@noindent -illustrates how you would write the first line of a definition of the -@code{border-pattern} class option of the class @code{Window}.@refill - -The template is - -@example -@group -@@defcv @var{category} @var{class} @var{name} -@dots{} -@@end defcv -@end group -@end example - -@code{@@defcv} creates an entry in the index of variables. - -@findex defivar -@item @@defivar @var{class} @var{name} -The @code{@@defivar} command is the definition command for instance -variables in object-oriented programming. @code{@@defivar} is -equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill - -The template is: - -@example -@group -@@defivar @var{class} @var{instance-variable-name} -@var{body-of-definition} -@@end defivar -@end group -@end example - -@code{@@defivar} creates an entry in the index of variables. - -@findex defop -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defop} command is the general definition command for -entities that may resemble methods in object-oriented programming. -These entities take arguments, as functions do, but are associated -with particular classes of objects.@refill - -For example, some systems have constructs called @dfn{wrappers} that -are associated with classes as methods are, but that act more like -macros than like functions. You could use @code{@@defop Wrapper} to -describe one of these.@refill - -Sometimes it is useful to distinguish methods and @dfn{operations}. -You can think of an operation as the specification for a method. -Thus, a window system might specify that all window classes have a -method named @code{expose}; we would say that this window system -defines an @code{expose} operation on windows in general. Typically, -the operation has a name and also specifies the pattern of arguments; -all methods that implement the operation must accept the same -arguments, since applications that use the operation do so without -knowing which method will implement it.@refill - -Often it makes more sense to document operations than methods. For -example, window application developers need to know about the -@code{expose} operation, but need not be concerned with whether a -given class of windows has its own method to implement this operation. -To describe this operation, you would write:@refill - -@example -@@defop Operation windows expose -@end example - -The @code{@@defop} command is written at the beginning of a line and -is followed on the same line by the overall name of the category of -operation, the name of the class of the operation, the name of the -operation, and its arguments, if any.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defop -@end group -@end example - -@code{@@defop} creates an entry, such as `@code{expose} on -@code{windows}', in the index of functions.@refill - -@findex defmethod -@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defmethod} command is the definition command for methods -in object-oriented programming. A method is a kind of function that -implements an operation for a particular class of objects and its -subclasses. In the Lisp Machine, methods actually were functions, but -they were usually defined with @code{defmethod}. - -@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. -The command is written at the beginning of a line and is followed by -the name of the class of the method, the name of the method, and its -arguments, if any.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defmethod @code{bar-class} bar-method argument -@dots{} -@@end defmethod -@end group -@end example - -@noindent -illustrates the definition for a method called @code{bar-method} of -the class @code{bar-class}. The method takes an argument.@refill - -The template is: - -@example -@group -@@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defmethod -@end group -@end example - -@code{@@defmethod} creates an entry, such as `@code{bar-method} on -@code{bar-class}', in the index of functions.@refill -@end table - -@node Data Types, , Abstract Objects, Def Cmds in Detail -@subsection Data Types - -Here is the command for data types:@refill - -@table @code -@findex deftp -@item @@deftp @var{category} @var{name} @var{attributes}@dots{} -The @code{@@deftp} command is the generic definition command for data -types. The command is written at the beginning of a line and is -followed on the same line by the category, by the name of the type -(which is a word like @code{int} or @code{float}), and then by names of -attributes of objects of that type. Thus, you could use this command -for describing @code{int} or @code{float}, in which case you could use -@code{data type} as the category. (A data type is a category of -certain objects for purposes of deciding which operations can be -performed on them.)@refill - -In Lisp, for example, @dfn{pair} names a particular data -type, and an object of that type has two slots called the -@sc{car} and the @sc{cdr}. Here is how you would write the first line -of a definition of @code{pair}.@refill - -@example -@group -@@deftp @{Data type@} pair car cdr -@dots{} -@@end deftp -@end group -@end example - -@need 950 -The template is: - -@example -@group -@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@var{body-of-definition} -@@end deftp -@end group -@end example - -@code{@@deftp} creates an entry in the index of data types. -@end table - -@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands -@section Conventions for Writing Definitions -@cindex Definition conventions -@cindex Conventions for writing definitions - -When you write a definition using @code{@@deffn}, @code{@@defun}, or -one of the other definition commands, please take care to use -arguments that indicate the meaning, as with the @var{count} argument -to the @code{forward-word} function. Also, if the name of an argument -contains the name of a type, such as @var{integer}, take care that the -argument actually is of that type.@refill - -@node Sample Function Definition, , Def Cmd Conventions, Definition Commands -@section A Sample Function Definition -@cindex Function definitions -@cindex Command definitions -@cindex Macro definitions -@cindex Sample function definition - -A function definition uses the @code{@@defun} and @code{@@end defun} -commands. The name of the function follows immediately after the -@code{@@defun} command and it is followed, on the same line, by the -parameter list.@refill - -Here is a definition from @cite{The GNU Emacs Lisp Reference Manual}. -(@xref{Calling Functions, , Calling Functions, elisp, The GNU Emacs -Lisp Reference Manual}.) - -@quotation -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just -like @code{funcall} but with one difference: the last of -@var{arguments} is a list of arguments to give to -@var{function}, rather than a single argument. We also say -that this list is @dfn{appended} to the other arguments. - -@code{apply} returns the result of calling @var{function}. -As with @code{funcall}, @var{function} must either be a Lisp -function or a primitive function; special forms and macros -do not make sense in @code{apply}. - -@example -(setq f 'list) - @result{} list -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @result{} 10 -(apply '+ '(1 2 3 4)) - @result{} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end example - -An interesting example of using @code{apply} is found in the description -of @code{mapcar}.@refill -@end defun -@end quotation - -@need 1200 -In the Texinfo source file, this example looks like this: - -@example -@group -@@defun apply function &rest arguments - -@@code@{apply@} calls @@var@{function@} with -@@var@{arguments@}, just like @@code@{funcall@} but with one -difference: the last of @@var@{arguments@} is a list of -arguments to give to @@var@{function@}, rather than a single -argument. We also say that this list is @@dfn@{appended@} -to the other arguments. -@end group - -@group -@@code@{apply@} returns the result of calling -@@var@{function@}. As with @@code@{funcall@}, -@@var@{function@} must either be a Lisp function or a -primitive function; special forms and macros do not make -sense in @@code@{apply@}. -@end group - -@group -@@example -(setq f 'list) - @@result@{@} list -(apply f 'x 'y 'z) -@@error@{@} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @@result@{@} 10 -(apply '+ '(1 2 3 4)) - @@result@{@} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @@result@{@} (a b c x y z) -@@end example -@end group - -@group -An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}.@@refill -@@end defun -@end group -@end example - -@noindent -In this manual, this function is listed in the Command and Variable -Index under @code{apply}.@refill - -Ordinary variables and user options are described using a format like -that for functions except that variables do not take arguments. - -@node Footnotes, Conditionals, Definition Commands, Top -@comment node-name, next, previous, up -@chapter Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon -the primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.}@refill - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu - -@node Footnote Commands, Footnote Styles, Footnotes, Footnotes -@section Footnote Commands - -In Texinfo, footnotes are created with the @code{@@footnote} command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. The template -is: - -@example -@@footnote@{@var{text}@} -@end example - -Footnotes may be of any length, but are usually short.@refill - -For example, this clause is followed by a sample -footnote@footnote{Here is the sample footnote.}; in the Texinfo -source, it looks like this:@refill - -@example -@dots{}a sample footnote @@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -@strong{Warning:} Don't use footnotes in the argument of the -@code{@@item} command for a @code{@@table} table. This doesn't work; -because of limitations of @TeX{}, there is no way to fix it. To avoid -the problem, move the footnote into the body text of the table. - -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line.@refill - -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}.@refill - -@node Footnote Styles, , Footnote Commands, Footnotes -@section Footnote Styles - -Info has two footnote styles, which determine where the text of the -footnote is located:@refill - -@itemize @bullet -@cindex @samp{@r{End}} node footnote style -@item -In the `End' node style, all the footnotes for a single node -are placed at the end of that node. The footnotes are separated from -the rest of the node by a line of dashes with the word -@samp{Footnotes} within it. Each footnote begins with an -@samp{(@var{n})} reference mark.@refill - -@need 700 -@noindent -Here is an example of a single footnote in the end of node style:@refill - -@example -@group - --------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node.@refill - -The name of the node containing the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node.@refill - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style:@refill - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) Note that the first syllable of "Texinfo" is -pronounced like "speck", not "hex". @dots{} -@end group -@end smallexample -@end itemize - -A Texinfo file may be formatted into an Info file with either footnote -style.@refill - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{texinfo-format-buffer} and -@code{texinfo-format-region} use the `separate' style and -@code{makeinfo} uses the `end' style.@refill - -@c !!! note: makeinfo's --footnote-style option overrides footnotestyle -@ignore -If you use @code{makeinfo} to create the Info file, the -@samp{--footnote-style} option determines which style is used, -@samp{end} for the end of node style or @samp{separate} for the -separate node style. Thus, to format the Texinfo manual in the -separate node style, you would use the following shell command:@refill - -@example -makeinfo --footnote-style=separate texinfo.texi -@end example - -@noindent -To format the Texinfo manual in the end of node style, you would -type:@refill - -@example -makeinfo --footnote-style=end texinfo.texi -@end example -@end ignore -@ignore -If you use @code{texinfo-format-buffer} or -@code{texinfo-format-region} to create the Info file, the value of the -@code{texinfo-footnote-style} variable controls the footnote style. -It can be either @samp{"separate"} for the separate node style or -@samp{"end"} for the end of node style. (You can change the value of -this variable with the @kbd{M-x edit-options} command (@pxref{Edit -Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or -with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining -and Setting Variables, emacs, The GNU Emacs Manual}).@refill - -The @code{texinfo-footnote-style} variable also controls the style if -you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} -command in Emacs.@refill -@end ignore -This chapter contains two footnotes.@refill - -@node Conditionals, Macros, Footnotes, Top -@comment node-name, next, previous, up -@chapter Conditionally Visible Text -@cindex Conditionally visible text -@cindex Text, conditionally visible -@cindex Visibility of conditional text -@cindex If text conditionally visible -@findex ifhtml -@findex ifinfo -@findex iftex - -Sometimes it is good to use different text for a printed manual and -its corresponding Info file. In this case, you can use the -@dfn{conditional commands} to specify which text is for the printed manual -and which is for the Info file.@refill - -@menu -* Conditional Commands:: How to specify text for HTML, Info, or @TeX{}. -* Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. -* set clear value:: How to designate which text to format (for - both Info and @TeX{}); and how to set a - flag to a string that you can insert. -@end menu - -@node Conditional Commands, Using Ordinary TeX Commands, Conditionals, Conditionals -@ifinfo -@heading Using @code{@@ifinfo} and @code{@@iftex} -@end ifinfo - -@code{@@ifinfo} begins segments of text that should be ignored -by @TeX{} when it -typesets the printed manual. The segment of text appears only -in the Info file. -The @code{@@ifinfo} command should appear on a line by itself; end -the Info-only text with a line containing @code{@@end ifinfo} by -itself. At the beginning of a Texinfo file, the Info permissions are -contained within a region marked by @code{@@ifinfo} and @code{@@end -ifinfo}. (@xref{Info Summary and Permissions}.)@refill - -The @code{@@iftex} and @code{@@end iftex} commands are similar to the -@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they -specify text that will appear in the printed manual but not in the Info -file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which -specify text to appear only in HTML output.@refill - -@need 700 -For example, - -@example -@@iftex -This text will appear only in the printed manual. -@@end iftex - -@@ifinfo -However, this text will appear only in Info. -@@end ifinfo -@end example - -@noindent -The preceding example produces the following line: - -@iftex -This text will appear only in the printed manual. -@end iftex - -@ifinfo -However, this text will appear only in Info. -@end ifinfo - -@noindent -Note how you only see one of the two lines, depending on whether you -are reading the Info version or the printed version of this -manual.@refill - -The @code{@@titlepage} command is a special variant of @code{@@iftex} that -is used for making the title and copyright pages of the printed -manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill - -@node Using Ordinary TeX Commands, set clear value, Conditional Commands, Conditionals -@comment node-name, next, previous, up -@section Using Ordinary @TeX{} Commands -@cindex @TeX{} commands, using ordinary -@cindex Ordinary @TeX{} commands, using -@cindex Commands using ordinary @TeX{} -@cindex plain @TeX{} - -Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, -you can embed some plain @TeX{} commands. Info will ignore these -commands since they are only in that part of the file which is seen by -@TeX{}. You can write the @TeX{} commands as you would write them in -a normal @TeX{} file, except that you must replace the @samp{\} used -by @TeX{} with an @samp{@@}. For example, in the @code{@@titlepage} -section of a Texinfo file, you can use the @TeX{} command -@code{@@vskip} to format the copyright page. (The @code{@@titlepage} -command causes Info to ignore the region automatically, as it does -with the @code{@@iftex} command.)@refill - -However, many features of plain @TeX{} will not work, as they are -overridden by features of Texinfo. - -@findex tex -You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} -commands, by delineating a region with the @code{@@tex} and @code{@@end -tex} commands. (The @code{@@tex} command also causes Info to ignore the -region, like the @code{@@iftex} -command.)@refill - -@cindex Mathematical expressions -For example, here is a mathematical expression written in -plain @TeX{}:@refill - -@example -@@tex -$$ \chi^2 = \sum_@{i=1@}^N - \left (y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@@end tex -@end example - -@noindent -The output of this example will appear only in a printed manual. If -you are reading this in Info, you will not see anything after this -paragraph. -@iftex -In a printed manual, the above expression looks like -this: -@end iftex - -@tex -$$ \chi^2 = \sum_{i=1}^N - \left(y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@end tex - -@node set clear value, , Using Ordinary TeX Commands, Conditionals -@comment node-name, next, previous, up -@section @code{@@set}, @code{@@clear}, and @code{@@value} - -You can direct the Texinfo formatting commands to format or ignore parts -of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, -and @code{@@ifclear} commands.@refill - -In addition, you can use the @code{@@set @var{flag}} command to set the -value of @var{flag} to a string of characters; and use -@code{@@value@{@var{flag}@}} to insert that string. You can use -@code{@@set}, for example, to set a date and use @code{@@value} to -insert the date in several places in the Texinfo file.@refill - -@menu -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. -@end menu - -@node ifset ifclear, value, set clear value, set clear value -@subsection @code{@@ifset} and @code{@@ifclear} - -@findex ifset -When a @var{flag} is set, the Texinfo formatting commands format text -between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end -ifset} commands. When the @var{flag} is cleared, the Texinfo formatting -commands do @emph{not} format the text. - -Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a -@var{flag}; a @dfn{flag} can be any single word. The format for the -command looks like this:@refill -@findex set - -@example -@@set @var{flag} -@end example - -Write the conditionally formatted text between @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, like this:@refill - -@example -@group -@@ifset @var{flag} -@var{conditional-text} -@@end ifset -@end group -@end example - -For example, you can create one document that has two variants, such as -a manual for a `large' and `small' model:@refill - -@example -You can use this machine to dig up shrubs -without hurting them. - -@@set large - -@@ifset large -It can also dig up fully grown trees. -@@end ifset - -Remember to replant promptly @dots{} -@end example - -@noindent -In the example, the formatting commands will format the text between -@code{@@ifset large} and @code{@@end ifset} because the @code{large} -flag is set.@refill - -@findex clear -Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear}, -a flag. Clearing a flag is the opposite of setting a flag. The -command looks like this:@refill - -@example -@@clear @var{flag} -@end example - -@noindent -Write the command on a line of its own. - -When @var{flag} is cleared, the Texinfo formatting commands do -@emph{not} format the text between @code{@@ifset @var{flag}} and -@code{@@end ifset}; that text is ignored and does not appear in either -printed or Info output.@refill - -For example, if you clear the flag of the preceding example by writing -an @code{@@clear large} command after the @code{@@set large} command -(but before the conditional text), then the Texinfo formatting commands -ignore the text between the @code{@@ifset large} and @code{@@end ifset} -commands. In the formatted output, that text does not appear; in both -printed and Info output, you see only the lines that say, ``You can use -this machine to dig up shrubs without hurting them. Remember to replant -promptly @dots{}''. - -@findex ifclear -If a flag is cleared with an @code{@@clear @var{flag}} command, then -the formatting commands format text between subsequent pairs of -@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag -is set with @code{@@set @var{flag}}, then the formatting commands do -@emph{not} format text between an @code{@@ifclear} and an @code{@@end -ifclear} command; rather, they ignore that text. An @code{@@ifclear} -command looks like this:@refill - -@example -@@ifclear @var{flag} -@end example - -@need 700 -In brief, the commands are:@refill - -@table @code -@item @@set @var{flag} -Tell the Texinfo formatting commands that @var{flag} is set.@refill - -@item @@clear @var{flag} -Tell the Texinfo formatting commands that @var{flag} is cleared.@refill - -@item @@ifset @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to format -the text up to the following @code{@@end ifset} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -ignore text up to the following @code{@@end ifset} command.@refill - -@item @@ifclear @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to ignore -the text up to the following @code{@@end ifclear} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -format the text up to the following @code{@@end ifclear} -command.@refill -@end table - -@node value, value Example, ifset ifclear, set clear value -@subsection @code{@@value} -@findex value - -You can use the @code{@@set} command to specify a value for a flag, -which is expanded by the @code{@@value} command. The value is a string -a characters. - -Write the @code{@@set} command like this: - -@example -@@set foo This is a string. -@end example - -@noindent -This sets the value of @code{foo} to ``This is a string.'' - -The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with -the string to which @var{flag} is set.@refill - -Thus, when @code{foo} is set as shown above, the Texinfo formatters convert - -@example -@group -@@value@{foo@} -@exdent @r{to} -This is a string. -@end group -@end example - -You can write an @code{@@value} command within a paragraph; but you -must write an @code{@@set} command on a line of its own. - -If you write the @code{@@set} command like this: - -@example -@@set foo -@end example - -@noindent -without specifying a string, the value of @code{foo} is an empty string. - -If you clear a previously set flag with an @code{@@clear @var{flag}} -command, a subsequent @code{@@value@{flag@}} command is invalid and the -string is replaced with an error message that says @samp{@{No value for -"@var{flag}"@}}. - -For example, if you set @code{foo} as follows:@refill - -@example -@@set how-much very, very, very -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{how-much@} wet day. -@exdent @r{into} -It is a very, very, very wet day. -@end group -@end example - -If you write - -@example -@@clear how-much -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{how-much@} wet day. -@exdent @r{into} -It is a @{No value for "how-much"@} wet day. -@end group -@end example - -@node value Example, , value, set clear value -@subsection @code{@@value} Example - -You can use the @code{@@value} command to limit the number of places you -need to change when you record an update to a manual. -Here is how it is done in @cite{The GNU Make Manual}: - -@need 1000 -@noindent -Set the flags: - -@example -@group -@@set EDITION 0.35 Beta -@@set VERSION 3.63 Beta -@@set UPDATED 14 August 1992 -@@set UPDATE-MONTH August 1992 -@end group -@end example - -@need 750 -@noindent -Write text for the first @code{@@ifinfo} section, for people reading the -Texinfo file: - -@example -@group -This is Edition @@value@{EDITION@}, -last updated @@value@{UPDATED@}, -of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, Version @@value@{VERSION@}. -@end group -@end example - -@need 1000 -@noindent -Write text for the title page, for people reading the printed manual: -@c List only the month and the year since that looks less fussy on a -@c printed cover than a date that lists the day as well. - -@example -@group -@@title GNU Make -@@subtitle A Program for Directing Recompilation -@@subtitle Edition @@value@{EDITION@}, @dots{} -@@subtitle @@value@{UPDATE-MONTH@} -@end group -@end example - -@noindent -(On a printed cover, a date listing the month and the year looks less -fussy than a date listing the day as well as the month and year.) - -@need 750 -@noindent -Write text for the Top node, for people reading the Info file: - -@example -@group -This is Edition @@value@{EDITION@} -of the @@cite@{GNU Make Manual@}, -last updated @@value@{UPDATED@} -for @@code@{make@} Version @@value@{VERSION@}. -@end group -@end example - -@need 950 -After you format the manual, the text in the first @code{@@ifinfo} -section looks like this: - -@example -@group -This is Edition 0.35 Beta, last updated 14 August 1992, -of `The GNU Make Manual', for `make', Version 3.63 Beta. -@end group -@end example - -When you update the manual, change only the values of the flags; you do -not need to rewrite the three sections. - - -@node Macros, Format/Print Hardcopy, Conditionals, Top -@chapter Macros: Defining New Texinfo Commands -@cindex Macros -@cindex Defining new Texinfo commands -@cindex New Texinfo commands, defining -@cindex Texinfo commands, defining new -@cindex User-defined Texinfo commands - -A Texinfo @dfn{macro} allows you to define a new Texinfo command as any -sequence of text and/or existing commands (including other macros). The -macro can have any number of @dfn{parameters}---text you supply each -time you use the macro. (This has nothing to do with the -@code{@@defmac} command, which is for documenting macros in the subject -of the manual; @pxref{Def Cmd Template}.) - -@menu -* Defining Macros:: Both defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -@end menu - - -@node Defining Macros, Invoking Macros, Macros, Macros -@section Defining Macros -@cindex Defining macros -@cindex Macro definitions - -@findex macro -You use the Texinfo @code{@@macro} command to define a macro. For example: - -@example -@@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@} -@var{text} @dots{} \@var{param1}\ @dots{} -@@end macro -@end example - -The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to -arguments supplied when the macro is subsequently used in the document -(see the next section). - -If a macro needs no parameters, you can define it either with an empty -list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro -foo}). - -@cindex Body of a macro -@cindex Mutually recursive macros -@cindex Recursion, mutual -The definition or @dfn{body} of the macro can contain any Texinfo -commands, including previously-defined macros. (It is not possible to -have mutually recursive Texinfo macros.) In the body, instances of a -parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in -the example above, are replaced by the corresponding argument from the -macro invocation. - -@findex unmacro -@cindex Macros, undefining -@cindex Undefining macros -You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. -It is not an error to undefine a macro that is already undefined. -For example: - -@example -@@unmacro foo -@end example - - -@node Invoking Macros, , Defining Macros, Macros -@section Invoking Macros -@cindex Invoking macros -@cindex Macro invocation - -After a macro is defined (see the previous section), you can use -(@dfn{invoke}) it in your document like this: - -@example -@@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@} -@end example - -@noindent and the result will be just as if you typed the body of -@var{macro-name} at that spot. For example: - -@example -@@macro foo @{p, q@} -Together: \p\ & \q\. -@@end macro -@@foo@{a, b@} -@end example - -@noindent produces: - -@display -Together: a & b. -@end display - -@cindex Backslash, and macros -Thus, the arguments and parameters are separated by commas and delimited -by braces; any whitespace after (but not before) a comma is ignored. To -insert a comma, brace, or backslash in an argument, prepend a backslash, -as in - -@example -@@@var{macro-name} @{\\\@{\@}\,@} -@end example - -@noindent -which will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macro-name}. - -If the macro is defined to take a single argument, and is invoked -without any braces, the entire rest of the line after the macro name is -supplied as the argument. For example: - -@example -@@macro bar @{p@} -Twice: \p\, \p\. -@@end macro -@@bar aah -@end example - -@noindent produces: - -@display -Twice: aah, aah. -@end display - - -@node Format/Print Hardcopy, Create an Info File, Macros, Top -@comment node-name, next, previous, up -@chapter Format and Print Hardcopy -@cindex Format and print hardcopy -@cindex Hardcopy, printing it -@cindex Making a printed manual -@cindex Sorting indices -@cindex Indices, sorting -@cindex @TeX{} index sorting -@pindex texindex - -There are three major shell commands for making a printed manual from a -Texinfo file: one for converting the Texinfo file into a file that will be -printed, a second for sorting indices, and a third for printing the -formatted document. When you use the shell commands, you can either -work directly in the operating system shell or work within a shell -inside GNU Emacs.@refill - -If you are using GNU Emacs, you can use commands provided by Texinfo -mode instead of shell commands. In addition to the three commands to -format a file, sort the indices, and print the result, Texinfo mode -offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue.@refill - -@menu -* Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format in a shell. -* Format with texi2dvi:: A simpler way to use the shell. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What you need to do to use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -@end menu - -@node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy -@ifinfo -@heading Use @TeX{} -@end ifinfo - -The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, if used right, -does an exceptionally good job. @xref{Obtaining TeX, , How to Obtain -@TeX{}}, for information on how to obtain @TeX{}.@refill - -The @code{makeinfo}, @code{texinfo-format-region}, and -@code{texinfo-format-buffer} commands read the very same @@-commands -in the Texinfo file as does @TeX{}, but process them differently to -make an Info file; see @ref{Create an Info File}.@refill - -@node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format using @code{tex} and @code{texindex} -@cindex Shell formatting with @code{tex} and @code{texindex} -@cindex Formatting with @code{tex} and @code{texindex} -@cindex DVI file - -Format the Texinfo file with the shell command @code{tex} followed by -the name of the Texinfo file. This command produces a formatted -@sc{dvi} file as well as several auxiliary files containing indices, -cross references, etc. The @sc{dvi} file (for @dfn{DeVice Independent} -file) can be printed on a wide variety of printers.@refill - -The @code{tex} formatting command itself does not sort the indices; it -writes an output file of unsorted index data. This is a misfeature of -@TeX{}. (The @code{texi2dvi} command automatically generates indices; -see @ref{Format with texi2dvi, , Format using @code{texi2dvi}}.) To -generate a printed index after running the @code{tex} command, you first -need a sorted index to work from. The @code{texindex} command sorts -indices. (The source file @file{texindex.c} comes as part of the -standard GNU distribution and is usually installed when Emacs is -installed.)@refill -@pindex texindex -@ignore -Usage: texindex [-k] [-T tempdir] infile [-o outfile] ... - -Each infile arg can optionally be followed by a `-o outfile' arg; -for each infile that is not followed by a -o arg, the infile name with -`s' (for `sorted') appended is used for the outfile. - --T dir is the directory to put temp files in, instead of /tmp. --k means `keep tempfiles', for debugging. -@end ignore - -The @code{tex} formatting command outputs unsorted index files under -names that obey a standard convention. These names are the name of -your main input file to the @code{tex} formatting command, with -everything after the first period thrown away, and the two letter -names of indices added at the end. For example, the raw index output -files for the input file @file{foo.texinfo} would be @file{foo.cp}, -@file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and -@file{foo.ky}. Those are exactly the arguments to give to -@code{texindex}.@refill - -@need 1000 -Or else, you can use @samp{??} as ``wild-cards'' and give the command in -this form:@refill - -@example -texindex foo.?? -@end example - -@noindent -This command will run @code{texindex} on all the unsorted index files, -including any that you have defined yourself using @code{@@defindex} -or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} -even if there are similarly named files with two letter extensions -that are not index files, such as @samp{foo.el}. The @code{texindex} -command reports but otherwise ignores such files.)@refill - -For each file specified, @code{texindex} generates a sorted index file -whose name is made by appending @samp{s} to the input file name. The -@code{@@printindex} command knows to look for a file of that name. -@code{texindex} does not alter the raw index output file.@refill - -After you have sorted the indices, you need to rerun the @code{tex} -formatting command on the Texinfo file. This regenerates a formatted -@sc{dvi} file with up-to-date index entries.@footnote{If you use more -than one index and have cross references to an index other than the -first, you must run @code{tex} @emph{three times} to get correct output: -once to generate raw index data; again (after @code{texindex}) to output -the text of the indices and determine their true page numbers; and a -third time to output correct page numbers in cross references to them. -However, cross references to indices are rare.}@refill - -To summarize, this is a three step process: - -@enumerate -@item -Run the @code{tex} formatting command on the Texinfo file. This -generates the formatted @sc{dvi} file as well as the raw index files -with two letter extensions.@refill - -@item -Run the shell command @code{texindex} on the raw index files to sort -them. This creates the corresponding sorted index files.@refill - -@item -Rerun the @code{tex} formatting command on the Texinfo file. This -regenerates a formatted @sc{dvi} file with the index entries in the -correct order. This second run also corrects the page numbers for -the cross references. (The tables of contents are always correct.)@refill -@end enumerate - -You need not run @code{texindex} each time after you run the -@code{tex} formatting. If you do not, on the next run, the @code{tex} -formatting command will use whatever sorted index files happen to -exist from the previous use of @code{texindex}. This is usually -@sc{ok} while you are debugging.@refill - -@node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format using @code{texi2dvi} -@pindex texi2dvi @r{(shell script)} - -The @code{texi2dvi} command is a shell script that automatically runs -both @code{tex} and @code{texindex} as many times as necessary to -produce a @sc{dvi} file with up-to-date, sorted indices. It simplifies -the @code{tex}---@code{texindex}---@code{tex} sequence described in the -previous section. - -@need 1000 -The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is the -shell prompt):@refill - -@example -prompt$ @kbd{texi2dvi @var{filename}@dots{}} -@end example - -@node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Shell Print Using @code{lpr -d} -@pindex lpr @r{(@sc{dvi} print command)} - -You can print a @sc{dvi} file with the @sc{dvi} print command. The -precise printing command to use depends on your system; @samp{lpr -d} is -common. The @sc{dvi} print command may require a file name without any -extension or with a @samp{.dvi} extension.@refill - -@need 1200 -The following commands, for example, sort the indices, format, and -print the @cite{Bison Manual} (where @samp{%} is the shell -prompt):@refill - -@example -@group -% tex bison.texinfo -% texindex bison.?? -% tex bison.texinfo -% lpr -d bison.dvi -@end group -@end example - -@noindent -(Remember that the shell commands may be different at your site; but -these are commonly used versions.)@refill - -@need 1000 -Using the @code{texi2dvi} shell script, you simply need type:@refill - -@example -@group -% texi2dvi bison.texinfo -% lpr -d bison.dvi -@end group -@end example - -@node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy -@comment node-name, next, previous, up -@section From an Emacs Shell @dots{} -@cindex Print, format from Emacs shell -@cindex Format, print from Emacs shell -@cindex Shell, format, print from -@cindex Emacs shell, format, print from -@cindex GNU Emacs shell, format, print from - -You can give formatting and printing commands from a shell within GNU -Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Format/Print -Hardcopy, , Format and Print Hardcopy}, for details.@refill - -You can switch to and from the shell buffer while @code{tex} is -running and do other editing. If you are formatting a long document -on a slow machine, this can be very convenient.@refill - -You can also use @code{texi2dvi} from an Emacs shell. For example, -here is how to use @code{texi2dvi} to format and print @cite{Using and -Porting GNU CC} from a shell within Emacs (where @samp{%} is the shell -prompt):@refill - -@example -@group -% texi2dvi gcc.texinfo -% lpr -d gcc.dvi -@end group -@end example -@ifinfo - -@xref{Texinfo Mode Printing}, for more information about formatting -and printing in Texinfo mode.@refill -@end ifinfo - -@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy -@section Formatting and Printing in Texinfo Mode -@cindex Region printing in Texinfo mode -@cindex Format and print in Texinfo mode -@cindex Print and format in Texinfo mode - -Texinfo mode provides several predefined key commands for @TeX{} -formatting and printing. These include commands for sorting indices, -looking at the printer queue, killing the formatting job, and -recentering the display of the buffer in which the operations -occur.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -Run @code{texi2dvi} on the current buffer.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -Run @TeX{} on the current region.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}.@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -Print a @sc{dvi} file that was made with @code{texinfo-tex-region} or -@code{texinfo-tex-buffer}.@refill - -@item C-c C-t C-q -@itemx M-x tex-show-print-queue -Show the print queue.@refill - -@item C-c C-t C-d -@itemx M-x texinfo-delete-from-print-queue -Delete a job from the print queue; you will be prompted for the job -number shown by a preceding @kbd{C-c C-t C-q} command -(@code{texinfo-show-tex-print-queue}).@refill - -@item C-c C-t C-k -@itemx M-x tex-kill-job -Kill the currently running @TeX{} job started by -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other -process running in the Texinfo shell buffer.@refill - -@item C-c C-t C-x -@itemx M-x texinfo-quit-job -Quit a @TeX{} formatting job that has stopped because of an error by -sending an @key{x} to it. When you do this, @TeX{} preserves a record -of what it did in a @file{.log} file.@refill - -@item C-c C-t C-l -@itemx M-x tex-recenter-output-buffer -Redisplay the shell buffer in which the @TeX{} printing and formatting -commands are run to show its most recent output.@refill -@end table - -@need 1000 -Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right):@refill - -@example -@group -C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} -C-c C-t C-p @r{Print the @sc{dvi} file.} -C-c C-t C-q @r{Display the printer queue.} -@end group -@end example - -The Texinfo mode @TeX{} formatting commands start a subshell in Emacs -called the @file{*tex-shell*}. The @code{texinfo-tex-command}, -@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} -commands are all run in this shell. - -You can watch the commands operate in the @samp{*tex-shell*} buffer, -and you can switch to and from and use the @samp{*tex-shell*} buffer -as you would any other shell buffer.@refill - -@need 1500 -The formatting and print commands depend on the values of several variables. -The default values are:@refill - -@example -@group - @r{Variable} @r{Default value} - -texinfo-texi2dvi-command "texi2dvi" -texinfo-tex-command "tex" -texinfo-texindex-command "texindex" -texinfo-delete-from-print-queue-command "lprm" -texinfo-tex-trailer "@@bye" -tex-start-of-header "%**start" -tex-end-of-header "%**end" -tex-dvi-print-command "lpr -d" -tex-show-queue-command "lpq" -@end group -@end example - -You can change the values of these variables with the @kbd{M-x -edit-options} command (@pxref{Edit Options, , Editing Variable Values, -emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command -(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU -Emacs Manual}), or with your @file{.emacs} initialization file -(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill - -@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Using the Local Variables List -@cindex Local variables -@cindex Compile command for formatting -@cindex Format with the compile command - -Yet another way to apply the @TeX{} formatting command to a Texinfo file -is to put that command in a @dfn{local variables list} at the end of the -Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} -commands as a @code{compile-command} and have Emacs run it by typing -@kbd{M-x compile}. This creates a special shell called the -@file{*compilation*} buffer in which Emacs runs the compile command. -For example, at the end of the @file{gdb.texinfo} file, after the -@code{@@bye}, you could put the following:@refill - -@example -@group -@@c Local Variables: -@@c compile-command: "texi2dvi gdb.texinfo" -@@c End: -@end group -@end example - -@noindent -This technique is most often used by programmers who also compile programs -this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill - -@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy -@comment node-name, next, previous, up -@section @TeX{} Formatting Requirements Summary -@cindex Requirements for formatting -@cindex Formatting requirements - -Every Texinfo file that is to be input to @TeX{} must begin with a -@code{\input} command and must contain an @code{@@setfilename} command and -an @code{@@settitle} command:@refill - -@example -\input texinfo -@@setfilename @var{arg-not-used-by-@TeX{}} -@@settitle @var{name-of-manual} -@end example - -@noindent -The first command instructs @TeX{} to load the macros it needs to -process a Texinfo file, the second command opens auxiliary files, and -the third specifies the title of printed manual. - -@need 1000 -Every Texinfo file must end with a line that terminates @TeX{} -processing and forces out unfinished pages:@refill - -@example -@@bye -@end example - -Strictly speaking, these four lines are all a Texinfo file needs for -@TeX{}, besides the body. (The @code{@@setfilename} line is the only -line that a Texinfo file needs for Info formatting.)@refill - -Usually, the file's first line contains an @samp{@@c -*-texinfo-*-} -comment that causes Emacs to switch to Texinfo mode when you edit the -file. In addition, the beginning usually includes an -@code{@@setchapternewpage} command, a title page, a copyright page, and -permissions. Besides an @code{@@bye}, the end of a file usually -includes indices and a table of contents.@refill - -@iftex -For more information, see -@ref{setchapternewpage, , @code{@@setchapternewpage}}, -@ref{Headings, ,Page Headings}, -@ref{Titlepage & Copyright Page}, -@ref{Printing Indices & Menus}, and -@ref{Contents}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{setchapternewpage, , @code{@@setchapternewpage}},@* -@ref{Headings, ,Page Headings},@* -@ref{Titlepage & Copyright Page},@* -@ref{Printing Indices & Menus}, and@* -@ref{Contents}. -@end ifinfo - -@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Preparing to Use @TeX{} -@cindex Preparing to use @TeX{} -@cindex @TeX{} input initialization -@cindex @code{TEXINPUTS} environment variable -@vindex TEXINPUTS -@cindex @b{.profile} initialization file -@cindex @b{.cshrc} initialization file -@cindex Initialization file for @TeX{} input - -@TeX{} needs to know where to find the @file{texinfo.tex} file -that you have told it to input with the @samp{\input texinfo} command -at the beginning of the first line. The @file{texinfo.tex} file tells -@TeX{} how to handle @@-commands. (@file{texinfo.tex} is -included in the standard GNU distributions.)@refill - -Usually, the @file{texinfo.tex} file is put in the default directory -that contains @TeX{} macros (the @file{/usr/lib/tex/macros} -directory) when GNU Emacs or other GNU software is installed. -In this case, @TeX{} will -find the file and you do not need to do anything special. -Alternatively, you can put @file{texinfo.tex} in the directory in -which the Texinfo source file is located, and @TeX{} will find it -there.@refill - -However, you may want to specify the location of the @code{\input} file -yourself. One way to do this is to write the complete path for the file -after the @code{\input} command. Another way is to set the -@code{TEXINPUTS} environment variable in your @file{.cshrc} or -@file{.profile} file. The @code{TEXINPUTS} environment variable will tell -@TeX{} where to find the @file{texinfo.tex} file and any other file that -you might want @TeX{} to use.@refill - -Whether you use a @file{.cshrc} or @file{.profile} file depends on -whether you use @code{csh}, @code{sh}, or @code{bash} for your shell -command interpreter. When you use @code{csh}, it looks to the -@file{.cshrc} file for initialization information, and when you use -@code{sh} or @code{bash}, it looks to the @file{.profile} file.@refill - -@need 1000 -In a @file{.cshrc} file, you could use the following @code{csh} command -sequence:@refill - -@example -setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros -@end example - -@need 1000 -In a @file{.profile} file, you could use the following @code{sh} command -sequence: - -@example -@group -TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros -export TEXINPUTS -@end group -@end example - -@noindent -This would cause @TeX{} to look for @file{\input} file first in the current -directory, indicated by the @samp{.}, then in a hypothetical user's -@file{me/mylib} directory, and finally in the system library.@refill - -@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Overfull ``hboxes'' -@cindex Overfull @samp{hboxes} -@cindex @samp{hboxes}, overfull -@cindex Final output - -@TeX{} is sometimes unable to typeset a line without extending it into -the right margin. This can occur when @TeX{} comes upon what it -interprets as a long word that it cannot hyphenate, such as an -electronic mail network address or a very long title. When this -happens, @TeX{} prints an error message like this:@refill - -@example -Overfull \hbox (20.76302pt too wide) -@end example - -@noindent -(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. -The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill - -@TeX{} also provides the line number in the Texinfo source file and -the text of the offending line, which is marked at all the places that -@TeX{} knows how to hyphenate words. -@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -for more information about typesetting errors.@refill - -If the Texinfo file has an overfull hbox, you can rewrite the sentence -so the overfull hbox does not occur, or you can decide to leave it. A -small excursion into the right margin often does not matter and may not -even be noticeable.@refill - -@cindex Black rectangle in hardcopy -@cindex Rectangle, ugly, black in hardcopy -However, unless told otherwise, @TeX{} will print a large, ugly, black -rectangle beside the line that contains the overfull hbox. This is so -you will notice the location of the problem if you are correcting a -draft.@refill - -@need 1000 -@findex finalout -To prevent such a monstrosity from marring your final printout, write -the following in the beginning of the Texinfo file on a line of its own, -before the @code{@@titlepage} command:@refill - -@example -@@finalout -@end example - -@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Printing ``Small'' Books -@findex smallbook -@cindex Small book size -@cindex Book, printing small -@cindex Page sizes for books -@cindex Size of printed book - -By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch -format. However, you can direct @TeX{} to typeset a document in a 7 by -9.25 inch format that is suitable for bound books by inserting the -following command on a line by itself at the beginning of the Texinfo -file, before the title page:@refill - -@example -@@smallbook -@end example - -@noindent -(Since regular sized books are often about 7 by 9.25 inches, this -command might better have been called the @code{@@regularbooksize} -command, but it came to be called the @code{@@smallbook} command by -comparison to the 8.5 by 11 inch format.)@refill - -If you write the @code{@@smallbook} command between the -start-of-header and end-of-header lines, the Texinfo mode @TeX{} -region formatting command, @code{texinfo-tex-region}, will format the -region in ``small'' book size (@pxref{Start of Header}).@refill - -The Free Software Foundation distributes printed copies of @cite{The GNU -Emacs Manual} and other manuals in the ``small'' book size. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}, for information about commands that make it easier -to produce examples for a smaller manual.@refill - -@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Printing on A4 Paper -@cindex A4 paper, printing on -@cindex Paper size, European A4 -@cindex European A4 paper -@findex afourpaper - -You can tell @TeX{} to typeset a document for printing on European size -A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself between @code{@@iftex} and @code{@@end iftex} lines near -the beginning of the Texinfo file, before the title page:@refill - -For example, this is how you would write the header for this manual:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename texinfo -@@settitle Texinfo -@@syncodeindex vr fn -@@iftex -@@afourpaper -@@end iftex -@@c %**end of header -@end group -@end example - -@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Cropmarks and Magnification - -@findex cropmarks -@cindex Cropmarks for printing -@cindex Printing cropmarks -You can attempt to direct @TeX{} to print cropmarks at the corners of -pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} -command on a line by itself between @code{@@iftex} and @code{@@end -iftex} lines near the beginning of the Texinfo file, before the title -page, like this:@refill - -@example -@group -@@iftex -@@cropmarks -@@end iftex -@end group -@end example - -This command is mainly for printers that typeset several pages on one -sheet of film; but you can attempt to use it to mark the corners of a -book set to 7 by 9.25 inches with the @code{@@smallbook} command. -(Printers will not produce cropmarks for regular sized output that is -printed on regular sized paper.) Since different printing machines work -in different ways, you should explore the use of this command with a -spirit of adventure. You may have to redefine the command in the -@file{texinfo.tex} definitions file.@refill - -@findex mag @r{(@TeX{} command)} -@cindex Magnified printing -@cindex Larger or smaller pages -You can attempt to direct @TeX{} to typeset pages larger or smaller than -usual with the @code{\mag} @TeX{} command. Everything that is typeset -is scaled proportionally larger or smaller. (@code{\mag} stands for -``magnification''.) This is @emph{not} a Texinfo @@-command, but is a -plain @TeX{} command that is prefixed with a backslash. You have to -write this command between @code{@@tex} and @code{@@end tex} -(@pxref{Using Ordinary TeX Commands, , Using Ordinary @TeX{} -Commands}).@refill - -Follow the @code{\mag} command with an @samp{=} and then a number that -is 1000 times the magnification you desire. For example, to print pages -at 1.2 normal size, write the following near the beginning of the -Texinfo file, before the title page:@refill - -@example -@group -@@tex -\mag=1200 -@@end tex -@end group -@end example - -With some printing technologies, you can print normal-sized copies that -look better than usual by using a larger-than-normal master.@refill - -Depending on your system, @code{\mag} may not work or may work only at -certain magnifications. Be prepared to experiment.@refill - -@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top -@comment node-name, next, previous, up -@chapter Creating an Info File -@cindex Creating an Info file -@cindex Info, creating an on-line file -@cindex Formatting a file for Info - -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same.@refill - -A Texinfo file must possess an @code{@@setfilename} line near its -beginning, otherwise the Info formatting commands will fail.@refill - -For information on installing the Info file in the Info system, see -@ref{Install an Info File}.@refill - -@menu -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. -@end menu - -@node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File -@ifinfo -@heading @code{makeinfo} Preferred -@end ifinfo - -The @code{makeinfo} utility creates an Info file from a Texinfo source -file more quickly than either of the Emacs formatting commands and -provides better error messages. We recommend it. @code{makeinfo} is a -C program that is independent of Emacs. You do not need to run Emacs to -use @code{makeinfo}, which means you can use @code{makeinfo} on machines -that are too small to run Emacs. You can run @code{makeinfo} in -any one of three ways: from an operating system shell, from a shell -inside Emacs, or by typing a key command in Texinfo mode in Emacs. -@refill - -The @code{texinfo-format-region} and the @code{texinfo-format-buffer} -commands are useful if you cannot run @code{makeinfo}. Also, in some -circumstances, they format short regions or buffers more quickly than -@code{makeinfo}.@refill - -@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File -@section Running @code{makeinfo} from a Shell - -To create an Info file from a Texinfo file, type @code{makeinfo} -followed by the name of the Texinfo file. Thus, to create the Info -file for Bison, type the following at the shell prompt (where @samp{%} -is the prompt):@refill - -@example -% makeinfo bison.texinfo -@end example - -(You can run a shell inside Emacs by typing @kbd{M-x -shell}.)@refill - -@ifinfo -Sometimes you will want to specify options. For example, if you wish -to discover which version of @code{makeinfo} you are using, -type:@refill - -@example -% makeinfo --version -@end example - -@xref{makeinfo options}, for more information. -@end ifinfo - -@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File -@comment node-name, next, previous, up -@section Options for @code{makeinfo} -@cindex @code{makeinfo} options -@cindex Options for @code{makeinfo} - -The @code{makeinfo} command takes a number of options. Most often, -options are used to set the value of the fill column and specify the -footnote style. Each command line option is a word preceded by -@samp{--}@footnote{@samp{--} has replaced @samp{+}, the old introductory -character, to maintain POSIX.2 compatibility without losing long-named -options.} or a letter preceded by @samp{-}. You can use abbreviations -for the option names as long as they are unique.@refill - -For example, you could use the following command to create an Info -file for @file{bison.texinfo} in which each line is filled to only 68 -columns (where @samp{%} is the prompt):@refill - -@example -% makeinfo --fill-column=68 bison.texinfo -@end example - -You can write two or more options in sequence, like this:@refill - -@example -% makeinfo --no-split --fill-column=70 @dots{} -@end example - -@noindent -This would keep the Info file together as one possibly very long -file and would also set the fill column to 70.@refill - -@iftex -If you wish to discover which version of @code{makeinfo} -you are using, type:@refill - -@example -% makeinfo --version -@end example -@end iftex - -The options are:@refill - -@need 100 -@table @code -@item -D @var{var} -Cause @var{var} to be defined. This is equivalent to -@code{@@set @var{var}} in the Texinfo file. - -@need 150 -@item --error-limit @var{limit} -Set the maximum number of errors that @code{makeinfo} will report -before exiting (on the assumption that continuing would be useless). -The default number of errors that can be reported before -@code{makeinfo} gives up is 100.@refill - -@need 150 -@item --fill-column @var{width} -Specify the maximum number of columns in a line; this is the right-hand -edge of a line. Paragraphs that are filled will be filled to this -width. (Filling is the process of breaking up and connecting lines so -that lines are the same length as or shorter than the number specified -as the fill column. Lines are broken between words.) The default value -for @code{fill-column} is 72. -@refill - -@item --footnote-style @var{style} -Set the footnote style to @var{style}, either @samp{end} for the end -node style or @samp{separate} for the separate node style. The value -set by this option overrides the value set in a Texinfo file by an -@code{@@footnotestyle} command. When the footnote style is -@samp{separate}, @code{makeinfo} makes a new node containing the -footnotes found in the current node. When the footnote style is -@samp{end}, @code{makeinfo} places the footnote references at the end -of the current node.@refill - -@need 150 -@item -I @var{dir} -Add @code{dir} to the directory search list for finding files that are -included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. - -@need 150 -@item --no-headers -Do not include menus or node lines in the output. This results in an -@sc{ascii} file that you cannot read in Info since it does not contain -the requisite nodes or menus; but you can print such a file in a -single, typewriter-like font and produce acceptable output. - -@need 150 -@item --no-split -Suppress the splitting stage of @code{makeinfo}. Normally, large -output files (where the size is greater than 70k bytes) are split into -smaller subfiles, each one approximately 50k bytes. If you specify -@samp{--no-split}, @code{makeinfo} will not split up the output -file.@refill - -@need 100 -@item --no-pointer-validate -@item --no-validate -Suppress the pointer-validation phase of @code{makeinfo}. Normally, -after a Texinfo file is processed, some consistency checks are made to -ensure that cross references can be resolved, etc. -@xref{Pointer Validation}.@refill - -@need 150 -@item --no-warn -Suppress the output of warning messages. This does @emph{not} -suppress the output of error messages, only warnings. You might -want this if the file you are creating has examples of Texinfo cross -references within it, and the nodes that are referenced do not actually -exist.@refill - -@item --no-number-footnotes -Suppress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@need 150 -@item --output @var{file} -@itemx -o @var{file} -Specify that the output should be directed to @var{file} and not to the -file name specified in the @code{@@setfilename} command found in the Texinfo -source. @var{file} can be the special token @samp{-}, which specifies -standard output. - -@need 150 -@item --paragraph-indent @var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command. The value of @var{indent} is -interpreted as follows:@refill - -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, do not change the -existing indentation at the starts of paragraphs.@refill - -@item -If the value of @var{indent} is zero, delete any existing -indentation.@refill - -@item -If the value of @var{indent} is greater than zero, indent each -paragraph by that number of spaces.@refill -@end itemize - -@need 100 -@item --reference-limit @var{limit} -Set the value of the number of references to a node that -@code{makeinfo} will make without reporting a warning. If a node has more -than this number of references in it, @code{makeinfo} will make the -references but also report a warning.@refill - -@need 150 -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to -@code{@@clear @var{var}} in the Texinfo file. - -@need 100 -@item --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -Normally, @code{makeinfo} only outputs messages if there are errors or -warnings.@refill - -@need 100 -@item --version -Report the version number of this copy of @code{makeinfo}.@refill -@end table - -@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File -@section Pointer Validation -@cindex Pointer validation with @code{makeinfo} -@cindex Validation of pointers - -If you do not suppress pointer-validation, @code{makeinfo} will check -the validity of the final Info file. Mostly, this means ensuring that -nodes you have referenced really exist. Here is a complete list of what -is checked:@refill - -@enumerate -@item -If a `Next', `Previous', or `Up' node reference is a reference to a -node in the current file and is not an external reference such as to -@file{(dir)}, then the referenced node must exist.@refill - -@item -In every node, if the `Previous' node is different from the `Up' node, -then the `Previous' node must also be pointed to by a `Next' node.@refill - -@item -Every node except the `Top' node must have an `Up' pointer.@refill - -@item -The node referenced by an `Up' pointer must contain a reference to the -current node in some manner other than through a `Next' reference. -This includes menu entries and cross references.@refill - -@item -If the `Next' reference of a node is not the same as the `Next' reference -of the `Up' reference, then the node referenced by the `Next' pointer -must have a `Previous' pointer that points back to the current node. -This rule allows the last node in a section to point to the first node -of the next chapter.@refill -@end enumerate - -@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File -@section Running @code{makeinfo} inside Emacs -@cindex Running @code{makeinfo} in Emacs -@cindex @code{makeinfo} inside Emacs -@cindex Shell, running @code{makeinfo} in - -You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the -@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In -Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c -C-m C-b} by default.@refill - -@table @kbd -@item C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@findex makeinfo-region - -@item C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@findex makeinfo-buffer -@end table - -When you invoke either @code{makeinfo-region} or -@code{makeinfo-buffer}, Emacs prompts for a file name, offering the -name of the visited file as the default. You can edit the default -file name in the minibuffer if you wish, before typing @key{RET} to -start the @code{makeinfo} process.@refill - -The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands -run the @code{makeinfo} program in a temporary shell buffer. If -@code{makeinfo} finds any errors, Emacs displays the error messages in -the temporary buffer.@refill - -@cindex Errors, parsing -@cindex Parsing errors -@findex next-error -You can parse the error messages by typing @kbd{C-x `} -(@code{next-error}). This causes Emacs to go to and position the -cursor on the line in the Texinfo source that @code{makeinfo} thinks -caused the error. @xref{Compilation, , Running @code{make} or -Compilers Generally, emacs, The GNU Emacs Manual}, for more -information about using the @code{next-error} command.@refill - -In addition, you can kill the shell in which the @code{makeinfo} -command is running or make the shell buffer display its most recent -output.@refill - -@table @kbd -@item C-c C-m C-k -@itemx M-x makeinfo-kill-job -@findex makeinfo-kill-job -Kill the current running @code{makeinfo} job created by -@code{makeinfo-region} or @code{makeinfo-buffer}.@refill - -@item C-c C-m C-l -@itemx M-x makeinfo-recenter-output-buffer -@findex makeinfo-recenter-output-buffer -Redisplay the @code{makeinfo} shell buffer to display its most recent -output.@refill -@end table - -@noindent -(Note that the parallel commands for killing and recentering a @TeX{} -job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode -Printing}.)@refill - -You can specify options for @code{makeinfo} by setting the -@code{makeinfo-options} variable with either the @kbd{M-x -edit-options} or the @kbd{M-x set-variable} command, or by setting the -variable in your @file{.emacs} initialization file.@refill - -For example, you could write the following in your @file{.emacs} file:@refill - -@example -@group -(setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") -@end group -@end example - -@c If you write these three cross references using xref, you see -@c three references to the same named manual, which looks strange. -@iftex -For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and -Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs -Manual}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* -@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* -@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* -@ref{makeinfo options, , Options for @code{makeinfo}}. -@end ifinfo - -@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File -@comment node-name, next, previous, up -@section The @code{texinfo-format@dots{}} Commands -@findex texinfo-format-region -@findex texinfo-format-buffer - -In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo -file with the @code{texinfo-format-region} command. This formats the -current region and displays the formatted text in a temporary buffer -called @samp{*Info Region*}.@refill - -Similarly, you can format a buffer with the -@code{texinfo-format-buffer} command. This command creates a new -buffer and generates the Info file in it. Typing @kbd{C-x C-s} will -save the Info file under the name specified by the -@code{@@setfilename} line which must be near the beginning of the -Texinfo file.@refill - -@table @kbd -@item C-c C-e C-r -@itemx @code{texinfo-format-region} -Format the current region for Info. -@findex texinfo-format-region - -@item C-c C-e C-b -@itemx @code{texinfo-format-buffer} -Format the current buffer for Info. -@findex texinfo-format-buffer -@end table - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands provide you with some error checking, and other functions can -provide you with further help in finding formatting errors. These -procedures are described in an appendix; see @ref{Catching Mistakes}. -However, the @code{makeinfo} program is often faster and -provides better error checking (@pxref{makeinfo in Emacs}).@refill - -@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File -@comment node-name, next, previous, up -@section Batch Formatting -@cindex Batch formatting for Info -@cindex Info batch formatting - -You can format Texinfo files for Info using @code{batch-texinfo-format} -and Emacs Batch mode. You can run Emacs in Batch mode from any shell, -including a shell inside of Emacs. (@xref{Command Switches, , Command -Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill - -Here is the command to format all the files that end in @file{.texinfo} -in the current directory (where @samp{%} is the shell prompt):@refill - -@example -% emacs -batch -funcall batch-texinfo-format *.texinfo -@end example - -@noindent -Emacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them.@refill - -Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; -it is not interactive. It kills the Batch mode Emacs on completion.@refill - -@code{batch-texinfo-format} is convenient if you lack @code{makeinfo} -and want to format several Texinfo files at once. When you use Batch -mode, you create a new Emacs process. This frees your current Emacs, so -you can continue working in it. (When you run -@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot -use that Emacs for anything else until the command finishes.)@refill - -@node Tag and Split Files, , Batch Formatting, Create an Info File -@comment node-name, next, previous, up -@section Tag Files and Split Files -@cindex Making a tag table automatically -@cindex Tag table, making automatically - -If a Texinfo file has more than 30,000 bytes, -@code{texinfo-format-buffer} automatically creates a tag table -for its Info file; @code{makeinfo} always creates a tag table. With -a @dfn{tag table}, Info can jump to new nodes more quickly than it can -otherwise.@refill - -@cindex Indirect subfiles -In addition, if the Texinfo file contains more than about 70,000 -bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the -large Info file into shorter @dfn{indirect} subfiles of about 50,000 -bytes each. Big files are split into smaller files so that Emacs does -not need to make a large buffer to hold the whole of a large Info -file; instead, Emacs allocates just enough memory for the small, split -off file that is needed at the time. This way, Emacs avoids wasting -memory when you run Info. (Before splitting was implemented, Info -files were always kept short and @dfn{include files} were designed as -a way to create a single, large printed manual out of the smaller Info -files. @xref{Include Files}, for more information. Include files are -still used for very large documents, such as @cite{The Emacs Lisp -Reference Manual}, in which each chapter is a separate file.)@refill - -When a file is split, Info itself makes use of a shortened version of -the original file that contains just the tag table and references to -the files that were split off. The split off files are called -@dfn{indirect} files.@refill - -The split off files have names that are created by appending @w{@samp{-1}}, -@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the -@code{@@setfilename} command. The shortened version of the original file -continues to have the name specified by @code{@@setfilename}.@refill - -At one stage in writing this document, for example, the Info file was saved -as @file{test-texinfo} and that file looked like this:@refill - -@example -@group -Info file: test-texinfo, -*-Text-*- -produced by texinfo-format-buffer -from file: new-texinfo-manual.texinfo - -^_ -Indirect: -test-texinfo-1: 102 -test-texinfo-2: 50422 -@end group -@group -test-texinfo-3: 101300 -^_^L -Tag table: -(Indirect) -Node: overview^?104 -Node: info file^?1271 -@end group -@group -Node: printed manual^?4853 -Node: conventions^?6855 -@dots{} -@end group -@end example - -@noindent -(But @file{test-texinfo} had far more nodes than are shown here.) Each of -the split off, indirect files, @file{test-texinfo-1}, -@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file -after the line that says @samp{Indirect:}. The tag table is listed after -the line that says @samp{Tag table:}. @refill - -In the list of indirect files, the number following the file name -records the cumulative number of bytes in the preceding indirect files, -not counting the file list itself, the tag table, or the permissions -text in each file. In the tag table, the number following the node name -records the location of the beginning of the node, in bytes from the -beginning.@refill - -If you are using @code{texinfo-format-buffer} to create Info files, -you may want to run the @code{Info-validate} command. (The -@code{makeinfo} command does such a good job on its own, you do not -need @code{Info-validate}.) However, you cannot run the @kbd{M-x -Info-validate} node-checking command on indirect files. For -information on how to prevent files from being split and how to -validate the structure of the nodes, see @ref{Using -Info-validate}.@refill - - -@node Install an Info File, Command List, Create an Info File, Top -@comment node-name, next, previous, up -@chapter Installing an Info File -@cindex Installing an Info file -@cindex Info file installation -@cindex @file{dir} directory for Info installation - -Info files are usually kept in the @file{info} directory. You can read -Info files using the standalone Info program or the Info reader built -into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) - -@menu -* Directory file:: The top level menu for all Info files. -* New Info File:: Listing a new info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: @code{install-info} options. -@end menu - -@node Directory file, New Info File, Install an Info File, Install an Info File -@ifinfo -@heading The @file{dir} File -@end ifinfo - -For Info to work, the @file{info} directory must contain a file that -serves as a top level directory for the Info system. By convention, -this file is called @file{dir}. (You can find the location of this file -within Emacs by typing @kbd{C-h i} to enter Info and then typing -@kbd{C-x C-f} to see the pathname to the @file{info} directory.) - -The @file{dir} file is itself an Info file. It contains the top level -menu for all the Info files in the system. The menu looks like -this:@refill - -@example -@group -* Menu: - -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -* Texinfo: (texinfo). With one source file, make - either a printed manual using - TeX or an Info file. -@dots{} -@end group -@end example - -Each of these menu entries points to the `Top' node of the Info file -that is named in parentheses. (The menu entry does not need to -specify the `Top' node, since Info goes to the `Top' node if no node -name is mentioned. @xref{Other Info Files, , Nodes in Other Info -Files}.)@refill - -Thus, the @samp{Info} entry points to the `Top' node of the -@file{info} file and the @samp{Emacs} entry points to the `Top' node -of the @file{emacs} file.@refill - -In each of the Info files, the `Up' pointer of the `Top' node refers -back to the @code{dir} file. For example, the line for the `Top' -node of the Emacs manual looks like this in Info:@refill - -@example -File: emacs Node: Top, Up: (DIR), Next: Distrib -@end example - -@noindent -(Note that in this case, the @file{dir} file name is written in upper -case letters---it can be written in either upper or lower case. Info -has a feature that it will change the case of the file name to lower -case if it cannot find the name as written.)@refill -@c !!! Can any file name be written in upper or lower case, -@c or is dir a special case? -@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 - - -@node New Info File, Other Info Directories, Directory file, Install an Info File -@section Listing a New Info File -@cindex Adding a new info file -@cindex Listing a new info file -@cindex New info file, listing it in @file{dir} file -@cindex Info file, listing new one -@cindex @file{dir} file listing - -To add a new Info file to your system, you must write a menu entry to -add to the menu in the @file{dir} file in the @file{info} directory. -For example, if you were adding documentation for GDB, you would write -the following new entry:@refill - -@example -* GDB: (gdb). The source-level C debugger. -@end example - -@noindent -The first part of the menu entry is the menu entry name, followed by a -colon. The second part is the name of the Info file, in parentheses, -followed by a period. The third part is the description. - -The name of an Info file often has a @file{.info} extension. Thus, the -Info file for GDB might be called either @file{gdb} or @file{gdb.info}. -The Info reader programs automatically try the file name both with and -without @file{.info}; so it is better to avoid clutter and not to write -@samp{.info} explicitly in the menu entry. For example, the GDB menu -entry should use just @samp{gdb} for the file name, not @samp{gdb.info}. - - -@node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File -@comment node-name, next, previous, up -@section Info Files in Other Directories -@cindex Installing Info in another directory -@cindex Info installed in another directory -@cindex Another Info directory - -If an Info file is not in the @file{info} directory, there are three -ways to specify its location:@refill - -@itemize @bullet -@item -Write the pathname in the @file{dir} file as the second part of the -menu.@refill - -@item -If you are using Emacs, list the name of the file in a second @file{dir} -file, in its directory; and then add the name of that directory to the -@code{Info-directory-list} variable in your personal or site -initialization file. - -This tells Emacs's Info reader where to look for @file{dir} -files. Emacs merges the files named @file{dir} from each of the listed -directories. (In Emacs Version 18, you can set the -@code{Info-directory} variable to the name of only one -directory.)@refill - -@item -Specify the @file{info} directory name in the @code{INFOPATH} -environment variable in your @file{.profile} or @file{.cshrc} -initialization file. (Only you and others who set this environment -variable will be able to find Info files whose location is specified -this way.)@refill -@end itemize - -For example, to reach a test file in the @file{~bob/manuals} -directory, you could add an entry like this to the menu in the -@file{dir} file:@refill - -@example -* Test: (/home/bob/manuals/info-test). Bob's own test file. -@end example - -@noindent -In this case, the absolute file name of the @file{info-test} file is -written as the second part of the menu entry.@refill - -@vindex Info-directory-list -Alternatively, you could write the following in your @file{.emacs} -file:@refill - -@example -@group -(setq Info-directory-list - '("/home/bob/manuals" - "/usr/local/emacs/info")) -@end group -@end example - -@c reworded to avoid overfill hbox -This tells Emacs to merge the @file{dir} file from the -@file{/home/bob/manuals} directory with the @file{dir} file from the -@file{"/usr/local/emacs/info}" directory. Info will list the -@file{/home/bob/manuals/info-test} file as a menu entry in the -@file{/home/bob/manuals/dir} file.@refill - -@vindex INFOPATH -Finally, you can tell Info where to look by setting the -@code{INFOPATH} environment variable in your @file{.cshrc} or -@file{.profile} file.@refill - -If you use @code{sh} or @code{bash} for your shell command interpreter, -you must set the @code{INFOPATH} environment variable in the -@file{.profile} initialization file; but if you use @code{csh}, you must -set the variable in the @file{.cshrc} initialization file. The two -files use slightly different command formats.@refill - -@itemize @bullet -@item -In a @file{.cshrc} file, you could set the @code{INFOPATH} -variable as follows:@refill - -@smallexample -setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info -@end smallexample - -@item -In a @file{.profile} file, you would achieve the same effect by -writing:@refill - -@smallexample -INFOPATH=.:~bob/manuals:/usr/local/emacs/info -export INFOPATH -@end smallexample -@end itemize - -@noindent -The @samp{.} indicates the current directory. Emacs uses the -@code{INFOPATH} environment variable to initialize the value of Emacs's -own @code{Info-directory-list} variable. - - -@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File -@section Installing Info Directory Files - -When you install an Info file onto your system, you can use the program -@code{install-info} to update the Info directory file @file{dir}. -Normally the makefile for the package runs @code{install-info}, just -after copying the Info file into its proper installed location. - -@findex dircategory -@findex direntry -In order for the Info file to work with @code{install-info}, you should -use the commands @code{@@dircategory} and @code{@@direntry} in the -Texinfo source file. Use @code{@@direntry} to specify the menu entry to -add to the Info directory file, and use @code{@@dircategory} to specify -which part of the Info directory to put it in. Here is how these -commands are used in this manual: - -@smallexample -@@dircategory Texinfo documentation system -@@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -@@end direntry -@end smallexample - -Here's what this produces in the Info file: - -@smallexample -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -END-INFO-DIR-ENTRY -@end smallexample - -@noindent -The @code{install-info} program sees these lines in the Info file, and -that is how it knows what to do. - -Always use the @code{@@direntry} and @code{@@dircategory} commands near -the beginning of the Texinfo input, before the first @code{@@node} -command. If you use them later on in the input, @code{install-info} -will not notice them. - -If you use @code{@@dircategory} more than once in the Texinfo source, -each usage specifies one category; the new menu entry is added to the -Info directory file in each of the categories you specify. If you use -@code{@@direntry} more than once, each usage specifies one menu entry; -each of these menu entries is added to the directory in each of the -specified categories. - - -@node Invoking install-info, , Installing Dir Entries, Install an Info File -@section Invoking install-info - -@pindex install-info - -@code{install-info} inserts menu entries from an Info file into the -top-level @file{dir} file in the Info system (see the previous sections -for an explanation of how the @file{dir} file works). It's most often -run as part of software installation, or when constructing a dir file -for all manuals on a system. Synopsis: - -@example -install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] -@end example - -If @var{info-file} or @var{dir-file} are not specified, the various -options (described below) that define them must be. There are no -compile-time defaults, and standard input is never used. -@code{install-info} can read only one info file and write only one dir -file per invocation. - -Options: - -@table @samp -@item --delete -@opindex --delete -Only delete existing entries in @var{info-file}; don't insert any new -entries. - -@item --dir-file=@var{name} -@opindex --dir-file=@var{name} -Specify file name of the Info directory file. This is equivalent to -using the @var{dir-file} argument. - -@item --entry=@var{text} -@opindex --entry=@var{text} -Insert @var{text} as an Info directory entry; @var{text} should have the -form of an Info menu item line plus zero or more extra lines starting -with whitespace. If you specify more than one entry, they are all -added. If you don't specify any entries, they are determined from -information in the Info file itself. - -@item --help -@opindex --help -Display a usage message listing basic usage and all available options, -then exit successfully. - -@item --info-file=@var{file} -@opindex --info-file=@var{file} -Specify Info file to install in the directory. -This is equivalent to using the @var{info-file} argument. - -@item --info-dir=@var{dir} -@opindex --info-dir=@var{dir} -Equivalent to @samp{--dir-file=@var{dir}/dir}. - -@item --item=@var{text} -@opindex --item=@var{text} -Same as --entry=@var{text}. An Info directory entry is actually a menu -item. - -@item --quiet -@opindex --quiet -Suppress warnings. - -@item --remove -@opindex --remove -Same as --delete. - -@item --section=@var{sec} -@opindex --section=@var{sec} -Put this file's entries in section @var{sec} of the directory. If you -specify more than one section, all the entries are added in each of the -sections. If you don't specify any sections, they are determined from -information in the Info file itself. - -@item --version -@opindex --version -@cindex version number, finding -Display version information and exit successfully. - -@end table - - -@c ================ Appendix starts here ================ - -@node Command List, Tips, Install an Info File, Top -@appendix @@-Command List -@cindex Alphabetical @@-command list -@cindex List of @@-commands -@cindex @@-command list - -Here is an alphabetical list of the @@-commands in Texinfo. Square -brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, -@samp{@dots{}}, indicates repeated text.@refill - -@sp 1 -@table @code -@item @@@var{whitespace} -An @code{@@} followed by a space, tab, or newline produces a normal, -stretchable, interword space. @xref{Multiple Spaces}. - -@item @@! -Generate an exclamation point that really does end a sentence (usually -after an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@" -@itemx @@' -Generate an umlaut or acute accent, respectively, over the next -character, as in @"o and @'o. @xref{Inserting Accents}. - -@item @@* -Force a line break. Do not end a paragraph that uses @code{@@*} with -an @code{@@refill} command. @xref{Line Breaks}.@refill - -@item @@,@{@var{c}@} -Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting -Accents}. - -@item @@- -Insert a discretionary hyphenation point. @xref{- and hyphenation}. - -@item @@. -Produce a period that really does end a sentence (usually after an -end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@: -Indicate to @TeX{} that an immediately preceding period, question -mark, exclamation mark, or colon does not end a sentence. Prevent -@TeX{} from inserting extra whitespace as it does at the end of a -sentence. The command has no effect on the Info file output. -@xref{Not Ending a Sentence}.@refill - -@item @@= -Generate a macro (bar) accent over the next character, as in @=o. -@xref{Inserting Accents}. - -@item @@? -Generate a question mark that really does end a sentence (usually after -an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@@@ -Stands for an at sign, @samp{@@}.@* -@xref{Braces Atsigns, , Inserting @@ and braces}. - -@item @@^ -@itemx @@` -Generate a circumflex (hat) or grave accent, respectively, over the next -character, as in @^o. -@xref{Inserting Accents}. - -@item @@@{ -Stands for a left brace, @samp{@{}.@* -@xref{Braces Atsigns, , Inserting @@ and braces}. - -@item @@@} -Stands for a right-hand brace, @samp{@}}.@* -@xref{Braces Atsigns, , Inserting @@ and braces}. - -@item @@= -Generate a tilde accent over the next character, as in @~N. -@xref{Inserting Accents}. - -@item @@AA@{@} -@itemx @@aa@{@} -Generate the uppercase and lowercase Scandinavian A-ring letters, -respectively: @AA{}, @aa{}. @xref{Inserting Accents}. - -@item @@AE@{@} -@itemx @@ae@{@} -Generate the uppercase and lowercase AE ligatures, respectively: -@AE{}, @ae{}. @xref{Inserting Accents}. - -@item @@appendix @var{title} -Begin an appendix. The title appears in the table -of contents of a printed manual. In Info, the title is -underlined with asterisks. @xref{unnumbered & appendix, , The -@code{@@unnumbered} and @code{@@appendix} Commands}.@refill - -@item @@appendixsec @var{title} -@itemx @@appendixsection @var{title} -Begin an appendix section within an appendix. The section title appears -in the table of contents of a printed manual. In Info, the title is -underlined with equal signs. @code{@@appendixsection} is a longer -spelling of the @code{@@appendixsec} command. @xref{unnumberedsec -appendixsec heading, , Section Commands}.@refill - -@item @@appendixsubsec @var{title} -Begin an appendix subsection within an appendix. The title appears -in the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , Subsection Commands}.@refill - -@item @@appendixsubsubsec @var{title} -Begin an appendix subsubsection within a subappendix. The title -appears in the table of contents of a printed manual. In Info, the -title is underlined with periods. @xref{subsubsection,, The `subsub' -Commands}.@refill - -@item @@asis -Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to -print the table's first column without highlighting (``as is''). -@xref{Two-column Tables, , Making a Two-column Table}.@refill - -@item @@author @var{author} -Typeset @var{author} flushleft and underline it. @xref{title -subtitle author, , The @code{@@title} and @code{@@author} -Commands}.@refill - -@item @@b@{@var{text}@} -Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill - -@ignore -@item @@br -Force a paragraph break. If used within a line, follow @code{@@br} -with braces. @xref{br, , @code{@@br}}.@refill -@end ignore - -@item @@bullet@{@} -Generate a large round dot, or the closest possible -thing to one. @xref{bullet, , @code{@@bullet}}.@refill - -@item @@bye -Stop formatting a file. The formatters do not see the contents of a -file following an @code{@@bye} command. @xref{Ending a File}.@refill - -@item @@c @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -either the Info file or the printed manual. A synonym for -@code{@@comment}. @xref{Comments, , Comments}.@refill - -@item @@cartouche -Highlight an example or quotation by drawing a box with rounded -corners around it. Pair with @code{@@end cartouche}. No effect in -Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@item @@center @var{line-of-text} -Center the line of text following the command. -@xref{titlefont center sp, , @code{@@center}}.@refill - -@item @@centerchap @var{line-of-text} -Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, -@code{@@chapter}}. - -@item @@chapheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{majorheading & chapheading, , @code{@@majorheading} -and @code{@@chapheading}}.@refill - -@item @@chapter @var{title} -Begin a chapter. The chapter title appears in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{chapter, , @code{@@chapter}}.@refill - -@item @@cindex @var{entry} -Add @var{entry} to the index of concepts. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@cite@{@var{reference}@} -Highlight the name of a book or other reference that lacks a -companion Info file. @xref{cite, , @code{@@cite}}.@refill - -@item @@clear @var{flag} -Unset @var{flag}, preventing the Texinfo formatting commands from -formatting text between subsequent pairs of @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, and preventing -@code{@@value@{@var{flag}@}} from expanding to the value to which -@var{flag} is set. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@code@{@var{sample-code}@} -Highlight text that is an expression, a syntactically complete token -of a program, or a program name. @xref{code, , @code{@@code}}.@refill - -@item @@comment @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -either the Info file or the printed manual. A synonym for @code{@@c}. -@xref{Comments, , Comments}.@refill - -@item @@contents -Print a complete table of contents. Has no effect in Info, which uses -menus instead. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@copyright@{@} -Generate a copyright symbol. @xref{copyright symbol, , -@code{@@copyright}}.@refill - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Describe an @sc{ascii} control character. Insert actual control character -into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill -@end ignore - -@item @@defcodeindex @var{index-name} -Define a new index and its indexing command. Print entries in an -@code{@@code} font. @xref{New Indices, , Defining New -Indices}.@refill - -@item @@defcv @var{category} @var{class} @var{name} -@itemx @@defcvx @var{category} @var{class} @var{name} -Format a description for a variable associated with a class in -object-oriented programming. Takes three arguments: the category of -thing being defined, the class to which it belongs, and its name. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} -Format a description for a function, interactive command, or similar -entity that may take arguments. @code{@@deffn} takes as arguments the -category of entity being described, the name of this particular -entity, and its arguments, if any. @xref{Definition Commands}.@refill - -@item @@defindex @var{index-name} -Define a new index and its indexing command. Print entries in a roman -font. @xref{New Indices, , Defining New Indices}.@refill - -@c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96. -@item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -Create new @@-command for Info that marks text by enclosing it in -strings that precede and follow the text. Write definition inside of -@code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized -Highlighting}.@refill - -@item @@defivar @var{class} @var{instance-variable-name} -@itemx @@defivarx @var{class} @var{instance-variable-name} -This command formats a description for an instance variable in -object-oriented programming. The command is equivalent to @samp{@@defcv -@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defmac @var{macro-name} @var{arguments}@dots{} -@itemx @@defmacx @var{macro-name} @var{arguments}@dots{} -Format a description for a macro. The command is equivalent to -@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} -Format a description for a method in object-oriented programming. The -command is equivalent to @samp{@@defop Method @dots{}}. Takes as -arguments the name of the class of the method, the name of the -method, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} -Format a description for an operation in object-oriented programming. -@code{@@defop} takes as arguments the overall name of the category of -operation, the name of the class of the operation, the name of the -operation, and its arguments, if any. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@defopt @var{option-name} -@itemx @@defoptx @var{option-name} -Format a description for a user option. The command is equivalent to -@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defspec @var{special-form-name} @var{arguments}@dots{} -@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} -Format a description for a special form. The command is equivalent to -@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} -Format a description for a data type. @code{@@deftp} takes as arguments -the category, the name of the type (which is a word like @samp{int} or -@samp{float}), and then the names of attributes of objects of that type. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a function or similar entity that may take -arguments and that is typed. @code{@@deftypefn} takes as arguments the -classification of entity being described, the type, the name of the -entity, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} -@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} -Format a description for a function in a typed language. -The command is equivalent to @samp{@@deftypefn Function @dots{}}. -@xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypevr @var{classification} @var{data-type} @var{name} -@itemx @@deftypevrx @var{classification} @var{data-type} @var{name} -Format a description for something like a variable in a typed -language---an entity that records a value. Takes as arguments the -classification of entity being described, the type, and the name of the -entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in -Detail}. - -@item @@deftypevar @var{data-type} @var{variable-name} -@itemx @@deftypevarx @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@defun @var{function-name} @var{arguments}@dots{} -@itemx @@defunx @var{function-name} @var{arguments}@dots{} -Format a description for functions. The command is equivalent to -@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvar @var{variable-name} -@itemx @@defvarx @var{variable-name} -Format a description for variables. The command is equivalent to -@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvr @var{category} @var{name} -@itemx @@defvrx @var{category} @var{name} -Format a description for any kind of variable. @code{@@defvr} takes -as arguments the category of the entity and the name of the entity. -@xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@detailmenu@{@} -Use to avoid Makeinfo confusion stemming from the detailed node listing -in a master menu. @xref{Master Menu Parts}. - -@item @@dfn@{@var{term}@} -Highlight the introductory or defining use of a term. -@xref{dfn, , @code{@@dfn}}.@refill - -@item @@dircategory @var{dirpart} -Specify a part of the Info directory menu where this file's entry should -go. @xref{Installing Dir Entries}. - -@item @@direntry -Begin the Info directory menu entry for this file. -@xref{Installing Dir Entries}. - -@need 100 -@item @@display -Begin a kind of example. Indent text, do not fill, do not select a -new font. Pair with @code{@@end display}. @xref{display, , -@code{@@display}}.@refill - -@item @@dmn@{@var{dimension}@} -Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a -thin space before @var{dimension}. No effect in Info. -@xref{dmn, , @code{@@dmn}}.@refill - -@need 100 -@item @@dots@{@} -Insert an ellipsis: @samp{@dots{}}. -@xref{dots, , @code{@@dots}}.@refill - -@item @@email@{@var{address}@} -Indicate an electronic mail address. -@xref{email, , @code{@@email}}.@refill - -@need 100 -@item @@emph@{@var{text}@} -Highlight @var{text}; text is displayed in @emph{italics} in printed -output, and surrounded by asterisks in Info. @xref{Emphasis, , Emphasizing Text}.@refill - -@item @@end @var{environment} -Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting -Commands,,@@-commands}. - -@item @@enddots@{@} -Generate an end-of-sentence of ellipsis, like this @enddots{} -@xref{dots,,@code{@@dots@{@}}}. - -@need 100 -@item @@enumerate [@var{number-or-letter}] -Begin a numbered list, using @code{@@item} for each entry. -Optionally, start list with @var{number-or-letter}. Pair with -@code{@@end enumerate}. @xref{enumerate, , -@code{@@enumerate}}.@refill - -@need 100 -@item @@equiv@{@} -Indicate to the reader the exact equivalence of two forms with a -glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill - -@item @@error@{@} -Indicate to the reader with a glyph that the following text is -an error message: @samp{@error{}}. @xref{Error Glyph}.@refill - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings for even-numbered (left-hand) pages. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page headings for even-numbered (left-hand) pages. Only -supported within @code{@@iftex}. @xref{Custom Headings, , How to Make -Your Own Headings}.@refill - -@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for every page. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@example -Begin an example. Indent text, do not fill, and select fixed-width font. -Pair with @code{@@end example}. @xref{example, , -@code{@@example}}.@refill - -@item @@exclamdown@{@} -Generate an upside-down exclamation point. @xref{Inserting Accents}. - -@item @@exdent @var{line-of-text} -Remove any indentation a line might have. @xref{exdent, , -Undoing the Indentation of a Line}.@refill - -@item @@expansion@{@} -Indicate the result of a macro expansion to the reader with a special -glyph: @samp{@expansion{}}. -@xref{expansion, , @expansion{} Indicating an Expansion}.@refill - -@item @@file@{@var{filename}@} -Highlight the name of a file, buffer, node, or directory. @xref{file, , -@code{@@file}}.@refill - -@item @@finalout -Prevent @TeX{} from printing large black warning rectangles beside -over-wide lines. @xref{Overfull hboxes}.@refill - -@need 100 -@item @@findex @var{entry} -Add @var{entry} to the index of functions. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@need 200 -@item @@flushleft -@itemx @@flushright -Left justify every line but leave the right end ragged. -Leave font as is. Pair with @code{@@end flushleft}. -@code{@@flushright} analogous. -@xref{flushleft & flushright, , @code{@@flushleft} and -@code{@@flushright}}.@refill - -@need 200 -@item @@footnote@{@var{text-of-footnote}@} -Enter a footnote. Footnote text is printed at the bottom of the page -by @TeX{}; Info may format in either `End' node or `Separate' node style. -@xref{Footnotes}.@refill - -@item @@footnotestyle @var{style} -Specify an Info file's footnote style, either @samp{end} for the end -node style or @samp{separate} for the separate node style. -@xref{Footnotes}.@refill - -@item @@format -Begin a kind of example. Like @code{@@example} or @code{@@display}, -but do not narrow the margins and do not select the fixed-width font. -Pair with @code{@@end format}. @xref{example, , -@code{@@example}}.@refill - -@item @@ftable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of functions. Pair with @code{@@end ftable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@item @@group -Hold text together that must appear on one printed page. Pair with -@code{@@end group}. Not relevant to Info. @xref{group, , -@code{@@group}}.@refill - -@item @@H@{@var{c}@} -Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. - -@item @@heading @var{title} -Print an unnumbered section-like heading in the text, but not in the -table of contents of a printed manual. In Info, the title is -underlined with equal signs. @xref{unnumberedsec appendixsec heading, -, Section Commands}.@refill - -@item @@headings @var{on-off-single-double} -Turn page headings on or off, and/or specify single-sided or double-sided -page headings for printing. @xref{headings on off, , The -@code{@@headings} Command}. - -@item @@i@{@var{text}@} -Print @var{text} in @i{italic} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@ifclear @var{flag} -If @var{flag} is cleared, the Texinfo formatting commands format text -between @code{@@ifclear @var{flag}} and the following @code{@@end -ifclear} command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@ifhtml -@itemx @@ifinfo -Begin a stretch of text that will be ignored by @TeX{} when it typesets -the printed manual. The text appears only in the HTML resp.@: Info -file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. -@xref{Conditionals, , Conditionally Visible Text}.@refill - -@item @@ifset @var{flag} -If @var{flag} is set, the Texinfo formatting commands format text -between @code{@@ifset @var{flag}} and the following @code{@@end ifset} -command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@iftex -Begin a stretch of text that will not appear in the Info file, but -will be processed only by @TeX{}. Pair with @code{@@end iftex}. -@xref{Conditionals, , Conditionally Visible Text}.@refill - -@item @@ignore -Begin a stretch of text that will not appear in either the Info file -or the printed output. Pair with @code{@@end ignore}. -@xref{Comments, , Comments and Ignored Text}.@refill - -@item @@include @var{filename} -Incorporate the contents of the file @var{filename} into the Info file -or printed document. @xref{Include Files}.@refill - -@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} -Make a cross reference to an Info file for which there is no printed -manual. @xref{inforef, , Cross references using -@code{@@inforef}}.@refill - -@item \input @var{macro-definitions-file} -Use the specified macro definitions file. This command is used only -in the first line of a Texinfo file to cause @TeX{} to make use of the -@file{texinfo} macro definitions file. The backslash in @code{\input} -is used instead of an @code{@@} because @TeX{} does not -recognize @code{@@} until after it has read the definitions file. -@xref{Header, , The Texinfo File Header}.@refill - -@item @@item -Indicate the beginning of a marked paragraph for @code{@@itemize} and -@code{@@enumerate}; indicate the beginning of the text of a first column -entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. -@xref{Lists and Tables}.@refill - -@item @@itemize @var{mark-generating-character-or-command} -Produce a sequence of indented paragraphs, with a mark inside the left -margin at the beginning of each paragraph. Pair with @code{@@end -itemize}. @xref{itemize, , @code{@@itemize}}.@refill - -@item @@itemx -Like @code{@@item} but do not generate extra vertical space above the -item text. @xref{itemx, , @code{@@itemx}}.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate text that is characters of input to be typed by -users. @xref{kbd, , @code{@@kbd}}.@refill - -@item @@key@{@var{key-name}@} -Highlight @var{key-name}, a name for a key on a keyboard. -@xref{key, , @code{@@key}}.@refill - -@item @@kindex @var{entry} -Add @var{entry} to the index of keys. @xref{Index Entries, , Defining the -Entries of an Index}.@refill - -@item @@L@{@} -@itemx @@l@{@} -Generate the uppercase and lowercase Polish suppressed-L letters, -respectively: @L{}, @l{}. - -@c Possibly this can be tossed now that we have macros. --karl, 16sep96. -@item @@global@@let@var{new-command}=@var{existing-command} -Equate a new highlighting command with an existing one. Only for -@TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end -iftex}. @xref{Customized Highlighting}.@refill - -@item @@lisp -Begin an example of Lisp code. Indent text, do not fill, and select -fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, , -@code{@@lisp}}.@refill - -@item @@lowersections -Change subsequent chapters to sections, sections to subsections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@item @@macro @var{macro-name} @{@var{params}@} -Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}. -Only supported by Makeinfo and Texi2dvi. @xref{Defining Macros}. - -@item @@majorheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. Generate more vertical whitespace before -the heading than the @code{@@chapheading} command. In Info, the chapter -heading line is underlined with asterisks. @xref{majorheading & -chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. -@xref{math, , @code{@@math}: Inserting Mathematical Expressions}. - -@item @@menu -Mark the beginning of a menu of nodes in Info. No effect in a printed -manual. Pair with @code{@@end menu}. @xref{Menus}.@refill - -@item @@minus@{@} -Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill - -@item @@multitable @var{column-width-spec} -Begin a multi-column table. Pair with @code{@@end multitable}. -@xref{Multitable Column Widths}. - -@item @@need @var{n} -Start a new page in a printed manual if fewer than @var{n} mils -(thousandths of an inch) remain on the current page. @xref{need, , -@code{@@need}}.@refill - -@item @@node @var{name, next, previous, up} -Define the beginning of a new node in Info, and serve as a locator for -references for @TeX{}. @xref{node, , @code{@@node}}.@refill - -@item @@noindent -Prevent text from being indented as if it were a new paragraph. -@xref{noindent, , @code{@@noindent}}.@refill - -@item @@O@{@} -@itemx @@o@{@} -Generate the uppercase and lowercase Owith-slash letters, respectively: -@O{}, @o{}. - -@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for odd-numbered (right-hand) -pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, , -How to Make Your Own Headings}.@refill - -@item @@OE@{@} -@itemx @@oe@{@} -Generate the uppercase and lowercase OE ligatures, respectively: -@OE{}, @oe{}. @xref{Inserting Accents}. - -@item @@page -Start a new page in a printed manual. No effect in Info. -@xref{page, , @code{@@page}}.@refill - -@item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces; delete indentation -if the value of @var{indent} is 0; and do not change indentation if -@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph -Indenting}.@refill - -@item @@pindex @var{entry} -Add @var{entry} to the index of programs. @xref{Index Entries, , Defining -the Entries of an Index}.@refill - -@item @@point@{@} -Indicate the position of point in a buffer to the reader with a -glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating -Point in a Buffer}.@refill - -@item @@pounds@{@} -Generate the pounds sterling currency sign. -@xref{pounds,,@code{@@pounds@{@}}}. - -@item @@print@{@} -Indicate printed output to the reader with a glyph: -@samp{@print{}}. @xref{Print Glyph}.@refill - -@item @@printindex @var{index-name} -Print an alphabetized two-column index in a printed manual or generate -an alphabetized menu of index entries for Info. @xref{Printing -Indices & Menus}.@refill - -@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with a lower case `see' in a printed -manual. Use within parentheses only. Do not follow command with a -punctuation mark---the Info formatting commands automatically insert -terminating punctuation as needed. Only the first argument is mandatory. -@xref{pxref, , @code{@@pxref}}.@refill - -@item @@questiondown@{@} -Generate an upside-down question mark. @xref{Inserting Accents}. - -@item @@quotation -Narrow the margins to indicate text that is quoted from another real -or imaginary work. Write command on a line of its own. Pair with -@code{@@end quotation}. @xref{quotation, , -@code{@@quotation}}.@refill - -@need 100 -@item @@r@{@var{text}@} -Print @var{text} in @r{roman} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@raisesections -Change subsequent sections to chapters, subsections to sections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@need 300 -@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference. In a printed manual, the reference does not start -with a `See'. Follow command with a punctuation mark. Only the first -argument is mandatory. @xref{ref, , @code{@@ref}}.@refill - -@need 300 -@item @@refill -In Info, refill and indent the paragraph after all the other processing -has been done. No effect on @TeX{}, which always refills. This command -is no longer needed, since all formatters now automatically refill. -@xref{Refilling Paragraphs}.@refill - -@need 300 -@item @@result@{@} -Indicate the result of an expression to the reader with a special -glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill - -@item @@ringaccent@{@var{c}@} -Generate a ring accent over the next character, as in @ringaccent{o}. -@xref{Inserting Accents}. - -@item @@samp@{@var{text}@} -Highlight @var{text} that is a literal example of a sequence of -characters. Used for single characters, for statements, and often for -entire shell commands. @xref{samp, , @code{@@samp}}.@refill - -@item @@sc@{@var{text}@} -Set @var{text} in a printed output in @sc{the small caps font} and -set text in the Info file in uppercase letters. -@xref{Smallcaps}.@refill - -@item @@section @var{title} -Begin a section within a chapter. In a printed manual, the section -title is numbered and appears in the table of contents. In Info, the -title is underlined with equal signs. @xref{section, , -@code{@@section}}.@refill - -@item @@set @var{flag} [@var{string}] -Make @var{flag} active, causing the Texinfo formatting commands to -format text between subsequent pairs of @code{@@ifset @var{flag}} and -@code{@@end ifset} commands. Optionally, set value of @var{flag} to -@var{string}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@setchapternewpage @var{on-off-odd} -Specify whether chapters start on new pages, and if so, whether on -odd-numbered (right-hand) new pages. @xref{setchapternewpage, , -@code{@@setchapternewpage}}.@refill - -@item @@setfilename @var{info-file-name} -Provide a name to be used by the Info file. This command is essential -for @TeX{} formatting as well, even though it produces no output. -@xref{setfilename, , @code{@@setfilename}}.@refill - -@item @@settitle @var{title} -Provide a title for page headers in a printed manual. -@xref{settitle, , @code{@@settitle}}.@refill - -@item @@shortcontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@summarycontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@shorttitlepage@{@var{title}@} -Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. - -@need 400 -@item @@smallbook -Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format. @xref{smallbook, , -Printing Small Books}. Also, see @ref{smallexample & smalllisp, , -@code{@@smallexample} and @code{@@smalllisp}}.@refill - -@need 400 -@item @@smallexample -Indent text to indicate an example. Do not fill, select fixed-width -font. In @code{@@smallbook} format, print text in a smaller font than -with @code{@@example}. Pair with @code{@@end smallexample}. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}.@refill - -@need 400 -@item @@smalllisp -Begin an example of Lisp code. Indent text, do not fill, select -fixed-width font. In @code{@@smallbook} format, print text in a -smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & -smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill - -@need 700 -@item @@sp @var{n} -Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill - -@item @@ss@{@} -Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. - -@need 700 -@item @@strong @var{text} -Emphasize @var{text} by typesetting it in a @strong{bold} font for the -printed manual and by surrounding it with asterisks for Info. -@xref{emph & strong, , Emphasizing Text}.@refill - -@item @@subheading @var{title} -Print an unnumbered subsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@subsection @var{title} -Begin a subsection within a section. In a printed manual, the -subsection title is numbered and appears in the table of contents. In -Info, the title is underlined with hyphens. @xref{subsection, , -@code{@@subsection}}.@refill - -@item @@subsubheading @var{title} -Print an unnumbered subsubsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with periods. @xref{subsubsection, , The `subsub' -Commands}.@refill - -@item @@subsubsection @var{title} -Begin a subsubsection within a subsection. In a printed manual, -the subsubsection title is numbered and appears in the table of -contents. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@subtitle @var{title} -In a printed manual, set a subtitle in a normal sized font flush to -the right-hand side of the page. Not relevant to Info, which does not -have title pages. @xref{title subtitle author, , @code{@@title} -@code{@@subtitle} and @code{@@author} Commands}.@refill - -@item @@summarycontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@shortcontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@need 300 -@item @@syncodeindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument, printing the entries from the first index in -@code{@@code} font. @xref{Combining Indices}.@refill - -@need 300 -@item @@synindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument. Do not change the font of @var{from-index} -entries. @xref{Combining Indices}.@refill - -@need 100 -@item @@t@{@var{text}@} -Print @var{text} in a @t{fixed-width}, typewriter-like font. -No effect in Info. @xref{Fonts}.@refill - -@item @@tab -Separate columns in a multitable. @xref{Multitable Rows}. - -@need 400 -@item @@table @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. Write -each first column entry on the same line as @code{@@item}. First -column entries are printed in the font resulting from -@var{formatting-command}. Pair with @code{@@end table}. -@xref{Two-column Tables, , Making a Two-column Table}. -Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, -and @ref{itemx, , @code{@@itemx}}.@refill - -@item @@TeX@{@} -Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{} -and @copyright{}}.@refill - -@item @@tex -Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Using -Ordinary TeX Commands, , Using Ordinary @TeX{} Commands}.@refill - -@item @@thischapter -@itemx @@thischaptername -@itemx @@thisfile -@itemx @@thispage -@itemx @@thistitle -Only allowed in a heading or footing. Stands for the number and name of -the current chapter (in the format `Chapter 1: Title'), the chapter name -only, the filename, the current page number, and the title of the -document, respectively. @xref{Custom Headings, , How to Make Your Own -Headings}.@refill - -@item @@tindex @var{entry} -Add @var{entry} to the index of data types. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@title @var{title} -In a printed manual, set a title flush to the left-hand side of the -page in a larger than normal font and underline it with a black rule. -Not relevant to Info, which does not have title pages. @xref{title -subtitle author, , The @code{@@title} @code{@@subtitle} and -@code{@@author} Commands}.@refill - -@need 400 -@item @@titlefont@{@var{text}@} -In a printed manual, print @var{text} in a larger than normal font. -Not relevant to Info, which does not have title pages. -@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} -and @code{@@sp} Commands}.@refill - -@need 300 -@item @@titlepage -Indicate to Texinfo the beginning of the title page. Write command on -a line of its own. Pair with @code{@@end titlepage}. Nothing between -@code{@@titlepage} and @code{@@end titlepage} appears in Info. -@xref{titlepage, , @code{@@titlepage}}.@refill - -@need 150 -@item @@today@{@} -Insert the current date, in `1 Jan 1900' style. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@top @var{title} -In a Texinfo file to be formatted with @code{makeinfo}, identify the -topmost @code{@@node} line in the file, which must be written on the line -immediately preceding the @code{@@top} command. Used for -@code{makeinfo}'s node pointer insertion feature. The title is -underlined with asterisks. Both the @code{@@node} line and the @code{@@top} -line normally should be enclosed by @code{@@ifinfo} and @code{@@end -ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo -Pointer Creation, , Creating Pointers with @code{makeinfo}}. - -@item @@u@var{c} -@itemx @@ubaraccent@var{c} -@itemx @@udotaccent@var{c} -Generate a breve, underbar, or underdot accent, respectively, over or -under the character @var{c}, as in @u{o}, @ubaraccent{o}, -@udotaccent{o}. @xref{Inserting Accents}. - -@item @@unnumbered @var{title} -In a printed manual, begin a chapter that appears without chapter -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with asterisks. -@xref{unnumbered & appendix, , @code{@@unnumbered} and -@code{@@appendix}}.@refill - -@item @@unnumberedsec @var{title} -In a printed manual, begin a section that appears without section -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with equal signs. -@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill - -@item @@unnumberedsubsec @var{title} -In a printed manual, begin an unnumbered subsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with hyphens. -@xref{unnumberedsubsec appendixsubsec subheading, , -@code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@unnumberedsubsubsec @var{title} -In a printed manual, begin an unnumbered subsubsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@url@{@var{url}@} -Highlight text that is a uniform resource locator for the World Wide -Web. @xref{url, , @code{@@url}}.@refill - -@item @@v@var{c} -Generate check accent over the character @var{c}, as in @v{o}. -@xref{Inserting Accents}. - -@item @@value@{@var{flag}@} -Replace @var{flag} with the value to which it is set by @code{@@set -@var{flag}}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Highlight a metasyntactic variable, which is something that stands for -another piece of text. @xref{var, , Indicating Metasyntactic -Variables}.@refill - -@need 400 -@item @@vindex @var{entry} -Add @var{entry} to the index of variables. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@need 400 -@item @@vskip @var{amount} -In a printed manual, insert whitespace so as to push text on the -remainder of the page towards the bottom of the page. Used in -formatting the copyright page with the argument @samp{0pt plus -1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used -only in contexts ignored for Info. @xref{Copyright & Permissions, , -The Copyright Page and Printed Permissions}.@refill - -@need 400 -@item @@vtable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of variables. Pair with @code{@@end vtable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@need 400 -@item @@w@{@var{text}@} -Prevent @var{text} from being split across two lines. Do not end a -paragraph that uses @code{@@w} with an @code{@@refill} command. -@xref{w, , @code{@@w}}.@refill - -@need 400 -@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with `See' in a printed manual. Follow -command with a punctuation mark. Only the first argument is -mandatory. @xref{xref, , @code{@@xref}}.@refill -@end table - -@node Tips, Sample Texinfo File, Command List, Top -@comment node-name, next, previous, up -@appendix Tips and Hints - -Here are some tips for writing Texinfo documentation:@refill - -@cindex Tips -@cindex Usage tips -@cindex Hints -@itemize @bullet -@item -Write in the present tense, not in the past or the future. - -@item -Write actively! For example, write ``We recommend that @dots{}'' rather -than ``It is recommended that @dots{}''. - -@item -Use 70 or 72 as your fill column. Longer lines are hard to read. - -@item -Include a copyright notice and copying permissions. -@end itemize - -@subsubheading Index, index, index! - -Write many index entries, in different ways. -Readers like indices; they are helpful and convenient. - -Although it is easiest to write index entries as you write the body of -the text, some people prefer to write entries afterwards. In either -case, write an entry before the paragraph to which it applies. This -way, an index entry points to the first page of a paragraph that is -split across pages. - -Here are more hints we have found valuable: - -@itemize @bullet -@item -Write each index entry differently, so each entry refers to a different -place in the document. - -@item -Write index entries only where a topic is discussed significantly. For -example, it is not useful to index ``debugging information'' in a -chapter on reporting bugs. Someone who wants to know about debugging -information will certainly not find it in that chapter. - -@item -Consistently capitalize the first word of every concept index entry, -or else consistently use lower case. Terse entries often call for -lower case; longer entries for capitalization. Whichever case -convention you use, please use one or the other consistently! Mixing -the two styles looks bad. - -@item -Always capitalize or use upper case for those words in an index for -which this is proper, such as names of countries or acronyms. Always -use the appropriate case for case-sensitive names, such as those in C or -Lisp. - -@item -Write the indexing commands that refer to a whole section immediately -after the section command, and write the indexing commands that refer to -the paragraph before the paragraph. - -@need 1000 -In the example that follows, a blank line comes after the index -entry for ``Leaping'': - -@example -@group -@@section The Dog and the Fox -@@cindex Jumping, in general -@@cindex Leaping - -@@cindex Dog, lazy, jumped over -@@cindex Lazy dog jumped over -@@cindex Fox, jumps over dog -@@cindex Quick fox jumps over dog -The quick brown fox jumps over the lazy dog. -@end group -@end example - -@noindent -(Note that the example shows entries for the same concept that are -written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so -readers can look up the concept in different ways.) -@end itemize - -@subsubheading Blank lines - -@itemize @bullet -@item -Insert a blank line between a sectioning command and the first following -sentence or paragraph, or between the indexing commands associated with -the sectioning command and the first following sentence or paragraph, as -shown in the tip on indexing. Otherwise, a formatter may fold title and -paragraph together. - -@item -Always insert a blank line before an @code{@@table} command and after an -@code{@@end table} command; but never insert a blank line after an -@code{@@table} command or before an @code{@@end table} command. - -@need 1000 -For example, - -@example -@group -Types of fox: - -@@table @@samp -@@item Quick -Jump over lazy dogs. -@end group - -@group -@@item Brown -Also jump over lazy dogs. -@@end table - -@end group -@group -@@noindent -On the other hand, @dots{} -@end group -@end example - -Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end -itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the -same way. -@end itemize - -@subsubheading Complete phrases - -Complete phrases are easier to read than @dots{} - -@itemize @bullet -@item -Write entries in an itemized list as complete sentences; or at least, as -complete phrases. Incomplete expressions @dots{} awkward @dots{} like -this. - -@item -Write the prefatory sentence or phrase for a multi-item list or table as -a complete expression. Do not write ``You can set:''; instead, write -``You can set these variables:''. The former expression sounds cut off. -@end itemize - -@subsubheading Editions, dates and versions - -Write the edition and version numbers and date in three places in every -manual: - -@enumerate -@item -In the first @code{@@ifinfo} section, for people reading the Texinfo file. - -@item -In the @code{@@titlepage} section, for people reading the printed manual. - -@item -In the `Top' node, for people reading the Info file. -@end enumerate - -@noindent -Also, it helps to write a note before the first @code{@@ifinfo} -section to explain what you are doing. - -@need 800 -@noindent -For example: - -@example -@group -@@c ===> NOTE! <== -@@c Specify the edition and version numbers and date -@@c in *three* places: -@@c 1. First ifinfo section 2. title page 3. top node -@@c To find the locations, search for !!set -@end group - -@group -@@ifinfo -@@c !!set edition, date, version -This is Edition 4.03, January 1992, -of the @@cite@{GDB Manual@} for GDB Version 4.3. -@dots{} -@end group -@end example - -@noindent ----or use @code{@@set} and @code{@@value} -(@pxref{value Example, , @code{@@value} Example}). - -@subsubheading Definition Commands - -Definition commands are @code{@@deffn}, @code{@@defun}, -@code{@@defmac}, and the like, and enable you to write descriptions in -a uniform format.@refill - -@itemize @bullet -@item -Write just one definition command for each entity you define with a -definition command. The automatic indexing feature creates an index -entry that leads the reader to the definition. - -@item -Use @code{@@table} @dots{} @code{@@end table} in an appendix that -contains a summary of functions, not @code{@@deffn} or other definition -commands. -@end itemize - -@subsubheading Capitalization - -@itemize @bullet -@item -Capitalize @samp{Texinfo}; it is a name. Do not write the @samp{x} or -@samp{i} in upper case. - -@item -Capitalize @samp{Info}; it is a name. - -@item -Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase -@samp{T} and @samp{X}. This command causes the formatters to -typeset the name according to the wishes of Donald Knuth, who wrote -@TeX{}. -@end itemize - -@subsubheading Spaces - -Do not use spaces to format a Texinfo file, except inside of -@code{@@example} @dots{} @code{@@end example} and similar commands. - -@need 700 -For example, @TeX{} fills the following: - -@example -@group - @@kbd@{C-x v@} - @@kbd@{M-x vc-next-action@} - Perform the next logical operation - on the version-controlled file - corresponding to the current buffer. -@end group -@end example - -@need 950 -@noindent -so it looks like this: - -@iftex -@quotation - @kbd{C-x v} - @kbd{M-x vc-next-action} - Perform the next logical operation on the version-controlled file - corresponding to the current buffer. -@end quotation -@end iftex -@ifinfo -@quotation -`C-x v' `M-x vc-next-action' Perform the next logical operation on the -version-controlled file corresponding to the current buffer. -@end quotation -@end ifinfo - -@noindent -In this case, the text should be formatted with -@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. - -@subsubheading @@code, @@samp, @@var, and @samp{---} - -@itemize @bullet -@item -Use @code{@@code} around Lisp symbols, including command names. -For example, - -@example -The main function is @@code@{vc-next-action@}, @dots{} -@end example - -@item -Avoid putting letters such as @samp{s} immediately after an -@samp{@@code}. Such letters look bad. - -@item -Use @code{@@var} around meta-variables. Do not write angle brackets -around them. - -@item -Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} -typesets these as a long dash and the Info formatters reduce three -hyphens to two. -@end itemize - -@subsubheading Periods Outside of Quotes - -Place periods and other punctuation marks @emph{outside} of quotations, -unless the punctuation is part of the quotation. This practice goes -against publishing conventions in the United States, but enables the -reader to distinguish between the contents of the quotation and the -whole passage. - -For example, you should write the following sentence with the period -outside the end quotation marks: - -@example -Evidently, @samp{au} is an abbreviation for ``author''. -@end example - -@noindent -since @samp{au} does @emph{not} serve as an abbreviation for -@samp{author.} (with a period following the word). - -@subsubheading Introducing New Terms - -@itemize @bullet -@item -Introduce new terms so that a reader who does not know them can -understand them from context; or write a definition for the term. - -For example, in the following, the terms ``check in'', ``register'' and -``delta'' are all appearing for the first time; the example sentence should be -rewritten so they are understandable. - -@quotation -The major function assists you in checking in a file to your -version control system and registering successive sets of changes to -it as deltas. -@end quotation - -@item -Use the @code{@@dfn} command around a word being introduced, to indicate -that the reader should not expect to know the meaning already, and -should expect to learn the meaning from this passage. -@end itemize - -@subsubheading @@pxref - -@c !!! maybe include this in the tips on pxref -@ignore -By the way, it is okay to use pxref with something else in front of -it within the parens, as long as the pxref is followed by the close -paren, and the material inside the parens is not part of a larger -sentence. Also, you can use xref inside parens as part of a complete -sentence so long as you terminate the cross reference with punctuation. -@end ignore -Absolutely never use @code{@@pxref} except in the special context for -which it is designed: inside parentheses, with the closing parenthesis -following immediately after the closing brace. One formatter -automatically inserts closing punctuation and the other does not. This -means that the output looks right both in printed output and in an Info -file, but only when the command is used inside parentheses. - -@subsubheading Invoking from a Shell - -You can invoke programs such as Emacs, GCC, and GAWK from a shell. -The documentation for each program should contain a section that -describes this. Unfortunately, if the node names and titles for these -sections are all different, readers find it hard to search for the -section.@refill - -Name such sections with a phrase beginning with the word -@w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way -users can find the section easily. - -@subsubheading @sc{ansi c} Syntax - -When you use @code{@@example} to describe a C function's calling -conventions, use the @sc{ansi c} syntax, like this:@refill - -@example -void dld_init (char *@@var@{path@}); -@end example - -@noindent -And in the subsequent discussion, refer to the argument values by -writing the same argument names, again highlighted with -@code{@@var}.@refill - -@need 800 -Avoid the obsolete style that looks like this:@refill - -@example -#include <dld.h> - -dld_init (path) -char *path; -@end example - -Also, it is best to avoid writing @code{#include} above the -declaration just to indicate that the function is declared in a -header file. The practice may give the misimpression that the -@code{#include} belongs near the declaration of the function. Either -state explicitly which header file holds the declaration or, better -yet, name the header file used for a group of functions at the -beginning of the section that describes the functions.@refill - -@subsubheading Bad Examples - -Here are several examples of bad writing to avoid: - -In this example, say, `` @dots{} you must @code{@@dfn}@{check -in@} the new version.'' That flows better. - -@quotation -When you are done editing the file, you must perform a -@code{@@dfn}@{check in@}. -@end quotation - -In the following example, say, ``@dots{} makes a unified interface such as VC -mode possible.'' - -@quotation -SCCS, RCS and other version-control systems all perform similar -functions in broadly similar ways (it is this resemblance which makes -a unified control mode like this possible). -@end quotation - -And in this example, you should specify what `it' refers to: - -@quotation -If you are working with other people, it assists in coordinating -everyone's changes so they do not step on each other. -@end quotation - -@subsubheading And Finally @dots{} - -@itemize @bullet -@item -Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last -sound in the name `Bach'. But pronounce Texinfo as in `speck': -@samp{teckinfo}. - -@item -Write notes for yourself at the very end of a Texinfo file after the -@code{@@bye}. None of the formatters process text after the -@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} -@code{@@end ignore}. -@end itemize - -@node Sample Texinfo File, Sample Permissions, Tips, Top -@comment node-name, next, previous, up -@appendix A Sample Texinfo File -@cindex Sample Texinfo file, no comments - -Here is a complete, short sample Texinfo file, without any commentary. -You can see this file, with comments, in the first chapter. -@xref{Short Sample, , A Short Sample Texinfo File}. - -@sp 1 -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Document -@@c %**end of header - -@@setchapternewpage odd - -@@ifinfo -This is a short example of a complete Texinfo file. - -Copyright 1990 Free Software Foundation, Inc. -@@end ifinfo - -@@titlepage -@@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} - -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage - -@@node Top, First Chapter, (dir), (dir) -@@comment node-name, next, previous, up - -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Concept Index:: This index has two entries. -@@end menu - -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up -@@chapter First Chapter -@@cindex Sample index entry - -This is the contents of the first chapter. -@@cindex Another sample index entry - -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate - -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. - -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up -@@unnumbered Concept Index - -@@printindex cp - -@@contents -@@bye -@end example - -@node Sample Permissions, Include Files, Sample Texinfo File, Top -@appendix Sample Permissions -@cindex Permissions -@cindex Copying permissions - -Texinfo files should contain sections that tell the readers that they -have the right to copy and distribute the Texinfo file, the Info file, -and the printed manual.@refill - -Also, if you are writing a manual about software, you should explain -that the software is free and either include the GNU General Public -License (GPL) or provide a reference to it. @xref{Distrib, , -Distribution, emacs, The GNU Emacs Manual}, for an example of the text -that could be used in the software ``Distribution'', ``General Public -License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, -, Texinfo Copying Conditions}, for an example of a brief explanation -of how the copying conditions provide you with rights. @refill - -@menu -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. -@end menu - -@node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions -@ifinfo -@appendixsec Inserting Permissions -@end ifinfo - -In a Texinfo file, the first @code{@@ifinfo} section usually begins -with a line that says what the file documents. This is what a person -reading the unprocessed Texinfo file or using the advanced Info -command @kbd{g *} sees first. @inforef{Expert, Advanced Info -commands, info}, for more information. (A reader using the regular -Info commands usually starts reading at the first node and skips -this first section, which is not in a node.)@refill - -In the @code{@@ifinfo} section, the summary sentence is followed by a -copyright notice and then by the copying permission notice. One of -the copying permission paragraphs is enclosed in @code{@@ignore} and -@code{@@end ignore} commands. This paragraph states that the Texinfo -file can be processed through @TeX{} and printed, provided the printed -manual carries the proper copying permission notice. This paragraph -is not made part of the Info file since it is not relevant to the Info -file; but it is a mandatory part of the Texinfo file since it permits -people to process the Texinfo file in @TeX{} and print the -results.@refill - -In the printed manual, the Free Software Foundation copying permission -notice follows the copyright notice and publishing information and is -located within the region delineated by the @code{@@titlepage} and -@code{@@end titlepage} commands. The copying permission notice is exactly -the same as the notice in the @code{@@ifinfo} section except that the -paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is -not part of the notice.@refill - -To make it simple to insert a permission notice into each section of -the Texinfo file, sample permission notices for each section are -reproduced in full below.@refill - -Note that you may need to specify the correct name of a section -mentioned in the permission notice. For example, in @cite{The GDB -Manual}, the name of the section referring to the General Public -License is called the ``GDB General Public License'', but in the -sample shown below, that section is referred to generically as the -``GNU General Public License''. If the Texinfo file does not carry a -copy of the General Public License, leave out the reference to it, but -be sure to include the rest of the sentence.@refill - -@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions -@comment node-name, next, previous, up -@appendixsec @samp{ifinfo} Copying Permissions -@cindex @samp{ifinfo} permissions - -In the @code{@@ifinfo} section of a Texinfo file, the standard Free -Software Foundation permission notice reads as follows:@refill - -@example -This file documents @dots{} - -Copyright 1992 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -@@ignore -Permission is granted to process this file through TeX -and print the results, provided the printed document -carries a copying permission notice identical to this -one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@@end ignore -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and provided -that the entire resulting derived work is distributed -under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute -translations of this manual into another language, -under the above conditions for modified versions, -except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -@end example - -@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions -@comment node-name, next, previous, up -@appendixsec Titlepage Copying Permissions -@cindex Titlepage permissions - -In the @code{@@titlepage} section of a Texinfo file, the standard Free -Software Foundation copying permission notice follows the copyright -notice and publishing information. The standard phrasing is as -follows:@refill - -@example -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and provided -that the entire resulting derived work is distributed -under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute -translations of this manual into another language, -under the above conditions for modified versions, -except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -@end example - -@node Include Files, Headings, Sample Permissions, Top -@comment node-name, next, previous, up -@appendix Include Files -@cindex Include files - -When @TeX{} or an Info formatting command sees an @code{@@include} -command in a Texinfo file, it processes the contents of the file named -by the command and incorporates them into the @sc{dvi} or Info file being -created. Index entries from the included file are incorporated into -the indices of the output file.@refill - -Include files let you keep a single large document as a collection of -conveniently small parts.@refill - -@menu -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. -@end menu - -@node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files -@appendixsec How to Use Include Files -@findex include - -To include another file within a Texinfo file, write the -@code{@@include} command at the beginning of a line and follow it on -the same line by the name of a file to be included. For -example:@refill - -@example -@@include buffers.texi -@end example - -An included file should simply be a segment of text that you expect to -be included as is into the overall or @dfn{outer} Texinfo file; it -should not contain the standard beginning and end parts of a Texinfo -file. In particular, you should not start an included file with a -line saying @samp{\input texinfo}; if you do, that phrase is inserted -into the output file as is. Likewise, you should not end an included -file with an @code{@@bye} command; nothing after @code{@@bye} is -formatted.@refill - -In the past, you were required to write an @code{@@setfilename} line at the -beginning of an included file, but no longer. Now, it does not matter -whether you write such a line. If an @code{@@setfilename} line exists -in an included file, it is ignored.@refill - -Conventionally, an included file begins with an @code{@@node} line that -is followed by an @code{@@chapter} line. Each included file is one -chapter. This makes it easy to use the regular node and menu creating -and updating commands to create the node pointers and menus within the -included file. However, the simple Emacs node and menu creating and -updating commands do not work with multiple Texinfo files. Thus you -cannot use these commands to fill in the `Next', `Previous', and `Up' -pointers of the @code{@@node} line that begins the included file. Also, -you cannot use the regular commands to create a master menu for the -whole file. Either you must insert the menus and the `Next', -`Previous', and `Up' pointers by hand, or you must use the GNU Emacs -Texinfo mode command, @code{texinfo-multiple-files-update}, that is -designed for @code{@@include} files.@refill - -@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files -@appendixsec @code{texinfo-multiple-files-update} -@findex texinfo-multiple-files-update - -GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} -command. This command creates or updates `Next', `Previous', and `Up' -pointers of included files as well as those in the outer or overall -Texinfo file, and it creates or updates a main menu in the outer file. -Depending whether you call it with optional arguments, the command -updates only the pointers in the first @code{@@node} line of the -included files or all of them:@refill - -@table @kbd -@item M-x texinfo-multiple-files-update -Called without any arguments:@refill - -@itemize @minus -@item -Create or update the `Next', `Previous', and `Up' pointers of the -first @code{@@node} line in each file included in an outer or overall -Texinfo file.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -Create or update a main menu in the outer file.@refill -@end itemize - -@item C-u M-x texinfo-multiple-files-update -Called with @kbd{C-u} as a prefix argument: - -@itemize @minus{} -@item -Create or update pointers in the first @code{@@node} line in each -included file. - -@item -Create or update the `Top' level node pointers of the outer file. - -@item -Create and insert a master menu in the outer file. The master menu -is made from all the menus in all the included files.@refill -@end itemize - -@item C-u 8 M-x texinfo-multiple-files-update -Called with a numeric prefix argument, such as @kbd{C-u 8}: - -@itemize @minus -@item -Create or update @strong{all} the `Next', `Previous', and `Up' pointers -of all the included files.@refill - -@item -Create or update @strong{all} the menus of all the included -files.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -And then create a master menu in the outer file. This is similar to -invoking @code{texinfo-master-menu} with an argument when you are -working with just one file.@refill -@end itemize -@end table - -Note the use of the prefix argument in interactive use: with a regular -prefix argument, just @w{@kbd{C-u}}, the -@code{texinfo-multiple-files-update} command inserts a master menu; -with a numeric prefix argument, such as @kbd{C-u 8}, the command -updates @strong{every} pointer and menu in @strong{all} the files and then inserts a -master menu.@refill - -@node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files -@appendixsec Include File Requirements -@cindex Include file requirements -@cindex Requirements for include files - -If you plan to use the @code{texinfo-multiple-files-update} command, -the outer Texinfo file that lists included files within it should -contain nothing but the beginning and end parts of a Texinfo file, and -a number of @code{@@include} commands listing the included files. It -should not even include indices, which should be listed in an included -file of their own.@refill - -Moreover, each of the included files must contain exactly one highest -level node (conventionally, @code{@@chapter} or equivalent), -and this node must be the first node in the included file. -Furthermore, each of these highest level nodes in each included file -must be at the same hierarchical level in the file structure. -Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an -@code{@@unnumbered} node. Thus, normally, each included file contains -one, and only one, chapter or equivalent-level node.@refill - -The outer file should contain only @emph{one} node, the `Top' node. It -should @emph{not} contain any nodes besides the single `Top' node. The -@code{texinfo-multiple-files-update} command will not process -them.@refill - -@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files -@appendixsec Sample File with @code{@@include} -@cindex Sample @code{@@include} file -@cindex Include file sample -@cindex @code{@@include} file sample - -Here is an example of a complete outer Texinfo file with @code{@@include} files -within it before running @code{texinfo-multiple-files-update}, which -would insert a main or master menu:@refill - -@example -@group -\input texinfo @@c -*-texinfo-*- -@c %**start of header -@@setfilename include-example.info -@@settitle Include Example -@c %**end of header -@end group - -@group -@@setchapternewpage odd -@@titlepage -@@sp 12 -@@center @@titlefont@{Include Example@} -@@sp 2 -@@center by Whom Ever -@end group - -@group -@@page -@@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. -@@end titlepage -@end group - -@group -@@ifinfo -@@node Top, First, (dir), (dir) -@@top Master Menu -@@end ifinfo -@end group - -@group -@@include foo.texinfo -@@include bar.texinfo -@@include concept-index.texinfo -@end group - -@group -@@summarycontents -@@contents - -@@bye -@end group -@end example - -An included file, such as @file{foo.texinfo}, might look like -this:@refill - -@example -@group -@@node First, Second, , Top -@@chapter First Chapter - -Contents of first chapter @dots{} -@end group -@end example - -The full contents of @file{concept-index.texinfo} might be as simple as this: - -@example -@group -@@node Concept Index, , Second, Top -@@unnumbered Concept Index - -@@printindex cp -@end group -@end example - -The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference -Manual} is named @file{elisp.texi}. This outer file contains a master -menu with 417 entries and a list of 41 @code{@@include} -files.@refill - -@node Include Files Evolution, , Sample Include File, Include Files -@comment node-name, next, previous, up -@appendixsec Evolution of Include Files - -When Info was first created, it was customary to create many small -Info files on one subject. Each Info file was formatted from its own -Texinfo source file. This custom meant that Emacs did not need to -make a large buffer to hold the whole of a large Info file when -someone wanted information; instead, Emacs allocated just enough -memory for the small Info file that contained the particular -information sought. This way, Emacs could avoid wasting memory.@refill - -References from one file to another were made by referring to the file -name as well as the node name. (@xref{Other Info Files, , Referring to -Other Info Files}. Also, see @ref{Four and Five Arguments, , -@code{@@xref} with Four and Five Arguments}.)@refill - -Include files were designed primarily as a way to create a single, -large printed manual out of several smaller Info files. In a printed -manual, all the references were within the same document, so @TeX{} -could automatically determine the references' page numbers. The Info -formatting commands used include files only for creating joint -indices; each of the individual Texinfo files had to be formatted for -Info individually. (Each, therefore, required its own -@code{@@setfilename} line.)@refill - -However, because large Info files are now split automatically, it is -no longer necessary to keep them small.@refill - -Nowadays, multiple Texinfo files are used mostly for large documents, -such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects -in which several different people write different sections of a -document simultaneously.@refill - -In addition, the Info formatting commands have been extended to work -with the @code{@@include} command so as to create a single large Info -file that is split into smaller files if necessary. This means that -you can write menus and cross references without naming the different -Texinfo files.@refill - -@node Headings, Catching Mistakes, Include Files, Top -@comment node-name, next, previous, up -@appendix Page Headings -@cindex Headings -@cindex Footings -@cindex Page numbering -@cindex Page headings -@cindex Formatting headings and footings - -Most printed manuals contain headings along the top of every page -except the title and copyright pages. Some manuals also contain -footings. (Headings and footings have no meaning to Info, which is -not paginated.)@refill - -@menu -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. -@end menu - -@node Headings Introduced, Heading Format, Headings, Headings -@ifinfo -@heading Headings Introduced -@end ifinfo - -Texinfo provides standard page heading formats for manuals that are printed -on one side of each sheet of paper and for manuals that are printed on -both sides of the paper. Usually, you will use one or other of these -formats, but you can specify your own format, if you wish.@refill - -In addition, you can specify whether chapters should begin on a new -page, or merely continue the same page as the previous chapter; and if -chapters begin on new pages, you can specify whether they must be -odd-numbered pages.@refill - -By convention, a book is printed on both sides of each sheet of paper. -When you open a book, the right-hand page is odd-numbered, and -chapters begin on right-hand pages---a preceding left-hand page is -left blank if necessary. Reports, however, are often printed on just -one side of paper, and chapters begin on a fresh page immediately -following the end of the preceding chapter. In short or informal -reports, chapters often do not begin on a new page at all, but are -separated from the preceding text by a small amount of whitespace.@refill - -The @code{@@setchapternewpage} command controls whether chapters begin -on new pages, and whether one of the standard heading formats is used. -In addition, Texinfo has several heading and footing commands that you -can use to generate your own heading and footing formats.@refill - -In Texinfo, headings and footings are single lines at the tops and -bottoms of pages; you cannot create multiline headings or footings. -Each header or footer line is divided into three parts: a left part, a -middle part, and a right part. Any part, or a whole line, may be left -blank. Text for the left part of a header or footer line is set -flushleft; text for the middle part is centered; and, text for the -right part is set flushright.@refill - -@node Heading Format, Heading Choice, Headings Introduced, Headings -@comment node-name, next, previous, up -@appendixsec Standard Heading Formats - -Texinfo provides two standard heading formats, one for manuals printed -on one side of each sheet of paper, and the other for manuals printed -on both sides of the paper. - -By default, nothing is specified for the footing of a Texinfo file, -so the footing remains blank.@refill - -The standard format for single-sided printing consists of a header -line in which the left-hand part contains the name of the chapter, the -central part is blank, and the right-hand part contains the page -number.@refill - -@need 950 -A single-sided page looks like this: - -@example -@group - _______________________ - | | - | chapter page number | - | | - | Start of text ... | - | ... | - | | - -@end group -@end example - -The standard format for two-sided printing depends on whether the page -number is even or odd. By convention, even-numbered pages are on the -left- and odd-numbered pages are on the right. (@TeX{} will adjust the -widths of the left- and right-hand margins. Usually, widths are -correct, but during double-sided printing, it is wise to check that -pages will bind properly---sometimes a printer will produce output in -which the even-numbered pages have a larger right-hand margin than the -odd-numbered pages.)@refill - -In the standard double-sided format, the left part of the left-hand -(even-numbered) page contains the page number, the central part is -blank, and the right part contains the title (specified by the -@code{@@settitle} command). The left part of the right-hand -(odd-numbered) page contains the name of the chapter, the central part -is blank, and the right part contains the page number.@refill - -@need 750 -Two pages, side by side as in an open book, look like this:@refill - -@example -@group - _______________________ _______________________ - | | | | - | page number title | | chapter page number | - | | | | - | Start of text ... | | More text ... | - | ... | | ... | - | | | | - -@end group -@end example - -@noindent -The chapter name is preceded by the word @samp{Chapter}, the chapter -number and a colon. This makes it easier to keep track of where you -are in the manual.@refill - -@node Heading Choice, Custom Headings, Heading Format, Headings -@comment node-name, next, previous, up -@appendixsec Specifying the Type of Heading - -@TeX{} does not begin to generate page headings for a standard Texinfo -file until it reaches the @code{@@end titlepage} command. Thus, the -title and copyright pages are not numbered. The @code{@@end -titlepage} command causes @TeX{} to begin to generate page headings -according to a standard format specified by the -@code{@@setchapternewpage} command that precedes the -@code{@@titlepage} section.@refill - -@need 1000 -There are four possibilities:@refill - -@table @asis -@item No @code{@@setchapternewpage} command -Cause @TeX{} to specify the single-sided heading format, with chapters -on new pages. This is the same as @code{@@setchapternewpage on}.@refill - -@item @code{@@setchapternewpage on} -Specify the single-sided heading format, with chapters on new pages.@refill - -@item @code{@@setchapternewpage off} -Cause @TeX{} to start a new chapter on the same page as the last page of -the preceding chapter, after skipping some vertical whitespace. Also -cause @TeX{} to typeset for single-sided printing. (You can override -the headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage odd} -Specify the double-sided heading format, with chapters on new pages.@refill -@end table - -@noindent -Texinfo lacks an @code{@@setchapternewpage even} command.@refill - -@node Custom Headings, , Heading Choice, Headings -@comment node-name, next, previous, up -@appendixsec How to Make Your Own Headings - -You can use the standard headings provided with Texinfo or specify -your own.@refill - -@c Following paragraph is verbose to prevent overfull hboxes. -Texinfo provides six commands for specifying headings and -footings. The @code{@@everyheading} command and -@code{@@everyfooting} command generate page headers and footers -that are the same for both even- and odd-numbered pages. -The @code{@@evenheading} command and @code{@@evenfooting} -command generate headers and footers for even-numbered -(left-hand) pages; and the @code{@@oddheading} command and -@code{@@oddfooting} command generate headers and footers for -odd-numbered (right-hand) pages.@refill - -Write custom heading specifications in the Texinfo file immediately -after the @code{@@end titlepage} command. Enclose your specifications -between @code{@@iftex} and @code{@@end iftex} commands since the -@code{texinfo-format-buffer} command may not recognize them. Also, -you must cancel the predefined heading commands with the -@code{@@headings off} command before defining your own -specifications.@refill - -@need 1000 -Here is how to tell @TeX{} to place the chapter name at the left, the -page number in the center, and the date at the right of every header -for both even- and odd-numbered pages:@refill - -@example -@group -@@iftex -@@headings off -@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} -@@end iftex -@end group -@end example - -@noindent -You need to divide the left part from the central part and the central -part from the right had part by inserting @samp{@@|} between parts. -Otherwise, the specification command will not be able to tell where -the text for one part ends and the next part begins.@refill - -Each part can contain text or @@-commands. The text -is printed as if the part were within an ordinary paragraph in the -body of the page. The @@-commands replace -themselves with the page number, date, chapter name, or -whatever.@refill - -@need 950 -Here are the six heading and footing commands:@refill - -@findex everyheading -@findex everyfooting -@table @code -@item @@everyheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} - -The `every' commands specify the format for both even- and odd-numbered -pages. These commands are for documents that are printed on one side -of each sheet of paper, or for documents in which you want symmetrical -headers or footers.@refill - -@findex evenheading -@findex evenfooting -@findex oddheading -@findex oddfooting -@item @@evenheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} - -@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} - -The `even' and `odd' commands specify the format for even-numbered -pages and odd-numbered pages. These commands are for books and -manuals that are printed on both sides of each sheet of paper.@refill -@end table - -Use the @samp{@@this@dots{}} series of @@-commands to -provide the names of chapters -and sections and the page number. You can use the -@samp{@@this@dots{}} commands in the left, center, or right portions -of headers and footers, or anywhere else in a Texinfo file so long as -they are between @code{@@iftex} and @code{@@end iftex} commands.@refill - -@need 1000 -Here are the @samp{@@this@dots{}} commands:@refill - -@table @code -@findex thispage -@item @@thispage -Expands to the current page number.@refill -@c !!! Karl Berry says that `thissection' fails on page breaks. -@ignore -@item @@thissection -Expands to the name of the current section.@refill -@end ignore - -@findex thischaptername -@item @@thischaptername -Expands to the name of the current chapter.@refill - -@findex thischapter -@item @@thischapter -Expands to the number and name of the current -chapter, in the format `Chapter 1: Title'.@refill - -@findex thistitle -@item @@thistitle -Expands to the name of the document, as specified by the -@code{@@settitle} command.@refill - -@findex thisfile -@item @@thisfile -For @code{@@include} files only: expands to the name of the current -@code{@@include} file. If the current Texinfo source file is not an -@code{@@include} file, this command has no effect. This command does -@emph{not} provide the name of the current Texinfo source file unless -it is an @code{@@include} file. (@xref{Include Files}, for more -information about @code{@@include} files.)@refill -@end table - -@noindent -You can also use the @code{@@today@{@}} command, which expands to the -current date, in `1 Jan 1900' format.@refill -@findex today - -Other @@-commands and text are printed in a header or footer just as -if they were in the body of a page. It is useful to incorporate text, -particularly when you are writing drafts:@refill - -@example -@group -@@iftex -@@headings off -@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter -@@everyfooting @@| @@| Version: 0.27: @@today@{@} -@@end iftex -@end group -@end example - -Beware of overlong titles: they may overlap another part of the -header or footer and blot it out.@refill - -@node Catching Mistakes, Refilling Paragraphs, Headings, Top -@comment node-name, next, previous, up -@appendix Formatting Mistakes -@cindex Structure, catching mistakes in -@cindex Nodes, catching mistakes -@cindex Catching mistakes -@cindex Correcting mistakes -@cindex Mistakes, catching -@cindex Problems, catching -@cindex Debugging the Texinfo structure - -Besides mistakes in the content of your documentation, there -are two kinds of mistake you can make with Texinfo: you can make mistakes -with @@-commands, and you can make mistakes with the structure of the -nodes and chapters.@refill - -Emacs has two tools for catching the @@-command mistakes and two for -catching structuring mistakes.@refill - -For finding problems with @@-commands, you can run @TeX{} or a region -formatting command on the region that has a problem; indeed, you can -run these commands on each region as you write it.@refill - -For finding problems with the structure of nodes and chapters, you can use -@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} -command and you can use the @kbd{M-x Info-validate} command.@refill - -@menu -* makeinfo preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with @TeX{} formatting. -* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. -@end menu - -@node makeinfo preferred, Debugging with Info, Catching Mistakes, Catching Mistakes -@ifinfo -@heading @code{makeinfo} Find Errors -@end ifinfo - -The @code{makeinfo} program does an excellent job of catching errors -and reporting them---far better than @code{texinfo-format-region} or -@code{texinfo-format-buffer}. In addition, the various functions for -automatically creating and updating node pointers and menus remove -many opportunities for human error.@refill - -If you can, use the updating commands to create and insert pointers -and menus. These prevent many errors. Then use @code{makeinfo} (or -its Texinfo mode manifestations, @code{makeinfo-region} and -@code{makeinfo-buffer}) to format your file and check for other -errors. This is the best way to work with Texinfo. But if you -cannot use @code{makeinfo}, or your problem is very puzzling, then you -may want to use the tools described in this appendix.@refill - -@node Debugging with Info, Debugging with TeX, makeinfo preferred, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Catching Errors with Info Formatting -@cindex Catching errors with Info formatting -@cindex Debugging with Info formatting - -After you have written part of a Texinfo file, you can use the -@code{texinfo-format-region} or the @code{makeinfo-region} command to -see whether the region formats properly.@refill - -Most likely, however, you are reading this section because for some -reason you cannot use the @code{makeinfo-region} command; therefore, the -rest of this section presumes that you are using -@code{texinfo-format-region}.@refill - -If you have made a mistake with an @@-command, -@code{texinfo-format-region} will stop processing at or after the -error and display an error message. To see where in the buffer the -error occurred, switch to the @samp{*Info Region*} buffer; the cursor -will be in a position that is after the location of the error. Also, -the text will not be formatted after the place where the error -occurred (or more precisely, where it was detected).@refill - -For example, if you accidentally end a menu with the command @code{@@end -menus} with an `s' on the end, instead of with @code{@@end menu}, you -will see an error message that says:@refill - -@example -@@end menus is not handled by texinfo -@end example - -@noindent -The cursor will stop at the point in the buffer where the error -occurs, or not long after it. The buffer will look like this:@refill - -@example -@group ----------- Buffer: *Info Region* ---------- -* Menu: - -* Using texinfo-show-structure:: How to use - `texinfo-show-structure' - to catch mistakes. -* Running Info-Validate:: How to check for - unreferenced nodes. -@@end menus -@point{} ----------- Buffer: *Info Region* ---------- -@end group -@end example - -The @code{texinfo-format-region} command sometimes provides slightly -odd error messages. For example, the following cross reference fails to format:@refill - -@example -(@@xref@{Catching Mistakes, for more info.) -@end example - -@noindent -In this case, @code{texinfo-format-region} detects the missing closing -brace but displays a message that says @samp{Unbalanced parentheses} -rather than @samp{Unbalanced braces}. This is because the formatting -command looks for mismatches between braces as if they were -parentheses.@refill - -Sometimes @code{texinfo-format-region} fails to detect mistakes. For -example, in the following, the closing brace is swapped with the -closing parenthesis:@refill - -@example -(@@xref@{Catching Mistakes), for more info.@} -@end example - -@noindent -Formatting produces: -@example -(*Note for more info.: Catching Mistakes) -@end example - -The only way for you to detect this error is to realize that the -reference should have looked like this:@refill - -@example -(*Note Catching Mistakes::, for more info.) -@end example - -Incidentally, if you are reading this node in Info and type @kbd{f -@key{RET}} (@code{Info-follow-reference}), you will generate an error -message that says: - -@example -No such node: "Catching Mistakes) The only way @dots{} -@end example - -@noindent -This is because Info perceives the example of the error as the first -cross reference in this node and if you type a @key{RET} immediately -after typing the Info @kbd{f} command, Info will attempt to go to the -referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info -will complete the node name of the correctly written example and take -you to the `Catching Mistakes' node. (If you try this, you can return -from the `Catching Mistakes' node by typing @kbd{l} -(@code{Info-last}).) - -@c !!! section on using Elisp debugger ignored. -@ignore -Sometimes @code{texinfo-format-region} will stop long after the -original error; this is because it does not discover the problem until -then. In this case, you will need to backtrack.@refill - -@c menu -@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. -@c end menu - -@c node Using the Emacs Lisp Debugger -@c appendixsubsec Using the Emacs Lisp Debugger -@c index Using the Emacs Lisp debugger -@c index Emacs Lisp debugger -@c index Debugger, using the Emacs Lisp - -If an error is especially elusive, you can turn on the Emacs Lisp -debugger and look at the backtrace; this tells you where in the -@code{texinfo-format-region} function the problem occurred. You can -turn on the debugger with the command:@refill - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} -@end example - -@noindent -and turn it off with - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} -@end example - -Often, when you are using the debugger, it is easier to follow what is -going on if you use the Emacs Lisp files that are not byte-compiled. -The byte-compiled sources send octal numbers to the debugger that may -look mysterious. To use the uncompiled source files, load -@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} -command.@refill - -The debugger will not catch an error if @code{texinfo-format-region} -does not detect one. In the example shown above, -@code{texinfo-format-region} did not find the error when the whole -list was formatted, but only when part of the list was formatted. -When @code{texinfo-format-region} did not find an error, the debugger -did not find one either. @refill - -However, when @code{texinfo-format-region} did report an error, it -invoked the debugger. This is the backtrace it produced:@refill - -@example ----------- Buffer: *Backtrace* ---------- -Signalling: (search-failed "[@},]") - re-search-forward("[@},]") - (while ...) - (let ...) - texinfo-format-parse-args() - (let ...) - texinfo-format-xref() - funcall(texinfo-format-xref) - (if ...) - (let ...) - (if ...) - (while ...) - texinfo-format-scan() - (save-excursion ...) - (let ...) - texinfo-format-region(103370 103631) -* call-interactively(texinfo-format-region) ----------- Buffer: *Backtrace* ---------- -@end example - -The backtrace is read from the bottom up. -@code{texinfo-format-region} was called interactively; and it, in -turn, called various functions, including @code{texinfo-format-scan}, -@code{texinfo-format-xref} and @code{texinfo-format-parse-args}. -Inside the function @code{texinfo-format-parse-args}, the function -@code{re-search-forward} was called; it was this function that could -not find the missing right-hand brace.@refill - -@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs -Manual}, for more information.@refill -@end ignore - -@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Catching Errors with @TeX{} Formatting -@cindex Catching errors with @TeX{} formatting -@cindex Debugging with @TeX{} formatting - -You can also catch mistakes when you format a file with @TeX{}.@refill - -Usually, you will want to do this after you have run -@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on -the same file, because @code{texinfo-format-buffer} sometimes displays -error messages that make more sense than @TeX{}. (@xref{Debugging -with Info}, for more information.)@refill - -For example, @TeX{} was run on a Texinfo file, part of which is shown -here:@refill - -@example ----------- Buffer: texinfo.texi ---------- -name of the Texinfo file as an extension. The -@@samp@{??@} are `wildcards' that cause the shell to -substitute all the raw index files. (@@xref@{sorting -indices, for more information about sorting -indices.)@@refill ----------- Buffer: texinfo.texi ---------- -@end example - -@noindent -(The cross reference lacks a closing brace.) -@TeX{} produced the following output, after which it stopped:@refill - -@example ----------- Buffer: *tex-shell* ---------- -Runaway argument? -@{sorting indices, for more information about sorting -indices.) @@refill @@ETC. -! Paragraph ended before @@xref was complete. -<to be read again> - @@par -l.27 - -? ----------- Buffer: *tex-shell* ---------- -@end example - -In this case, @TeX{} produced an accurate and -understandable error message: - -@example -Paragraph ended before @@xref was complete. -@end example - -@noindent -@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. -@samp{l.27} means that @TeX{} detected the problem on line 27 of the -Texinfo file. The @samp{?} is the prompt @TeX{} uses in this -circumstance.@refill - -Unfortunately, @TeX{} is not always so helpful, and sometimes you must -truly be a Sherlock Holmes to discover what went wrong.@refill - -In any case, if you run into a problem like this, you can do one of three -things.@refill - -@enumerate -@item -You can tell @TeX{} to continue running and ignore just this error by -typing @key{RET} at the @samp{?} prompt.@refill - -@item -You can tell @TeX{} to continue running and to ignore all errors as best -it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill - -This is often the best thing to do. However, beware: the one error -may produce a cascade of additional error messages as its consequences -are felt through the rest of the file. (To stop @TeX{} when it is -producing such an avalanche of error messages, type @kbd{C-d} (or -@kbd{C-c C-d}, if you are running a shell inside Emacs.))@refill - -@item -You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} -at the @samp{?} prompt.@refill -@end enumerate - -Please note that if you are running @TeX{} inside Emacs, you need to -switch to the shell buffer and line at which @TeX{} offers the @samp{?} -prompt.@refill - -Sometimes @TeX{} will format a file without producing error messages even -though there is a problem. This usually occurs if a command is not ended -but @TeX{} is able to continue processing anyhow. For example, if you fail -to end an itemized list with the @code{@@end itemize} command, @TeX{} will -write a @sc{dvi} file that you can print out. The only error message that -@TeX{} will give you is the somewhat mysterious comment that@refill - -@example -(@@end occurred inside a group at level 1) -@end example - -@noindent -However, if you print the @sc{dvi} file, you will find that the text -of the file that follows the itemized list is entirely indented as if -it were part of the last item in the itemized list. The error message -is the way @TeX{} says that it expected to find an @code{@@end} -command somewhere in the file; but that it could not determine where -it was needed.@refill - -Another source of notoriously hard-to-find errors is a missing -@code{@@end group} command. If you ever are stumped by -incomprehensible errors, look for a missing @code{@@end group} command -first.@refill - -If the Texinfo file lacks header lines, -@TeX{} may stop in the -beginning of its run and display output that looks like the following. -The @samp{*} indicates that @TeX{} is waiting for input.@refill - -@example -This is TeX, Version 3.14159 (Web2c 7.0) -(test.texinfo [1]) -* -@end example - -@noindent -In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then -write the header lines in the Texinfo file and run the @TeX{} command -again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} -instead of @samp{@@}; and in this circumstance, you are working -directly with @TeX{}, not with Texinfo.)@refill - -@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Using @code{texinfo-show-structure} -@cindex Showing the structure of a file -@findex texinfo-show-structure - -It is not always easy to keep track of the nodes, chapters, sections, and -subsections of a Texinfo file. This is especially true if you are revising -or adding to a Texinfo file that someone else has written.@refill - -In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} -command lists all the lines that begin with the @@-commands that -specify the structure: @code{@@chapter}, @code{@@section}, -@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} -as prefix argument, if interactive), -the command also shows the @code{@@node} lines. The -@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in -Texinfo mode, by default.@refill - -The lines are displayed in a buffer called the @samp{*Occur*} buffer, -indented by hierarchical level. For example, here is a part of what was -produced by running @code{texinfo-show-structure} on this manual:@refill - -@example -@group - Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| - unnum\\|major\\|chapheading \\|heading \\|appendix\\)" - in buffer texinfo.texi. - @dots{} - 4177:@@chapter Nodes - 4198: @@heading Two Paths - 4231: @@section Node and Menu Illustration - 4337: @@section The @@code@{@@@@node@} Command - 4393: @@subheading Choosing Node and Pointer Names - 4417: @@subsection How to Write an @@code@{@@@@node@} Line - 4469: @@subsection @@code@{@@@@node@} Line Tips - @dots{} -@end group -@end example - -This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin -with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} -commands respectively. If you move your cursor into the @samp{*Occur*} -window, you can position the cursor over one of the lines and use the -@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to -the corresponding spot in the Texinfo file. @xref{Other Repeating -Search, , Using Occur, emacs, The GNU Emacs Manual}, for more -information about @code{occur-mode-goto-occurrence}.@refill - -The first line in the @samp{*Occur*} window describes the @dfn{regular -expression} specified by @var{texinfo-heading-pattern}. This regular -expression is the pattern that @code{texinfo-show-structure} looks for. -@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, -for more information.@refill - -When you invoke the @code{texinfo-show-structure} command, Emacs will -display the structure of the whole buffer. If you want to see the -structure of just a part of the buffer, of one chapter, for example, -use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the -region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is -how the example used above was generated. (To see the whole buffer -again, use @kbd{C-x n w} (@code{widen}).)@refill - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with -@code{@@node} as well as the lines beginning with the @@-sign commands -for @code{@@chapter}, @code{@@section}, and the like.@refill - -You can remind yourself of the structure of a Texinfo file by looking at -the list in the @samp{*Occur*} window; and if you have mis-named a node -or left out a section, you can correct the mistake.@refill - -@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Using @code{occur} -@cindex Occurrences, listing with @code{@@occur} -@findex occur - -Sometimes the @code{texinfo-show-structure} command produces too much -information. Perhaps you want to remind yourself of the overall structure -of a Texinfo file, and are overwhelmed by the detailed list produced by -@code{texinfo-show-structure}. In this case, you can use the @code{occur} -command directly. To do this, type@refill - -@example -@kbd{M-x occur} -@end example - -@noindent -and then, when prompted, type a @dfn{regexp}, a regular expression for -the pattern you want to match. (@xref{Regexps, , Regular Expressions, -emacs, The GNU Emacs Manual}.) The @code{occur} command works from -the current location of the cursor in the buffer to the end of the -buffer. If you want to run @code{occur} on the whole buffer, place -the cursor at the beginning of the buffer.@refill - -For example, to see all the lines that contain the word -@samp{@@chapter} in them, just type @samp{@@chapter}. This will -produce a list of the chapters. It will also list all the sentences -with @samp{@@chapter} in the middle of the line.@refill - -If you want to see only those lines that start with the word -@samp{@@chapter}, type @samp{^@@chapter} when prompted by -@code{occur}. If you want to see all the lines that end with a word -or phrase, end the last word with a @samp{$}; for example, -@samp{catching mistakes$}. This can be helpful when you want to see -all the nodes that are part of the same chapter or section and -therefore have the same `Up' pointer.@refill - -@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, -for more information.@refill - -@node Running Info-Validate, , Using occur, Catching Mistakes -@comment node-name, next, previous, up -@appendixsec Finding Badly Referenced Nodes -@findex Info-validate -@cindex Nodes, checking for badly referenced -@cindex Checking for badly referenced nodes -@cindex Looking for badly referenced nodes -@cindex Finding badly referenced nodes -@cindex Badly referenced nodes - -You can use the @code{Info-validate} command to check whether any of -the `Next', `Previous', `Up' or other node pointers fail to point to a -node. This command checks that every node pointer points to an -existing node. The @code{Info-validate} command works only on Info -files, not on Texinfo files.@refill - -The @code{makeinfo} program validates pointers automatically, so you -do not need to use the @code{Info-validate} command if you are using -@code{makeinfo}. You only may need to use @code{Info-validate} if you -are unable to run @code{makeinfo} and instead must create an Info file -using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or -if you write an Info file from scratch.@refill - -@menu -* Using Info-validate:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. -@end menu - -@node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate -@appendixsubsec Running @code{Info-validate} -@cindex Running @code{Info-validate} -@cindex Info validating a large file -@cindex Validating a large file - -To use @code{Info-validate}, visit the Info file you wish to check and -type:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note that the @code{Info-validate} command requires an upper case -`I'. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}.)@refill - -If your file is valid, you will receive a message that says ``File appears -valid''. However, if you have a pointer that does not point to a node, -error messages will be displayed in a buffer called @samp{*problems in -info file*}.@refill - -For example, @code{Info-validate} was run on a test file that contained -only the first node of this manual. One of the messages said:@refill - -@example -In node "Overview", invalid Next: Texinfo Mode -@end example - -@noindent -This meant that the node called @samp{Overview} had a `Next' pointer that -did not point to anything (which was true in this case, since the test file -had only one node in it).@refill - -Now suppose we add a node named @samp{Texinfo Mode} to our test case -but we do not specify a `Previous' for this node. Then we will get -the following error message:@refill - -@example -In node "Texinfo Mode", should have Previous: Overview -@end example - -@noindent -This is because every `Next' pointer should be matched by a -`Previous' (in the node where the `Next' points) which points back.@refill - -@code{Info-validate} also checks that all menu entries and cross references -point to actual nodes.@refill - -Note that @code{Info-validate} requires a tag table and does not work -with files that have been split. (The @code{texinfo-format-buffer} -command automatically splits large files.) In order to use -@code{Info-validate} on a large file, you must run -@code{texinfo-format-buffer} with an argument so that it does not split -the Info file; and you must create a tag table for the unsplit -file.@refill - -@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate -@comment node-name, next, previous, up -@appendixsubsec Creating an Unsplit File -@cindex Creating an unsplit file -@cindex Unsplit file creation - -You can run @code{Info-validate} only on a single Info file that has a -tag table. The command will not work on the indirect subfiles that -are generated when a master file is split. If you have a large file -(longer than 70,000 bytes or so), you need to run the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such -a way that it does not create indirect subfiles. You will also need -to create a tag table for the Info file. After you have done this, -you can run @code{Info-validate} and look for badly referenced -nodes.@refill - -The first step is to create an unsplit Info file. To prevent -@code{texinfo-format-buffer} from splitting a Texinfo file into -smaller Info files, give a prefix to the @kbd{M-x -texinfo-format-buffer} command:@refill - -@example -C-u M-x texinfo-format-buffer -@end example - -@noindent -or else - -@example -C-u C-c C-e C-b -@end example - -@noindent -When you do this, Texinfo will not split the file and will not create -a tag table for it. @refill -@cindex Making a tag table manually -@cindex Tag table, making manually - -@node Tagifying, Splitting, Unsplit, Running Info-Validate -@appendixsubsec Tagifying a File - -After creating an unsplit Info file, you must create a tag table for -it. Visit the Info file you wish to tagify and type:@refill - -@example -M-x Info-tagify -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an -Info file with a tag table that you can validate.@refill - -The third step is to validate the Info file:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-validate}.) -In brief, the steps are:@refill - -@example -@group -C-u M-x texinfo-format-buffer -M-x Info-tagify -M-x Info-validate -@end group -@end example - -After you have validated the node structure, you can rerun -@code{texinfo-format-buffer} in the normal way so it will construct a -tag table and split the file automatically, or you can make the tag -table and split the file manually.@refill - -@node Splitting, , Tagifying, Running Info-Validate -@comment node-name, next, previous, up -@appendixsubsec Splitting a File Manually -@cindex Splitting an Info file manually -@cindex Info file, splitting manually - -You should split a large file or else let the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it -for you automatically. (Generally you will let one of the formatting -commands do this job for you. @xref{Create an Info File}.)@refill - -The split-off files are called the indirect subfiles.@refill - -Info files are split to save memory. With smaller files, Emacs does not -have make such a large buffer to hold the information.@refill - -If an Info file has more than 30 nodes, you should also make a tag -table for it. @xref{Using Info-validate}, for information -about creating a tag table. (Again, tag tables are usually created -automatically by the formatting command; you only need to create a tag -table yourself if you are doing the job manually. Most likely, you -will do this for a large, unsplit file on which you have run -@code{Info-validate}.)@refill - -@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 -@ignore -Before running @code{Info-split}, you need to load the @code{info} library -into Emacs by giving the command @kbd{M-x load-library @key{RET} info -@key{RET}}. -@end ignore - -Visit the Info file you wish to tagify and split and type the two -commands:@refill - -@example -M-x Info-tagify -M-x Info-split -@end example - -@noindent -(Note that the @samp{I} in @samp{Info} is upper case.)@refill - -When you use the @code{Info-split} command, the buffer is modified into a -(small) Info file which lists the indirect subfiles. This file should be -saved in place of the original visited file. The indirect subfiles are -written in the same directory the original file is in, with names generated -by appending @samp{-} and a number to the original file name.@refill - -The primary file still functions as an Info file, but it contains just -the tag table and a directory of subfiles.@refill - -@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top -@comment node-name, next, previous, up -@appendix Refilling Paragraphs -@cindex Refilling paragraphs -@cindex Filling paragraphs -@findex refill - -The @code{@@refill} command refills and, optionally, indents the first -line of a paragraph.@footnote{Perhaps the command should have been -called the @code{@@refillandindent} command, but @code{@@refill} is -shorter and the name was chosen before indenting was possible.} The -@code{@@refill} command is no longer important, but we describe it here -because you once needed it. You will see it in many old Texinfo -files.@refill - -Without refilling, paragraphs containing long @@-constructs may look -bad after formatting because the formatter removes @@-commands and -shortens some lines more than others. In the past, neither the -@code{texinfo-format-region} command nor the -@code{texinfo-format-buffer} command refilled paragraphs -automatically. The @code{@@refill} command had to be written at the -end of every paragraph to cause these formatters to fill them. (Both -@TeX{} and @code{makeinfo} have always refilled paragraphs -automatically.) Now, all the Info formatters automatically fill and -indent those paragraphs that need to be filled and indented.@refill - -The @code{@@refill} command causes @code{texinfo-format-region} and -@code{texinfo-format-buffer} to refill a paragraph in the Info file -@emph{after} all the other processing has been done. For this reason, -you can not use @code{@@refill} with a paragraph containing either -@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will -override those two commands.@refill - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands now automatically append @code{@@refill} to the end of each -paragraph that should be filled. They do not append @code{@@refill} to -the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} -and therefore do not refill or indent them.@refill - -@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top -@comment node-name, next, previous, up -@appendix @@-Command Syntax -@cindex @@-command syntax - -The character @samp{@@} is used to start special Texinfo commands. -(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo -has four types of @@-command:@refill - -@table @asis -@item 1. Non-alphabetic commands. -These commands consist of an @@ followed by a punctuation mark or other -character that is not part of the alphabet. Non-alphabetic commands -are almost always part of the text within a paragraph, and never take -any argument. The two characters (@@ and the other one) are complete -in themselves; none is followed by braces. The non-alphabetic -commands are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@@}, -@code{@@@{}, and @code{@@@}}.@refill - -@item 2. Alphabetic commands that do not require arguments. -These commands start with @@ followed by a word followed by left- and -right-hand braces. These commands insert special symbols in the -document; they do not require arguments. For example, -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', -and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill - -@item 3. Alphabetic commands that require arguments within braces. -These commands start with @@ followed by a letter or a word, followed by an -argument within braces. For example, the command @code{@@dfn} indicates -the introductory or defining use of a term; it is used as follows: @samp{In -Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill - -@item 4. Alphabetic commands that occupy an entire line. -These commands occupy an entire line. The line starts with @@, -followed by the name of the command (a word); for example, @code{@@center} -or @code{@@cindex}. If no argument is needed, the word is followed by -the end of the line. If there is an argument, it is separated from -the command name by a space. Braces are not used.@refill -@end table - -@cindex Braces and argument syntax -Thus, the alphabetic commands fall into classes that have -different argument syntaxes. You cannot tell to which class a command -belongs by the appearance of its name, but you can tell by the -command's meaning: if the command stands for a glyph, it is in -class 2 and does not require an argument; if it makes sense to use the -command together with other text as part of a paragraph, the command -is in class 3 and must be followed by an argument in braces; -otherwise, it is in class 4 and uses the rest of the line as its -argument.@refill - -The purpose of having a different syntax for commands of classes 3 and -4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command @code{@@refill}, which is always -used at the end of a paragraph immediately following the final period -or other punctuation character. @code{@@refill} takes no argument and -does @emph{not} require braces. @code{@@refill} never confuses the -Emacs paragraph commands because it cannot appear at the beginning of -a line.@refill - -@node Obtaining TeX, New Features, Command Syntax, Top -@appendix How to Obtain @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@c !!! Here is information about obtaining TeX. Update it whenever. -@c !!! Also consider updating TeX.README on prep. -@c Updated by RJC on 1 March 1995, conversation with MacKay. -@c Updated by kb@cs.umb.edu on 29 July 1996. -@TeX{} is freely redistributable. You can obtain @TeX{} for Unix -systems via anonymous ftp or on tape or CD-ROM. The core material -consists of Karl Berry's Web2c @TeX{} distribution. - -On-line retrieval instructions are available from either: -@example -@url{ftp://ftp.tug.org/tex/unixtex.ftp} -@url{http://www.tug.org/unixtex.ftp} -@end example - -The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals; the University of -Washington maintains and supports a tape distribution; the @TeX{} Users -Group co-sponsors a complete CD-ROM @TeX{} distribution. - -For the FSF Source Code CD-ROM, please contact: - -@iftex -@display -@group -Free Software Foundation, Inc. -59 Temple Place Suite 330 -Boston, MA w{ } 02111-1307 -USA - -Telephone: @w{@t{+}1--617--542--5942} -Fax: (including Japan) @w{@t{+}1--617--542--2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031--13--2473 (KDD) -@w{ } @w{ } @w{ } 0066--3382--0158 (IDC) -Electronic mail: @code{gnu@@prep.ai.mit.edu} -@end group -@end display -@end iftex -@ifinfo -@display -@group -Free Software Foundation, Inc. -59 Temple Place Suite 330 -Boston, MA @w{ } 02111-1307 -USA - -Telephone: @w{@t{+}1-617-542-5942} -Fax: (including Japan) @w{@t{+}1-617-542-2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031-13-2473 (KDD) -@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) -Electronic mail: @code{gnu@@prep.ai.mit.edu} -@end group -@end display -@end ifinfo - -To order a full distribution on CD-ROM, please see: -@display -@url{http://www.tug.org/tex-live.html} -@end display - -@noindent -(The distribution is also available by FTP; see the URL's above.) - -To order a full distribution from the University of Washington on either a -1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge, send -$210 to: - -@display -@group -Pierre A. MacKay -Denny Hall, Mail Stop DH-10 -University of Washington -Seattle, WA @w{ } 98195 -USA - -Telephone: @t{+}1--206--543--2268 -Electronic mail: @code{mackay@@cs.washington.edu} -@end group -@end display - -Please make checks payable to the University of Washington. -Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. - -Prepaid orders are the only orders that can now be handled. Overseas -sites: please add to the base cost, if desired, $20.00 for shipment -via air parcel post, or $30.00 for shipment via courier. - -Please check with the above for current prices and formats. - - -@node New Features, Command and Variable Index, Obtaining TeX, Top -@appendix Second Edition Features - -@tex -% Widen the space for the first column so three control-character -% strings fit in the first column. Switched back to default .8in -% value at end of chapter. -\global\tableindent=1.0in -@end tex - -The second edition of the Texinfo manual describes more than 20 new -Texinfo mode commands and more than 50 previously undocumented Texinfo -@@-commands. This edition is more than twice the length of the first -edition.@refill - -Here is a brief description of the new commands.@refill - -@menu -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@end menu - -@node New Texinfo Mode Commands, New Commands, New Features, New Features -@appendixsec New Texinfo Mode Commands - -Texinfo mode provides commands and features especially designed for -working with Texinfo files. More than 20 new commands have been -added, including commands for automatically creating and updating -both nodes and menus. This is a tedious task when done by hand.@refill - -The keybindings are intended to be somewhat mnemonic.@refill - -@subheading Update all nodes and menus - -The @code{texinfo-master-menu} command is the primary command: - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -Create or update a master menu. -With @kbd{C-u} as a prefix argument, -first create or update all nodes -and regular menus. -@end table - -@subheading Update Pointers - -@noindent -Create or update `Next', `Previous', and `Up' node pointers.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -Update a node. - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -Update every node in the buffer. -@end table - -@subheading Update Menus - -@noindent -Create or update menus.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -Make or update a menu. - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -Make or update all the menus in a buffer. -With @kbd{C-u} as a prefix argument, -first update all the nodes. -@end table - -@subheading Insert Title as Description - -@noindent -Insert a node's chapter or section title in the space for the -description in a menu entry line; position point so you can edit the -insert. (This command works somewhat differently than the other -insertion commands, which insert only a predefined string.)@refill - -@noindent -@xref{Inserting, Inserting Frequently Used Commands}. - -@table @kbd -@item C-c C-c C-d -Insert title. -@end table - -@subheading Format for Info - -@noindent -Provide keybindings both for the Info formatting commands that are -written in Emacs Lisp and for @code{makeinfo} that is written in -C.@refill - -@noindent -@xref{Info Formatting}. - -@noindent -Use the Emacs lisp @code{texinfo-format@dots{}} commands: - -@table @kbd -@item C-c C-e C-r -Format the region. - -@item C-c C-e C-b -Format the buffer. -@end table - -@noindent -Use @code{makeinfo}: - -@table @kbd -@item C-c C-m C-r -Format the region. - -@item C-c C-m C-b -Format the buffer. - -@item C-c C-m C-l -Recenter the @code{makeinfo} output buffer. - -@item C-c C-m C-k -Kill the @code{makeinfo} formatting job. -@end table - -@subheading Typeset and Print - -@noindent -Typeset and print Texinfo documents from within Emacs.@refill - -@ifinfo -@noindent -@xref{Printing}. -@end ifinfo -@iftex -@noindent -@xref{Printing, , Formatting and Printing}. -@end iftex - -@table @kbd -@item C-c C-t C-b -Run @code{texi2dvi} on the buffer. - -@item C-c C-t C-r -Run @TeX{} on the region. - -@item C-c C-t C-i -Run @code{texindex}. - -@item C-c C-t C-p -Print the @sc{dvi} file. - -@item C-c C-t C-q -Show the print queue. - -@item C-c C-t C-d -Delete a job from the print queue. - -@item C-c C-t C-k -Kill the current @TeX{} formatting job. - -@item C-c C-t C-x -Quit a currently stopped @TeX{} formatting job. - -@item C-c C-t C-l -Recenter the output buffer. -@end table - -@subheading Other Updating Commands - -@noindent -The ``other updating commands'' do not have standard keybindings because -they are used less frequently.@refill - -@noindent -@xref{Other Updating Commands}. - -@table @kbd -@item M-x texinfo-insert-node-lines -Insert missing @code{@@node} lines using -section titles as node names. - -@item M-x texinfo-multiple-files-update -Update a multi-file document. -With a numeric prefix, such as @kbd{C-u 8}, -update @strong{every} pointer and -menu in @strong{all} the files and -then insert a master menu. - -@item M-x texinfo-indent-menu-description -Indent descriptions in menus. - -@item M-x texinfo-sequential-node-update -Insert node pointers in strict sequence. -@end table - -@node New Commands, , New Texinfo Mode Commands, New Features -@appendixsec New Texinfo @@-Commands - -The second edition of the Texinfo manual describes more than 50 -commands that were not described in the first edition. A third or so -of these commands existed in Texinfo but were not documented in the -manual; the others are new. Here is a listing, with brief -descriptions of them:@refill - -@subheading Indexing - -@noindent -Create your own index, and merge indices.@refill - -@noindent -@xref{Indices}. - -@table @kbd -@item @@defindex @var{index-name} -Define a new index and its indexing command. -See also the @code{@@defcodeindex} command. - -@c written verbosely to avoid overfull hbox -@item @@synindex @var{from-index} @var{into-index} -Merge the @var{from-index} index into the @var{into-index} index. -See also the @code{@@syncodeindex} command. -@end table - -@subheading Definitions - -@noindent -Describe functions, variables, macros, -commands, user options, special forms, and other such artifacts in a -uniform format.@refill - -@noindent -@xref{Definition Commands}. - -@table @kbd -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -Format a description for functions, interactive -commands, and similar entities. - -@item @@defvr, @@defop, @dots{} -15 other related commands. -@end table - -@subheading Glyphs - -@noindent -Indicate the results of evaluation, expansion, -printed output, an error message, equivalence of expressions, and the -location of point.@refill - -@noindent -@xref{Glyphs}. - -@table @kbd -@item @@equiv@{@} -@itemx @equiv{} -Equivalence: - -@item @@error@{@} -@itemx @error{} -Error message - -@item @@expansion@{@} -@itemx @expansion{} -Macro expansion - -@item @@point@{@} -@itemx @point{} -Position of point - -@item @@print@{@} -@itemx @print{} -Printed output - -@item @@result@{@} -@itemx @result{} -Result of an expression -@end table - -@subheading Page Headings - -@noindent -Customize page headings. - -@noindent -@xref{Headings}. - -@table @kbd -@item @@headings @var{on-off-single-double} -Headings on or off, single, or double-sided. - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Footings for even-numbered (left-hand) pages. - -@item @@evenheading, @@everyheading, @@oddheading, @dots{} -Five other related commands. - -@item @@thischapter -Insert name of chapter and chapter number. - -@item @@thischaptername, @@thisfile, @@thistitle, @@thispage -Related commands. -@end table - -@subheading Formatting - -@noindent -Format blocks of text. - -@noindent -@xref{Quotations and Examples}, and@* -@ref{Lists and Tables, , Making Lists and Tables}. - -@table @kbd -@item @@cartouche -Draw rounded box surrounding text (not in Info). - -@item @@enumerate @var{optional-arg} -Enumerate a list with letters or numbers. - -@item @@exdent @var{line-of-text} -Remove indentation. - -@item @@flushleft -Left justify. - -@item @@flushright -Right justify. - -@item @@format -Do not narrow nor change font. - -@item @@ftable @var{formatting-command} -@itemx @@vtable @var{formatting-command} -Two-column table with indexing. - -@item @@lisp -For an example of Lisp code. - -@item @@smallexample -@itemx @@smalllisp -Like @@table and @@lisp @r{but for} @@smallbook. -@end table - -@subheading Conditionals - -@noindent -Conditionally format text. - -@noindent -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@table @kbd -@item @@set @var{flag} [@var{string}] -Set a flag. Optionally, set value -of @var{flag} to @var{string}. - -@item @@clear @var{flag} -Clear a flag. - -@item @@value@{@var{flag}@} -Replace with value to which @var{flag} is set. - -@item @@ifset @var{flag} -Format, if @var{flag} is set. - -@item @@ifclear @var{flag} -Ignore, if @var{flag} is set. -@end table - -@subheading @@heading series for Titles - -@noindent -Produce unnumbered headings that do not appear in a table of contents. - -@noindent -@xref{Structuring}. - -@table @kbd -@item @@heading @var{title} -Unnumbered section-like heading not listed -in the table of contents of a printed manual. - -@item @@chapheading, @@majorheading, @@subheading, @@subsubheading -Related commands. -@end table - -@need 1000 -@subheading Font commands - -@need 1000 -@noindent -@xref{Smallcaps}, and @* -@ref{Fonts}. - -@table @kbd -@item @@r@{@var{text}@} -Print in roman font. - -@item @@sc@{@var{text}@} -Print in @sc{small caps} font. -@end table - -@subheading Miscellaneous - -@noindent -See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* -see @ref{Customized Highlighting},@* -see @ref{Overfull hboxes},@* -see @ref{Footnotes},@* -see @ref{dmn, , Format a Dimension},@* -see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* -see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* -see @ref{minus, , Inserting a Minus Sign},@* -see @ref{paragraphindent, , Paragraph Indenting},@* -see @ref{Cross Reference Commands},@* -see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* -see @ref{Custom Headings, , How to Make Your Own Headings}. - -@table @kbd -@item @@author @var{author} -Typeset author's name. - -@ignore -@item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -Define a highlighting command for Info. (Info only.) -@end ignore - -@item @@finalout -Produce cleaner printed output. - -@item @@footnotestyle @var{end-or-separate} -Specify footnote style. - -@item @@dmn@{@var{dimension}@} -Format a dimension. - -@item @@global@@let@var{new-cmd}=@var{existing-cmd} -Define a highlighting command for @TeX{}. (@TeX{} only.) - -@item @@lowersections -Reduce hierarchical level of sectioning commands. - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. - -@item @@minus@{@} -Generate a minus sign. - -@item @@paragraphindent @var{asis-or-number} -Specify paragraph indentation. - -@item @@raisesections -Raise hierarchical level of sectioning commands. - -@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} -Make a reference. In the printed manual, the -reference does not start with the word `see'. - -@item @@title @var{title} -Typeset @var{title} in the alternative -title page format. - -@item @@subtitle @var{subtitle} -Typeset @var{subtitle} in the alternative -title page format. - -@item @@today@{@} -Insert the current date. -@end table -@tex -% Switch width of first column of tables back to default value -\global\tableindent=.8in -@end tex - - -@node Command and Variable Index, Concept Index, New Features, Top -@comment node-name, next, previous, up -@unnumbered Command and Variable Index - -This is an alphabetical list of all the @@-commands, assorted Emacs Lisp -functions, and several variables. To make the list easier to use, the -commands are listed without their preceding @samp{@@}.@refill - -@printindex fn - - -@node Concept Index, , Command and Variable Index, Top -@unnumbered Concept Index - -@printindex cp - - -@summarycontents -@contents -@bye diff --git a/gnu/usr.bin/texinfo/util/mkinstalldirs b/gnu/usr.bin/texinfo/util/mkinstalldirs deleted file mode 100644 index 58b613d6d82..00000000000 --- a/gnu/usr.bin/texinfo/util/mkinstalldirs +++ /dev/null @@ -1,40 +0,0 @@ -#! /bin/sh -# mkinstalldirs --- make directory hierarchy -# Author: Noah Friedman <friedman@prep.ai.mit.edu> -# Created: 1993-05-16 -# Public domain - -# $Id: mkinstalldirs,v 1.3 2002/06/10 13:51:04 espie Exp $ - -errstatus=0 - -for file -do - set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` - shift - - pathcomp= - for d - do - pathcomp="$pathcomp$d" - case "$pathcomp" in - -* ) pathcomp=./$pathcomp ;; - esac - - if test ! -d "$pathcomp"; then - echo "mkdir $pathcomp" 1>&2 - - mkdir "$pathcomp" || lasterr=$? - - if test ! -d "$pathcomp"; then - errstatus=$lasterr - fi - fi - - pathcomp="$pathcomp/" - done -done - -exit $errstatus - -# mkinstalldirs ends here diff --git a/gnu/usr.bin/texinfo/util/update-info b/gnu/usr.bin/texinfo/util/update-info deleted file mode 100644 index 0d31fde4d27..00000000000 --- a/gnu/usr.bin/texinfo/util/update-info +++ /dev/null @@ -1,875 +0,0 @@ -#!/bin/sh -# update-info -- update dir file from all extant info pages. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, you can either send email to this -# program's maintainer or write to: The Free Software Foundation, -# Inc.; 59 Temple Place, Suite 330; Boston, MA 02111-1307, USA. -# -# Author: rhawes@dmapub.dma.org. Please report bugs to him. -# -# run this program to install update-info -# ###SECTION 0### install script -# These constants set the version numbers for both files: -PROGRAM_VERSION="1.4" -PACKAGE_VERSION="4.0" - -# ENVIRONMENT -if test -z "$TMPDIR"; then - TMPDIR="/usr/tmp" -fi - -TMP_SED="$TMPDIR/uss$$.info" -TMP_F_ADD_SECTION="$TMPDIR/ufa$$.info" -TMP_F_DELETE_INVALID="$TMPDIR/ufd$$.info" -TMP_F_INSERT_MISSING="$TMPDIR/ufi$$.info" -TMP_FILES="$TMP_SED $TMP_F_ADD_SECTION $TMP_F_DELETE_INVALID\ - $TMP_F_INSERT_MISSING" - -trap 'rm -f $TMP_FILES' 0 - -# file boundaries -UPDATE_INFO="/^# _file: 'update-info'_/" -UPDATE_INFO_F="/^# _file: 'update-info.f'_/" - -# @F_ADD_SECTION@ -echo 'Item_Num=`expr "$Item_Num" + "1"` -echo "$1">>"$TMP_SECTIONS" -if test "$Item_Status"; then - Item_Status=`echo "${Item_Status} -X"` -else - Item_Status="X" -fi '>$TMP_F_ADD_SECTION - -# @F_INSERT_MISSING@ -echo 'if test -z "$Create_Node"; then - rm -f ${Info_Node}.old - cp $Info_Node ${Info_Node}.old - echo "$BACKUP_MSG" -fi -echo "/$MENU_BEGIN/ -+,$ d -r $TMP_MENU -w -q"|ed -s $Info_Node>/dev/null'>$TMP_F_INSERT_MISSING - -# @F_DELETE_INVALID@ -echo ' -rm -f ${Info_Node}.old -cp $Info_Node ${Info_Node}.old -echo "$BACKUP_MSG" -echo "/$MENU_BEGIN/ -+,$ d -w -q"|ed -s $Info_Node>/dev/null -sed -f "$TMP_SED" "$TMP_MENU">>"$Info_Node"'>$TMP_F_DELETE_INVALID - -cat<<Sed_Script_EOF>$TMP_SED -s/@UPDATE_INFO_VERSION@/$PROGRAM_VERSION/g -s/@TEXINFO_VERSION@/$PACKAGE_VERSION/g -s/@SET_ITEM@/Item_Status=\`echo "\$Item_Status"|sed -e "\${1}s%^.*%\${2}%"\`/ -/@F_ADD_SECTION@/r $TMP_F_ADD_SECTION -/@F_ADD_SECTION@/d -/@F_DELETE_INVALID@/r $TMP_F_DELETE_INVALID -/@F_DELETE_INVALID@/d -/@F_INSERT_MISSING@/r $TMP_F_INSERT_MISSING -/@F_INSERT_MISSING@/d -Sed_Script_EOF - -sed -e "1,${UPDATE_INFO}d" -e "$UPDATE_INFO_F,\$d" -f $TMP_SED $0>update-info -sed -e "1,${UPDATE_INFO_F}d" -f $TMP_SED $0>update-info.f -chmod +x update-info update-info.f -echo "installed update-info, and update-info.f into `pwd`" -rm -f $TMP_FILES -exit - -# _file: 'update-info'_ -#!/bin/sh -#update-info (GNU texinfo @TEXINFO_VERSION@) @UPDATE_INFO_VERSION@ -#Copyright (C) 1997 Free Software Foundation, Inc. -#update-info comes with NO WARRANTY, to the extent permitted by law. -#You may redistribute copies of update-info -#under the terms of the GNU General Public License. -#For more information about these matters, see the files named COPYING." -#Author: Richard L. Hawes - -# ###SECTION 1### Constants -set -h 2>/dev/null -# ENVIRONMENT -if test -z "$TMPDIR"; then - TMPDIR="/usr/tmp" -fi -if test -z "$LINES"; then - LINES=24 -fi -if test -z "$COLUMNS"; then - COLUMNS=80 -fi -if test -z "$EDITOR"; then - EDITOR=vi -fi -if test -z "$LINENO"; then - LINENO="0" -fi -# constants redefined by update-info.f -PROMPT1="(y=yes, Y=yes to all, n=no, N=No to all):" -FUNCTIONS="" -# -ARGUMENTS="$*" -DISPLAY_NUM=`expr "$LINES" - 4` -CONTROL_D="{Ctrl-D}" -DIR_SECTION="^INFO-DIR-SECTION" -ENTRY_END="^END-INFO-DIR-ENTRY" -ENTRY_START="^START-INFO-DIR-ENTRY" -MENU_BEGIN='^\*\([ ]\)\{1,\}Menu:' -MENU_ITEM='^\* ([^ ]).*:([ ])+\(' -SECTION_TITLE="^[A-Za-z0-9]" -MENU_FILTER1='s/^\*\([ ]\)\{1,\}/* /' -MENU_FILTER2='s/\([ ]\)\{1,\}$//g' -TMP_ITEM="${TMPDIR}/ui${$}.info" -TMP_LIST="${TMPDIR}/ul${$}.info" -TMP_MENU="${TMPDIR}/um${$}.info" -TMP_SECTIONS="${TMPDIR}/us${$}.info" # used only in Detect_Missing -TMP_SED="$TMP_SECTIONS" # used only in Detect_Invalid routines -TMP_FILE1="${TMPDIR}/ux${$}.info" -TMP_FILE2="${TMPDIR}/uy${$}.info" -TMP_COUNT="$TMP_FILE2" -TMP_FILE_LIST="$TMP_LIST $TMP_MENU $TMP_SECTIONS $TMP_FILE1 $TMP_FILE2\ - $TMP_ITEM" -TRY_HELP_MSG="Try --help for more information" -if zcat --version 2>/dev/null>/dev/null; then - CAT_COMMAND="zcat -f" -else - echo "$0:$LINENO: GNU zcat not found">&2 - CAT_COMMAND="cat" -fi - -# ###SECTION 100### main program -#variables set by options -Create_Node="" -Debug=":" -Interactive="" -Load_Functions="y" -Mode="" -# -Inserts="0" -Inserts_Total="0" -Invalid="0" -Invalid_Total="0" -Changed="" - -while test "$*" - do - case "$1" in - -c) Create_Node="y";; - -ci|-ic) Create_Node="y"; Interactive="y";; - -cif|-cfi|-ifc|-icf|-fci|-fic) Create_Node="y" - Interactive="y"; Load_Functions="";; - --debug) set -eux; Debug="set>&2";; - -d|--delete) Mode="Detect_Invalid";; - -f) Load_Functions="";; - -i|--interactive) Interactive="y";; - -fi|-if) Load_Functions=""; Interactive="y";; - -id|-di) Mode="Detect_Invalid"; Interactive="y";; - +i|+d|+f);; - --version) -cat<<VersionEOF -update-info (GNU texinfo @TEXINFO_VERSION@) @UPDATE_INFO_VERSION@ -Copyright (C) 1997 Free Software Foundation, Inc. -update-info comes with NO WARRANTY, to the extent permitted by law. -You may redistribute copies of update-info -under the terms of the GNU General Public License. -For more information about these matters, see the files named COPYING. -Author: Richard L. Hawes -VersionEOF - exit;; - - --help) -cat<<HelpEndOfFile -Usage: update-info [OPTION]... INFO_PATH/INFO_DIR_FILE - -It detects and inserts missing menu items into the info node file. - -Options: --c create a new info node - --debug print debug information to standard error path --d, --delete delete invalid menu items (ignore missing menu items) --f do not load functions (file update-info.f) - --help print this help message and exit --i, --interactive interactive mode prompts before inserting or removing - menu items - --version print current version and exit -Backup of the info node has a '.old' suffix added. This is a shell script. -Files: update-info.f -- contains functions (optional). -Environment Variables: COLUMNS, EDITOR, LINES, TMPDIR -Email bug reports to bug-texinfo@gnu.org. -HelpEndOfFile - exit;; - - [-+]*) echo "$0:$LINENO: \"$1\" is not a valid option">&2 - echo "$TRY_HELP_MSG">&2 - exit 2;; - *) break;; - esac - shift - done - -if test "$#" -lt "1"; then - echo "$0:$LINENO: Too few parameters">&2 - echo "$TRY_HELP_MSG">&2 - exit 2 -elif test "$#" -gt "1"; then - echo "$0:$LINENO: Too many parameters">&2 - echo "$TRY_HELP_MSG">&2 - exit 2 -fi -Info_Path="$1" -Info_Node=`basename "$Info_Path"` -if echo "$Info_Node"|grep ".*dir$">/dev/null; then - : -else - echo "$0:$LINENO: $Info_Node is not a valid info node name">&2 - exit 2 -fi -Info_Pathname=`dirname "$Info_Path"` -cd "$Info_Pathname"||exit - -BACKUP_MSG="Backed up $Info_Node to ${Info_Node}.old." -HANGUP_MSG="Hang up on \"update-info $ARGUMENTS\"" -INSERT_MSG="menu item(s) were inserted (not counting duplicates)." -INSERT_MSG2="total menu item(s) were inserted into `pwd`/$Info_Node" -DELETE_MSG="invalid menu item(s) were removed (not counting duplicates)." -DELETE_MSG2="total invalid menu item(s) were removed from `pwd`/$Info_Node" - -if test "$Create_Node"; then - if test "$Mode"; then - echo "$0:$LINENO: ERROR: Illogical option combination: -d -c">&2 - echo "$TRY_HELP_MSG">&2 - exit 2 - fi - if test -f "$Info_Node"; then - rm -f ${Info_Node}.old - mv "$Info_Node" "${Info_Node}.old" - echo "$BACKUP_MSG" - fi - echo "Creating new Info Node: `pwd`/$Info_Node" -cat>$Info_Node<<NodeEndOfFile||exit - -This is the file .../info/dir, which contains the topmost node of the -Info hierarchy. The first time you invoke Info you start off -looking at that node, which is (dir)Top. - -File: dir Node: Top This is the top of the INFO tree - This (the Directory node) gives a menu of major topics. - Typing "d" returns here, "q" exits, "?" lists all INFO commands, "h" - gives a primer for first-timers, "mTexinfo<Return>" visits Texinfo topic, - etc. - Or click mouse button 2 on a menu item or cross reference to select it. - --- PLEASE ADD DOCUMENTATION TO THIS TREE. (See INFO topic first.) --- - -* Menu: The list of major topics begins on the next line. - -NodeEndOfFile -else - if test ! -f "$Info_Node"; then - echo "$0:$LINENO: $Info_Node is irregular or nonexistant">&2 - exit 2 - elif test ! -r "$Info_Node"; then - echo "$0:$LINENO: $Info_Node is not readable">&2 - exit 2 - elif test ! -w "$Info_Node"; then - echo "$0:$LINENO: $Info_Node is not writeable">&2 - exit 2 - fi -fi - -if test "$Load_Functions" -a "$Interactive" -a -z "$Mode"; then - if FUNCTIONS_VERSION=`( update-info.f )`; then - if test `echo "$FUNCTIONS_VERSION"\ - |cut -d' ' -f5` = "@UPDATE_INFO_VERSION@"; then - echo "Loading functions..." - . update-info.f - else - echo "$0:$LINENO: wrong version of update-info.f">&2 - echo "(functions were not loaded)">&2 - fi - else - echo "(functions were not loaded)">&2 - fi -fi - - -trap ' eval "$Debug"; rm -f $TMP_FILE_LIST; exit ' 0 -if test "$Interactive"; then - if test ! -t "1"; then - echo "$0:$LINENO: Cannot run in interactive mode "\ - "standard out is redirected">&2 - exit 2 - fi - trap ' ' 2 3 -else - trap ' rm -f $TMP_FILE_LIST - echo "$0:$LINENO: received INT signal. All edits are canceled.">&2 - exit ' 2 - trap ' rm -f $TMP_FILE_LIST - echo "$0:$LINENO: received QUIT signal. All edits are canceled.">&2 - exit ' 3 -fi -if test -z "$Mode"; then - trap ' - if test "$Changed"; then - { - echo $HANGUP_MSG - @F_INSERT_MISSING@ - Inserts_Total=`wc -c<"$TMP_COUNT"` - echo $Inserts_Total $INSERT_MSG2 - }|mail "$LOGNAME" - fi - rm -f $TMP_FILE_LIST - exit ' 1 -else - trap ' - if test "$Changed"; then - { - echo $HANGUP_MSG - @F_DELETE_INVALID@ - Invalid_Total=`wc -l<"$TMP_SED"` - echo $Invalid_Total $DELETE_MSG2 - }|mail $LOGNAME - fi - rm -f $TMP_FILE_LIST - exit ' 1 -fi - -sed -e "1,/$MENU_BEGIN/d" -e "$MENU_FILTER1" -e "$MENU_FILTER2"<$Info_Node\ -|tee $TMP_MENU\ -|sed -n -e '/\* /{ -s/).*$//g -s/\.gz$// -s/\.info$// -s/^.*(//p -}'|sort -u>$TMP_FILE1 -ls -F|sed -e '/\/$/d' -e '/[-.][0-9]/d'\ - -e '/:$/d' -e '/^$/d' -e "/^${Info_Node}~\$/d"\ - -e "/^${Info_Node}\$/d" -e "/^${Info_Node}.old\$/d"\ - -e 's/\.gz$//' -e 's/\.info$//'|sort>$TMP_FILE2 - -if test -z "$Mode"; then - #Detect Missing - comm -13 $TMP_FILE1 $TMP_FILE2>$TMP_LIST - cat</dev/null>$TMP_COUNT - #get sections, initialize variables - sed -n -e "/$SECTION_TITLE/p" "$TMP_MENU">"$TMP_SECTIONS" - Item_Num=`wc -l<"$TMP_SECTIONS"|tr -d ' '` - Item_Status=`echo\ - |awk "BEGIN{for(i=1;i<=${Item_Num};i++)printf(\"_\n\")}"` - Item_Dir="$Item_Num" - for Info_Name in `cat $TMP_LIST` - do - if test -r "$Info_Name"; then - Info_File="$Info_Name" - elif test -r "${Info_Name}.info"; then - Info_File="${Info_Name}.info" - elif test -r "${Info_Name}.gz"; then - Info_File="${Info_Name}.gz" - elif test -r "${Info_Name}.info.gz"; then - Info_File="${Info_Name}.info.gz" - else - echo "$0:$LINENO: can't find info file for ${Info_Name}?">&2 - fi - #generate menu item - echo|tr -d '\012'>$TMP_FILE1 - eval $CAT_COMMAND "$Info_File"\ - |sed -n -e "/$DIR_SECTION/w $TMP_FILE1"\ - -e "/$ENTRY_START/,/$ENTRY_END/{ - $MENU_FILTER1 - p - }"|awk "BEGIN{Mode=0} - /^$/{if(Mode==1)exit} - /^([ ])+([^ ])+/{if(Mode==1)print} - /^[^ ]/{if(Mode==1)exit} - /${MENU_ITEM}${Info_Name}\)\./{if(Mode==0){Mode++ - print} - else - exit}">"$TMP_ITEM" - if test ! -s "$TMP_ITEM"; then - echo "* $Info_Name: ($Info_Name).">"$TMP_ITEM" - fi - Item_Status=`echo "$Item_Status"|sed -e '1,$s/^./_/'` - if test -s "$TMP_FILE1"; then - Item_Section=`sed -e "s/$DIR_SECTION[ ]*//"\ - <$TMP_FILE1` - else - Item_Section=`echo "Miscellaneous"` - fi - Size=`echo "$Item_Section"|wc -l|tr -d ' '` - # initialize variables, check for new sections - Num1=1 - while test "$Num1" -le "$Size" - do - Item=`echo "$Item_Section"|sed -n -e "${Num1}p"` - if Num=`grep -in "^$Item$" "$TMP_SECTIONS"`; then - Num=`echo "$Num"|sed -e 's/:.*$//g'` - ##F#Set_Item - set "$Num" "X" - @SET_ITEM@ - else - set "$Item" - @F_ADD_SECTION@ - fi - Num1=`expr "$Num1" + "1"` - done - if test "$Interactive"; then - echo "$Item_Section" - cat "$TMP_ITEM" - echo "add menu item for $Info_File? " - while true - do - echo "$PROMPT1"|tr -d '\012' - read Answer - case $Answer in - y) break;; - e) - if test "$FUNCTIONS"; then - Select_Sections - break - else - echo "Can't edit. "\ - "Functions are not loaded.">&2 - fi;; - Y) Interactive=""; break;; - n) continue 2;; - N) break 2;; - *) echo "\"$Answer\" "\ - "is an invalid response">&2;; - esac - done - fi - if echo "$Item_Status"|grep '^X'>/dev/null; then - # edit $TMP_MENU - - Changed="y" - ( - trap ' ' 1 2 3 - Tmp_Var=`echo "$Item_Status"|tr -d '\012'` - Key=`awk -F':' ' FNR==1{ print $1}' $TMP_ITEM` - # add new sections to 'dir' file - if test "$Item_Num" -gt "$Item_Dir"; then - if test "$Item_Dir" -ne "0"; then - sed -e "1,${Item_Dir}d" -e 'i\ - -' "$TMP_SECTIONS">>"$TMP_MENU" - else - sed -e 'i\ - -' "$TMP_SECTIONS">>"$TMP_MENU" - fi - fi - # awk determines the insertion points for each section - awk -F":" "function Insert(Line){ - if(Mode==2){ - Mode=1;if(substr(\"$Tmp_Var\",Item++,1)==\"X\") - print Line - } - } - BEGIN{Mode=1;Item=1} - /$SECTION_TITLE/{Insert(FNR-1);if(Mode>=1)Mode=2} - /${MENU_ITEM}.*\)\./{if(\$1>Item_Name)Insert(FNR-1)} - /^$/{Insert(FNR-1)} - END{Insert(FNR)}" Item_Name="$Key" "$TMP_MENU"\ - |sort -nr|sed -e "s%\$% r $TMP_ITEM%"|sed -e '$a\ -w -' -e '$a\ -q -'|ed -s "$TMP_MENU" - echo "$Item_Status"|tr -cd "X">>$TMP_COUNT - ) - - Inserts=`expr "$Inserts" + "1"` - echo "$Info_File installed into section(s):"\ - |tr -d '\012' - echo "$Item_Status"|awk '/X/{printf(" %d", FNR)}' - echo - Item_Dir="$Item_Num" - else - echo "$Info_File not installed (no section selected)" - fi - done - # print summary - trap ' ' 1 2 3 - if test "$Changed"; then - @F_INSERT_MISSING@ - Inserts_Total=`wc -c<"$TMP_COUNT"|tr -d " "` - if test "$Inserts" -ne "$Inserts_Total"; then - echo "$Inserts $INSERT_MSG" - fi - echo "$Inserts_Total $INSERT_MSG2" - fi -else - # Detect Invalid - cat</dev/null>"$TMP_SED" - comm -23 $TMP_FILE1 $TMP_FILE2>$TMP_LIST - for Info_Name in `cat $TMP_LIST` - do - if test "$Interactive"; then - # display invalid menu item(s) - awk "BEGIN{Mode=1} - /^([ ])+([^ ])+/{if(Mode==2)print} - /^$/{if(Mode==2)Mode=1} - /$SECTION_TITLE/{Section=\$0} - /^[^ ]/{if(Mode==2)Mode=1} - /${MENU_ITEM}${Info_Name}\)\./{if(Mode==1){Mode++ - print Section - print}}" $TMP_MENU - echo "delete menu item for $Info_Name? " - while true - do - echo\ - "(y=yes, n=no, Y=yes to all, N=No to all):"\ - |tr -d '\012' - read Answer - case "$Answer" in - y) break;; - Y) Interactive=""; break;; - n) continue 2;; - N) break 2;; - *) echo "\"$Answer\" "\ - "is an invalid reponse">&2;; - esac - done - fi - # remove menu item from $TMP_MENU - Invalid=`expr "$Invalid" + "1"` - Changed="y" - ( - trap ' ' 1 2 3 - echo\ - "invalid menu item for $Info_Name removed from section(s):"\ - |tr -d '\012' - awk "function Delete(Last){ - printf(\"%d,%dd\n\",First,Last-1)>>\"$TMP_SED\"} - BEGIN{Mode=1;Section=0} - /^$/{if(Mode==2){Delete(FNR);Mode=1}} - /$SECTION_TITLE/{Section++} - /^[^ ]/{if(Mode==2){Delete(FNR);Mode=1}} - /${MENU_ITEM}${Info_Name}\)\./{if(Mode==1){ - First=FNR;printf(\" %d\",Section);Mode=2}} - END{if(Mode==2)Delete(FNR+1)}" $TMP_MENU - echo - ) - done - - # display a summary - trap ' ' 1 2 3 - if test "$Changed"; then - Invalid_Total=`wc -l<"$TMP_SED"|tr -d ' '` - @F_DELETE_INVALID@ - if test "$Invalid" -ne "$Invalid_Total"; then - echo "$Invalid $DELETE_MSG" - fi - echo "$Invalid_Total $DELETE_MSG2" - fi -fi -if test -z "$Changed"; then - echo "Nothing to do" -fi -rm -f $TMP_FILE_LIST -eval "$Debug" -exit 0 -# _file: 'update-info.f'_ -#update-info.f (GNU texinfo @TEXINFO_VERSION@) @UPDATE_INFO_VERSION@ -#Copyright (C) 1997 Free Software Foundation, Inc. -#update-info comes with NO WARRANTY, to the extent permitted by law. -#You may redistribute copies of update-info -#under the terms of the GNU General Public License. -#For more information about these matters, see the files named COPYING." -#Author: Richard L. Hawes - -# update-info.f functions for update-info - -# ###SECTION 1### functions used to insert missing menu items - -Set_Item (){ -# set item status -@SET_ITEM@ -} - -Add_Section (){ -# add a section -@F_ADD_SECTION@ -} - -# ###SECTION 2### functions for menu selection of sections - -Print (){ -# print a line without a linefeed -echo "$*"|tr -d '\012' -} - -Get_Answer (){ -# get an answer to question -_gs_Valid="$1" -_gs_Prompt="$2" -set -f -Answer="" -while test -z "$Answer" - do - Print "$_gs_Prompt" - if read Answer; then - : - else - Answer="$CONTROL_D" - echo - fi - if expr "$Answer" : "[$_gs_Valid]$">/dev/null; then - : - else - Print "\"$Answer\" is not a valid response! --">&2 - Answer="" - fi - done -set +f -} - -Do_Previous (){ -# go to previous screen -if test "$Previous"; then - Next="$Top_Item" - Top_Item="$Previous" - if Previous=`expr "$Top_Item" - "$DISPLAY_NUM"`; then - if test "$Previous" -le "0"; then - Previous="" - fi - else - Previous="" - fi -elif test "$Next"; then - Last_Page -else - Print "There is no previous page. ">&2 -fi -} - -Do_Next (){ -# process go to next -if test "$Next"; then - Previous="$Top_Item" - Top_Item="$Next" - Set_Next -elif test "$Previous"; then - Top_Item="1" - Previous="" - Set_Next -else - Print "There is no next page. ">&2 -fi -} - -Do_Add_Section (){ -# process add section command -echo -echo "Please enter the name of the new section:" -if read Answer; then - Answer=`echo "$Answer"\ - |sed -e 's/^\([ ]\)\{1,\}//g' -e "$MENU_FILTER2"` - if test "$Answer"; then - Add_Section "$Answer" - Last_Page - clear - fi -else - Answer="" -fi -if test -z "$Answer"; then - clear - Print "no section added. " -fi -} - -Do_Edit (){ -# process edit item command -if test -t "2"; then - _de_Done="" - cp "$TMP_ITEM" "$TMP_FILE1" - while test -z "$_de_Done" - do - eval $EDITOR "$TMP_FILE1" - clear - _de_Done="t" - if sed -n -e "$MENU_FILTER1" -e '1p' "$TMP_FILE1"\ - |egrep "${MENU_ITEM}${Info_Name}\)\.">/dev/null; then - : - else - sed -n -e '1p' "$TMP_FILE1" - echo "Pattern mismatch: `echo\ - "/${MENU_ITEM}${Info_Name}\)\./"\ - |tr -d "\011"`">&2 - echo - _de_Done="" - fi - if sed -n -e '2,$p' "$TMP_FILE1"|grep '^[^ ]'>&2; then - echo "These lines must have leading spaces">&2 - echo - _de_Done="" - fi - if test -z "$_de_Done"; then - Get_Answer "yn" "Invalid entry, cancel edits? (y or n):" - if test "y" = "$Answer"; then - clear - Print "Canceling edits -- invalid entry ">&2 - _de_Done="t" - fi - else - sed -e "$MENU_FILTER1" -e "$MENU_FILTER2" -e '/^$/d'\ - <"$TMP_FILE1">"$TMP_ITEM" - fi - done -else - Print "editor cannot run with error path redirected " -fi -} - -Do_Number (){ -# process number -_dn_Num="$1" -if test "$_dn_Num" -ge 1 -a "$_dn_Num" -le "$Item_Num"; then - if test `echo "$Item_Status"|sed -n -e "${_dn_Num}p"` = "_"; then - Set_Item "$_dn_Num" "X" - else - Set_Item "$_dn_Num" "_" - fi -else - Print "\"$_dn_Num\" is an invalid section number. ">&2 -fi -} - -Do_Help (){ -# process menu help -echo -echo "\ -Enter the following commands seperated -by spaces and terminated by<ENTER>: -# : (section number) toggle section -a : add a new section -e : edit item -- changes will not be - accepted if you change the - '(info_file_name).' or delete - the key parts: '*' 'Menu Name' ':' -h : get this help screen -n : next page -p : previous page -q : quit and do not put into menu -s : save and put into menu" -Print "Press enter to continue:" -read junk -clear -} - -Set_Next (){ -# determine value of Next -Next=`expr "$DISPLAY_NUM" + "$Top_Item"` -if test "$Next" -gt "$Item_Num"; then - Next="" -fi -} - -Last_Page (){ -# go to last page of menu -Top_Item=`echo|awk "BEGIN{printf(\"%d\", -int((${Item_Num}-1)/${DISPLAY_NUM})*${DISPLAY_NUM}+1)}"` -if test "$Top_Item" -gt "$DISPLAY_NUM"; then - Previous=`expr "$Top_Item" '-' "$DISPLAY_NUM"` -else - Previous="" -fi -Set_Next -} - -Select_Sections (){ -# prompt user for which sections -set -f -Top_Item="1" -Previous="" -Set_Next -clear -echo "Default sections are selected." -Done="" -while test -z "$Done" - do - awk "FNR==1{printf(\"%s\n\", substr(\$0,1,${COLUMNS}))}" $TMP_ITEM - Tmp_Var=`echo "$Item_Status"|tr -d '\012'` - awk "BEGIN{Max=$Top_Item+$DISPLAY_NUM} - FNR>=$Top_Item{if(FNR>=Max)exit - printf(\"%2d:%s %s\n\",FNR,substr(\"$Tmp_Var\",FNR,1), - substr(\$0,1,${COLUMNS}-5))}" "$TMP_SECTIONS" - echo "Enter 1-${Item_Num}, add, edit, help," - if test "$Previous" -o "$Next"; then - Print "next, previous, " - fi - Print "quit, save :" - read Command_List||Command_List="$CONTROL_D" - Command_List=`echo "$Command_List"\ - |tr '\011' ' '|tr ' ' '\012'|sed -e "/^$/d"` - clear - if test -z "$Command_List"; then - Help="y" - else - Help="" - fi - while test "$Command_List" - do - Command=`echo "$Command_List"|sed -n -e '1p'` - Command_List=`echo "$Command_List"|sed -e '1d'` - case "$Command" in - [0-9]|[0-9][0-9]) Do_Number "$Command";; - n*) Do_Next;; - p*) Do_Previous;; - a*) Do_Add_Section;; - e*) Do_Edit; break;; - h*) Help="y";; - s*) Done="s"; break;; - q*) Done="q" - Item_Status=`echo "$Item_Status"|sed -e '1,$s/^./_/'` - break;; - *) Print "$Command is not a valid command. ">&2 - Help="y";; - esac - done - if test "$Help"; then - Do_Help - fi - echo - done -set +f -# if new sections added, remove unused ones -if test "$Item_Num" -gt "$Item_Dir"; then - Tmp_Var=`echo "$Item_Status"|awk "FNR>$Item_Dir{ - if(\\$0==\"_\")printf(\"%d\n\", FNR)}"` - if test "$Tmp_Var"; then - Tmp_Var1=`echo "$Tmp_Var"|sed -e 's/$/d/'` - sed -e "$Tmp_Var1" "$TMP_SECTIONS">$TMP_FILE1 - cp $TMP_FILE1 "$TMP_SECTIONS" - Item_Status=`echo "$Item_Status"|sed -e "$Tmp_Var1"` - Tmp_Var="" - Tmp_Var1="" - Item_Num=`wc -l<"$TMP_SECTIONS"|tr -d ' '` - fi -fi -} - -# ###SECTION 100### Constants that redefine -PROMPT1="(y=yes, e=edit, Y=yes to all, n=no, N=No to all):" -FUNCTIONS="y" -# -echo "update-info.f (GNU texinfo @TEXINFO_VERSION@) @UPDATE_INFO_VERSION@" |