diff options
| author | ru <ru@FreeBSD.org> | 2002-03-25 13:08:32 +0000 |
|---|---|---|
| committer | ru <ru@FreeBSD.org> | 2002-03-25 13:08:32 +0000 |
| commit | 5500b59c459afe212e4ee8d1c1847e051a9b7653 (patch) | |
| tree | a83aebd48e0338a00136e68cbd70a1ef081175fc /contrib/texinfo/doc | |
| parent | 05f7b4b96773cc26ff78d5e68babd66861aa07a8 (diff) | |
| download | FreeBSD-src-5500b59c459afe212e4ee8d1c1847e051a9b7653.zip FreeBSD-src-5500b59c459afe212e4ee8d1c1847e051a9b7653.tar.gz | |
Import of stripped down GNU texinfo 4.1
Diffstat (limited to 'contrib/texinfo/doc')
| -rw-r--r-- | contrib/texinfo/doc/README | 14 | ||||
| -rwxr-xr-x | contrib/texinfo/doc/help2man | 515 | ||||
| -rw-r--r-- | contrib/texinfo/doc/info-stnd.texi | 438 | ||||
| -rw-r--r-- | contrib/texinfo/doc/info.1 | 10 | ||||
| -rw-r--r-- | contrib/texinfo/doc/info.texi | 1239 | ||||
| -rw-r--r-- | contrib/texinfo/doc/install-info.1 | 21 | ||||
| -rw-r--r-- | contrib/texinfo/doc/makeinfo.1 | 167 | ||||
| -rw-r--r-- | contrib/texinfo/doc/texindex.1 | 17 | ||||
| -rw-r--r-- | contrib/texinfo/doc/texinfo.txi | 2171 | ||||
| -rw-r--r-- | contrib/texinfo/doc/version-stnd.texi | 4 | ||||
| -rw-r--r-- | contrib/texinfo/doc/version.texi | 7 |
11 files changed, 2978 insertions, 1625 deletions
diff --git a/contrib/texinfo/doc/README b/contrib/texinfo/doc/README index c10fad9..9bd6390 100644 --- a/contrib/texinfo/doc/README +++ b/contrib/texinfo/doc/README @@ -1,6 +1,6 @@ This directory contains documentation on the Texinfo system and the TeX sources needed to process Texinfo sources. We recommend using the -texi2dvi included in the distribution to run a Texinfo manual through +texi2dvi included in this distribution to run a Texinfo manual through TeX to produce a DVI file. The .tex files are not installed automatically because TeX installations @@ -8,14 +8,14 @@ vary so widely. Installing them in the wrong place would give a false sense of security. So, you should simply cp *.tex to the appropriate place. If your installation follows the TeX Directory Structure standard (http://tug.org/tds/), this will be the directory -<texmf>/tex/texinfo/ for texinfo.tex and <texmf>/tex/plain/dvips/ for -epsf.tex. If you use the default installation paths, <texmf> will be -/usr/local/share/texmf. On systems with TeX preinstalled, as most -GNU/Linux distributions offer, <texmf> will often be something like -/usr/share/texmf. +TEXMF/tex/texinfo/ for texinfo.tex, TEXMF/tex/plain/dvips/ for epsf.tex, +and TEXMF/pdftex/plain/misc for pdfcolor.tex. If you use the default +installation paths, TEXMF will be /usr/local/share/texmf. On systems +with TeX preinstalled, as most GNU/Linux distributions offer, TEXMF +will often be something like /usr/share/texmf. It is also possible to put these .tex files in a `local' place instead -of overwriting existing ones, but it is more complicated. See your TeX +of overwriting existing ones, but this is more complicated. See your TeX documentation in general and the texmf.cnf file in particular for information. If you add files to your TeX installations, not just replace existing diff --git a/contrib/texinfo/doc/help2man b/contrib/texinfo/doc/help2man index d33f7cd..8f40e8d 100755 --- a/contrib/texinfo/doc/help2man +++ b/contrib/texinfo/doc/help2man @@ -1,7 +1,7 @@ #!/usr/local/bin/perl -w # Generate a short man page from --help and --version output. -# Copyright © 1997, 98, 99 Free Software Foundation, Inc. +# Copyright © 1997, 1998, 1999, 2000 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 @@ -18,6 +18,7 @@ # Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. # Written by Brendan O'Dea <bod@compusol.com.au> +# Available from ftp://ftp.gnu.org/gnu/help2man/ use 5.004; use strict; @@ -26,11 +27,11 @@ use Text::Tabs qw(expand); use POSIX qw(strftime setlocale LC_TIME); my $this_program = 'help2man'; -my $this_version = '1.013'; +my $this_version = '1.24'; my $version_info = <<EOT; -$this_program $this_version +GNU $this_program $this_version -Copyright (C) 1997, 98, 99 Free Software Foundation, Inc. +Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. @@ -49,95 +50,134 @@ Usage: $this_program [OPTION]... EXECUTABLE -o, --output=FILE send output to `FILE' -N, --no-info suppress pointer to Texinfo manual --help print this help, then exit - --version print $this_program program version number, then exit + --version print version number, then exit EXECUTABLE should accept `--help' and `--version' options. + +Report bugs to <bug-help2man\@gnu.org>. EOT my $section = 1; -my ($include, $opt_name, $opt_include, $opt_output, $opt_no_info); - -# Parse options. -Getopt::Long::config('bundling'); -GetOptions ( +my ($opt_name, @opt_include, $opt_output, $opt_no_info); +my %opt_def = ( 'n|name=s' => \$opt_name, 's|section=s' => \$section, - 'i|include=s' => \$include, - 'I|opt-include=s' => \$opt_include, + 'i|include=s' => sub { push @opt_include, [ pop, 1 ] }, + 'I|opt-include=s' => sub { push @opt_include, [ pop, 0 ] }, 'o|output=s' => \$opt_output, 'N|no-info' => \$opt_no_info, - help => sub { print $help_info; exit }, - version => sub { print $version_info; exit }, +); + +# Parse options. +Getopt::Long::config('bundling'); +GetOptions (%opt_def, + help => sub { print $help_info; exit }, + version => sub { print $version_info; exit }, ) or die $help_info; die $help_info unless @ARGV == 1; my %include = (); -my @include = (); # to retain order +my %append = (); +my @include = (); # retain order given in include file + +# Provide replacement `quote-regex' operator for pre-5.005. +BEGIN { eval q(sub qr { '' =~ $_[0]; $_[0] }) if $] < 5.005 } # Process include file (if given). Format is: # -# [section name] -# verbatim text +# [section name] +# verbatim text +# +# or +# +# /pattern/ +# verbatim text +# -if ($include or $opt_include) +while (@opt_include) { - if (open INC, $include || $opt_include) + my ($inc, $required) = @{shift @opt_include}; + + next unless -f $inc or $required; + die "$this_program: can't open `$inc' ($!)\n" + unless open INC, $inc; + + my $key; + my $hash = \%include; + + while (<INC>) { - my $sect; + # [section] + if (/^\[([^]]+)\]/) + { + $key = uc $1; + $key =~ s/^\s+//; + $key =~ s/\s+$//; + $hash = \%include; + push @include, $key unless $include{$key}; + next; + } - while (<INC>) + # /pattern/ + if (m!^/(.*)/([ims]*)!) { - if (/^\[([^]]+)\]/) + my $pat = $2 ? "(?$2)$1" : $1; + + # Check pattern. + eval { $key = qr($pat) }; + if ($@) { - $sect = uc $1; - $sect =~ s/^\s+//; - $sect =~ s/\s+$//; - next; + $@ =~ s/ at .*? line \d.*//; + die "$inc:$.:$@"; } - # Silently ignore anything before the first - # section--allows for comments and revision info. - next unless $sect; - - push @include, $sect unless $include{$sect}; - $include{$sect} ||= ''; - $include{$sect} .= $_; + $hash = \%append; + next; } - close INC; - - die "$this_program: no valid information found in `$include'\n" - unless %include; - - # Compress trailing blank lines. - for (keys %include) + # Check for options before the first section--anything else is + # silently ignored, allowing the first for comments and + # revision info. + unless ($key) { - $include{$_} =~ s/\n+$//; - $include{$_} .= "\n" unless /^NAME$/; + # handle options + if (/^-/) + { + local @ARGV = split; + GetOptions %opt_def; + } + + next; } + + $hash->{$key} ||= ''; + $hash->{$key} .= $_; } - else - { - die "$this_program: can't open `$include' ($!)\n" if $include; - } + + close INC; + + die "$this_program: no valid information found in `$inc'\n" + unless $key; +} + +# Compress trailing blank lines. +for my $hash (\(%include, %append)) +{ + for (keys %$hash) { $hash->{$_} =~ s/\n+$/\n/ } } # Turn off localisation of executable's ouput. @ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3; -# Turn off localisation of date (for strftime) +# Turn off localisation of date (for strftime). setlocale LC_TIME, 'C'; -# Expand tabs, strip trailing spaces and break into paragraphs -sub paragraphs { split /\n\n+/, join '', expand @_ } - -# Grab help and version paragraphs from executable -my @help = paragraphs `$ARGV[0] --help 2>/dev/null` - or die "$this_program: can't get `--help' info from $ARGV[0]\n"; - -my @version = paragraphs `$ARGV[0] --version 2>/dev/null` - or die "$this_program: can't get `--version' info from $ARGV[0]\n"; +# Grab help and version info from executable. +my ($help_text, $version_text) = map { + join '', map { s/ +$//; expand $_ } `$ARGV[0] --$_ 2>/dev/null` + or die "$this_program: can't get `--$_' info from $ARGV[0]\n" +} qw(help version); my $date = strftime "%B %Y", localtime; (my $program = $ARGV[0]) =~ s!.*/!!; @@ -165,7 +205,7 @@ if ($opt_output) # # and seperated from any copyright/author details by a blank line. -$_ = shift @version; +($_, $version_text) = split /\n+/, $version_text, 2; if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or /^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/) @@ -187,163 +227,245 @@ else $program =~ s!.*/!!; -# no info for `info' itself +# No info for `info' itself. $opt_no_info = 1 if $program eq 'info'; -# --name overrides --include contents -$include{NAME} = "$program \\- $opt_name" if $opt_name; +# --name overrides --include contents. +$include{NAME} = "$program \\- $opt_name\n" if $opt_name; -# Default (useless) NAME paragraph -$include{NAME} ||= "$program \\- manual page for $program $version"; +# Default (useless) NAME paragraph. +$include{NAME} ||= "$program \\- manual page for $program $version\n"; # Man pages traditionally have the page title in caps. my $PROGRAM = uc $program; -# Header. -print <<EOT; -.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version. -.TH $PROGRAM "$section" "$date" "$package $version" FSF -.SH NAME -$include{NAME} -EOT +# Extract usage clause(s) [if any] for SYNOPSIS. +if ($help_text =~ s/^Usage:( +(\S+))(.*)((?:\n(?: {6}\1| *or: +\S).*)*)//m) +{ + my @syn = $2 . $3; + + if ($_ = $4) + { + s/^\n//; + for (split /\n/) { s/^ *(or: +)?//; push @syn, $_ } + } -my $break; -my $accumulate = 1; -my @description = (); + my $synopsis = ''; + for (@syn) + { + $synopsis .= ".br\n" if $synopsis; + s!^\S*/!!; + s/^(\S+) *//; + $synopsis .= ".B $1\n"; + s/\s+$//; + s/(([][]|\.\.+)+)/\\fR$1\\fI/g; + s/^/\\fI/ unless s/^\\fR//; + $_ .= '\fR'; + s/(\\fI)( *)/$2$1/g; + s/\\fI\\fR//g; + s/^\\fR//; + s/\\fI$//; + s/^\./\\&./; + + $synopsis .= "$_\n"; + } + + $include{SYNOPSIS} ||= $synopsis; +} + +# Process text, initial section is DESCRIPTION. +my $sect = 'DESCRIPTION'; +$_ = "$help_text\n\n$version_text"; + +# Normalise paragraph breaks. +s/^\n+//; +s/\n*$/\n/; +s/\n\n+/\n\n/g; + +# Temporarily exchange leading dots, apostrophes and backslashes for +# tokens. +s/^\./\x80/mg; +s/^'/\x81/mg; +s/\\/\x82/g; + +# Start a new paragraph (if required) for these. +s/([^\n])\n(Report +bugs|Email +bug +reports +to|Written +by)/$1\n\n$2/g; sub convert_option; -# Output converted --help information. -for (@help) +while (length) { - chomp; + # Convert some standard paragraph names. + if (s/^(Options|Examples): *\n//) + { + $sect = uc $1; + next; + } - if (s/^Usage: +\S+ +(.*)\n?//) + # Copyright section + if (/^Copyright +[(\xa9]/) { - # Turn the usage clause into a synopsis. - my $synopsis = ''; - - do { - my $syn = $1; - $syn =~ s/(([][]|\.\.+)+)/\\fR$1\\fI/g; - $syn =~ s/^/\\fI/ unless $syn =~ s/^\\fR//; - $syn .= '\fR'; - $syn =~ s/\\fI( *)\\fR/$1/g; - - $synopsis .= ".br\n" unless $accumulate; - $synopsis .= ".B $program\n"; - $synopsis .= "$syn\n"; - $accumulate = 0; - } while s/^(?:Usage| *or): +\S+ +(.*)\n?//; - - # Include file overrides SYNOPSIS. - print ".SH SYNOPSIS\n", $include{SYNOPSIS} || $synopsis; - - # Dump any accumulated description text. - print ".SH DESCRIPTION\n"; - print @description; - - # Add additional description text from include file. - if ($include{DESCRIPTION}) + $sect = 'COPYRIGHT'; + $include{$sect} ||= ''; + $include{$sect} .= ".PP\n" if $include{$sect}; + + my $copy; + ($copy, $_) = split /\n\n/, $_, 2; + + for ($copy) { - print ".PP\n" unless $include{DESCRIPTION} =~ /^\..P/; - print $include{DESCRIPTION}; + # Add back newline + s/\n*$/\n/; + + # Convert iso9959-1 copyright symbol or (c) to nroff + # character. + s/^Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/mg; + + # Insert line breaks before additional copyright messages + # and the disclaimer. + s/(.)\n(Copyright |This +is +free +software)/$1\n.br\n$2/g; + + # Join hyphenated lines. + s/([A-Za-z])-\n */$1/g; } - $break = 1; - next unless $_; + $include{$sect} .= $copy; + $_ ||= ''; + next; } - # Accumulate text if the synopsis has not been produced yet. - if ($accumulate) + # Catch bug report text. + if (/^(Report +bugs|Email +bug +reports +to) /) { - push @description, ".PP\n" if @description; - push @description, "$_\n"; - next; + $sect = 'REPORTING BUGS'; } - # Convert some standard paragraph names - if (s/^(Options|Examples): *\n//) + # Author section. + elsif (/^Written +by/) { - print qq(.SH \U$1\n); - $break = ''; - next unless length; + $sect = 'AUTHOR'; } - # Catch bug report text. - if (/^Report bugs |^Email bug reports to /) + # Examples, indicated by an indented leading $, % or > are + # rendered in a constant width font. + if (/^( +)([\$\%>] )\S/) { - print qq(.SH "REPORTING BUGS"\n$_\n); - $break = ''; + my $indent = $1; + my $prefix = $2; + my $break = '.IP'; + $include{$sect} ||= ''; + while (s/^$indent\Q$prefix\E(\S.*)\n*//) + { + $include{$sect} .= "$break\n\\f(CW$prefix$1\\fR\n"; + $break = '.br'; + } + next; } - # Option subsections have second line indented. - if (s/^(\S.*)\n / /) + my $matched = ''; + $include{$sect} ||= ''; + + # Sub-sections have a trailing colon and the second line indented. + if (s/^(\S.*:) *\n / /) { - print qq(.SS "$1"\n); - $break = ''; + $matched .= $& if %append; + $include{$sect} .= qq(.SS "$1"\n); } - my $output = ''; - while (length) - { - my $indent = 0; + my $indent = 0; + my $content = ''; - # Tagged paragraph - if (s/^( +(\S.*?) +)(\S.*)\n?//) + # Option with description. + if (s/^( {1,10}([+-]\S.*?))(?:( +)|\n( {20,}))(\S.*)\n//) + { + $matched .= $& if %append; + $indent = length ($4 || "$1$3"); + $content = ".TP\n\x83$2\n\x83$5\n"; + unless ($4) { - $indent = length $1; - $output .= ".TP\n$2\n$3\n"; - $break = 1; + # Indent may be different on second line. + $indent = length $& if /^ {20,}/; } + } - # Indented paragraph - elsif (s/^( +)(\S.*)\n?//) - { - $indent = length $1; - $output .= ".IP\n$2\n"; - $break = 1; - } + # Option without description. + elsif (s/^ {1,10}([+-]\S.*)\n//) + { + $matched .= $& if %append; + $content = ".HP\n\x83$1\n"; + $indent = 80; # not continued + } - # Left justified paragraph - else - { - s/(.*)\n?//; - $output .= ".PP\n" if $break; - $output .= "$1\n"; - $break = 1; - } + # Indented paragraph with tag. + elsif (s/^( +(\S.*?) +)(\S.*)\n//) + { + $matched .= $& if %append; + $indent = length $1; + $content = ".TP\n\x83$2\n\x83$3\n"; + } + + # Indented paragraph. + elsif (s/^( +)(\S.*)\n//) + { + $matched .= $& if %append; + $indent = length $1; + $content = ".IP\n\x83$2\n"; + } + + # Left justified paragraph. + else + { + s/(.*)\n//; + $matched .= $& if %append; + $content = ".PP\n" if $include{$sect}; + $content .= "$1\n"; + } - # Continuations - $output .= "$1\n" while s/^ {$indent}(\S.*)\n?//; + # Append continuations. + while (s/^ {$indent}(\S.*)\n//) + { + $matched .= $& if %append; + $content .= "\x83$1\n" } - $_ = $output; + # Move to next paragraph. + s/^\n+//; - # Escape backslashes. - s/\\/\\e/g; + for ($content) + { + # Leading dot and apostrophe protection. + s/\x83\./\x80/g; + s/\x83'/\x81/g; + s/\x83//g; - # Convert options. - s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge; - print; -} + # Convert options. + s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge; + } -# Print any include items other than the ones we have already dealt -# with. -for (@include) -{ - print qq(.SH "$_"\n$include{$_}) - unless /^(NAME|SYNOPSIS|DESCRIPTION|SEE ALSO)$/; + # Check if matched paragraph contains /pat/. + if (%append) + { + for my $pat (keys %append) + { + if ($matched =~ $pat) + { + $content .= ".PP\n" unless $append{$pat} =~ /^\./; + $content .= $append{$pat}; + } + } + } + + $include{$sect} .= $content; } # Refer to the real documentation. -if ($include{'SEE ALSO'} or !$opt_no_info) +unless ($opt_no_info) { - print qq(.SH "SEE ALSO"\n); - print $include{'SEE ALSO'}, ".PP\n" if $include{'SEE ALSO'}; - - print <<EOT unless $opt_no_info; + $sect = 'SEE ALSO'; + $include{$sect} ||= ''; + $include{$sect} .= ".PP\n" if $include{$sect}; + $include{$sect} .= <<EOT; The full documentation for .B $program is maintained as a Texinfo manual. If the @@ -358,27 +480,34 @@ should give you access to the complete manual. EOT } -# Output converted --version information. -for (@version) -{ - chomp; - - # Join hyphenated lines. - s/([A-Za-z])-\n */$1/g; - - # Convert copyright symbol or (c) to nroff character. - s/Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/g; - - # Insert appropriate headings for copyright and author. - if (/^Copyright \\/) { print ".SH COPYRIGHT\n" } - elsif (/^Written +by/) { print ".SH AUTHOR\n" } - else { print ".PP\n"; } +# Output header. +print <<EOT; +.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version. +.TH $PROGRAM "$section" "$date" "$package $version" FSF +EOT - # Insert line breaks before additional copyright messages and the - # disclaimer. - s/(.)\n(Copyright |This is free software)/$1\n.br\n$2/g; +# Section ordering. +my @pre = qw(NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES); +my @post = ('AUTHOR', 'REPORTING BUGS', 'COPYRIGHT', 'SEE ALSO'); +my $filter = join '|', @pre, @post; - print "$_\n"; +# Output content. +for (@pre, (grep ! /^($filter)$/o, @include), @post) +{ + if ($include{$_}) + { + my $quote = /\W/ ? '"' : ''; + print ".SH $quote$_$quote\n"; + + for ($include{$_}) + { + # Replace leading dot, apostrophe and backslash tokens. + s/\x80/\\&./g; + s/\x81/\\&'/g; + s/\x82/\\e/g; + print; + } + } } exit; @@ -387,15 +516,15 @@ exit; # embolden. Option arguments get italicised. sub convert_option { - my $option = '\fB' . shift; + local $_ = '\fB' . shift; - $option =~ s/-/\\-/g; - unless ($option =~ s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/) + s/-/\\-/g; + unless (s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/) { - $option =~ s/=(.)/\\fR=\\fI$1/; - $option =~ s/ (.)/ \\fI$1/; - $option .= '\fR'; + s/=(.)/\\fR=\\fI$1/; + s/ (.)/ \\fI$1/; + $_ .= '\fR'; } - $option; + $_; } diff --git a/contrib/texinfo/doc/info-stnd.texi b/contrib/texinfo/doc/info-stnd.texi index c08a8a5..aaccfd2 100644 --- a/contrib/texinfo/doc/info-stnd.texi +++ b/contrib/texinfo/doc/info-stnd.texi @@ -6,13 +6,14 @@ @synindex fn cp @synindex ky cp @comment %**end of header -@comment $Id: info-stnd.texi,v 1.23 1999/06/25 21:57:04 karl Exp $ +@comment $Id: info-stnd.texi,v 1.33 2002/03/02 15:03:54 karl Exp $ -@include version.texi +@include version-stnd.texi @dircategory Texinfo documentation system @direntry -* Standalone info program: (info-stnd). Standalone Info-reading program. +* info standalone: (info-stnd). Read Info documents without Emacs. +* infokey: (info-stnd)Invoking infokey. Compile Info customizations. @end direntry @ifinfo @@ -22,7 +23,8 @@ 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, 97, 98, 99 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 93, 96, 97, 98, 99, +2001, 02 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 @@ -54,7 +56,7 @@ approved by the Free Software Foundation. @author Brian J. Fox (bfox@@gnu.org) @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 93, 97, 98, 99 Free Software Foundation +Copyright @copyright{} 1992, 93, 97, 98, 99, 2001, 02 Free Software Foundation This manual is for GNU Info version @value{VERSION}, @value{UPDATED}. @@ -75,6 +77,8 @@ except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end titlepage +@contents + @ifnottex @node Top @top GNU Info @@ -91,8 +95,7 @@ This manual is for Info version @value{VERSION}, updated @value{UPDATED}. * What is Info:: What is Info? * Invoking Info:: 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. +* Scrolling Commands:: Commands for reading the text within a node. * Node Commands:: Commands for selecting a new node. * Searching Commands:: Commands for searching an Info file. * Xref Commands:: Commands for selecting cross references. @@ -100,7 +103,9 @@ This manual is for Info version @value{VERSION}, updated @value{UPDATED}. * 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, +* Custom Key Bindings:: How to define your own key-to-command + bindings. +* Index:: Global index containing keystrokes, command names, variable names, and general concepts. @end menu @@ -120,7 +125,9 @@ that you read in Info. @node Invoking Info @chapter Invoking Info -@cindex invoking info + +@cindex Info, invoking +@cindex invoking Info @cindex command line options @cindex options, command line @cindex arguments, command line @@ -136,6 +143,7 @@ info [@var{option}]@dots{} [@var{menu-item}@dots{}] The program accepts the following options: @table @code +@anchor{--apropos} @item --apropos=@var{string} @cindex Searching all indices @cindex Info files@r{, searching all indices} @@ -147,6 +155,9 @@ you are not sure which Info file explains certain issues, this option is your friend. Note that if your system has a lot of Info files installed, searching all of them might take some time. +You can invoke the apropos command from inside Info; see +@ref{Searching Commands}. + @cindex directory path @item --directory @var{directory-path} @itemx -d @var{directory-path} @@ -229,6 +240,9 @@ another program as a way to provide online help, or as a quick way of starting to read an Info file at a certain node when you don't know the exact name of that node. +This command can also be invoked from inside Info; see @ref{Searching +Commands}. + @item --node @var{nodename} @itemx -n @var{nodename} @cindex node, selecting from the command line @@ -251,6 +265,18 @@ 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. +@cindex colors in man pages +@cindex ANSI escape sequences in man pages +@item --raw-escapes +@itemx -R +Do not remove ANSI escape sequences from man pages. Some versions of +Groff, the GNU document formatter, produce man pages with ANSI escape +sequences for bold, italics, and underlined characters, and for +colorized text. By default, Info removes those escape sequences +before it displays the man page. If your terminal supports these +escapes, use @code{--raw-escapes} to let the terminal handle them and +display the man pages with those attributes. + @cindex replaying recorded keystrokes @item --restore=@var{dribble-file} Read keystrokes from @var{dribble-file}, presumably recorded during @@ -300,6 +326,8 @@ Prints the version information of Info and exits. This option binds functions to keys differently, to emulate the key bindings of @code{vi} and Less. The default key bindings are generally modeled after Emacs. +(@xref{Custom Key Bindings}, +for a more general way of altering GNU Info's key bindings.) @item @var{menu-item} @cindex menu, following @@ -455,7 +483,8 @@ 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 + +@node Scrolling Commands @chapter Moving Text Within a Window @cindex scrolling @@ -470,17 +499,7 @@ with ``vi-like operation''. @table @asis @item @key{SPC} (@code{scroll-forward}) -@itemx @key{NEXT} (an arrow key) -@itemx @key{C-v} -@itemx @key{C-f}, vi-like operation -@itemx @key{f}, vi-like operation -@itemx @key{M-SPC}, vi-like operation @kindex SPC, in Info windows -@kindex NEXT -@kindex C-v -@kindex C-f, vi-like operation -@kindex f, vi-like operation -@kindex M-SPC, vi-like operation @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, @@ -490,46 +509,71 @@ argument of 4 would shift all of the text in the window up 4 lines 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. If you are at -the end of a node, SPC takes you to the ``next'' node, so that you can -read an entire manual from start to finish by repeating SPC. +the end of a node, @key{SPC} takes you to the ``next'' node, so that you can +read an entire manual from start to finish by repeating @key{SPC}. The default scroll size is one screen-full, but it can be changed by -invoking the (@code{scroll-forward-set-window}) command, @samp{z} under -@samp{--vi-keys}, with a numeric argument. +invoking the (@code{scroll-forward-page-only-set-window}) command, +@samp{z} under @samp{--vi-keys}, with a numeric argument. + +@item @key{NEXT} (an arrow key) (@code{scroll-forward-page-only}) +@itemx @key{C-v} +@itemx @key{C-f}, vi-like operation +@itemx @key{f}, vi-like operation +@itemx @key{M-SPC}, vi-like operation +@kindex NEXT +@kindex C-v +@kindex C-f, vi-like operation +@kindex f, vi-like operation +@kindex M-SPC, vi-like operation +@findex scroll-forward-page-only +Shift the text in this window up. This is identical to the @key{SPC} +operation above, except that it never scrolls beyond the end of the +current node. @kindex PageDown The @key{NEXT} key is known as the @key{PageDown} key on some -keyboards. When you use @key{NEXT} or @key{PageDown} to scroll, Info -never scrolls beyond the end of the current node. +keyboards. -@item @key{z} (@code{scroll-forward-set-window}, vi-like operation) +@item @key{z} (@code{scroll-forward-page-only-set-window}, vi-like operation) @kindex z, vi-like operation -@findex scroll-forward-set-window -Scroll forward, like with @key{SPC}, but if a numeric argument is +@findex scroll-forward-page-only-set-window +Scroll forward, like with @key{NEXT}, but if a numeric argument is specified, it becomes the default scroll size for subsequent -@code{scroll-forward} and @code{scroll-backward} commands. +@code{scroll-forward} and @code{scroll-backward} commands and their +ilk. @item @key{DEL} (@code{scroll-backward}) -@itemx @key{PREVIOUS} (arrow key) +@kindex DEL, in Info windows +@findex scroll-backward +Shift the text in this window down. The inverse of +@code{scroll-forward}. +If you are at the start of a node, @key{DEL} takes you to the +``previous'' node, so that you can read an entire manual from finish to +start by repeating @key{DEL}. The default scroll size can be changed by +invoking the (@code{scroll-backward-page-only-set-window}) command, +@samp{w} under @samp{--vi-keys}, with a numeric argument. + +@itemx @key{PREVIOUS} (arrow key) (@code{scroll-backward-page-only}) @itemx @key{PRIOR} (arrow key) @itemx @key{M-v} @itemx @key{b}, vi-like operation @itemx @key{C-b}, vi-like operation -@kindex DEL, in Info windows @kindex PREVIOUS @kindex M-v @kindex b, vi-like operation @kindex C-b, vi-like operation -@findex scroll-backward +@findex scroll-backward-page-only Shift the text in this window down. The inverse of -@code{scroll-forward}. The default scroll size can be changed by -invoking the(@code{scroll-backward-set-window}) command, @samp{w} under +@code{scroll-forward-page-only}. Does not scroll beyond the start of +the current node. The default scroll size can be changed by invoking +the(@code{scroll-backward-page-only-set-window}) command, @samp{w} under @samp{--vi-keys}, with a numeric argument. -@item @key{w} (@code{scroll-backward-set-window}, vi-like operation) +@item @key{w} (@code{scroll-backward-page-only-set-window}, vi-like operation) @kindex w, vi-like operation -@findex scroll-backward-set-window -Scroll backward, like with @key{DEL}, but if a numeric argument is +@findex scroll-backward-page-only-set-window +Scroll backward, like with @key{PREVIOUS}, but if a numeric argument is specified, it becomes the default scroll size for subsequent @code{scroll-forward} and @code{scroll-backward} commands. @@ -592,6 +636,9 @@ viewing the beginning of a node, what happens is controlled by the variable @code{scroll-behavior}. @xref{Variables, @code{scroll-behavior}}, for more information. +The @code{scroll-forward-page-only} and @code{scroll-backward-page-only} +commands never scroll beyond the current node. + @kindex PageUp The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or @@ -628,8 +675,9 @@ invisible. When long lines are truncated, the modeline displays the @samp{$} character near its left edge. @end table -@node Node Commands, Searching Commands, Scrolling Commands, Top -@chapter Selecting a New Node + +@node Node Commands +@chapter Selecting a Node @cindex nodes, selection of This section details the numerous Info commands which select a new node @@ -879,7 +927,8 @@ 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 + +@node Searching Commands @chapter Searching an Info File @cindex searching @@ -965,6 +1014,11 @@ where the found index entry points to. @findex next-index-match Move to the node containing the next matching index item from the last @samp{i} command. + +@item @kbd{M-x index-apropos} +@findex index-apropos +Grovel the indices of all the known Info files on your system for a +string, and build a menu of the possible matches. @end table The most basic searching command is @samp{s} or @samp{/} @@ -993,7 +1047,23 @@ even for a string that includes only lower-case letters, by using the @samp{N} commands operate case-sensitively if the last search command was @samp{S}. -@node Xref Commands, Window Commands, Searching Commands, Top +The most efficient means of finding something quickly in a manual is +the @samp{i} command (@code{index-search}). This command prompts for +a string, and then looks for that string in all the indices of the +current Info manual. If it finds a matching index entry, it displays +the node to which that entry refers and prints the full text of the +entry in the echo area. You can press @samp{,} +(@code{next-index-match}) to find more matches. A good Info manual +has all of its important concepts indexed, so the @samp{i} command +lets you use a manual as a reference. + +If you don't know what manual documents something, try the @kbd{M-x +index-apropos}. It prompts for a string and then looks up that string +in all the indices of all the Info documents installed on your system. +It can also be invoked from the command line; see @ref{--apropos}. + + +@node Xref Commands @chapter Selecting Cross References We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} @@ -1144,7 +1214,8 @@ On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for Select the menu item or note reference appearing on this line. @end table -@node Window Commands, Printing Nodes, Xref Commands, Top + +@node Window Commands @chapter Manipulating Multiple Windows @cindex windows, manipulating @@ -1530,8 +1601,9 @@ 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 + +@node Printing Nodes +@chapter Printing Nodes @cindex printing In general, we recommend that you use @TeX{} to format the document and @@ -1559,7 +1631,8 @@ under the assumption that text written to that file will be printed by the underlying OS. @end table -@node Miscellaneous Commands, Variables, Printing Nodes, Top + +@node Miscellaneous Commands @chapter Miscellaneous Commands GNU Info contains several commands which self-document GNU Info: @@ -1729,7 +1802,8 @@ 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 + +@node Variables @chapter Manipulating Variables GNU Info contains several @dfn{variables} whose values are looked at by @@ -1737,6 +1811,10 @@ 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. +There are two ways to set the value of a variable: interactively, using +the @code{set-variable} command described below, or in the @code{#var} +section of the @code{.infokey} file. @xref{Custom Key Bindings}. + @table @asis @item @kbd{M-x set-variable} @cindex variables, setting @@ -1781,15 +1859,6 @@ 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 @@ -1810,15 +1879,14 @@ 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 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. @item scroll-behavior @vindex scroll-behavior @@ -1858,16 +1926,234 @@ 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. +@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 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}. + +@end table + + +@node Custom Key Bindings +@chapter Customizing Key Bindings and Variables + +@cindex default key bindings, overriding +@cindex overriding default key bindings +@cindex customizing key bindings +@cindex key bindings, customizing +@cindex infokey +@cindex .info +@cindex .infokey +@cindex _info file (MS-DOS) + +For those whose editor/pager of choice is not Emacs and who are not +entirely satisfied with the --vi-keys option (@pxref{--vi-keys}), GNU +Info provides a way to define different key-to-command bindings and +variable settings from the defaults described in this document. + +On startup, GNU Info looks for a configuration file in the invoker's +HOME directory called @file{.info}@footnote{Due to the limitations of +DOS filesystems, the MS-DOS version of Info looks for a file +@file{_info} instead. If the @env{HOME} variable is not defined, Info +additionally looks in the current directory.}. If it is present, and +appears to contain Info configuration data, and was created with the +current version of the @code{infokey} command, then Info adopts the +key bindings and variable settings contained therein. + +The @file{.info} file contains compact, non-textual data for reasons of +efficiency and because its design was lifted wholesale from the GNU Less +program, which also does it that way. It must be created by compiling a +textual source file using the @code{infokey} command. + +@menu +* Invoking infokey:: +* infokey source format:: +@end menu + + +@node Invoking infokey +@section Invoking @command{infokey} + +@cindex invoking infokey +@cindex infokey, invoking +@cindex _infokey file (MS-DOS) + +@command{infokey} compiles a source file +(@file{$HOME/.infokey}@footnote{This file is named @file{_infokey} in +the MS-DOS version, and is looked for in the current directory if +@env{HOME} is undefined.} by default) containing Info customizations +into a binary format (@file{$HOME/.info} by default). GNU Info reads +the binary file at startup to override the default key bindings and +variable definitions. Synopsis: + +@example +infokey [@var{option}@dots{}] [@var{input-file}] +@end example + +Besides the standard @option{--help} and @option{--version}, the only +option is @option{--output @var{file}}. This tells @command{infokey} to +write the binary data to @var{file} instead of @file{$HOME/.info}. + + +@node infokey source format +@section @command{infokey} source format + +@cindex infokey source format +@cindex .infokey source format +@cindex format of .infokey source + +The format of the source file read by @command{infokey} is most easily +illustrated by example. For instance, here is a sample @file{.infokey} +source file suitable for aficionados of @command{vi} or @command{less}: + +@example +#info +j next-line +k prev-line +l forward-char +h backward-char +\kd next-line +\ku prev-line +\kr forward-char +\kl backward-char +\ scroll-forward +\kD scroll-forward-page-only +b scroll-backward +\kU scroll-backward-page-only +g beginning-of-node +\kh beginning-of-node +G end-of-node +\ke end-of-node +\t select-reference-this-line +- history-node +n next-node +p prev-node +u up-node +t top-node +d dir-node +#var +scroll-step=1 +@end example + +The source file consists of one or more @dfn{sections}. +Each section starts with a line that identifies the type of section. +Possible sections are: + +@table @code +@item #info +Key bindings for Info windows. +The start of this section is indicated by a line containing just +@code{#info} by itself. If this is the first section in the source +file, the @code{#info} line can be omitted. The rest of this section +consists of lines of the form: + +@example +@var{string} whitespace @var{action} [ whitespace [ # comment ] ] newline +@end example + +Whitespace is any sequence of one or more spaces and/or tabs. Comment +is any sequence of any characters, excluding newline. @var{string} is +the key sequence which invokes the action. @var{action} is the name of +an Info command. The characters in @var{string} are interpreted +literally or prefixed by a caret (@code{^}) to indicate a control +character. A backslash followed by certain characters specifies input +keystrokes as follows: + +@table @code +@item \b +Backspace +@item \e +Escape (ESC) +@item \n +Newline +@item \r +Return +@item \t +Tab +@item \ku +Up arrow +@item \kd +Down arrow +@item \kl +Left arrow +@item \kr +Right arrow +@item \kU +Page Up +@item \kD +Page Down +@item \kh +HOME +@item \ke +END +@item \kx +Delete (DEL) +@item \m@var{x} +Meta-@var{x} where @var{x} is any character as described above. +@end table + +Backslash followed by any other character indicates that character is to +be taken literally. Characters which must be preceded by a backslash +include caret, space, tab, and backslash itself. + +@item #echo-area +Key bindings for the echo area. +The start of this section is indicated by a line containing just +@code{#echo-area} by itself. The rest of this section has a syntax +identical to that for the key definitions for the Info area, described +above. + +@item #var +Variable initializations. +The start of this section is indicated by a line containing just +@code{#var} by itself. Following this line is a list of variable +assignments, one per line. Each line consists of a variable name +(@xref{Variables},) followed by @code{=} followed by a value. +There may be no white space between the variable name and the @code{=}, +and all characters following the @code{=}, including white space, +are included in the value. @end table +Blank lines and lines starting with @code{#} are ignored, except for +the special section header lines. + +Key bindings defined in the @file{.info} file take precedence over GNU +Info's default key bindings, whether or not @samp{--vi-keys} is used. A +default key binding may be disabled by overriding it in the @file{.info} +file with the action @code{invalid}. In addition, @emph{all} default +key bindings can be disabled by adding this line @emph{anywhere} in the +relevant section: + +@example +#stop +@end example + +This will cause GNU Info to ignore all the default key commands for that +section. + +Beware: @code{#stop} can be dangerous. Since it disables all default +key bindings, you must supply enough new key bindings to enable all +necessary actions. Failure to bind any key to the @code{quit} command, +for example, can lead to frustration. + +The order in which key bindings are defined in the @file{.info} file is +not important, except that the command summary produced by the +@code{get-help-window} command only displays the @emph{first} key that +is bound to each command. @c the following is incomplete @@ -1916,10 +2202,10 @@ Building DIR on the fly. Some common ways to organize Info files. @end ignore -@node GNU Info Global Index, , Variables, Top -@appendix Global Index + +@node Index +@appendix Index @printindex cp -@contents @bye diff --git a/contrib/texinfo/doc/info.1 b/contrib/texinfo/doc/info.1 index f572a4f..6221075 100644 --- a/contrib/texinfo/doc/info.1 +++ b/contrib/texinfo/doc/info.1 @@ -1,12 +1,11 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. -.TH INFO "1" "September 1999" "GNU texinfo 4.0" FSF +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24. +.TH INFO "1" "March 2002" "GNU texinfo 4.1" FSF .SH NAME info \- read Info documents .SH SYNOPSIS .B info [\fIOPTION\fR]... [\fIMENU-ITEM\fR...] .SH DESCRIPTION -.PP Read documentation in Info format. .SH OPTIONS .TP @@ -34,6 +33,9 @@ specify nodes in first visited Info file. \fB\-\-output\fR=\fIFILENAME\fR output selected nodes to FILENAME. .TP +\fB\-\-raw\-escapes\fR +don't remove ANSI escapes from man pages. +.TP \fB\-\-restore\fR=\fIFILENAME\fR read initial keystrokes from FILENAME. .TP @@ -74,7 +76,7 @@ show file ./foo.info, not searching dir Email bug reports to bug-texinfo@gnu.org, general questions and discussion to help-texinfo@gnu.org. .SH COPYRIGHT -Copyright \(co 1999 Free Software Foundation, Inc. +Copyright \(co 2002 Free Software Foundation, Inc. There is NO warranty. You may redistribute this software under the terms of the GNU General Public License. For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/info.texi b/contrib/texinfo/doc/info.texi index c81bfd2..73a7033 100644 --- a/contrib/texinfo/doc/info.texi +++ b/contrib/texinfo/doc/info.texi @@ -2,8 +2,11 @@ @comment %**start of header @setfilename info.info @settitle Info +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp @comment %**end of header -@comment $Id: info.texi,v 1.11 1999/04/19 21:37:23 karl Exp $ +@comment $Id: info.texi,v 1.22 2002/02/09 00:54:34 karl Exp $ @dircategory Texinfo documentation system @direntry @@ -14,72 +17,84 @@ This file describes how to use Info, the on-line, menu-driven GNU documentation system. -Copyright (C) 1989, 92, 96, 97, 98, 99 Free Software Foundation, Inc. +Copyright (C) 1989, 92, 96, 97, 98, 99, 2000, 2001 +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). +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs 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. +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' -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. +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. @end ifinfo @titlepage @title Info -@subtitle The online, menu-driven GNU documentation system +@subtitle The online, hyper-text GNU documentation system @author Brian Fox +@author and the GNU Texinfo community @page @vskip 0pt plus 1filll -Copyright @copyright{} 1989, 92, 93, 96, 97, 98, 99 Free Software -Foundation, Inc. +Copyright @copyright{} 1989, 92, 93, 96, 97, 98, 99, 2000, 2001 +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. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. @end titlepage @ifnottex @node Top @top Info: An Introduction -Info is a program for reading documentation, which you are using now. +Info is a program, which you are using now, for reading documentation of +computer programs. The GNU Project distributes most of its on-line +manuals in the Info format, so you need a program called @dfn{Info +reader} to read the manuals. One of such programs you are using now. + +@ifinfo +If you are new to Info and want to learn how to use it, type the +command @kbd{h} now. It brings you to a programmed instruction +sequence. -To learn how to use Info, type the command @kbd{h}. It brings you -to a programmed instruction sequence. +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 @end ifnottex @menu * Getting Started:: Getting started using an Info reader. * Advanced Info:: Advanced commands within Info. * Creating an Info File:: How to make your own Info file. +* Index:: An index of topics, commands, and variables. @end menu @node Getting Started, Advanced Info, Top, Top @@ -89,28 +104,31 @@ to a programmed instruction sequence. 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 +file. The third part briefly explains 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 +@ifnotinfo +This manual is primarily designed for browsing with an Info reader +program on a computer, so that you can try Info commands while reading +about them. Reading it on paper or with an HTML browser 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. +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. +@cindex Info reader, how to invoke +@cindex entering Info 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. +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. +Type @code{emacs} at the command line; then type @kbd{C-h i} +(@kbd{Control-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 @@ -121,88 +139,93 @@ the screen. @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 +@end ifnotinfo @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-^L:: The Space, DEL, B and ^L commands. * Help-M:: Menus -* Help-Adv:: Some advanced Info commands +* Help-Xref:: Following cross-references +* Help-Int:: Some intermediate Info commands * Help-Q:: Quitting Info @end menu -@node Help-Small-Screen, Help, , Getting Started -@comment node-name, next, previous, up +@node Help-Small-Screen @section Starting Info on a Small Screen -@iftex +@ifnotinfo (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 +@end ifnotinfo -Since your terminal has an unusually small number of lines on its +@cindex small screen, moving around +Since your terminal has a relatively 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 +If you see the text @samp{--All----} 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}. +and see another screen full, press @key{SPC}, the Space bar. To move +back up, press the key labeled @samp{Backspace} or @samp{DEL} (on some +keyboards, this key might be labeled @samp{Delete}). @ifinfo -Here are 40 lines of junk, so you can try Spaces and Deletes and +Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} 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 @* +@format +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 +This is line 57 +This is line 58 +This is line 59 +@end format 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. +@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you +understand the about the @samp{Space} and @samp{Backspace} keys. 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 @@ -211,124 +234,221 @@ get to the normal start of the course. You are talking to the program Info, for reading documentation. +@cindex node, in Info documents 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''. +level of detail. This node's topic is ``how to use Info''. The mode +line says that this is node @samp{Help} in the file @file{info}. +@cindex header of Info node 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 +it now) 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. - +whose name you know. In the stand-alone Info reader program, the +header line shows the names of this node and the info file as well. +In Emacs, the header line is displayed in a special typeface, and it +doesn't scroll off the screen when you scroll the display. The names +of this node and of its Info file are omitted by Emacs from the header +line. + + Besides a @samp{Next}, a node can have a @samp{Previous} or an +@samp{Up} links, or both. As you can see, this node has all of these +links. + +@kindex n @r{(Info mode)} 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; +@format +>> Type @kbd{n} to move there. Type just one character; do not type the quotes and do not type a @key{RET} afterward. +@end format +@noindent @samp{>>} in the margin means it is really time to try a command. +@format +>> If you have a mouse, and if you already practiced typing @kbd{n} + to get to the next node, click now with the right mouse button on + the @samp{Next} link to do the same ``the mouse way''. +@end format + @node Help-P, Help-^L, Help, Getting Started @comment node-name, next, previous, up @section Returning to the Previous node +@kindex p @r{(Info mode)} 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. +node, @samp{Help-^L}. In Emacs, @kbd{n} runs the Emacs command +@code{Info-next}, and @kbd{p} runs @code{Info-prev}. + +@format +>> But do not type @kbd{n} yet. First, try the @kbd{p} command, + or click the mouse on the @samp{Prev} link, which takes you to the + @samp{Previous} node. When you get there, you can do an @kbd{n} + again to return here. +@end format + + If you read this in Emacs, you will see an @samp{Info} item in the +menu bar, close to its right edge. Clicking your mouse on the +@samp{Info} menu-bar item opens a menu of commands which include +@samp{Next} and @samp{Prev} (and also some others which you didn't yet +learn about). 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. +@format +>> Now do an @kbd{n}, or click the mouse on the @samp{Next} link, to + get to the node @samp{Help-^L} and learn more. +@end format @node Help-^L, Help-M, Help-P, Getting Started @comment node-name, next, previous, up -@section The Space, Delete, B and ^L commands. +@section The Space, DEL, 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 node's mode line tells you that you are now at node @samp{Help-^L}, +and the header line tells you 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}). - +@kindex SPC @r{(Info mode)} +@kindex DEL @r{(Info mode)} +@kindex BACKSPACE @r{(Info mode)} +@findex Info-scroll-up +@findex Info-scroll-down + The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which +we call ``Backspace or DEL'' in this manual is labeled differently on +different keyboards. Look for a key which is a little ways above the +@key{ENTER} or @key{RET} key and which you normally use outside Emacs +to erase the character before the cursor, i.e.@: the character you +typed last. It might be labeled @samp{Backspace} or @samp{<-} or +@samp{DEL}, or sometimes @samp{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. @key{SPC} moves forward, to show what was below the +bottom of the screen. @key{DEL} or @key{BACKSPACE} 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). In Emacs, @key{SPC} runs +the command @code{Info-scroll-up}, while @key{BACKSPACE} runs +@code{Info-scroll-down}. + +@format +>> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to + return here). +@end format + + When you type the @key{SPC}, the two lines that were at the bottom of +the screen appear at the top, followed by more lines. @key{DEL} or +@key{BACKSPACE} 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 are reading this in Emacs, note that the header line is +always visible, never scrolling off the display. That way, you can +always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you +can conveniently go to one of these links from anywhere in the node by +clicking the mouse on one of these links. + +@cindex reading Info documents top to bottom +@cindex Info documents as tutorials + @key{SPC} and @key{DEL} not only move forward and backward through +the current node. When these keys hit the beginning or the end of the +current node, they move to preceding or subsequent nodes. +Specifically, they scroll through all the nodes in an Info file as a +single logical sequence. In this sequence, a node's subnodes appear +following their parent. If a node has a menu, @key{SPC} takes you +into the subnodes listed in the menu, one by one. Once you reach the +end of a node, and have seen all of its subnodes, @key{SPC} takes you +to the next node or to the parent's next node. This is so you could +read the entire manual top to bottom by just typing @key{SPC}. + +@kindex PAGEUP @r{(Info mode)} +@kindex PAGEDOWN @r{(Info mode)} + Many keyboards nowadays have two scroll keys labeled @samp{PageUp} +and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}). If your +keyboard has these keys, you can use them to move forward and backward +through the text, like with @key{SPC} and @key{BACKSPACE}. However, +unlike @key{SPC} and @key{BACKSPACE}, @key{PAGEUP} and @key{PAGEDOWN} +keys will never scroll beyond the beginning or the end of the current +node. + +@kindex C-l @r{(Info mode)} + If your screen is ever garbaged, you can tell Info to display it +again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down +@key{CTRL} and type @kbd{L} or @kbd{l}). + +@format >> Type @kbd{C-l} now. +@end format +@kindex b @r{(Info mode)} 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. +a lot of @key{BACKSPACE} keys. You can also type simply @kbd{b} for +beginning. + +@format >> 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. + 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 @key{SPS}s. +@end format 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? +In that case, @kbd{b} won't do anything. Sorry; what can we do? +@kindex ? @r{(Info mode)} +@findex Info-summary 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 pressing @key{SPC} -repeatedly. +a @kbd{?} (in Emacs it runs the @code{Info-summary} command) which +displays a brief list of commands. When you are finished looking at +the list, make it go away by typing a @key{SPC} repeatedly. +@format >> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of ->> the list until finished. + the list until finished. Then type @key{SPC} several times, until + it goes away. +@end format + + (If you are using the stand-alone Info reader, type @kbd{C-x 0} to +return here, that is---press and hold @key{CTRL}, type an @kbd{x}, +then release @key{CTRL} and @kbd{x}, and press @kbd{0}---a zero, not +the letter ``o''.) 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 +will be expected to know how to use @key{SPC} and @key{BACKSPACE} 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. +@format +>> Now type @kbd{n}, or click the mouse on the @samp{Next} link, to + see the description of the @kbd{m} command. +@end format -@node Help-M, Help-Adv, Help-^L, Getting Started +@node Help-M, Help-Xref, 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. +@section Menus and the @kbd{m} command + +@cindex menus in an Info document +@cindex Info menus + With only the @kbd{n} (next) and @kbd{p} (previous) 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 @@ -339,13 +459,13 @@ 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 +* Foo: Node about FOO 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:}.]] +The subtopic name is Foo, and the node describing it is @samp{Node +about FOO}. 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 @@ -366,37 +486,42 @@ abbreviation for this: 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 +@format +>> Now use @key{SPC} to find the menu in this node, then come back to + the front with a @kbd{b} and some @key{SPC}s. 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. +@end format +@kindex m @r{(Info mode)} 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. +not do it yet!} Before you use @kbd{m}, you need to learn about +commands which prompt you for more input. So far, you have learned +several commands that do not need additional input; when you typed +one, Info processed it and was 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 +or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains text ending +in a colon, it means Info is trying to read more input for the last command. At such times, commands do not work, because Info tries to -use them as the argument. You must either type the argument and +use them as the input it needs. You must either type your response 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. +@findex Info-menu 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}. +a @key{RET}. In Emacs, @kbd{m} runs the command @code{Info-menu}. +@cindex abbreviating Info subnodes 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 @@ -406,14 +531,15 @@ 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. +@cindex completion of Info node names 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 +name. If you type the @key{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. +not need to type the argument: you just type a @key{RET}, and it +stands for the subtopic of the line you are on. Here is a menu to give you a chance to practice. This menu gives you three ways of going to one place, Help-FOO: @@ -424,66 +550,191 @@ three ways of going to one place, Help-FOO: * Help-FOO:: And yet another! @end menu +@format >> Now type just an @kbd{m} and see what happens: +@end format 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. + You can change your mind about doing the @kbd{m} by typing +@kbd{Control-g}. +@format >> Try that now; notice the bottom line clear. +@end format +@format >> Then type another @kbd{m}. +@end format ->> Now type @samp{BAR} item name. Do not type Return yet. +@format +>> Now type @kbd{BAR}, the item name. Do not type @key{RET} yet. +@end format - 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. + While you are typing the item name, you can use the @key{DEL} (or +@key{BACKSPACE}) 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. +@format +>> Press @key{DEL} to cancel the @samp{R}. You could type another @kbd{R} + to replace it. But you do not have to, since @samp{BA} is a valid + abbreviation. +@end format +@format >> 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). +@end format + + After visiting @samp{Help-FOO}, you should return here. + + Another way to move to the menu subtopic lines and between them is +to type @key{TAB}. Each time you type a @key{TAB}, you move to the +next subtopic line. To move to a previous subtopic line, type +@kbd{M-@key{TAB}}---that is, press and hold the @key{META} key and then +press @key{TAB}. (On some keyboards, the @key{META} key might be labeled +@samp{Alt}.) + + Once you move cursor to a subtopic line, press @key{RET} to go to +that subtopic's node. + +@cindex mouse support in Info mode +@kindex Mouse-2 @r{(Info mode)} + If your terminal supports a mouse, you have yet another way of going +to a subtopic. Move your mouse pointer to the subtopic line, +somewhere between the beginning @samp{*} and the colon @samp{:} which +ends the subtopic's brief name. You will see the subtopic's name +change its appearance (usually, its background color will change), and +the shape of the mouse pointer will change if your platform supports +that. After a while, if you leave the mouse on that spot, a tooltip +will pop up saying ``Mouse-2: go to that node''. (If the tooltips are +turned off or unavailable, this message is displayed in the @dfn{echo +area}, the bottom screen line where you typed the menu subtopics in +response to the prompt.) @kbd{Mouse-2} is the second button of your +mouse counting from the left---the rightmost button for two-button +mice, the middle button for 3-button mice. So pressing @kbd{Mouse-2} +while the mouse pointer is on a menu subtopic goes to that subtopic. + +@findex Info-mouse-follow-nearest-node + More generally, @kbd{Mouse-2} in an Info buffer runs the Emacs +command @code{Info-mouse-follow-nearest-node}, which finds the nearest +link to another node and goes there. For example, near a cross +reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the +node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At +end of the node's text @kbd{Mouse-2} moves to the next node, or up if +there's no next node. + + Here is another way to get to Help-FOO, a menu. You can ignore this +if you want, or else try it by typing @key{TAB} and then @key{RET}, or +clicking @kbd{Mouse-2} on it (but then please come back to here). @menu * Help-FOO:: @end menu +@format +>> Type @kbd{n} to see more commands. +@end format + @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'' + Congratulations! This is the node @samp{Help-FOO}. It has an @samp{Up} +pointer @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''. +@kindex u @r{(Info mode)} +@findex Info-up 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. +@kbd{u} for ``Up'' (the Emacs command run by @kbd{u} is +@code{Info-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. +(Some Info readers, such as the one built into Emacs, put you at the +same place where you were reading in @samp{Help-M}.) + + Another way to go Up is to click on the @samp{Up} pointer shown in +the header line (provided that you have a mouse). +@format >> Now type @kbd{u} to move back up to @samp{Help-M}. +@end format -@node Help-Adv, Help-Q, Help-M, Getting Started +@node Help-Xref, Help-Int, Help-M, Getting Started @comment node-name, next, previous, up -@section Some advanced Info commands +@section Following Cross-References + +@cindex cross references in Info documents + In Info documentation, you will see many @dfn{cross references}. +Cross references look like this: @xref{Help-Cross, Cross}. That text +is a real, live cross reference, whose name is @samp{Cross} and which +points to the node named @samp{Help-Cross}. + +@kindex f @r{(Info mode)} +@findex Info-follow-reference + There are two ways to follow a cross reference. You can move the +cursor to it and press @key{RET}, just as in a menu. @key{RET} +follows the cross reference that the cursor is on. Or you can type +@kbd{f} and then specify the name of the cross reference (in this +case, @samp{Cross}) as an argument. In Emacs Info, @kbd{f} runs +@code{Info-follow-reference}, + + In the @kbd{f} command, you select the cross reference with its +name, so it does not matter where the cursor was. If the cursor is on +or near a cross reference, @kbd{f} suggests that reference name in +parentheses as the default; typing @key{RET} will follow that +reference. However, if you type a different reference name, @kbd{f} +will follow the other reference which has that name. + +@format +>> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}. +@end format + + As you enter the reference name, you can use the @key{DEL} (or +@key{BACKSPACE}) 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 @kbd{f} command; you can +complete among all the cross reference names in the current node by +typing a @key{TAB}. + + To get a list of all the cross references in the current node, you +can type @kbd{?} after an @kbd{f}. The @kbd{f} continues to await a +cross reference name even after displaying the list, so if you don't +actually want to follow a reference, you should type a @kbd{Control-g} +to cancel the @kbd{f}. + +@format +>> Type @kbd{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. +@end format - The course is almost over, so please stick with it to the end. + The @key{TAB} and @kbd{M-@key{TAB}} key, which move between menu +items in a menu, also move between cross references outside of menus. +@node Help-Int, Help-Q, Help-Xref, Getting Started +@comment node-name, next, previous, up +@section Some intermediate Info commands + + The introductory course is almost over; please continue +a little longer to learn some intermediate-level commands. + + Most Info files have an index, which is actually a large node that +contains nothing but a menu. The menu has one menu item for each +topic listed in the index. You can find the index node from the main +menu of the file, with the @kbd{m} command; then you can use the +@kbd{m} command again in the index node to go to the node that +describes the topic. + + There is also a short-cut Info command, @kbd{i}, which does all of +that for you. It searches the index for a given topic (a string) and +goes to the node which is listed in the index for that topic. +@xref{Info Search}, for a full explanation. + +@kindex l @r{(Info mode)} +@findex Info-last +@cindex going back in Info mode 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 @@ -496,166 +747,235 @@ 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. + In Emacs, @kbd{l} runs the command @code{Info-last}. -Then follow directions again and you will end up back here. +@format +>> 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. +@end format 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, +which the header says is the @samp{Previous} node (from this node, the +@samp{Prev} link leads to @samp{Help-M}). + +@kindex d @r{(Info mode)} +@findex Info-directory +@cindex go to Directory node + The @kbd{d} command (@code{Info-directory} in Emacs) 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. The +Directory node lists all the manuals and other Info documents that +are, or could be, installed on your system. + +@format +>> Try doing a @kbd{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. - +@end format + +@kindex t @r{(Info mode)} +@findex Info-top-node +@cindex go to Top node + The @kbd{t} command moves to the @samp{Top} node of the manual. +This is useful if you want to browse the manual's main menu, or select +some specific top-level menu item. The Emacs command run by @kbd{t} +is @code{Info-top-node}. + + Clicking @kbd{Mouse-2} on or near a cross reference also follows the +reference. You can see that the cross reference is mouse-sensitive by +moving the mouse pointer to the reference and watching how the +underlying text and the mouse pointer change in response. + +@format >> Now type @kbd{n} to see the last node of the course. +@end format + + @xref{Advanced Info}, for more advanced Info features. @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 -@subsection 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 @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}.) + This chapter describes various advanced Info commands. (If you are +using a stand-alone Info reader, there are additional commands +specific to it, which are documented in several chapters of @ref{Top,, +GNU Info, info-stnd, GNU Info}.) + + This chapter also explains 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. +* Info Search:: How to search Info documents for specific subjects. * 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. +* Tags:: How to make tags 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 +@node Expert, Info Search, , Advanced Info @comment node-name, next, previous, up @section Advanced Info Commands -@kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{9}, and @kbd{e} +Here are some more Info commands that make it easier to move around. -If you know a node's name, you can go there by typing @kbd{g}, the +@unnumberedsubsec @kbd{g} goes to a node by name + +@kindex g @r{(Info mode)} +@findex Info-goto-node +@cindex go to a node by name + 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. +called @samp{Top} in this file. (This is equivalent to @kbd{t}, see +@ref{Help-Int}.) @kbd{gExpert@key{RET}} would come back here. +@kbd{g} in Emacs runs the command @code{Info-goto-node}. -Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. + Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. +But it does allow completion, so you can type @key{TAB} to complete a +partial node name. -To go to a node in another file, you can include the filename in the +@cindex go to another Info file + To go to a node in another file, you can include the file name 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 @samp{Top} in the Info file @file{dir}. Likewise, +@kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual. -The node name @samp{*} specifies the whole file. So you can look at + 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}}. +other file with @kbd{g(@var{filename})@key{RET}}. + +@unnumberedsubsec @kbd{1} -- @kbd{9} choose a menu subtopic by its number + +@kindex 1 @r{through} 9 @r{(Info mode)} +@findex Info-nth-menu-item +@cindex select @var{n}'th menu item + If you begrudge each character of type-in which your system requires, +you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, +@dots{}, @kbd{9}. They are short for the @kbd{m} command together +with a name of a menu subtopic. @kbd{1} goes through the first item +in the current node's menu; @kbd{2} goes through the second item, etc. +In the stand-alone reader, @kbd{0} goes through the last menu item; +this is so you need not count how many entries are there. In Emacs, +the digit keys run the command @code{Info-nth-menu-item}. + + If your display supports multiple fonts, and you are using Emacs' +Info mode to read Info files, the @samp{*} for the fifth menu item +stands out, either in color or in some other attribute, such as +underline, and so is the @samp{*} for the ninth item; this makes it +easy to see at a glance which number to use for an item. + + Some terminals don't support colors or underlining. If you need to +actually count items, it is better to use @kbd{m} instead, and specify +the name, or use @key{TAB} to quickly move between menu items. -The @kbd{s} command allows you to search a whole file for a string. +@unnumberedsubsec @kbd{e} makes Info document editable + +@kindex e @r{(Info mode)} +@findex Info-edit +@cindex edit Info document + 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}. + + The @kbd{e} command only works in Emacs, where it runs the command +@code{Info-edit}. The stand-alone Info reader doesn't allow you to +edit the Info file, so typing @kbd{e} there goes to the end of the +current node. + +@node Info Search, Add, Expert, Advanced Info +@comment node-name, next, previous, up +@section How to search Info documents for specific subjects + +@cindex searching Info documents +@cindex Info document as a reference + The commands which move between and inside nodes allow you to read +the entire manual or its large portions. But what if you need to find +some information in the manual as fast as you can, and you don't know +or don't remember in what node to look for it? This need arises when +you use a manual as a @dfn{reference}, or when it is impractical to +read the entire manual before you start using the programs it +describes. + + Info has powerful searching facilities that let you find things +quickly. You can search either the manual indices or its text. + +@kindex i @r{(Info mode)} +@findex Info-index + Since most subjects related to what the manual describes should be +indexed, you should try the index search first. The @kbd{i} command +prompts you for a subject and then looks up that subject in the +indices. If it finds an index entry with the subject you typed, it +goes to the node to which that index entry points. You should browse +through that node to see whether the issue you are looking for is +described there. If it isn't, type @kbd{,} one or more times to go +through additional index entries which match your subject. + + The @kbd{i} command finds all index entries which include the string +you typed @emph{as a substring}. For each match, Info shows in the +echo area the full index entry it found. Often, the text of the full +index entry already gives you enough information to decide whether it +is relevant to what you are looking for, so we recommend that you read +what Emacs shows in the echo are before looking at the node it +displays. + + Since @kbd{i} looks for a substring, you can search for subjects even +if you are not sure how they are spelled in the index. For example, +suppose you want to find something that is pertinent to commands which +complete partial input (e.g., when you type @key{TAB}). If you want +to catch index entries that refer to ``complete'', ``completion'', and +``completing'', you could type @kbd{icomplet@key{RET}}. + + Info documents which describe programs should index the commands, +options, and key sequences that the program provides. If you are +looking for a description of a command, an option, or a key, just type +their names when @kbd{i} prompts you for a topic. For example, if you +want to read the description of what the @kbd{C-f} key does, type +@kbd{iC-f@key{RET}}. Here @kbd{C-f} are 3 literal characters +@samp{C}, @samp{-}, and @samp{f}, not the ``Control-f'' command key +you type inside Emacs to run the command bound to @kbd{C-f}. + + In Emacs, @kbd{i} runs the command @code{Info-index}. + +@kindex s @r{(Info mode)} +@findex Info-search + 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} +order that they may be 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. +@kindex M-s @r{(Info mode)} + In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for +compatibility with other GNU packages that use @kbd{M-s} for a similar +kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the +command @code{Info-search}. -If your display supports multiple fonts, and you are using Emacs' Info -mode to read Info files, the @samp{*} for the fifth menu item is -underlined, 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 +@node Add, Menus, Info Search, 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. @@ -663,29 +983,33 @@ Create some nodes, in some file, to document that topic. 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}); this has the advantage that you -can also make a printed manual from them. However, if you want to edit -an Info file, here is how. + 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 you 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 +@cindex node delimiters + The new node can live in an existing documentation file, or in a new +one. It must have a @samp{^_} 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 +a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If +you put in a @samp{^L} to end a new node, be sure that there is a +@samp{^_} after it to start the next one, since @samp{^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 @samp{^L} @emph{right after} the +@samp{^_}.} + + The @samp{^_} starting a node must be followed by a newline or a +@samp{^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}, +@cindex node header line format +@cindex format of node headers + The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up} 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. @@ -693,30 +1017,35 @@ 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. +@cindex node name format +@cindex Directory node 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: +then it is relative to the current directory; otherwise, it is +relative starting from the standard directory for Info files 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 @samp{Directory} node is @file{(dir)}, it +points to a file @file{dir} which holds a large menu listing all the +Info documents installed on your site. The @samp{Top} node of a +document file listed in the @samp{Directory} should have an @samp{Up: (dir)} in it. +@cindex unstructured documents 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. +contain a file name, since when Info searches for a node, it does not +expect a file name 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 @@ -730,10 +1059,11 @@ to help identify the node for the user. The @kbd{m} command searches the current node's menu for the topic which it reads from the terminal. +@cindex menu and menu entry format 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 +with a @samp{* } lists a single topic. The name of the topic--what +the user must type at the @kbd{m}'s command prompt 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} @@ -741,8 +1071,8 @@ 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 +giving the name twice, the abbreviation @samp{* @var{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 @@ -761,8 +1091,8 @@ someone who wants to see them all need not keep revisiting the Menu. 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 +Info's files live in that file directory, but they do not have to; and +files in that directory are not automatically listed in the Info Directory node. Also, although the Info node graph is claimed to be a ``hierarchy'', @@ -781,9 +1111,10 @@ ever find out that it exists. @comment node-name, next, previous, up @section Creating Cross References +@cindex cross reference format 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{*}. +like a menu item except that it has @samp{*note} instead of @samp{*}. 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 @@ -793,32 +1124,95 @@ examples of cross references pointers: *Note details: commands. (See *note 3: Full Proof.) @end example -They are just examples. The places they ``lead to'' do not really exist! +@noindent +@emph{These are just examples.} The places they ``lead to'' do not +really exist! + +@menu +* Help-Cross:: Target of a cross-reference. +@end menu + + +@node Help-Cross, , , Cross-refs +@subsection 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 an Info document. So you +cannot expect this node to have a @samp{Next}, @samp{Previous} or +@samp{Up} links pointing back to where you came from. In general, the +@kbd{l} (el) command is the only way to get back there. + +@format +>> Type @kbd{l} to return to the node where the cross reference was. +@end format + +@node Help-Q, , Help-Int, Getting Started +@comment node-name, next, previous, up +@section Quitting Info + +@kindex q @r{(Info mode)} +@findex Info-exit +@cindex quitting Info mode + To get out of Info, back to what you were doing before, type @kbd{q} +for @dfn{Quit}. This runs @code{Info-exit} in Emacs. + + This is the end of the basic course on using Info. You have learned +how to move in an Info document, and how to follow menus and cross +references. This makes you ready for reading manuals top to bottom, +as new users should do when they learn a new package. + + Another set of Info commands is useful when you need to find +something quickly in a manual---that is, when you need to use a manual +as a reference rather than as a tutorial. We urge you to make learn +these search commands as well. If you want to do that now, follow this +cross reference to @ref{Info Search}. + +Yet another set of commands are meant for experienced users; 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. + +@format +>> Type @kbd{d} to go to the Info directory node; then type + @kbd{mInfo} and Return, to get to the node about Info and + see what other help is available. +@end format + @node Tags, Checking, Cross-refs, Advanced Info @comment node-name, next, previous, up -@section Tag Tables for Info Files +@section Tags Tables for Info Files +@cindex tags tables in 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 +it a tags table. Unlike the tags table for a program, the tags 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 +@findex Info-tagify + To make a tags 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 +file. Info files produced by the @code{makeinfo} command that is part +of the Texinfo package always have tags tables to begin with. + +@cindex stale tags tables +@cindex update Info tags table + Once the Info file has a tags table, you must make certain it is up +to date. If you edit an Info file directly (as opposed to editing its +Texinfo source), and, 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. +recorded in the tags table, Info will no longer be able to find that +node. To update the tags table, use the @code{Info-tagify} command +again. - An Info file tag table appears at the end of the file and looks like + An Info file tags table appears at the end of the file and looks like this: @example -^_ +^_^L Tag Table: File: info, Node: Cross-refs^?21419 File: info, Node: Tags^?22145 @@ -829,7 +1223,7 @@ End Tag Table @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 +a @samp{DEL} character, and the character position in the file of the beginning of the node. @@ -848,48 +1242,103 @@ 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. +@findex Info-validate 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; +The following variables may modify the behavior 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}. +Manual}. The stand-alone Info reader program has its own set of +variables, described in @ref{Variables,, Manipulating Variables, +info-stnd, GNU Info}. @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-directory-list +The list of directories to search for Info files. Each element is a +string (directory name) or @code{nil} (try default directory). If not +initialized Info uses the environment variable @env{INFOPATH} to +initialize it, or @code{Info-default-directory-list} if there is no +@env{INFOPATH} variable in the environment. + +If you wish to customize the Info directory search list for both Emacs +info and stand-alone Info, it is best to set the @env{INFOPATH} +environment variable, since that applies to both programs. + +@item Info-additional-directory-list +A list of additional directories to search for Info documentation files. +These directories are not searched for merging the @file{dir} file. + +@item Info-fontify +When set to a non-@code{nil} value, enables highlighting of Info +files. The default is @code{t}. You can change how the highlighting +looks by customizing the faces @code{info-node}, @code{info-menu-5}, +@code{info-xref}, @code{info-header-xref}, @code{info-header-node}, +@code{info-title-@var{n}-face} (where @var{n} is the level of the +section, a number between 1 and 4), and @code{info-menu-header}. To +customize a face, type @kbd{M-x customize-face @key{RET} @var{face} +@key{RET}}, where @var{face} is one of the face names listed here. + +@item Info-use-header-line +If non-@code{nil}, Emacs puts in the Info buffer a header line showing +the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does +not scroll with the rest of the buffer, making these links always +visible. + +@item Info-scroll-prefer-subnodes +If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or +@key{DEL}) keys in a menu visit subnodes of the current node before +scrolling to its end or beginning, respectively. For example, if the +node's menu appears on the screen, the next @key{SPC} moves to a +subnode indicated by the following menu item. Setting this option to +@code{nil} results in behavior similar to the stand-alone Info reader +program, which visits the first subnode from the menu only when you +hit the end of the current node. The default is @code{t}. @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. +selected. The Lisp code to be executed should follow the node +delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like +this: -@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). +@example +^_execute: (message "This is an active node!") +@end example -@item Info-directory -The standard directory for Info documentation files. Only used when the -function @code{Info-directory} is called. +@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}. @end vtable @node Creating an Info File -@chapter Creating an Info File +@chapter Creating an Info File from a Texinfo 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{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU +Documentation Format}, to learn how to write a Texinfo file. + +@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation +Format}, to learn how to create an Info file from a Texinfo file. + +@xref{Installing an Info File,,, texinfo, Texinfo: The GNU +Documentation Format}, to learn how to install an Info file after you +have created one. -@xref{Top,, Overview of Texinfo, texinfo, Texinfo}, to learn how to -write a Texinfo file. +@node Index +@unnumbered Index -@xref{Creating an Info File,,, texinfo, Texinfo}, to learn how to create -an Info file from a Texinfo file. +This is an alphabetical listing of all the commands, variables, and +topics discussed in this document. -@xref{Installing an Info File,,, texinfo, Texinfo}, to learn how to -install an Info file after you have created one. +@printindex cp @bye diff --git a/contrib/texinfo/doc/install-info.1 b/contrib/texinfo/doc/install-info.1 index f2b8c2a..54b8fcf 100644 --- a/contrib/texinfo/doc/install-info.1 +++ b/contrib/texinfo/doc/install-info.1 @@ -1,29 +1,25 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. -.TH INSTALL-INFO "1" "September 1999" "GNU texinfo 4.0" FSF +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24. +.TH INSTALL-INFO "1" "March 2002" "GNU texinfo 4.1" FSF .SH NAME install-info \- update info/dir entries .SH SYNOPSIS .B install-info [\fIOPTION\fR]... [\fIINFO-FILE \fR[\fIDIR-FILE\fR]] .SH DESCRIPTION -.PP Install or delete dir entries from INFO-FILE in the Info directory file DIR-FILE. .SH OPTIONS .TP \fB\-\-delete\fR delete existing entries for INFO-FILE from DIR-FILE; -.IP don't insert any new entries. .TP \fB\-\-dir\-file\fR=\fINAME\fR specify file name of Info directory file. -.IP This is equivalent to using the DIR-FILE argument. .TP \fB\-\-entry\fR=\fITEXT\fR insert TEXT as an Info directory entry. -.IP 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. @@ -35,7 +31,6 @@ display this help and exit. .TP \fB\-\-info\-file\fR=\fIFILE\fR specify Info file to install in the directory. -.IP This is equivalent to using the INFO-FILE argument. .TP \fB\-\-info\-dir\fR=\fIDIR\fR @@ -43,7 +38,6 @@ same as \fB\-\-dir\-file\fR=\fIDIR\fR/dir. .TP \fB\-\-item\fR=\fITEXT\fR same as \fB\-\-entry\fR TEXT. -.IP An Info directory entry is actually a menu item. .TP \fB\-\-quiet\fR @@ -54,7 +48,6 @@ same as \fB\-\-delete\fR. .TP \fB\-\-section\fR=\fISEC\fR put this file's entries in section SEC of the directory. -.IP 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 @@ -65,6 +58,11 @@ display version information and exit. .SH "REPORTING BUGS" Email bug reports to bug-texinfo@gnu.org, general questions and discussion to help-texinfo@gnu.org. +.SH COPYRIGHT +Copyright \(co 2002 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. .SH "SEE ALSO" The full documentation for .B install-info @@ -77,8 +75,3 @@ programs are properly installed at your site, the command .B info install-info .PP should give you access to the complete manual. -.SH COPYRIGHT -Copyright \(co 1999 Free Software Foundation, Inc. -There is NO warranty. You may redistribute this software -under the terms of the GNU General Public License. -For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/makeinfo.1 b/contrib/texinfo/doc/makeinfo.1 index 62d22b8..b56cb83 100644 --- a/contrib/texinfo/doc/makeinfo.1 +++ b/contrib/texinfo/doc/makeinfo.1 @@ -1,69 +1,117 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. -.TH MAKEINFO "1" "September 1999" "GNU texinfo 4.0" FSF +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24. +.TH MAKEINFO "1" "March 2002" "GNU texinfo 4.1" FSF .SH NAME makeinfo \- translate Texinfo documents .SH SYNOPSIS .B makeinfo -[\fIOPTION\fR]...\fI TEXINFO-FILE\fR... +[\fIOPTION\fR]... \fITEXINFO-FILE\fR... .SH DESCRIPTION -.PP -Translate Texinfo source documentation to various other formats: -Info files suitable for reading online with Emacs or standalone GNU Info -(by default); plain text (with \fB\-\-no\-headers\fR); or HTML (with \fB\-\-html\fR). -.SH OPTIONS +Translate Texinfo source documentation to various other formats, by default +Info files suitable for reading online with Emacs or standalone GNU Info. +.SS "General options:" .TP -\fB\-\-commands\-in\-node\-names\fR -allow @ commands in node names. +\fB\-\-error\-limit\fR=\fINUM\fR +quit after NUM errors (default 100). .TP -\fB\-D\fR VAR -define a variable, as with @set. +\fB\-\-force\fR +preserve output even if errors. +.TP +\fB\-\-help\fR +display this help and exit. +.TP +\fB\-\-no\-validate\fR +suppress node cross-reference validation. +.TP +\fB\-\-no\-warn\fR +suppress warnings (but not errors). +.TP +\fB\-\-reference\-limit\fR=\fINUM\fR +warn about at most NUM references (default 1000). +.TP +\fB\-v\fR, \fB\-\-verbose\fR +explain what is being done. +.TP +\fB\-\-version\fR +display version information and exit. +.SS "Output format selection (default is to produce Info):" +.TP +\fB\-\-docbook\fR +output DocBook rather than Info. +.TP +\fB\-\-html\fR +output HTML rather than Info. +.TP +\fB\-\-no\-headers\fR +output plain text, suppressing Info node +separators and Node: lines; also, write to +standard output without \fB\-\-output\fR. +.TP +\fB\-\-xml\fR +output XML (TexinfoML) rather than Info. +.SS "General output options:" .TP \fB\-E\fR, \fB\-\-macro\-expand\fR FILE output macro-expanded source to FILE. +ignoring any @setfilename. .TP -\fB\-\-error\-limit\fR=\fINUM\fR -quit after NUM errors (default 100). +\fB\-\-no\-split\fR +suppress splitting of Info or HTML output, +generate only one output file. +.TP +\fB\-\-number\-sections\fR +output chapter and sectioning numbers. +.TP +\fB\-o\fR, \fB\-\-output\fR=\fIFILE\fR +output to FILE (directory if split HTML), +.SS "Options for Info and plain text:" +.TP +\fB\-\-enable\-encoding\fR +output accented and special characters in +Info output based on @documentencoding. .TP \fB\-\-fill\-column\fR=\fINUM\fR break Info lines at NUM characters (default 72). .TP \fB\-\-footnote\-style\fR=\fISTYLE\fR -output footnotes according to STYLE: -.IP -`separate' to place footnotes in their own node, -`end' to place the footnotes at the end of the +output footnotes in Info according to STYLE: +`separate' to put them in their own node; +`end' to put them at the end of the node .IP -node in which they are defined (the default). +in which they are defined (default). .TP -\fB\-\-force\fR -preserve output even if errors. +\fB\-\-paragraph\-indent\fR=\fIVAL\fR +indent Info paragraphs by VAL spaces (default 3). +If VAL is `none', do not indent; if VAL is +`asis', preserve existing indentation. .TP -\fB\-\-help\fR -display this help and exit. +\fB\-\-split\-size\fR=\fINUM\fR +split Info files at size NUM (default 50000). +.SS "Input file options:" .TP -\fB\-\-html\fR -output HTML rather than Info format; +\fB\-\-commands\-in\-node\-names\fR +allow @ commands in node names. +.TP +\fB\-D\fR VAR +define the variable VAR, as with @set. .TP \fB\-I\fR DIR append DIR to the @include search path. .TP +\fB\-P\fR DIR +prepend DIR to the @include search path. +.TP +\fB\-U\fR VAR +undefine the variable VAR, as with @clear. +.SS "Conditional processing in input:" +.TP \fB\-\-ifhtml\fR -process @ifhtml and @html text even when not -.IP -generating HTML. +process @ifhtml and @html even if not generating HTML. .TP \fB\-\-ifinfo\fR process @ifinfo text even when generating HTML. .TP \fB\-\-iftex\fR -process @iftex and @tex text. -.IP -implies \fB\-\-no\-split\fR. -.TP -\fB\-\-no\-headers\fR -suppress Info node separators and Node: lines and -.IP -write to standard output without \fB\-\-output\fR. +process @iftex and @tex text; implies \fB\-\-no\-split\fR. .TP \fB\-\-no\-ifhtml\fR do not process @ifhtml and @html text. @@ -73,44 +121,7 @@ do not process @ifinfo text. .TP \fB\-\-no\-iftex\fR do not process @iftex and @tex text. -.TP -\fB\-\-no\-split\fR -suppress splitting of large Info output files or -generation of one HTML file per node. -.TP -\fB\-\-no\-validate\fR -suppress node cross-reference validation. -.TP -\fB\-\-no\-warn\fR -suppress warnings (but not errors). -.TP -\fB\-\-number\-sections\fR -include chapter, section, etc. numbers in output. -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIFILE\fR -output to FILE, ignoring any @setfilename. -.TP -\fB\-P\fR DIR -prepend DIR to the @include search path. -.TP -\fB\-\-paragraph\-indent\fR=\fIVAL\fR -indent Info paragraphs by VAL spaces (default 3). .IP -if VAL is `none', do not indent; -if VAL is `asis', preserve existing indentation. -.TP -\fB\-\-reference\-limit\fR=\fINUM\fR -warn about at most NUM references (default 1000). -.TP -\fB\-U\fR VAR -undefine a variable, as with @clear. -.TP -\fB\-v\fR, \fB\-\-verbose\fR -explain what is being done. -.TP -\fB\-\-version\fR -display version information and exit. -.PP The defaults for the @if... conditionals depend on the output format: if generating HTML, \fB\-\-ifhtml\fR is on and the others are off; if generating Info or plain text, \fB\-\-ifinfo\fR is on and the others are off. @@ -133,6 +144,11 @@ write one Info file however big .SH "REPORTING BUGS" Email bug reports to bug-texinfo@gnu.org, general questions and discussion to help-texinfo@gnu.org. +.SH COPYRIGHT +Copyright \(co 2002 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. .SH "SEE ALSO" The full documentation for .B makeinfo @@ -145,8 +161,3 @@ programs are properly installed at your site, the command .B info makeinfo .PP should give you access to the complete manual. -.SH COPYRIGHT -Copyright \(co 1999 Free Software Foundation, Inc. -There is NO warranty. You may redistribute this software -under the terms of the GNU General Public License. -For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/texindex.1 b/contrib/texinfo/doc/texindex.1 index 6708829..019d5e4 100644 --- a/contrib/texinfo/doc/texindex.1 +++ b/contrib/texinfo/doc/texindex.1 @@ -1,12 +1,11 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. -.TH TEXINDEX "1" "September 1999" "GNU texinfo 4.0" FSF +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24. +.TH TEXINDEX "1" "March 2002" "GNU texinfo 4.1" FSF .SH NAME texindex \- sort Texinfo index files .SH SYNOPSIS .B texindex -[\fIOPTION\fR]...\fI FILE\fR... +[\fIOPTION\fR]... \fIFILE\fR... .SH DESCRIPTION -.PP Generate a sorted index for each TeX output FILE. Usually FILE... is specified as `foo.??' for a document `foo.texi'. .SH OPTIONS @@ -28,6 +27,11 @@ display version information and exit .SH "REPORTING BUGS" Email bug reports to bug-texinfo@gnu.org, general questions and discussion to help-texinfo@gnu.org. +.SH COPYRIGHT +Copyright \(co 2002 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. .SH "SEE ALSO" The full documentation for .B texindex @@ -40,8 +44,3 @@ programs are properly installed at your site, the command .B info texindex .PP should give you access to the complete manual. -.SH COPYRIGHT -Copyright \(co 1999 Free Software Foundation, Inc. -There is NO warranty. You may redistribute this software -under the terms of the GNU General Public License. -For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/texinfo.txi b/contrib/texinfo/doc/texinfo.txi index 7e0bbd0..fed4c4c 100644 --- a/contrib/texinfo/doc/texinfo.txi +++ b/contrib/texinfo/doc/texinfo.txi @@ -1,5 +1,5 @@ \input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.txi,v 1.162 1999/09/28 19:38:01 karl Exp $ +@c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $ @c %**start of header @c All text is ignored before the setfilename. @@ -18,7 +18,7 @@ @footnotestyle separate @paragraphindent 2 -@finalout +@c finalout @comment %**end of header @@ -28,7 +28,7 @@ * install-info: (texinfo)Invoking install-info. Update info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. -* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. +* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. @end direntry @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a @@ -50,40 +50,24 @@ @ifinfo This file documents Texinfo, a documentation system that can produce -both online information and a printed manual from a single source file. +both online information and a printed manual from a single source. This +edition is for Texinfo version @value{VERSION}, @value{UPDATED}. -Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 +Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 Free Software Foundation, Inc. -This edition is for Texinfo version @value{VERSION}, @value{UPDATED}. - -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. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Section being ``History'', with no Front-Cover Texts, and with +no Back-Cover Texts. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. @end ifinfo @shorttitlepage Texinfo @titlepage -@c use the new format for titles @title Texinfo @subtitle The GNU Documentation Format @subtitle for Texinfo version @value{VERSION}, @value{UPDATED} @@ -96,7 +80,7 @@ by the Free Software Foundation. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 +Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 Free Software Foundation, Inc. This manual is for Texinfo version @value{VERSION}, @value{UPDATED}. @@ -110,21 +94,15 @@ ISBN 1-882114-67-1 @c for version 4.0, September 1999. @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.24 of November 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. +Cover art by Etienne Suvasa. -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, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Section being ``History'', with no Front-Cover Texts, and with +no Back-Cover Texts. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. -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 @summarycontents @@ -134,8 +112,8 @@ Cover art by Etienne Suvasa. @node Top @top Texinfo -Texinfo is a documentation system that uses a single source file to -produce both online information and printed output. +Texinfo is a documentation system that uses a single source to produce +both online information and printed output. The first part of this master menu lists the major nodes in this Info document, including the @@-command and concept indices. The rest of @@ -174,19 +152,17 @@ This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. * 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{}. +* Documentation Copying:: The GNU Free Documentation License. * 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 @@ -201,7 +177,7 @@ Overview of Texinfo * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* History:: Acknowledgements, contributors and genesis. Using Texinfo Mode @@ -241,6 +217,7 @@ The Texinfo File Header * 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. +* documentdescription:: Document summary for the HTML output. * setchapternewpage:: Start chapters on right-hand pages. * paragraphindent:: Specify paragraph indentation. * exampleindent:: Specify environment indentation. @@ -346,7 +323,8 @@ Indicating Definitions, Commands, etc. * code:: Indicating program code. * kbd:: Showing keyboard input. * key:: Specifying keys. -* samp:: Showing a literal sequence of characters. +* samp:: A literal sequence of characters. +* verb:: A verbatim sequence of characters. * var:: Indicating metasyntactic variables. * env:: Indicating environment variables. * file:: Indicating file names. @@ -366,19 +344,19 @@ Emphasizing Text 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:: How to illustrate Lisp code. +* Block Enclosing Commands:: Different constructs for different purposes. +* quotation:: Writing a quotation. +* example:: Writing an example in a fixed-width font. +* verbatim:: Writing a verbatim example. +* verbatiminclude:: Including a file verbatim. +* lisp:: Illustrating Lisp code. * small:: Forms for @code{@@smallbook}. -* 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. +* display:: Writing an example in the current font. +* format:: Writing an example without narrowed margins. +* exdent:: Undo indentation on a line. +* flushleft & flushright:: Pushing text flush left or flush right. +* noindent:: Preventing paragraph indentation. +* cartouche:: Drawing rounded rectangles around examples. Lists and Tables @@ -444,7 +422,7 @@ Inserting Space * Multiple Spaces:: Inserting multiple spaces. * dmn:: How to format a dimension. -Inserting Ellipsis, Dots, and Bullets +Inserting Ellipsis and Bullets * dots:: How to insert dots @dots{} * bullet:: How to insert a bullet. @@ -482,7 +460,7 @@ 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. +* - 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. @@ -519,8 +497,8 @@ Conditionally Visible Text @code{@@set}, @code{@@clear}, and @code{@@value} -* ifset ifclear:: Format a region if a flag is set. * set value:: Expand a flag variable to a string. +* ifset ifclear:: Format a region if a flag is set. * value Example:: An easy way to update edition information. Internationalization @@ -549,7 +527,7 @@ Formatting and Printing Hardcopy * Preparing for TeX:: What to do before you use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. +* A4 Paper:: How to print on A4 or A5 paper. * pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. @@ -558,7 +536,7 @@ Formatting and Printing Hardcopy Creating and Installing Info Files * Creating an Info File:: -* Install an Info File:: +* Installing an Info File:: Creating an Info File @@ -578,19 +556,13 @@ Creating an Info File Installing an Info File * Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new info file. +* 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. @@ -624,6 +596,7 @@ Finding Badly Referenced Nodes * Unsplit:: How to create an unsplit file. * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. + @end detailmenu @end menu @@ -642,38 +615,36 @@ when it is bad, it is better than nothing. @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}). +@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 +sharing any version of these programs that they might get from you. - 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 +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 +you can do these things. - To make sure that everyone has such rights, we have to forbid you to +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 +can get the source code. And you must tell them their rights. - Also, for our own protection, we must make certain that everyone finds +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 +reputation. -The precise conditions of the licenses for the programs currently -being distributed that relate to Texinfo are found in the General Public +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. @@ -707,7 +678,7 @@ that one document. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* History:: Acknowledgements, contributors and genesis. @end menu @@ -717,8 +688,8 @@ that one document. @cindex Bugs, reporting @cindex Suggestions for Texinfo, making @cindex Reporting bugs -We welcome bug reports or suggestions for the Texinfo system, both -programs and documentation. Please email them to +We welcome bug reports and suggestions for any aspect of the Texinfo system, +programs, documentation, installation, anything. Please email them to @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. @@ -743,11 +714,11 @@ Patches are most welcome; if possible, please make them with Merging Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU Emacs Manual}). -When sending email, please do not encode or split the messages in any -way if possible; it's much easier to deal with one plain text message, -however large, than many small ones. -@uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of -packaging multiple and/or binary files for email. +When sending patches, if possible please do not encode or split them in +any way; it's much easier to deal with one plain text message, however +large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/, +GNU shar} is a convenient way of packaging multiple and/or binary files +for email. @node Using Texinfo @@ -762,8 +733,8 @@ features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create a menu-driven, online Info file with nodes, menus, cross references, and indices. You can also create from that same source file an HTML output -file suitable for use with a web browser. @cite{The GNU Emacs Manual} -is a good example of a Texinfo file, as is this manual. +file suitable for use with a web browser, or an XML file. @cite{The GNU +Emacs Manual} is a good example of a Texinfo file, as is this manual. To make a printed document, you process a Texinfo source file with the @TeX{} typesetting program (but the Texinfo language is very different @@ -773,15 +744,20 @@ that you can typeset and print as a book or report (@pxref{Hardcopy}). @pindex makeinfo To output an Info file, process your Texinfo source with the @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command. -You can install the result in your Info tree (@pxref{Install an Info +You can install the result in your Info tree (@pxref{Installing an Info File}). -To output an HTML file, process your Texinfo source with @code{makeinfo} -using the @samp{--html} option. You can (for example) install the -result on your web site. +To output an HTML file, run @code{makeinfo --html} on your Texinfo +source. You can (for example) install the result on your web site. + +@cindex Docbook, converting to Texinfo +@cindex Conversion, from Docbook to Texinfo +To output an XML file, run @code{makeinfo --xml} on your Texinfo source. +To output DocBook, run @code{makeinfo --docbook}. If you want to +convert from Docbook @emph{to} Texinfo, please see +@uref{http://docbook2X.sourceforge.net/}. @cindex Output formats, supporting more -@cindex Docbook output format @cindex SGML-tools output format If you are a programmer and would like to contribute to the GNU project by implementing additional output formats for Texinfo, that would be @@ -831,7 +807,7 @@ output formats. You might as well just write the man page directly. If you wish to support man pages, the program @command{help2man} may be useful; it generates a traditional man page from the @samp{--help} output of a program. In fact, this is currently used to generate man -pages for the Texinfo programs themselves. It is free software written +pages for the Texinfo programs themselves. It is GNU software written by Brendan O'Dea, available from @uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}. @@ -975,12 +951,12 @@ document.) @file{texinfo.tex} contains the specifications for printing a document. You can get the latest version of @file{texinfo.tex} from @uref{ftp://ftp.gnu.org/gnu/texinfo.tex}. -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 +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 A4 or A5 size paper (@code{@@afourpaper}, +@code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}. +Also, see @ref{A4 Paper, ,Printing on A4 Paper}.) 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 @@ -1007,7 +983,6 @@ To get a copy of @TeX{}, see @node Formatting Commands, Conventions, Printed Books, Overview -@comment node-name, next, previous, up @section @@-commands @cindex @@-commands @cindex Formatting commands @@ -1091,8 +1066,8 @@ 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 @@ -1157,24 +1132,25 @@ Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, @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. +@strong{Caution:} Do not use tabs in a Texinfo file (except in verbatim +modes) ! @TeX{} uses variable-width fonts, which means that it is +impractical at best to define 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, for example, in an indented example. @noindent To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple -spaces when you press the @key{TAB} key.@refill +spaces when you press the @key{TAB} key. @noindent Also, you can run @code{untabify} in Emacs to convert tabs in a region -to multiple spaces.@refill +to multiple spaces. @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 @@ -1199,10 +1175,8 @@ the Info file or the printed manual by using the @code{@@ignore} and 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 +comments. + @cindex Ignored text @cindex Unprocessed text @findex ignore @@ -1210,15 +1184,15 @@ version of the document.@refill @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 +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 @@ -1258,7 +1232,8 @@ The @samp{\input texinfo} line tells @TeX{} to use 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 +title for the page headers (or footers) of the printed manual, and the +default document description title for the @samp{<head>} in HTML format. 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 @@ -1374,7 +1349,7 @@ appear in the printed document. @@ifinfo This is a short example of a complete Texinfo file. -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end ifinfo @end group @end example @@ -1386,17 +1361,17 @@ The titlepage segment does not appear in the Info file. @example @group +@@contents @@titlepage @@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} +@@title 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. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end titlepage @end group @end example @@ -1406,12 +1381,13 @@ Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. @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. +a menu, the master menu appears only in online output. @example @group -@@node Top, First Chapter, , (dir) -@@comment node-name, next, previous, up +@@ifnottex +@@node Top +@@end ifnottex @end group @end example @@ -1434,10 +1410,9 @@ chapter containing an enumerated list.@refill @example @group -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up +@@node First Chapter @@chapter First Chapter -@@cindex Sample index entry +@@cindex Chapter, first @end group @group @@ -1458,10 +1433,9 @@ This is the second item. @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. +The @@code@{makeinfo@} command transforms a Texinfo file +such as this into an Info file or other output; +@@TeX@ typesets it for a printed manual. @end group @end example @@ -1475,14 +1449,13 @@ document.@refill @example @group -@@node Concept Index, , First Chapter, Top +@@node Concept Index @@unnumbered Concept Index @end group @group @@printindex cp -@@contents @@bye @end group @end example @@ -1513,8 +1486,8 @@ manual. @end quotation -@node Acknowledgements and History -@section Acknowledgements and History +@node History +@section History @cindex Stallman, Richard M. @cindex Chassell, Robert J. @@ -1892,10 +1865,10 @@ about the page commands.@refill 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 +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. If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task.@refill @@ -2520,8 +2493,7 @@ M-x texinfo-sequential-node-update @end group @end example -@node Beginning a File, Ending a File, Texinfo Mode, Top -@comment node-name, next, previous, up +@node Beginning a File @chapter Beginning a Texinfo File @cindex Beginning a Texinfo file @cindex Texinfo file beginning @@ -2581,8 +2553,8 @@ 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 + +@node Sample Beginning @section Sample Texinfo File Beginning The following sample shows what is needed.@refill @@ -2631,14 +2603,15 @@ Published by @dots{} Permission is granted to @dots{} @@end titlepage -@@node Top, Overview, , (dir) +@@ifnottex +@@node Top +@@top @var{title} -@@ifinfo This document describes @dots{} This document applies to version @dots{} of the program named @dots{} -@@end ifinfo +@@end ifnottex @group @@menu @@ -2651,26 +2624,24 @@ of the program named @dots{} @end group @group -@@node First Chapter, Second Chapter, top, top -@@comment node-name, next, previous, up +@@node First Chapter @@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 + +@node Header @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 +@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. Thus, the beginning of a Texinfo file looks like this: @@ -2700,6 +2671,7 @@ or else like this: * 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. +* documentdescription:: Document summary for the HTML output. * setchapternewpage:: Start chapters on right-hand pages. * paragraphindent:: Specify paragraph indentation. * exampleindent:: Specify environment indentation. @@ -2739,8 +2711,8 @@ 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 + +@node Start of Header @subsection Start of Header @cindex Start of header line @@ -2816,18 +2788,21 @@ also reads @file{texinfo.cnf} if that file is present on your system (@pxref{Preparing for TeX,, Preparing for @TeX{}}). -@node settitle, setchapternewpage, setfilename, Header -@comment node-name, next, previous, up -@subsection @code{@@settitle} +@node settitle +@subsection @code{@@settitle}: Set the document title @findex settitle In order to be made into a printed manual, a Texinfo file must contain -a line that looks like this:@refill +a line that looks like this: @example @@settitle @var{title} @end example +In the HTML file produced by @command{makeinfo}, @var{title} serves as +the default document description in the @samp{<head>} part; see +@ref{documentdescription}, for how to change that. + 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; @@ -2866,8 +2841,40 @@ footings. @xref{Headings, , Page Headings}, for a detailed discussion of this process.@refill +@node documentdescription +@subsection @code{@@documentdescription}: Summary text +@cindex Document description +@cindex Description of document +@cindex Summary of document +@cindex <meta> HTML tag, and document description + +When producing HTML output for a document, @command{makeinfo} writes a +@samp{<meta>} element in the @samp{<head>} to give some idea of the +content of the document. By default, this @dfn{description} is the title +of the document, taken from the @code{@@settitle} command +(@pxref{settitle}). To change this, use the @code{@@documentdescription} +environment, as in: + +@example +@@documentdescription +descriptive text +@@end documendescription +@end example + +@noindent +This will produce the following output in the @samp{<head>} of the HTML: + +@example +<meta name=description content="descriptive text"> +@end example + +@code{@@documentdescription} must be specified before the first node of +the document. + + +@findex documentdescription @node setchapternewpage -@subsection @code{@@setchapternewpage} +@subsection @code{@@setchapternewpage}: @cindex Starting chapters @cindex Pages, starting odd @findex setchapternewpage @@ -2877,61 +2884,59 @@ 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 +preceding chapter, after a small amount of vertical whitespace. You can use the @code{@@setchapternewpage} command with various arguments to specify how @TeX{} should start chapters and whether it should format headers for printing on one or both sides of the paper -(single-sided or double-sided printing).@refill +(single-sided or double-sided printing). Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument.@refill +line followed by its argument. For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page:@refill +start on a fresh odd-numbered page: @example @@setchapternewpage odd @end example You can specify one of three alternatives with the -@code{@@setchapternewpage} command:@refill +@code{@@setchapternewpage} command: @table @asis @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 +format page headers for single-sided printing. @item @code{@@setchapternewpage on} Cause @TeX{} to start new chapters on new pages and to format page -headers for single-sided printing. This is the form most often -used for short reports or personal printing. - -This alternative is the default.@refill +headers for single-sided printing. This is the form most often used for +short reports or personal printing. This is the default. @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 +the form most often used for books and manuals. @end table -Texinfo does not have an @code{@@setchapternewpage even} command.@refill +Texinfo does not have an @code{@@setchapternewpage even} command, +because there is no printing tradition of starting chapters or books on +an even-numbered page. -You can countermand or modify the effect on headers of an -@code{@@setchapternewpage} command with an @code{@@headings} command. -@xref{headings on off, , The @code{@@headings} Command}.@refill +If you don't like the default headers that @code{@@setchapternewpage} +sets, you can explicit control them with the @code{@@headings} command. +@xref{headings on off, , The @code{@@headings} Command}. 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 +example, the title and copyright pages of a book are not numbered. By +convention, table of contents and frontmatter pages are numbered with +roman numerals and not in sequence with the rest of the document. Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it.@refill +command has no effect on it. We recommend not including any @code{@@setchapternewpage} command in your manual sources at all, since the desired output is not intrinsic to @@ -3066,23 +3071,23 @@ 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 +The copyright notice should read: @example Copyright @var{year} @var{copyright-owner} @end example @noindent -and be put on a line by itself.@refill +and be put on a line by itself. -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 +Standard text for the copyright permissions of free manuals is contained +in an appendix to this manual (@pxref{Documentation Copying, , GNU Free +Documentation License}). 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 *}. +reading the file using Info (except when using the advanced Info command +@kbd{g *}). @node Titlepage & Copyright Page @@ -3105,8 +3110,8 @@ output. Simply place any such leading material between @code{@@ifinfo} and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain text output. It will not show up in the Info readers. -@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the -standard text for the copyright permissions.@refill +@xref{Documentation Copying, , GNU Free Documentation License}, for the +standard text for the copyright permissions. @menu * titlepage:: Create a title for the printed document. @@ -3329,7 +3334,7 @@ may be useful if you have a very long title. Here is a real-life example: @@titlefont@{GNU Software@} @@sp 1 @@title for MS-Windows and MS-DOS -@@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@} +@@subtitle Edition @@value@{e@} for Release @@value@{cde@} @@author by Daniel Hagerty, Melissa Weisshaus @@author and Eli Zaretskii @end group @@ -3394,7 +3399,8 @@ Permissions must be given here as well as in the summary segment within header since this text appears only in the printed manual and the @samp{ifinfo} text appears only in the Info file. -@xref{Sample Permissions}, for the standard text.@refill +@xref{Documentation Copying,,GNU Free Documentation License}, for the +standard text. @node end titlepage @@ -3659,7 +3665,7 @@ Using Texinfo Mode @end group @end example -@node Software Copying Permissions, , The Top Node, Beginning a File +@node Software Copying Permissions @comment node-name, next, previous, up @section Software Copying Permissions @cindex Software copying permissions @@ -3674,9 +3680,8 @@ for the software that is documented, this section usually follows the 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 +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 @@ -3848,7 +3853,15 @@ sectioning command such as @code{@@unnumbered} before them. Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are -included in plain text output (generated by @code{makeinfo --no-headers}). +included in plain text output (generated by @code{makeinfo +--no-headers}), unless @code{makeinfo} is writing its output to standard +output. + +When @code{makeinfo} writes a short table of contents while producing +html output, the links in the short table of contents point to +corresponding entries in the full table of contents rather than the text +of the document. The links in the full table of contents point to the +main text of the document. The contents commands can be placed either at the very end of the file, after any indices (see the previous section) and just before the @@ -3858,8 +3871,7 @@ the former is that then the contents output is always up to date, because it reflects the processing just done. The advantage to the latter is that the contents are printed in the proper place, thus you do not need to rearrange the DVI file with @command{dviselect} or shuffle -paper. However, contents commands at the beginning of the document are -ignored when outputting to standard output. +paper. @findex setcontentsaftertitlepage @findex setshortcontentsaftertitlepage @@ -4033,25 +4045,25 @@ start new pages in the printed manual; the @code{@@heading} commands do not.@refill @end itemize -Here are the four groups of chapter structuring commands:@refill +Here are the four groups of chapter structuring commands: -@multitable @columnfractions .19 .30 .29 .22 +@tex +{\globaldefs = 1 \smallfonts} +@end tex -@item @tab @tab @tab No new page -@item Numbered @tab Unnumbered @tab Lettered and numbered - @tab Unnumbered -@item In contents @tab In contents @tab In contents @tab Not in contents -@item @tab @code{@@top} @tab - @tab @code{@@majorheading} -@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} - @tab @code{@@chapheading} -@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} - @tab @code{@@heading} -@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} - @tab @code{@@subheading} -@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} - @tab @code{@@subsubheading} +@multitable @columnfractions .19 .30 .29 .22 +@item @tab @tab @tab No new page +@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} +@item In contents @tab In contents @tab In contents @tab Omitted from@*contents +@item @tab @code{@@top} @tab @tab @code{@@majorheading} +@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading} +@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} +@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} +@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} @end multitable +@tex +{\globaldefs = 1 \textfonts} +@end tex @node makeinfo top @@ -4736,6 +4748,7 @@ capitalized; others are not.@refill @subsection @code{@@node} Line Requirements @cindex Node line requirements +@cindex Restrictions on node names Here are several requirements for @code{@@node} lines: @itemize @bullet @@ -4761,10 +4774,11 @@ node containing the pointer. @cindex @@-commands in nodename @cindex Node name, should not contain @@-commands @item -@w{@@-commands} used in node names generally confuse Info, so you should -avoid them. For a few rare cases when this is useful, Texinfo has -limited support for using @w{@@-commands} in node names; see -@ref{Pointer Validation}. +@w{@@-commands} used in node names generally confuse Info, so you +should avoid them. This includes punctuation characters that are +escaped with a @samp{@@}, such as @code{@@} and @code{@{}. For a few +rare cases when this is useful, Texinfo has limited support for using +@w{@@-commands} in node names; see @ref{Pointer Validation}. @need 750 Thus, the beginning of the section called @code{@@chapter} looks like @@ -4780,6 +4794,12 @@ this:@refill @end smallexample @item +@cindex Parentheses in nodename +You cannot use parentheses in node names, because a node name such as +@samp{(foo)bar} is interpreted by the Info readers as a node +@samp{bar} in an Info file @file{foo}. + +@item @cindex Apostrophe in nodename @cindex Colon in nodename @cindex Comma in nodename @@ -4787,7 +4807,7 @@ this:@refill @cindex Characters, invalid in node name @cindex Invalid characters in node names Unfortunately, you cannot use periods, commas, colons or apostrophes -within a node name; these confuse @TeX{} or the Info formatters.@refill +within a node name; these confuse @TeX{} or the Info formatters. @need 700 For example, the following is a section title: @@ -4846,7 +4866,7 @@ 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 +@xref{Installing an Info File}, for more information about installing an Info file in the @file{info} directory. @@ -4906,6 +4926,7 @@ 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 @section Creating Pointers with @code{makeinfo} @cindex Creating pointers with @code{makeinfo} @@ -4933,6 +4954,12 @@ This node pointer insertion feature in @code{makeinfo} relieves you from the need to update menus and pointers manually or with Texinfo mode commands. (@xref{Updating Nodes and Menus}.) +In most cases, you will want to take advantage of this feature and not +redundantly specify node pointers. However, Texinfo documents are not +required to be organized hierarchically or in fact contain sectioning +commands at all. For example, if you never intend the document to be +printed. In those cases, you will need to explicitly specify the pointers. + @node anchor @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets @@ -5278,7 +5305,7 @@ 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 +nodes of each Info document. (@xref{Installing an Info File}.) @need 700 For example: @@ -6275,48 +6302,47 @@ The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. An example of the two-argument form: @example -The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds -programs and texts. +The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} +holds programs and texts. @end example @noindent produces: @display -The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds -programs and texts. +The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} +holds programs and texts. @end display @noindent that is, the Info output is this: @example -The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds -programs and texts. +The official GNU ftp site (ftp://ftp.gnu.org/gnu) +holds programs and texts. @end example @noindent and the HTML output is this: @example -The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds -programs and texts. +The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> +holds programs and texts. @end example An example of the three-argument form: @example -The @@uref@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{} +The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{} @end example @noindent produces: @display -The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{} +The @uref{/man.cgi/1/ls,,ls(1)} program @dots{} @end display @noindent but with HTML: @example -The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program @dots{} +The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{} @end example To merely indicate a url without creating a link people can follow, use @code{@@url} (@pxref{url, @code{@@url}}). - Some people prefer to display url's in the unambiguous format: @display @@ -6324,7 +6350,7 @@ Some people prefer to display url's in the unambiguous format: @end display @noindent -@cindex <URL: convention, not used +@cindex <URL convention, not used You can use this form in the input file if you wish. We feel it's not necessary to clutter up the output with the extra @samp{<URL:} and @samp{>}, since any software that tries to detect url's in text already @@ -6351,8 +6377,8 @@ program. Also, you can emphasize text, in several different ways. * 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. @@ -6380,7 +6406,8 @@ not something else that should not be changed.@refill * code:: Indicating program code. * kbd:: Showing keyboard input. * key:: Specifying keys. -* samp:: Showing a literal sequence of characters. +* samp:: A literal sequence of characters. +* verb:: A verbatim sequence of characters. * var:: Indicating metasyntactic variables. * env:: Indicating environment variables. * file:: Indicating file names. @@ -6712,8 +6739,7 @@ example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and @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 +@node samp @subsection @code{@@samp}@{@var{text}@} @findex samp @@ -6767,6 +6793,38 @@ In English, the vowels are @samp{a}, @samp{e}, @end quotation +@node verb +@subsection @code{@@verb}@{<char>@var{text}<char>@} +@findex verb +@cindex Verbatim in-line text + +@cindex Delimiter character, for verbatim +Use the @code{@@verb} command to print a verbatim sequence of +characters. + +Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using +any unique delimiter character. Enclose the verbatim text, including the +delimiters, in braces. Text is printed in a fixed-width font: + +@example +How many @@verb@{|@@|@}-escapes does one need to print this +@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this? +@end example + +@noindent +produces + +@example +How many @verb{|@|}-escapes does one need to print this +@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this? +@end example + +This is in contrast to @code{@@samp} (see the previous +section), whose argument is normal Texinfo text, where the characters +@code{@@@{@}} are special; with @code{@@verb}, nothing is special except +the delimiter character you choose. + + @node var @subsection @code{@@var}@{@var{metasyntactic-variable}@} @findex var @@ -6859,11 +6917,11 @@ section). For example: @example -The @@env@{PATH@} environment variable sets the search path for commands. +The @@env@{PATH@} environment variable @dots{} @end example @noindent produces @quotation -The @env{PATH} environment variable sets the search path for commands. +The @env{PATH} environment variable @dots{} @end quotation @@ -7093,17 +7151,17 @@ the text to display if any. In HTML output, @code{@@email} produces a For example: @example -Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}. -Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. +Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, +suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. @end example @noindent produces @display -Send bug reports to @email{bug-texinfo@@gnu.org}. -Send suggestions to the @email{bug-texinfo@@gnu.org, same place}. +Send bug reports to @email{bug-texinfo@@gnu.org}, +suggestions to the @email{bug-texinfo@@gnu.org, same place}. @end display -@node Emphasis, , Indicating, Marking Text +@node Emphasis @comment node-name, next, previous, up @section Emphasizing Text @cindex Emphasizing text @@ -7267,7 +7325,8 @@ produces 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 +language. + @node Quotations and Examples @chapter Quotations and Examples @@ -7282,25 +7341,26 @@ 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 +line. @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:: How to illustrate Lisp code. +* Block Enclosing Commands:: Different constructs for different purposes. +* quotation:: Writing a quotation. +* example:: Writing an example in a fixed-width font. +* verbatim:: Writing a verbatim example. +* verbatiminclude:: Including a file verbatim. +* lisp:: Illustrating Lisp code. * small:: Forms for @code{@@smallbook}. -* 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. +* display:: Writing an example in the current font. +* format:: Writing an example without narrowed margins. +* exdent:: Undo indentation on a line. +* flushleft & flushright:: Pushing text flush left or flush right. +* noindent:: Preventing paragraph indentation. +* cartouche:: Drawing rounded rectangles around examples. @end menu + @node Block Enclosing Commands @section Block Enclosing Commands @@ -7310,16 +7370,22 @@ following sections: @table @code @item @@quotation Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default.@refill +printed in a roman font by default. @item @@example Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled.@refill +in a fixed-width font, and indented but not filled. + +@item @@verbatim +Mark a piece of text that is to be printed verbatim; no character +substitutions are made and all commands are ignored, until the next +@code{@@end verbatim}. The text is printed in a fixed-width font, +and not indented or filled. Extra spaces and blank lines are +significant, and tabs are expanded. @item @@smallexample Same as @code{@@example}, except that in @TeX{} this command typesets -text in a smaller font for the @code{@@smallbook} format than for the -default 8.5 by 11 inch format. +text in a smaller font. @item @@lisp Like @code{@@example}, but specifically for illustrating Lisp code. The @@ -7351,7 +7417,7 @@ 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 +paragraph. You can use the @code{@@cartouche} command within one of the above constructs to highlight the example or quotation by drawing a box with @@ -7408,13 +7474,13 @@ This is a foo. @node example -@section @code{@@example} +@section @code{@@example}: Example Text @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 +not part of the running text, such as computer input or output. @example @group @@ -7463,11 +7529,11 @@ Note that blank lines inside the beginning 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 +@strong{Caution:} Do not use tabs in the lines of an example or anywhere +else in Texinfo (except in verbatim environments)! The @TeX{} +implementation of Texinfo treats tabs as single spaces, and that is not +what they look like. (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 @@ -7483,66 +7549,84 @@ embedded within sentences, not set off from preceding and following text. @xref{code, , @code{@@code}}.) -@node noindent -@section @code{@@noindent} -@findex noindent +@node verbatim +@section @code{@@verbatim}: Literal Text +@findex verbatim +@cindex Verbatim environment -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 +Use the @code{@@verbatim} environment for printing of text that may +contain special characters or commands that should not be interpreted, +such as computer input or output (@code{@@example} interprets its text +as regular Texinfo commands). This is especially useful for including +automatically generated output in a Texinfo manual. Here is an example; +the output you see is just the same as the input, with a line +@code{@@verbatim} before and a line @code{@@end verbatim} after. + +@verbatim +This is an example of text written in a @verbatim +block. No character substitutions are made all commands +are ignored, until the next 'end verbatim' command. + +In the printed manual, the text is typeset in a +fixed-width font, and not indented or filled. All +spaces and blank lines are significant, including tabs. +@end verbatim + +Write a @code{@@verbatim} command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the verbatim +block with a @code{@@end verbatim} command, also written at the +beginning of a line by itself. The @code{@@end verbatim} will also +disappear from the output. -@need 1500 For example: +@c urg: got to trick this a bit: can't use @end verbatim inside @verbatim @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 +@exdent @@verbatim +@exdent @{ +@exdent <tab>@@command with strange characters: @@'e +@exdent expand<tab>me +@exdent @} +@exdent @@end verbatim @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 +@verbatim +{ + @command with strange characters: @'e +expand me +} +@end verbatim -@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 +Since the lines containing @code{@@verbatim} and @code{@@end verbatim} +will disappear, tyically you should put a blank line before the +@code{@@verbatim} and another blank line after the @code{@@end +verbatim}. Blank lines between the beginning @code{@@verbatim} and the +ending @code{@@end verbatim} will appear in the output.) -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 +@node verbatiminclude +@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim +@cindex Verbatim, include file +@cindex Including a file verbatim +@findex verbatiminclude -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 +You can include the exact contents of a file in the document with the +@code{@@verbatiminclude} command: + +@example +@@verbatiminclude @var{filename} +@end example + +The contents of @var{filename} is printed in a verbatim environment +(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed +exactly as it is, with all special characters and white space retained. @node lisp -@section @code{@@lisp} +@section @code{@@lisp}: Marking a Lisp Example @findex lisp @cindex Lisp example @@ -7567,9 +7651,9 @@ itself.@refill @node small @section @code{@@small@dots{}} Block Commands -@cindex Small book example -@cindex Example for a small book -@cindex Lisp example for a small book +@cindex Small examples +@cindex Examples in smaller fonts +@cindex Lisp examples in smaller fonts @findex smalldisplay @findex smallexample @findex smallformat @@ -7578,19 +7662,13 @@ itself.@refill In addition to the regular @code{@@example} and @code{@@lisp} commands, Texinfo has ``small'' example-style commands. These are @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and -@code{@@smalllisp}. All of these commands are designed for use with the -@code{@@smallbook} command (which causes @TeX{} to format a printed book for -a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size). +@code{@@smalllisp}. In @TeX{}, the @code{@@small@dots{}} 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{@@small@dots{}} -commands are equivalent to their non-small versions. - -In Info, the @code{@@small@dots{}} commands are also equivalent to their +font than the non-small example commands. Consequently, many examples +containing long lines fit on a page without needing to be shortened. + +In Info, the @code{@@small@dots{}} commands are equivalent to their non-small companion commands. Mark the end of an @code{@@small@dots{}} block with a corresponding @@ -7621,24 +7699,22 @@ programs; and that you know you can do these things.} @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. +@code{@@end smallexample}. In Info this text appears in its normal size; +but in printed manuals, 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. +@code{@@end smallexample}. In Info 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{@@small@dots{}} commands make it easier to prepare smaller -format manuals without forcing you to edit examples by hand to fit them -onto narrower pages.@refill +The @code{@@small@dots{}} commands make it easier to prepare manuals +without forcing you to edit examples by hand to fit them onto narrower +pages. As a general rule, a printed document looks better if you use only one of (for example) @code{@@example} or in @code{@@smallexample} @@ -7646,7 +7722,7 @@ consistently within a chapter. Only occasionally should you mix the two formats. @xref{smallbook, , Printing ``Small'' Books}, for more information -about the @code{@@smallbook} command.@refill +about the @code{@@smallbook} command. @node display @@ -7736,10 +7812,13 @@ 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 + +@node flushleft & flushright @section @code{@@flushleft} and @code{@@flushright} @findex flushleft @findex flushright +@cindex ragged right +@cindex ragged left The @code{@@flushleft} and @code{@@flushright} commands line up the ends of lines on the left and right margins of a page, @@ -7795,16 +7874,76 @@ right justifies every line but leaves the left end ragged. @end flushright -@node cartouche, , flushleft & flushright, Quotations and Examples -@section Drawing Cartouches Around Examples + +@node noindent +@section @code{@@noindent}: Omitting Indentation +@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 cartouche +@section @code{@@cartouche}: Rounded Rectangles Around Examples @findex cartouche @cindex Box with rounded corners +@cindex Rounded rectangles, around examples 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 +for emphasis. @code{@@cartouche} affects only the printed manual; it has no effect in other output files. @@ -7841,7 +7980,7 @@ In a printed manual, the example looks like this:@refill @end iftex -@node Lists and Tables, Indices, Quotations and Examples, Top +@node Lists and Tables @chapter Lists and Tables @cindex Making lists and tables @cindex Lists and tables, making @@ -8944,7 +9083,7 @@ 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)} +@findex <colon> @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 @@ -9070,6 +9209,8 @@ Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by Do not follow any of these commands with braces. +To produce a non-breakable space, see @ref{w, non-breakable space}. + @node dmn @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension @@ -9208,7 +9349,7 @@ commonly used in languages other than English. @cindex Es-zet @cindex Sharp S @cindex German S -@multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S} +@multitable {x@@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 @@ -9335,6 +9476,8 @@ available. @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign @findex minus +@cindex em-dash +@cindex hyphen 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 @@ -9361,10 +9504,11 @@ an itemized list, you do not need to type the braces (@pxref{itemize, , @code{@@itemize}}.) -@node math, Glyphs, minus, Insertions +@node math @section @code{@@math}: Inserting Mathematical Expressions @findex math @cindex Mathematical expressions +@cindex Formulas, mathematical You can write a short mathematical expression with the @code{@@math} command. Write the mathematical expression between braces, like this: @@ -9374,20 +9518,16 @@ command. Write the mathematical expression between braces, like this: @end example @iftex -@need 1000 -@noindent -This produces the following in @TeX{}: +@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: +@noindent and the following in Info: @end iftex @ifinfo -@noindent -This produces the following in Info: +@noindent This produces the following in Info: @end ifinfo @example @@ -9396,15 +9536,38 @@ This produces the following in Info: 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. +@code{@@math} implies @code{@@tex}. This not only makes it possible to +write superscripts and subscripts (as in the above example), but also +allows you to use any of the plain @TeX{} math control sequences. It's +simplest to use @samp{\} instead of @samp{@@} for these commands. As +in: +@example +@@math@{\sin 2\pi \equiv \cos 3\pi@} +@end example + +@iftex +@noindent which looks like this in @TeX{}: +@display +@math{\sin 2\pi \equiv \cos 3\pi} +@end display + +@noindent and +@end iftex +@noindent which looks like the input in Info and HTML: +@example +\sin 2\pi \equiv \cos 3\pi +@end example + +@cindex Displayed equations +@cindex Equations, displayed +For displayed equations, you must at present use @TeX{} directly +(@pxref{Raw Formatter Commands}). @node Glyphs @section Glyphs for Examples @cindex Glyphs +@cindex Examples, glyphs for In Texinfo, code is often illustrated in examples that are delimited by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and @@ -9429,12 +9592,11 @@ left- and right-hand braces.@refill * Point Glyph:: How to indicate the location of point. @end menu -@node Glyphs Summary, result, Glyphs, Glyphs -@ifinfo -@subheading Glyphs Summary + +@node Glyphs Summary +@subsection Glyphs Summary Here are the different glyph commands:@refill -@end ifinfo @table @asis @item @result{} @@ -9457,7 +9619,6 @@ message.@refill @code{@@point@{@}} shows the location of point.@refill @end table - @menu * result:: * expansion:: @@ -9467,7 +9628,8 @@ message.@refill * Point Glyph:: @end menu -@node result, expansion, Glyphs Summary, Glyphs + +@node result @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation @cindex Result of an expression @cindex Indicating evaluation @@ -9757,13 +9919,14 @@ 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 +University of Chicago Press.} @menu * Footnote Commands:: How to write a footnote in Texinfo. * Footnote Styles:: Controlling how footnotes appear in Info. @end menu + @node Footnote Commands @subsection Footnote Commands @@ -9783,16 +9946,21 @@ marker might end up starting 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 +this: @example @dots{}a sample footnote@@footnote@{Here is the sample footnote.@}; in the Texinfo source@dots{} @end example +As you can see, the source includes two punctuation marks next to each +other; in this case, @samp{.@};} is the sequence. This is normal (the +first ends the footnote and the second belongs to the sentence being +footnoted), so don't worry that it looks odd. + In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line.@refill +bottom of the page, below a horizontal line. In Info, the reference mark for a footnote is a pair of parentheses with the footnote number between them, like this: @samp{(1)}. The @@ -9950,7 +10118,7 @@ You can insert an image given in an external file with the @code{@@image} command: @example -@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} +@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@} @end example @cindex Formats for images @@ -9968,13 +10136,26 @@ PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). @code{makeinfo} uses @file{@var{filename}.txt} verbatim for Info output (more or less as if it was an @code{@@example}). @item +@code{makeinfo} +uses the optional fifth argument to @code{@@image} for the extension if +you supply it. For example: + +@pindex XPM image format +@example +@@image@{foo,,,,xpm@} +@end example + +@noindent +will cause @samp{makeinfo --html} to try @file{foo.xpm}. + @cindex GIF, unsupported due to patents @cindex PNG image format -@cindex JPEG image format -@code{makeinfo} producing HTML output tries @file{@var{filename}.png}; -if that does not exist, it tries @file{@var{filename}.jpg}. If that -does not exist either, it complains. (We cannot support GIF format due -to patents.) +@cindex JPG image format +If you do not supply the optional fifth argument, @samp{makeinfo +---html} first tries @file{@var{filename}.png}; if that does not exist, +it tries @file{@var{filename}.jpg}. If that does not exist either, it +complains. (We cannot support GIF format directly due to software +patents.) @end itemize @cindex Width of images @@ -10035,38 +10216,48 @@ For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be installed somewhere that @TeX{} can find it. (The standard location is @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a root of your @TeX{} directory tree.) This file is included in the -Texinfo distribution and is available from -@uref{ftp://tug.org/tex/epsf.tex}. +Texinfo distribution and is also available from +@uref{ftp://tug.org/tex/epsf.tex}, among other places. @code{@@image} can be used within a line as well as for displayed figures. Therefore, if you intend it to be displayed, be sure to leave a blank line before the command, or the output will run into the preceding text. +@cindex alt attribute for images +@cindex alternate text for images +When producing html, @code{makeinfo} sets the @dfn{alt attribute} for +inline images to the optional fourth argument to @code{@@image}, if +supplied. If not supplied, @code{makeinfo} uses the full file name of +the image being displayed. + @node Breaks @chapter Making and Preventing Breaks @cindex Making line and page breaks @cindex Preventing line and page breaks +@cindex Line 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 +Info file. +@cindex White space, excessive +@cindex Page breaks 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 +commands. @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. +* - 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. @@ -10074,6 +10265,7 @@ commands.@refill * need:: Another way to prevent unwanted page breaks. @end menu + @node Break Commands, Line Breaks, Breaks, Breaks @ifinfo @heading Break Commands @@ -10120,8 +10312,7 @@ Hold text together that must appear on one printed page.@refill 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 +@node Line Breaks @section @code{@@*}: Generate Line Breaks @findex * @r{(force line break)} @cindex Line breaks @@ -10176,7 +10367,8 @@ refilled after the line break occurs, negating the effect of the line break.@refill @end quotation -@node - and hyphenation, w, Line Breaks, Breaks + +@node - and hyphenation @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate @findex - @@ -10305,8 +10497,8 @@ and is followed by another line. The @code{@@br} command is seldom used. @end ignore -@node page, group, sp, Breaks -@comment node-name, next, previous, up + +@node page @section @code{@@page}: Start a New Page @cindex Page breaks @findex page @@ -10314,7 +10506,8 @@ The @code{@@br} command is seldom used. 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 +section of a Texinfo file to start the copyright page. + @node group, need, page, Breaks @comment node-name, next, previous, up @@ -10555,6 +10748,10 @@ definition.@refill The other specialized commands work like @code{@@defun}.@refill +@cindex Macros in definition commands +Note that, due to implementation difficulties, macros are not expanded +in @code{@@deffn} and all the other definition commands. + @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands @section Optional and Repeated Arguments @cindex Optional and repeated arguments @@ -11621,7 +11818,7 @@ with @code{@@iftex}, not raw formatter source as with @code{@@tex} (@pxref{Raw Formatter Commands}). -@node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals +@node Raw Formatter Commands @section Raw Formatter Commands @cindex @TeX{} commands, using ordinary @cindex HTML commands, using ordinary @@ -11697,147 +11894,45 @@ 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. -* set value:: Expand a flag variable to a string. -* value Example:: An easy way to update edition information. -@end menu - - -@node ifset ifclear -@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} name can be any single word, containing -letters, numerals, hyphens, or underscores. - -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 +Brief descriptions: @table @code -@item @@set @var{flag} -Tell the Texinfo formatting commands that @var{flag} is set.@refill +@item @@set @var{flag} [@var{value}] +Set the variable @var{flag}, to the optional @var{value} if specifed. @item @@clear @var{flag} -Tell the Texinfo formatting commands that @var{flag} is cleared.@refill +Undefine the variable @var{flag}, whether or not it was previously defined. @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 +If @var{flag} is set, text through the next @code{@@end ifset} command +is formatted. If @var{flag} is clear, text through the following +@code{@@end ifset} command is ignored. @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 +If @var{flag} is set, text through the next @code{@@end ifclear} command +is ignored. If @var{flag} is clear, text through the following +@code{@@end ifclear} command is formatted. @end table +@menu +* set value:: Expand a flag variable to a string. +* ifset ifclear:: Format a region if a flag is set. +* value Example:: An easy way to update edition information. +@end menu + @node set value @subsection @code{@@set} and @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. A flag is an -identifier; for best results, use only letters and numerals in a flag -name, not @samp{-} or @samp{_}---they will work in some contexts, but -not all, due to limitations in @TeX{}. The value is just a string of -characters, the remainder of the input line. +You use the @code{@@set} command to specify a value for a flag, which is +later expanded by the @code{@@value} command. + +A @dfn{flag} is an identifier. In general, it is best to use only +letters and numerals in a flag name, not @samp{-} or @samp{_}---they +will work in some contexts, but not all, due to limitations in @TeX{}. + +The value is the remainder of the input line, and can contain anything. Write the @code{@@set} command like this: @@ -11850,12 +11945,12 @@ This sets the value of the flag @code{foo} to ``This is a string.''. The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} command with the string to which @var{flag} is set. Thus, when -@code{foo} is set as shown above, the Texinfo formatters convert +@code{foo} is set as shown above, the Texinfo formatters convert this: @example @group @@value@{foo@} -@exdent @r{to} +@exdent @r{to this:} This is a string. @end group @end example @@ -11870,12 +11965,10 @@ If you write the @code{@@set} command like this: @end example @noindent -without specifying a string, the value of @code{foo} is an empty string. +without specifying a string, the value of @code{foo} is the empty string. If you clear a previously set flag with @code{@@clear @var{flag}}, 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}"@}}. +subsequent @code{@@value@{flag@}} command will report an error. For example, if you set @code{foo} as follows:@refill @@ -11912,12 +12005,83 @@ It is a @{No value for "how-much"@} wet day. @end example +@node ifset ifclear +@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. @code{@@ifclear} operates +analogously. + +Write the conditionally formatted text between @code{@@ifset @var{flag}} +and @code{@@end ifset} commands, like this: + +@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: + +@cindex shrubbery +@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. + +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. + +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: + +@example +@@ifclear @var{flag} +@end example + + @node value Example @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}: +You can use the @code{@@value} command to minimize 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}: @enumerate @item @@ -12033,14 +12197,9 @@ current hyphenation patterns (via the @TeX{} primitive @cindex ISO 639 codes @cindex Language codes -@cindex African languages -Here is the list of valid language codes. This list comes from -@uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free -translation project}. In the future we may wish to allow the 3-letter -POV codes described at @uref{http://www.sil.org/ethnologue/#contents}. -This will be necessary to support African languages. - -@multitable @columnfractions .06 .27 .06 .27 .06 .27 +Hereare the valid language codes, from ISO-639. + +@multitable @columnfractions .07 .26 .07 .26 .07 .26 @item @code{aa} @tab Afar @tab @code{ab} @tab Abkhazian @tab @@ -12245,11 +12404,12 @@ specification following, such as @samp{ISO-8859-1}. @cindex http-equiv, and charset @cindex meta HTML tag, and charset At present, this is used only in HTML output from @code{makeinfo}. If a -document encoding @var{enc} is specified, it is used in the -@samp{<meta>} tag is included in the @samp{<head>} of the output: +document encoding @var{enc} is specified, it is used in a +@samp{<meta>} tag included in the @samp{<head>} of the output: @example -<meta http-equiv="Content-Type" content="text/html; charset=@var{enc}"> +<meta http-equiv="Content-Type" content="text/html; + charset=@var{enc}"> @end example @@ -12297,7 +12457,6 @@ customized output in the Info file. @section Defining Macros @cindex Defining macros @cindex Macro definitions -@cindex Definitions, a.k.a.@: macros @findex macro You use the Texinfo @code{@@macro} command to define a macro, like this: @@ -12351,7 +12510,7 @@ To allow a macro to be used recursively, that is, in an argument to a call to itself, you must define it with @samp{@@rmacro}, like this: @example -@@rmacro rmac +@@rmacro rmac @{arg@} a\arg\b @@end rmacro @dots{} @@ -12423,6 +12582,8 @@ No arguments here. No arguments here. @end display +@cindex Comma, in macro arguments +@cindex Braces, in macro arguments To insert a comma, brace, or backslash in an argument, prepend a backslash, as in @@ -12432,7 +12593,8 @@ backslash, as in @noindent which will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macname}. +@samp{\@{@},} to @var{macname}. However, commas in parameters, even +if escaped by a backslash, might cause trouble in @TeX{}. If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is @@ -12481,13 +12643,18 @@ implementations, Texinfo macros have the following limitations. @itemize @bullet @item All macros are expanded inside at least one @TeX{} group. This means -that @set and other such commands will have no effect inside a macro. +that @code{@@set} and other such commands will have no effect inside a +macro. @item Macros containing a command which must be on a line by itself, such as a conditional, cannot be invoked in the middle of a line. @item +Commas in macro arguments, even if escaped by a backslash, don't +always work. + +@item The @TeX{} implementation cannot construct macros that define macros in the natural way. To do this, you must use conditionals and raw @TeX{}. For example: @@ -12511,6 +12678,10 @@ It is best to avoid comments inside macro definitions. @end itemize +If some macro feature causes errors when producing the printed version +of a manual, try expanding the macros with @command{makeinfo} by +invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format +with texi2dvi}. @node alias @section @samp{@@alias @var{new}=@var{existing}} @@ -12553,7 +12724,7 @@ Aliases must not be recursive, directly or indirectly. @findex definfoenclose A @code{@@definfoenclose} command may be used to define a highlighting -command for Info, but not for TeX. A command defined using +command for Info, but not for @TeX{}. A command defined using @code{@@definfoenclose} marks text by enclosing it in strings that precede and follow the text. You can use this to get closer control of your Info output. @@ -12595,7 +12766,7 @@ formatting command that inserts `//' before and `\\' after the argument to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you want `//bar\\' highlighted in Info. -Also, for TeX formatting, you could write +Also, for @TeX{} formatting, you could write @example @@iftex @@ -12604,14 +12775,13 @@ Also, for TeX formatting, you could write @end example @noindent -to define @code{@@phoo} as a command that causes TeX to typeset the +to define @code{@@phoo} as a command that causes @TeX{} to typeset the argument to @code{@@phoo} in italics. -Note that each definition applies to its own formatter: one for TeX, -the other for @code{texinfo-format-buffer} or -@code{texinfo-format-region}. The @code{@@definfoenclose} command need -not be within @samp{@@ifinfo}, but the raw @TeX{} commands do need to be -in @samp{@@iftex}. +Each definition applies to its own formatter: one for @TeX{}, the other +for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The +@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but +the raw @TeX{} commands do need to be in @samp{@@iftex}. @findex headword Here is another example: write @@ -12665,7 +12835,7 @@ print queue, and delete a job from the print queue. * Preparing for TeX:: What to do before you use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. +* A4 Paper:: How to print on A4 or A5 paper. * pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. @@ -12680,10 +12850,11 @@ file. @TeX{} is a very powerful typesetting program and, if used correctly, 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 (@pxref{Creating an Info File}). +The standalone @code{makeinfo} program and Emacs functions +@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 (@pxref{Creating an Info +File}). @node Format with tex/texindex @@ -12844,7 +13015,7 @@ Perhaps the most useful option to @code{texi2dvi} is after the @code{@@setfilename} in a temporary copy of the input file before running @TeX{}. With this, you can specify different printing formats, such as @code{@@smallbook} (@pxref{smallbook}), -@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pageparams} +@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} (@pxref{pagesizes}), without actually changing the document source. (You can also do this on a site-wide basis with @file{texinfo.cnf}; @pxref{Preparing for TeX,,Preparing for @TeX{}}). @@ -12852,16 +13023,15 @@ formats, such as @code{@@smallbook} (@pxref{smallbook}), For a list of other options, run @samp{texi2dvi --help}. -@node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy +@node Print with lpr @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}.) +installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr +-d foo.dvi}. -For example, the following commands, will (perhaps) suffice to sort the +For example, the following commands will (perhaps) suffice to sort the indices, format, and print the @cite{Bison Manual}: @example @@ -12875,15 +13045,15 @@ lpr -d bison.dvi @noindent (Remember that the shell commands may be different at your site; but -these are commonly used versions.)@refill +these are commonly used versions.) -@need 1000 -Using the @code{texi2dvi} shell script, you simply need type:@refill +Using the @code{texi2dvi} shell script (see the previous section): @example @group texi2dvi bison.texinfo lpr -d bison.dvi +# or perhaps dvips bison.dvi -o @end group @end example @@ -13155,26 +13325,28 @@ For more information, see: @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. +@TeX{} needs to know where to find the @file{texinfo.tex} file that the +@samp{\input texinfo} command on the first line reads. 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. + +Usually, the installer has put the @file{texinfo.tex} file in the +default directory that contains @TeX{} macros when GNU Texinfo, Emacs or +other GNU software is installed. In this case, @TeX{} will find the +file and you do not need to do anything special. If this has not been +done, you can put @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}). +Also, you should install @file{epsf.tex}, if it is not already installed +from another distribution. More details are at the end of the description +of the @code{@@image} command (@pxref{Images}). + +@pindex pdfcolor.tex@r{, installing} +Likewise for @file{pdfcolor.tex}, if it is not already installed and you +use pdftex. @pindex texinfo.cnf @r{installation} @cindex Customizing of @TeX{} for Texinfo @@ -13254,10 +13426,9 @@ redumping.) You can do this by running this command, assuming initex texinfo @@dump @end example -(@code{@@dump} is a @TeX{} primitive.) You'll then need to move -@file{texinfo.fmt} to wherever your @code{.fmt} files are found; -typically this will be in the subdirectory @file{web2c} of your @TeX{} -installation, for example, @file{/usr/local/share/tex/web2c}. +(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to +wherever your @code{.fmt} files are found; typically, this will be in the +subdirectory @file{web2c} of your @TeX{} installation. @node Overfull hboxes @@ -13305,10 +13476,10 @@ like this: @end example @noindent -(You can adjust the fraction as needed.) This huge value for +(You should adjust the fraction as needed.) This huge value for @code{\emergencystretch} cannot be the default, since then the typeset -output would generally be of noticeably lower quality. The default -value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension +output would generally be of noticeably lower quality; the default +is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension containing the current line width. @cindex Black rectangle in hardcopy @@ -13369,15 +13540,16 @@ require changing the source file. @node A4 Paper @section Printing on A4 Paper @cindex A4 paper, printing on -@cindex Paper size, European A4 +@cindex A5 paper, printing on +@cindex Paper size, A4 @cindex European A4 paper @findex afourpaper You can tell @TeX{} to format a document for printing on European size -A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself near the beginning of the Texinfo file, before the title -page. For example, this is how you would write the header for this -manual: +A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) +command. Write the command on a line by itself near the beginning of +the Texinfo file, before the title page. For example, this is how you +would write the header for this manual: @example @group @@ -13391,15 +13563,15 @@ manual: @end example @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to format with @code{@@afourpaper} that do not +@TeX{}}, for other ways to format for different paper sizes that do not require changing the source file. @findex afourlatex +@findex afourwide You may or may not prefer the formatting that results from the command @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in wide format. - @node pagesizes @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes @findex pagesizes @@ -13515,21 +13687,21 @@ You can generate a PDF output file from Texinfo source by using the @command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}. -PDF stands for Portable Document Format, and was invented by Adobe -Systems. The -@uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format -definition} is freely available, as is a -@uref{http://www.foolabs.com/xpdf/, free viewer} for the X window -system. Since PDF is a binary format, there is no @samp{@@ifpdf} or -@samp{@@pdf} command by analogy with the other output formats. +@dfn{PDF} stands for `Portable Document Format'. It was invented by +Adobe Systems some years ago for document interchange, based on their +PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader} +for the X window system is freely available, as is the +@uref{http://partners.adobe.com/asn/developer/technotes/, definition of +the file format}. Since PDF is a binary format, there are no +@samp{@@ifpdf} or @samp{@@pdf} commands as with the other output +formats. Despite the `portable' in the name, PDF files are nowhere near as -portable in practice as the plain ASCII formats (Info, HTML) Texinfo -also supports (portability relative to DVI is arguable). They also tend -to be much larger and do not support the bitmap fonts used by @TeX{} (by +portable in practice as the plain ASCII formats (Info, HTML) that +Texinfo supports (DVI portability is arguable). They also tend to be +much larger and do not support the bitmap fonts used by @TeX{} (by default) very well. Nevertheless, a PDF file does preserve an actual -printed document on a screen as faithfully as possible, unlike HTML, -say, so have their place. +printed document on a screen as faithfully as possible, so it has its place. PDF support in Texinfo is fairly rudimentary. @@ -13537,15 +13709,15 @@ PDF support in Texinfo is fairly rudimentary. @node Creating and Installing Info Files @chapter Creating and Installing Info Files -This chapter describes how to create and install info files. @xref{Info +This chapter describes how to create and install Info files. @xref{Info Files}, for general information about the file format itself. - @menu * Creating an Info File:: -* Install an Info File:: +* Installing an Info File:: @end menu + @node Creating an Info File @section Creating an Info File @cindex Creating an Info file @@ -13558,7 +13730,7 @@ file, HTML file, or plain text. @code{texinfo-format-region} and Texinfo to Info. For information on installing the Info file in the Info system, -@pxref{Install an Info File}. +@pxref{Installing an Info File}. @menu * makeinfo advantages:: @code{makeinfo} provides better error checking. @@ -13668,6 +13840,10 @@ can probably never be implemented in @TeX{}. It also makes @samp{--no-validate} is used. @xref{Pointer Validation}, for more details. +@item --docbook +@opindex --docbook +Generate DocBook output rather than Info. + @item --error-limit=@var{limit} @itemx -e @var{limit} @opindex --error-limit=@var{limit} @@ -13714,7 +13890,11 @@ created. With this option, they are preserved. Print a usage message listing all available options, then exit successfully. @item --html -Generate HTML output rather than Info. @xref{makeinfo html}. +@opindex --html +Generate HTML output rather than Info. @xref{makeinfo html}. By +default, the HTML output is split into one output file per source node, +and the split output is written into a subdirectory with the name of the +top-level info file. @item -I @var{dir} @opindex -I @var{dir} @@ -13796,8 +13976,8 @@ 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. For split -HTML output, @var{file} is the name of the output file for the top node -(@pxref{makeinfo html}). +HTML output, @var{file} is the name for the directory into which all +HTML nodes are written (@pxref{makeinfo html}). @item -P @var{dir} @opindex -P @var{dir} @@ -13850,6 +14030,10 @@ warnings. @opindex -V Print the version number, then exit successfully. +@item --xml +@opindex --xml +Generate XML output rather than Info. + @end table @@ -14205,14 +14389,26 @@ Info-validate}.@refill @subsection Generating HTML @cindex HTML -As an alternative to the normal Info format output you can use the +Besides generating output in the Info format, you can use the @samp{--html} option to generate output in HTML format, for installation -on a web site (for example). In this release, HTML output from -@code{makeinfo} is monolithic, splitting the output by chapter or node -is not supported. We hope to implement this feature soon. - -The HTML output file is named according to @code{@@setfilename}, but -with any @samp{.info} extension replaced with @samp{.html}. +on a web site (for example). By default, the HTML output is split at +node level. + +When splitting, the HTML output files are written into a subdirectory. +The subdirectory is named according to the name from +@code{@@setfilename} with any extension removed; for example, HTML +output for @code{@@setfilename emacs.info} would be written into a +subdirectory named @samp{emacs}. If that directory cannot be created +for any reason, then @samp{.html} is appended to the directory name, as +in @samp{emacs.html} (this is necessary because sometimes the info file +is named without an extension, e.g., @samp{texinfo}). If the +@samp{@var{name}.html} directory can't be created either, +@code{makeinfo} gives up. In any case, the top-level output file within +the directory is always named @samp{index.html}. + +Monolithic output (@code{--no-split}) is named according to +@code{@@setfilename} or @code{--outfile}. Cross-document node +references are not supported in monolithic HTML. Texinfo input marked up with the @code{@@ifhtml} command will produce output only with the @samp{--html} option supplied. Input marked up @@ -14221,29 +14417,26 @@ the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters which have special significance in HTML). The @samp{--footnote-style} option is currently ignored for HTML output; -footnotes are hyperlinked at the end of the output file. +footnotes are linked to the end of the output file. -The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The +The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The exception is that HTML 3.2 tables are generated from the @code{@@multitable} command, but tagged to degrade as well as possible in browsers without table support. Please report output from an -error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a -bug. +error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as +a bug. Navigation bars are inserted at the start of nodes, similarly to Info output. The @samp{--no-headers} option will suppress this if used with @samp{--no-split}. Header @code{<link>} elements in split output can support info-like navigation with browsers like Lynx and @w{Emacs W3} -which implement this @w{HTML 1.0} feature. You still won't normally get -the multi-file regexp and index search facilities provided by Info -readers. Otherwise, hyperlinks are generated from Texinfo commands -where appropriate. @samp{@@xref} commands to other documents are -generated assuming the other document is available in HTML form too, and -@samp{.html} is appended to the @samp{@@xref} Info file name. This -presumably will often not work. +which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to +other documents are generated assuming the other document is available +in split HTML form, and installed in the same HTML documentation tree, +at @file{../<info-document>/}. -@node Install an Info File +@node Installing an Info File @section Installing an Info File @cindex Installing an Info file @cindex Info file installation @@ -14285,7 +14478,7 @@ this:@refill text editor. * Texinfo: (texinfo). With one source file, make either a printed manual using - TeX or an Info file. + @@TeX@{@} or an Info file. @dots{} @end group @end example @@ -14316,9 +14509,9 @@ true in general, it is a special case for @file{dir}. @node New Info File @subsection 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 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 a new @cindex @file{dir} file listing @@ -14391,23 +14584,23 @@ standard @file{dir} file:@refill In this case, the absolute file name of the @file{info-test} file is written as the second part of the menu entry.@refill -Alternatively, you could write the following in your @file{.emacs} -file:@refill +Alternatively, you could write the following in your @file{.emacs} file: @vindex Info-directory-list @example @group (require 'info) (setq Info-directory-list - (cons (expand-file-name "/home/bob/info") Info-directory-list)) + (cons (expand-file-name "/home/bob/info") + Info-directory-list)) @end group @end example -This tells Emacs to merge the @file{dir} file from the -@file{/home/bob/info} directory with the system @file{dir} file. Info -will list the @file{/home/bob/info/info-test} file as a menu entry in -the @file{/home/bob/info/dir} file. Emacs does the merging only -when @kbd{M-x info} is first run, so if you want to set +This tells Emacs to merge the system @file{dir} file with the @file{dir} +file in @file{/home/bob/info}. Thus, Info will list the +@file{/home/bob/info/info-test} file as a menu entry in the +@file{/home/bob/info/dir} file. Emacs does the merging only when +@kbd{M-x info} is first run, so if you want to set @code{Info-directory-list} in an Emacs session where you've already run @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs to recompose the @file{dir} file. @@ -14461,7 +14654,7 @@ merges any files named @file{dir} in any directory listed in the @env{INFOPATH} variable into a single menu presented to you in the node called @samp{(dir)Top}. -@cindex @samp{:} @r{last in @env{INFOPATH}} +@cindex colon, last in @env{INFOPATH} However you set @env{INFOPATH}, if its last character is a colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this is replaced by the default (compiled-in) path. This gives you a way to @@ -14485,7 +14678,7 @@ copying an existing @file{dir} file and replace all the text after the special CTRL-_ characters that Info needs will be present. -@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File +@node Installing Dir Entries @subsection Installing Info Directory Files When you install an Info file onto your system, you can use the program @@ -14536,12 +14729,22 @@ If you use @code{@@dircategory} more than once in the Texinfo source, each usage specifies the `current' category; any subsequent @code{@@direntry} commands will add to that category. -Here are some recommended @code{@@dircategory} categories: `GNU -packages', `GNU programming tools', `GNU programming documentation', -`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual -utilities'. The idea is to include the `invoking' node for every -program installed by a package under `Individual utilities', and an -entry for the manual as a whole in the appropriate other category. +Here are some recommended @code{@@dircategory} categories: + +@display +GNU packages +GNU programming tools +GNU programming documentation +GNU Emacs Lisp +GNU libraries +Linux +TeX +Individual utilities +@end display + +The idea is to include the `Invoking' node for every program installed +by a package under `Individual utilities', and an entry for the manual +as a whole in the appropriate other category. @node Invoking install-info @@ -14750,6 +14953,9 @@ capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}. Generate the uppercase and lowercase AE ligatures, respectively: @AE{}, @ae{}. @xref{Inserting Accents}. +@itemx @@afivepaper +Change page dimensions for the A5 paper size. @xref{A4 Paper}. + @item @@afourlatex @itemx @@afourpaper @itemx @@afourwide @@ -15052,8 +15258,13 @@ 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}}. +@item @@documentdescription +Set the document description text, included in the HTML output. Pair +with @code{@@end documentdescription}. @xref{documentdescription,, +@code{@@documentdescription}}. + @item @@documentencoding @var{enc} -Declare the input encoding as @var{enc}. +Declare the input encoding to be @var{enc}. @xref{documentencoding,, @code{@@documentencoding}}. @item @@documentlanguage @var{CC} @@ -15245,9 +15456,10 @@ 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}]@} +@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} Include graphics image in external @var{filename} scaled to the given -@var{width} and/or @var{height}. @xref{Images}. +@var{width} and/or @var{height}, using @var{alt} text and looking for +@samp{@var{filename}.@var{ext}} in HTML. @xref{Images}. @item @@include @var{filename} Incorporate the contents of the file @var{filename} into the Info file @@ -15503,7 +15715,8 @@ command even if the @code{@@shortcontents} command is not there. @xref{Contents}. @item @@settitle @var{title} -Provide a title for page headers in a printed manual. +Provide a title for page headers in a printed manual, and the default +document description for HTML @samp{<head>}. @xref{settitle, , @code{@@settitle}}.@refill @item @@shortcontents @@ -15521,28 +15734,23 @@ rather than the regular 8.5 by 11 inch format. @xref{smallbook, , Printing Small Books}. Also, see @ref{small}. @item @@smalldisplay -Begin a kind of example. Like @code{@@smallexample} (indent text, no -filling), but do not select the fixed-width font. In @code{@@smallbook} -format, print text in a smaller font than with @code{@@display}. Pair -with @code{@@end smalldisplay}. @xref{small}. +Begin a kind of example. Like @code{@@smallexample} (narrow margins, no +filling), but do not select the fixed-width font. Pair with @code{@@end +smalldisplay}. @xref{small}. @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}. +font, narrow the margins. In printed manuals, print text in a smaller +font than with @code{@@example}. Pair with @code{@@end smallexample}. @xref{small}. @item @@smallformat Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow -the margins and do not select the fixed-width font. -In @code{@@smallbook} format, print text in a smaller font than -with @code{@@format}. Pair with @code{@@end smallformat}. -@xref{small}. +the margins. Pair with @code{@@end smallformat}. @xref{small}. @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{small}. +Begin an example of Lisp code. Same as @code{@@smallexample}. Pair +with @code{@@end smalllisp}. @xref{small}. @item @@sp @var{n} Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill @@ -15735,6 +15943,19 @@ Highlight a metasyntactic variable, which is something that stands for another piece of text. @xref{var, , Indicating Metasyntactic Variables}.@refill +@item @@verb@{@var{delim} @var{literal} @var{delim}@} +Output @var{literal}, delimited by the single character @var{delim}, +exactly as is (in the fixed-width font), including any whitespace or +Texinfo special characters. @xref{verb,,@code{verb}}. + +@item @@verbatim +Output the text of the environment exactly as is (in the fixed-width +font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}. + +@item @@verbatiminclude @var{filename} +Output the contents of @var{filename} exactly as is (in the fixed-width font). +@xref{verbatiminclude,,@code{verbatiminclude}}. + @item @@vindex @var{entry} Add @var{entry} to the index of variables. @xref{Index Entries, , Defining the Entries of an Index}.@refill @@ -16125,12 +16346,12 @@ file, but only when the command is used inside parentheses. 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 +sections are all different, they are difficult for users to find. + +So, there is a convention to name such sections with a phrase beginning +with the word `Invoking', as in `Invoking Emacs'; this way, users can +find the section easily. -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 @@ -16224,27 +16445,30 @@ You can see this file, with comments, in the first chapter. @@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. +Copyright (C) 2002 Free Software Foundation, Inc. @@end ifinfo @@titlepage -@@sp 10 @@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} +@@title Sample Title @@c The following two commands start the copyright page. @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end titlepage -@@node Top, First Chapter, , (dir) -@@comment node-name, next, previous, up +@@c Output the table of the contents at the beginning. +@@contents + +@@ifnottex +@@node Top + +This is the top node of a sample document. +@@end ifnottex @@menu * First Chapter:: The first chapter is the @@ -16252,10 +16476,10 @@ Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. * Concept Index:: This index has two entries. @@end menu -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up + +@@node First Chapter @@chapter First Chapter -@@cindex Sample index entry +@@cindex Chapter, first This is the contents of the first chapter. @@cindex Another sample index entry @@ -16270,165 +16494,20 @@ This is the first 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. +The @@code@{makeinfo@} command transforms a Texinfo source file +such as this into an Info file or HTML; and @@TeX typesets it +for a printed manual. -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up + +@@node Concept Index @@unnumbered Concept Index @@printindex cp -@@contents @@bye @end example -@node Sample Permissions -@appendix Sample Permissions -@cindex Permissions -@cindex Sample 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 -@section 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 - -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. - -@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions -@comment node-name, next, previous, up -@section @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 1999 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 -@section 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 @appendix Include Files @cindex Include files @@ -16440,7 +16519,7 @@ 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 +conveniently small parts. @menu * Using Include Files:: How to use the @code{@@include} command. @@ -16570,7 +16649,8 @@ 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 + +@node Include File Requirements @section Include File Requirements @cindex Include file requirements @cindex Requirements for include files @@ -16627,7 +16707,7 @@ would insert a main or master menu:@refill @group @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1999 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end titlepage @end group @@ -16680,8 +16760,8 @@ 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 + +@node Include Files Evolution @section Evolution of Include Files When Info was first created, it was customary to create many small @@ -18372,6 +18452,405 @@ Insert the current date. @end ignore +@node Documentation Copying +@appendix GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.1, March 2000 + +@display +Copyright @copyright{} 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document @dfn{free} in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, +@acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed +for human modification. Opaque formats include PostScript, +@acronym{PDF}, proprietary formats that can be read and edited only by +proprietary word processors, @acronym{SGML} or @acronym{XML} for which +the @acronym{DTD} and/or processing tools are not generally available, +and the machine-generated @acronym{HTML} produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has less than five). + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section entitled ``History'', and its title, and add to +it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +In any section entitled ``Acknowledgments'' or ``Dedications'', +preserve the section's title, and preserve in the section all the +substance and tone of each of the contributor acknowledgments +and/or dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section as ``Endorsements'' +or to conflict in title with any Invariant Section. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgments'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@appendixsubsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being @var{list their titles}, with the + Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + + @node Command and Variable Index @unnumbered Command and Variable Index diff --git a/contrib/texinfo/doc/version-stnd.texi b/contrib/texinfo/doc/version-stnd.texi new file mode 100644 index 0000000..fb7f62b --- /dev/null +++ b/contrib/texinfo/doc/version-stnd.texi @@ -0,0 +1,4 @@ +@set UPDATED 2 March 2002 +@set UPDATED-MONTH March 2002 +@set EDITION 4.1 +@set VERSION 4.1 diff --git a/contrib/texinfo/doc/version.texi b/contrib/texinfo/doc/version.texi index 2d7c149..af97803 100644 --- a/contrib/texinfo/doc/version.texi +++ b/contrib/texinfo/doc/version.texi @@ -1,3 +1,4 @@ -@set UPDATED 28 September 1999 -@set EDITION 4.0 -@set VERSION 4.0 +@set UPDATED 4 March 2002 +@set UPDATED-MONTH March 2002 +@set EDITION 4.1 +@set VERSION 4.1 |
