summaryrefslogtreecommitdiffstats
path: root/contrib/texinfo/doc
diff options
context:
space:
mode:
authorru <ru@FreeBSD.org>2003-05-02 00:48:41 +0000
committerru <ru@FreeBSD.org>2003-05-02 00:48:41 +0000
commit374ada20ea75e5e2d1945e7896180bea1f752477 (patch)
tree58bf7fa721f3333d934a90edf15dd134b60feacf /contrib/texinfo/doc
parent4d1fda8c19d6f882c382a685e1c553d80d8f0e11 (diff)
downloadFreeBSD-src-374ada20ea75e5e2d1945e7896180bea1f752477.zip
FreeBSD-src-374ada20ea75e5e2d1945e7896180bea1f752477.tar.gz
Import of stripped down GNU texinfo 4.5
Diffstat (limited to 'contrib/texinfo/doc')
-rw-r--r--contrib/texinfo/doc/README11
-rw-r--r--contrib/texinfo/doc/fdl.texi227
-rwxr-xr-xcontrib/texinfo/doc/help2man79
-rw-r--r--contrib/texinfo/doc/info-stnd.texi34
-rw-r--r--contrib/texinfo/doc/info.16
-rw-r--r--contrib/texinfo/doc/info.52
-rw-r--r--contrib/texinfo/doc/info.texi319
-rw-r--r--contrib/texinfo/doc/install-info.16
-rw-r--r--contrib/texinfo/doc/makeinfo.118
-rw-r--r--contrib/texinfo/doc/texindex.16
-rw-r--r--contrib/texinfo/doc/texinfo.56
-rw-r--r--contrib/texinfo/doc/texinfo.txi1725
-rw-r--r--contrib/texinfo/doc/version-stnd.texi8
-rw-r--r--contrib/texinfo/doc/version.texi8
14 files changed, 1398 insertions, 1057 deletions
diff --git a/contrib/texinfo/doc/README b/contrib/texinfo/doc/README
index dc734a6..a9372123 100644
--- a/contrib/texinfo/doc/README
+++ b/contrib/texinfo/doc/README
@@ -1,3 +1,12 @@
+$Id: README,v 1.3 2002/12/05 21:42:23 karl Exp $
+texinfo/doc/README
+
+ Copyright (C) 2002 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved.
+
This directory contains documentation on the Texinfo system and the TeX
sources needed to process Texinfo sources. We recommend using the
texi2dvi included in this distribution to run a Texinfo manual through
@@ -23,7 +32,7 @@ ones, you very likely have to update your ls-R file; do this with the
mktexlsr command. In older versions, this was named MakeTeXls-R.
You can get the latest texinfo.tex from
-ftp://ftp.gnu.org/gnu/texinfo.tex (and all GNU mirrors)
+ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex (and all GNU mirrors)
ftp://tug.org/tex/texinfo.tex (and all CTAN mirrors)
or on the FSF machines in /home/gd/gnu/doc/texinfo.tex.
If you have problems with the version in this distribution, please check
diff --git a/contrib/texinfo/doc/fdl.texi b/contrib/texinfo/doc/fdl.texi
index 361f90f..89a012d 100644
--- a/contrib/texinfo/doc/fdl.texi
+++ b/contrib/texinfo/doc/fdl.texi
@@ -3,10 +3,10 @@
@appendixsec GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
-@center Version 1.1, March 2000
+@center Version 1.2, November 2002
@display
-Copyright @copyright{} 2000 Free Software Foundation, Inc.
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
@@ -18,12 +18,12 @@ of this license document, but changing it is not allowed.
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.
+functional and useful 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
@@ -41,57 +41,69 @@ 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''.
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
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
+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. (Thus, 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.
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
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.
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
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
+general public, that is suitable for revising the document
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''.
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. 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.
+@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},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+@acronym{JPG}. Opaque formats include 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},
+PostScript or @acronym{PDF} 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
@@ -100,6 +112,21 @@ 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.
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
@item
VERBATIM COPYING
@@ -119,9 +146,10 @@ 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
+If you publish printed copies (or copies in media that commonly have
+printed covers) 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
@@ -139,16 +167,15 @@ 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.
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+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
@@ -176,7 +203,8 @@ if the original publisher of that version gives permission.
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).
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
@item
State on the Title page the name of the publisher of the
@@ -202,10 +230,10 @@ and required Cover Texts given in the Document's license notice.
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
+Preserve the section Entitled ``History'', Preserve 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
+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.
@@ -220,10 +248,10 @@ 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.
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
@@ -231,12 +259,15 @@ 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
+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.
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
@end enumerate
If the Modified Version includes new front-matter sections or
@@ -246,7 +277,7 @@ 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
+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
@@ -274,7 +305,7 @@ 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.
+license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
@@ -285,11 +316,11 @@ 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.''
+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 ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
@item
COLLECTIONS OF DOCUMENTS
@@ -310,18 +341,20 @@ 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.
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included an aggregate, this License does not
+apply to the other works in the aggregate which 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.
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
@item
TRANSLATION
@@ -332,10 +365,17 @@ 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.
+translation of this License, and all the license notices in the
+Document, and any Warrany Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
@item
TERMINATION
@@ -378,19 +418,28 @@ license notices just after the title page:
@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
+ under the terms of the GNU Free Documentation License, Version 1.2
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''.
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled
+ ``GNU Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
+@smallexample
+@group
+ 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}.
@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 you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
diff --git a/contrib/texinfo/doc/help2man b/contrib/texinfo/doc/help2man
index 8f40e8d..ea180b7 100755
--- a/contrib/texinfo/doc/help2man
+++ b/contrib/texinfo/doc/help2man
@@ -1,7 +1,8 @@
#!/usr/local/bin/perl -w
# Generate a short man page from --help and --version output.
-# Copyright © 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
+# Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 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
@@ -17,25 +18,25 @@
# along with this program; if not, write to the Free Software Foundation,
# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-# Written by Brendan O'Dea <bod@compusol.com.au>
+# Written by Brendan O'Dea <bod@debian.org>
# Available from ftp://ftp.gnu.org/gnu/help2man/
-use 5.004;
+use 5.005;
use strict;
use Getopt::Long;
use Text::Tabs qw(expand);
use POSIX qw(strftime setlocale LC_TIME);
my $this_program = 'help2man';
-my $this_version = '1.24';
+my $this_version = '1.29';
my $version_info = <<EOT;
GNU $this_program $this_version
-Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
+Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 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.
-Written by Brendan O'Dea <bod\@compusol.com.au>
+Written by Brendan O'Dea <bod\@debian.org>
EOT
my $help_info = <<EOT;
@@ -43,29 +44,46 @@ my $help_info = <<EOT;
Usage: $this_program [OPTION]... EXECUTABLE
- -n, --name=STRING use `STRING' as the description for the NAME paragraph
- -s, --section=SECTION use `SECTION' as the section for the man page
+ -n, --name=STRING description for the NAME paragraph
+ -s, --section=SECTION section number for manual page (1, 6, 8)
+ -m, --manual=TEXT name of manual (User Commands, ...)
+ -S, --source=TEXT source of program (FSF, Debian, ...)
-i, --include=FILE include material from `FILE'
-I, --opt-include=FILE include material from `FILE' if it exists
-o, --output=FILE send output to `FILE'
+ -p, --info-page=TEXT name of Texinfo manual
-N, --no-info suppress pointer to Texinfo manual
--help print this help, then exit
--version print version number, then exit
-EXECUTABLE should accept `--help' and `--version' options.
+EXECUTABLE should accept `--help' and `--version' options although
+alternatives may be specified using:
+
+ -h, --help-option=STRING help option string
+ -v, --version-option=STRING version option string
Report bugs to <bug-help2man\@gnu.org>.
EOT
my $section = 1;
-my ($opt_name, @opt_include, $opt_output, $opt_no_info);
+my $manual = '';
+my $source = '';
+my $help_option = '--help';
+my $version_option = '--version';
+my ($opt_name, @opt_include, $opt_output, $opt_info, $opt_no_info);
+
my %opt_def = (
- 'n|name=s' => \$opt_name,
- 's|section=s' => \$section,
- '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,
+ 'n|name=s' => \$opt_name,
+ 's|section=s' => \$section,
+ 'm|manual=s' => \$manual,
+ 'S|source=s' => \$source,
+ 'i|include=s' => sub { push @opt_include, [ pop, 1 ] },
+ 'I|opt-include=s' => sub { push @opt_include, [ pop, 0 ] },
+ 'o|output=s' => \$opt_output,
+ 'p|info-page=s' => \$opt_info,
+ 'N|no-info' => \$opt_no_info,
+ 'h|help-option=s' => \$help_option,
+ 'v|version-option=s' => \$version_option,
);
# Parse options.
@@ -81,9 +99,6 @@ my %include = ();
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]
@@ -175,9 +190,9 @@ setlocale LC_TIME, 'C';
# 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);
+ join '', map { s/ +$//; expand $_ } `$ARGV[0] $_ 2>/dev/null`
+ or die "$this_program: can't get `$_' info from $ARGV[0]\n"
+} $help_option, $version_option;
my $date = strftime "%B %Y", localtime;
(my $program = $ARGV[0]) =~ s!.*/!!;
@@ -239,6 +254,18 @@ $include{NAME} ||= "$program \\- manual page for $program $version\n";
# Man pages traditionally have the page title in caps.
my $PROGRAM = uc $program;
+# Set default page head/footers
+$source ||= "$program $version";
+unless ($manual)
+{
+ for ($section)
+ {
+ if (/^(1[Mm]|8)/) { $manual = 'System Administration Utilities' }
+ elsif (/^6/) { $manual = 'Games' }
+ else { $manual = 'User Commands' }
+ }
+}
+
# Extract usage clause(s) [if any] for SYNOPSIS.
if ($help_text =~ s/^Usage:( +(\S+))(.*)((?:\n(?: {6}\1| *or: +\S).*)*)//m)
{
@@ -377,7 +404,7 @@ while (length)
my $content = '';
# Option with description.
- if (s/^( {1,10}([+-]\S.*?))(?:( +)|\n( {20,}))(\S.*)\n//)
+ if (s/^( {1,10}([+-]\S.*?))(?:( +(?!-))|\n( {20,}))(\S.*)\n//)
{
$matched .= $& if %append;
$indent = length ($4 || "$1$3");
@@ -462,6 +489,8 @@ while (length)
# Refer to the real documentation.
unless ($opt_no_info)
{
+ my $info_page = $opt_info || $program;
+
$sect = 'SEE ALSO';
$include{$sect} ||= '';
$include{$sect} .= ".PP\n" if $include{$sect};
@@ -474,7 +503,7 @@ and
.B $program
programs are properly installed at your site, the command
.IP
-.B info $program
+.B info $info_page
.PP
should give you access to the complete manual.
EOT
@@ -483,7 +512,7 @@ EOT
# Output header.
print <<EOT;
.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version.
-.TH $PROGRAM "$section" "$date" "$package $version" FSF
+.TH $PROGRAM "$section" "$date" "$source" "$manual"
EOT
# Section ordering.
diff --git a/contrib/texinfo/doc/info-stnd.texi b/contrib/texinfo/doc/info-stnd.texi
index f888565..02640cf 100644
--- a/contrib/texinfo/doc/info-stnd.texi
+++ b/contrib/texinfo/doc/info-stnd.texi
@@ -1,5 +1,5 @@
\input texinfo @c -*-texinfo-*-
-@comment $Id: info-stnd.texi,v 1.43 2002/03/23 20:38:57 karl Exp $
+@comment $Id: info-stnd.texi,v 1.4 2002/11/06 00:42:29 karl Exp $
@comment %**start of header
@setfilename info-stnd.info
@include version-stnd.texi
@@ -14,7 +14,7 @@ This manual is for GNU Info (version @value{VERSION}, @value{UPDATED}),
a program for viewing documents in Info format (usually created from
Texinfo source files).
-Copyright @copyright{} 1992, 93, 96, 97, 98, 99, 2001, 02
+Copyright @copyright{} 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.
@quotation
@@ -73,8 +73,7 @@ first, as it includes more background information and a thorough tutorial.
* 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.
-* Custom Key Bindings:: How to define your own key-to-command
- bindings.
+* Custom Key Bindings:: How to define your own key-to-command bindings.
* Copying This Manual:: The GNU Free Documentation License.
* Index:: Global index containing keystrokes,
command names, variable names,
@@ -465,7 +464,7 @@ commands detailed in this section are used to shift which part of the
current node is visible on the screen.
Scrolling commands are bound differently when @samp{--vi-keys} operation
-(@pxref{--vi-keys}) is in effect. These key bindings are designated
+is in effect (@pxref{--vi-keys}). These key bindings are designated
with ``vi-like operation''.
@table @asis
@@ -1465,9 +1464,9 @@ Transpose the characters at the cursor.
The next group of commands deal with @dfn{killing}, and @dfn{yanking}
text@footnote{
Some people are used to calling these operations @dfn{cut} and
-@dfn{paste}, respectively.}. For an in depth discussion of killing and
-yanking, @pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs
-Manual}
+@dfn{paste}, respectively.}. For an in-depth discussion of killing and
+yanking, see @ref{Killing, , Killing and Deleting, emacs, the GNU Emacs
+Manual}.
@table @asis
@item @key{M-d} (@code{echo-area-kill-word})
@@ -1809,15 +1808,16 @@ Here is a list of the variables that you can set in Info.
@table @code
@item automatic-footnotes
@vindex automatic-footnotes
-When set to @code{On}, footnotes appear and disappear automatically.
-This variable is @code{On} by default. When a node is selected, a
-window containing the footnotes which appear in that node is created,
-and the footnotes are displayed within the new window. The window that
-Info creates to contain the footnotes is called @samp{*Footnotes*}. If
-a node is selected which contains no footnotes, and a @samp{*Footnotes*}
-window is on the screen, the @samp{*Footnotes*} window is deleted.
-Footnote windows created in this fashion are not automatically tiled so
-that they can use as little of the display as is possible.
+When set to @code{On}, footnotes appear and disappear automatically;
+else, they appear at the bottom of the node text. This variable is
+@code{Off} by default. When a node is selected, a window containing
+the footnotes which appear in that node is created, and the footnotes
+are displayed within the new window. The window that Info creates to
+contain the footnotes is called @samp{*Footnotes*}. If a node is
+selected which contains no footnotes, and a @samp{*Footnotes*} window
+is on the screen, the @samp{*Footnotes*} window is deleted. Footnote
+windows created in this fashion are not automatically tiled so that
+they can use as little of the display as is possible.
@item automatic-tiling
@vindex automatic-tiling
diff --git a/contrib/texinfo/doc/info.1 b/contrib/texinfo/doc/info.1
index 4f7808a..fc20e6a 100644
--- a/contrib/texinfo/doc/info.1
+++ b/contrib/texinfo/doc/info.1
@@ -1,5 +1,5 @@
-.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24.
-.TH INFO "1" "April 2002" "GNU texinfo 4.2" FSF
+.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.29.
+.TH INFO "1" "February 2003" "info 4.4" "User Commands"
.SH NAME
info \- read Info documents
.SH SYNOPSIS
@@ -77,7 +77,7 @@ Email bug reports to bug-texinfo@gnu.org,
general questions and discussion to help-texinfo@gnu.org.
Texinfo home page: http://www.gnu.org/software/texinfo/
.SH COPYRIGHT
-Copyright \(co 2002 Free Software Foundation, Inc.
+Copyright \(co 2003 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.5 b/contrib/texinfo/doc/info.5
index 0e7ed48..bcf5101 100644
--- a/contrib/texinfo/doc/info.5
+++ b/contrib/texinfo/doc/info.5
@@ -1,5 +1,5 @@
.\" info(5)
-.\" $Id: info.5,v 1.2 1998/07/31 17:39:31 karl Exp $
+.\" $Id: info.5,v 1.1 2002/08/25 23:38:38 karl Exp $
.\"
.\" Copyright (C) 1998 Free Software Foundation, Inc.
.\"
diff --git a/contrib/texinfo/doc/info.texi b/contrib/texinfo/doc/info.texi
index 3b1a95c..bbdee41 100644
--- a/contrib/texinfo/doc/info.texi
+++ b/contrib/texinfo/doc/info.texi
@@ -6,21 +6,16 @@
@syncodeindex vr cp
@syncodeindex ky cp
@comment %**end of header
-@comment $Id: info.texi,v 1.20 2002/03/18 06:45:49 eliz Exp $
+@comment $Id: info.texi,v 1.3 2002/11/06 00:45:36 karl Exp $
-@dircategory Texinfo documentation system
-@direntry
-* Info: (info). How to use the documentation browsing system.
-@end direntry
-
-@ifinfo
+@copying
This file describes how to use Info, the on-line, menu-driven GNU
documentation system.
-Copyright (C) 1989, 92, 96, 97, 98, 99, 2000, 2001, 2002
+Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002
Free Software Foundation, Inc.
-
+@quotation
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
@@ -37,7 +32,13 @@ 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
+@end quotation
+@end copying
+
+@dircategory Texinfo documentation system
+@direntry
+* Info: (info). How to use the documentation browsing system.
+@end direntry
@titlepage
@title Info
@@ -46,58 +47,36 @@ license to the document, as described in section 6 of the license.
@author and the GNU Texinfo community
@page
@vskip 0pt plus 1filll
-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 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.
+@insertcopying
@end titlepage
@ifnottex
@node Top
@top Info: An Introduction
-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.
+The GNU Project distributes most of its on-line manuals in the
+@dfn{Info format}, which you read using an @dfn{Info reader}. You are
+probably using an Info reader to read this 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.
+If you are new to the Info reader and want to learn how to use it,
+type the command @kbd{h} now. 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.
+To read about expert-level 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.
+* Expert Info:: Info commands for experts.
* 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
+@node Getting Started, Expert Info, Top, Top
@comment node-name, next, previous, up
@chapter Getting Started
@@ -241,15 +220,14 @@ 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 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. 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.
+ The top line of a node is its @dfn{header}. This node's header
+(look at 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. 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 duplicated in a special typeface,
+and the duplicate remains at the top of the window all the time even
+if you scroll through the node.
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
@@ -267,9 +245,9 @@ links.
@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''.
+>> If you are in Emacs and have a mouse, and if you already practiced
+ typing @kbd{n} to get to the next node, click now with the middle
+ mouse button on the @samp{Next} link to do the same ``the mouse way''.
@end format
@node Help-P, Help-^L, Help, Getting Started
@@ -280,40 +258,39 @@ links.
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}. In Emacs, @kbd{n} runs the Emacs command
-@code{Info-next}, and @kbd{p} runs @code{Info-prev}.
+node, @samp{Help-^L}.
@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.
+ or click the middle mouse button on the @samp{Prev} link. That
+ takes you to the @samp{Previous} node. Then use @kbd{n} 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
+menu bar, close to its right edge. Clicking the 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.
+ This all probably seems insultingly simple so far, but @emph{please
+don't} start skimming. Things will get complicated soon enough!
+Also, please do not try a new command until you are told it is time
+to. You could make Info skip past an important warning that was
+coming up.
@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.
+>> Now do an @kbd{n}, or click the middle mouse button 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, DEL, B and ^L commands.
- 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 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 highlighted and may be
+underlined as well; it says what the node is about.
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
@@ -336,9 +313,7 @@ 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}.
+the top until you have typed some spaces).
@format
>> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to
@@ -354,31 +329,34 @@ 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.
+can conveniently go to one of these links at any time by
+clicking the middle mouse button on the link.
@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}.
+the current node. They also move between nodes. @key{SPC} at the end
+of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at
+the beginning of a node moves to the previous node. In effect, these
+commands scroll through all the nodes in an Info file as a single
+logical sequence. You can read an entire manual top to bottom by just
+typing @key{SPC}, and move backward through the entire manual from
+bottom to top by typing @key{DEL} (or @key{BACKSPACE}).
+
+ 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.
@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.
+through the text of one node, like @key{SPC} and @key{BACKSPACE} (or
+@key{DEL}). However, @key{PAGEUP} and @key{PAGEDOWN} keys 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
@@ -391,18 +369,19 @@ again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down
@kindex b @r{(Info mode)}
To move back to the beginning of the node you are on, you can type
-a lot of @key{BACKSPACE} keys. You can also type simply @kbd{b} for
-beginning.
+the @key{BACKSPACE} key (or @key{DEL}) many times. You can also type
+@kbd{b} just once. @kbd{b} stands 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 @key{SPS}s.
+ Then come back, by typing @key{SPC} one or more times.
@end format
- If your screen is very tall, all of this node might fit at once.
-In that case, @kbd{b} won't do anything. Sorry; what can we do?
+ If your screen is very tall, all of this node might fit at once. In
+that case, @kbd{b} won't do anything. But you could observe the
+effect of the @kbd{b} key if you use a smaller window.
@kindex ? @r{(Info mode)}
@findex Info-summary
@@ -414,8 +393,8 @@ 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. Then type @key{SPC} several times, until
- it goes away.
+ the list until finished. Then type @key{SPC} several times. If
+ you are using Emacs, the help will then go away automatically.
@end format
(If you are using the stand-alone Info reader, type @kbd{C-x 0} to
@@ -429,8 +408,8 @@ move around in them without being told. Since not all terminals have
the same size screen, it would be impossible to warn you anyway.
@format
->> Now type @kbd{n}, or click the mouse on the @samp{Next} link, to
- see the description of the @kbd{m} command.
+>> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
+ to see the description of the @kbd{m} command.
@end format
@node Help-M, Help-Xref, Help-^L, Getting Started
@@ -459,7 +438,7 @@ special meaning---they are only for the human reader's benefit and do
not define additional subtopics. Here is an example:
@example
-* Foo: Node about FOO 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{Node
@@ -479,7 +458,7 @@ and so both it and the subtopic name are the same. There is an
abbreviation for this:
@example
-* Foo:: This tells about FOO
+* Foo:: This tells about FOO.
@end example
@noindent
@@ -494,26 +473,31 @@ both @samp{Foo}.
@kbd{m} command is not available.
@end format
+If you keep typing @key{SPC} once the menu appears on the screen, it
+will move to another node (the first one in the menu). If that
+happens, type @key{BACKSPACE} to come back.
+
@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 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.
+ The command to go to one of the subnodes is @kbd{m}. This is very
+different from the commands you have used: it is a command that
+prompts you for more input.
+
+ The Info commands you know do not need additional input; when you
+type one of them, Info processes it instantly and then is ready for
+another command. The @kbd{m} command is different: it needs to know
+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}
+blank. When it is blank, Info is ready for a command, such as @kbd{n}
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 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.
+in a colon, it means Info is reading more input for the last command.
+You can't type an Info command then, because Info is trying to read
+input, not commands. You must either give the input and finish the
+command you started, or type @kbd{Control-g} to cancel the command.
+When you have done one of those things, the input entry line becomes
+blank again. Then you can type Info commands again.
@findex Info-menu
The command to go to a subnode via a menu is @kbd{m}. After you type
@@ -532,21 +516,22 @@ 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 @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.
+ You can also use the @dfn{completion} feature to help enter the
+subtopic name. If you type the @key{TAB} key after entering part of a
+name, it will fill in more of the name---as much as Info can deduce
+from the part 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 @key{RET}, and it
-stands for the subtopic of the line you are on.
+stands for the subtopic of the line you are on. You can also click
+the middle mouse button directly on the subtopic line to go there.
Here is a menu to give you a chance to practice. This menu gives you
three ways of going to one place, Help-FOO:
@menu
* Foo: Help-FOO. A node you can visit for fun.
-* Bar: Help-FOO. Strange! two ways to get to the same place.
+* Bar: Help-FOO. We have made two ways to get to the same place.
* Help-FOO:: And yet another!
@end menu
@@ -606,18 +591,19 @@ 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.
+that. After a while, if you leave the mouse on that spot, a small
+window will pop up, saying ``Mouse-2: go to that node'', or the same
+message may appear at the bottom of the screen.
+
+ @kbd{Mouse-2} is the second button of your mouse counting from the
+left---the middle button on a 3-button mouse. (On a 2-button mouse,
+you may have to press both buttons together to ``press the middle
+button''.) The message tells you pressing @kbd{Mouse-2} with the
+current position of the mouse pointer (on subtopic in the menu) will
+go 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
+ More generally, @kbd{Mouse-2} in an Info buffer 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
@@ -655,8 +641,8 @@ 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).
+ Another way to go Up is to click @kbd{Mouse-2} 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}.
@@ -742,7 +728,7 @@ records the nodes where you have been in a special history list. The
@kbd{l} command revisits nodes in the history list; each successive
@kbd{l} command moves one step back through the history.
- If you have been following directions, ad @kbd{l} command now will get
+ If you have been following directions, an @kbd{l} command now will get
you back to @samp{Help-M}. Another @kbd{l} command would undo the
@kbd{u} and get you back to @samp{Help-FOO}. Another @kbd{l} would undo
the @kbd{m} and get you back to @samp{Help-M}.
@@ -792,27 +778,28 @@ underlying text and the mouse pointer change in response.
>> Now type @kbd{n} to see the last node of the course.
@end format
- @xref{Advanced Info}, for more advanced Info features.
+ @xref{Expert 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 Advanced Info
+@node Expert Info
@chapter Info for Experts
- This chapter describes various advanced Info commands. (If you are
-using a stand-alone Info reader, there are additional commands
+ This chapter describes various Info commands for experts. (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}.)
+better, since you can use it to make a printed manual or produce other
+formats, such as HTML and DocBook, as well as for generating Info
+files.) @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
+Documentation Format}.)
@menu
-* Expert:: Advanced Info commands: g, s, e, and 1 - 5.
+* Advanced:: 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.
@@ -823,7 +810,7 @@ Texinfo: The GNU Documentation Format}.)
* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
@end menu
-@node Expert, Info Search, , Advanced Info
+@node Advanced, Info Search, , Expert Info
@comment node-name, next, previous, up
@section Advanced Info Commands
@@ -837,7 +824,7 @@ 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
name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node
called @samp{Top} in this file. (This is equivalent to @kbd{t}, see
-@ref{Help-Int}.) @kbd{gExpert@key{RET}} would come back here.
+@ref{Help-Int}.) @kbd{gAdvanced@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.
@@ -894,7 +881,7 @@ only if the variable @code{Info-enable-edit} is non-@code{nil}.
edit the Info file, so typing @kbd{e} there goes to the end of the
current node.
-@node Info Search, Add, Expert, Advanced Info
+@node Info Search, Add, Advanced, Expert Info
@comment node-name, next, previous, up
@section How to search Info documents for specific subjects
@@ -970,7 +957,7 @@ kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the
command @code{Info-search}.
-@node Add, Menus, Info Search, Advanced Info
+@node Add, Menus, Info Search, Expert Info
@comment node-name, next, previous, up
@section Adding a new node to Info
@@ -985,8 +972,11 @@ Put that topic in the menu in the directory. @xref{Menus, Menu}.
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.
+this has the advantage that you can also make a printed manual or HTML
+from them. You would use the @samp{@@dircategory} and
+@samp{@@direntry} commands to put the manual into the Info directory.
+However, if you want to edit an Info file manually and install it
+manually, here is how.
@cindex node delimiters
The new node can live in an existing documentation file, or in a new
@@ -1000,12 +990,11 @@ 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}.
+@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{Expert Info}. The @samp{Next} node is @samp{Menus}.
@cindex node header line format
@cindex format of node headers
@@ -1051,7 +1040,7 @@ node is in the same file, it was not necessary to use one.
line. The file names are ignored by Info, but they serve as comments
to help identify the node for the user.
-@node Menus, Cross-refs, Add, Advanced Info
+@node Menus, Cross-refs, Add, Expert Info
@comment node-name, next, previous, up
@section How to Create Menus
@@ -1107,7 +1096,7 @@ collector, nothing terrible happens if a substructure is not pointed
to, but such a substructure is rather useless since nobody can
ever find out that it exists.
-@node Cross-refs, Tags, Menus, Advanced Info
+@node Cross-refs, Tags, Menus, Expert Info
@comment node-name, next, previous, up
@section Creating Cross References
@@ -1166,7 +1155,7 @@ 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
+as a reference rather than as a tutorial. We urge you to learn
these search commands as well. If you want to do that now, follow this
cross reference to @ref{Info Search}.
@@ -1182,7 +1171,7 @@ manner.
@end format
-@node Tags, Checking, Cross-refs, Advanced Info
+@node Tags, Checking, Cross-refs, Expert Info
@comment node-name, next, previous, up
@section Tags Tables for Info Files
@@ -1227,7 +1216,7 @@ a @samp{DEL} character, and the character position in the file of the
beginning of the node.
-@node Checking, Emacs Info Variables, Tags, Advanced Info
+@node Checking, Emacs Info Variables, Tags, Expert Info
@section Checking an Info File
When creating an Info file, it is easy to forget the name of a node when
@@ -1246,7 +1235,7 @@ usually few.
To check an Info file, do @kbd{M-x Info-validate} while looking at any
node of the file with Emacs Info mode.
-@node Emacs Info Variables, , Checking, Advanced Info
+@node Emacs Info Variables, , Checking, Expert Info
@section Emacs Info-mode Variables
The following variables may modify the behavior of Info-mode in Emacs;
@@ -1276,10 +1265,10 @@ 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
+looks by customizing the faces @code{info-node}, @code{info-xref},
+@code{info-header-xref}, @code{info-header-node}, @code{info-menu-5},
+@code{info-menu-header}, and @code{info-title-@var{n}-face} (where
+@var{n} is the level of the section, a number between 1 and 4). 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.
diff --git a/contrib/texinfo/doc/install-info.1 b/contrib/texinfo/doc/install-info.1
index a6fb8bf..cb46cd6 100644
--- a/contrib/texinfo/doc/install-info.1
+++ b/contrib/texinfo/doc/install-info.1
@@ -1,5 +1,5 @@
-.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24.
-.TH INSTALL-INFO "1" "April 2002" "GNU texinfo 4.2" FSF
+.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.29.
+.TH INSTALL-INFO "1" "February 2003" "install-info 4.4" "User Commands"
.SH NAME
install-info \- update info/dir entries
.SH SYNOPSIS
@@ -60,7 +60,7 @@ Email bug reports to bug-texinfo@gnu.org,
general questions and discussion to help-texinfo@gnu.org.
Texinfo home page: http://www.gnu.org/software/texinfo/
.SH COPYRIGHT
-Copyright \(co 2002 Free Software Foundation, Inc.
+Copyright \(co 2003 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 3500b68..2e65647 100644
--- a/contrib/texinfo/doc/makeinfo.1
+++ b/contrib/texinfo/doc/makeinfo.1
@@ -1,5 +1,5 @@
-.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24.
-.TH MAKEINFO "1" "April 2002" "GNU texinfo 4.2" FSF
+.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.29.
+.TH MAKEINFO "1" "February 2003" "makeinfo 4.4" "User Commands"
.SH NAME
makeinfo \- translate Texinfo documents
.SH SYNOPSIS
@@ -36,13 +36,13 @@ display version information and exit.
.SS "Output format selection (default is to produce Info):"
.TP
\fB\-\-docbook\fR
-output DocBook rather than Info.
+output DocBook XML rather than Info.
.TP
\fB\-\-html\fR
output HTML rather than Info.
.TP
\fB\-\-xml\fR
-output XML (TexinfoML) rather than Info.
+output Texinfo XML rather than Info.
.SS "General output options:"
.TP
\fB\-E\fR, \fB\-\-macro\-expand\fR FILE
@@ -117,6 +117,9 @@ process @ifplaintext even if not generating plain text.
\fB\-\-iftex\fR
process @iftex and @tex; implies \fB\-\-no\-split\fR.
.TP
+\fB\-\-ifxml\fR
+process @ifxml and @xml.
+.TP
\fB\-\-no\-ifhtml\fR
do not process @ifhtml and @html text.
.TP
@@ -128,6 +131,9 @@ do not process @ifplaintext text.
.TP
\fB\-\-no\-iftex\fR
do not process @iftex and @tex text.
+.TP
+\fB\-\-no\-ifxml\fR
+do not process @ifxml and @xml text.
.IP
The defaults for the @if... conditionals depend on the output format:
if generating HTML, \fB\-\-ifhtml\fR is on and the others are off;
@@ -142,7 +148,7 @@ makeinfo \fB\-\-html\fR foo.texi
write HTML to @setfilename
.TP
makeinfo \fB\-\-xml\fR foo.texi
-write XML to @setfilename
+write Texinfo XML to @setfilename
.TP
makeinfo \fB\-\-docbook\fR foo.texi
write DocBook XML to @setfilename
@@ -158,7 +164,7 @@ Email bug reports to bug-texinfo@gnu.org,
general questions and discussion to help-texinfo@gnu.org.
Texinfo home page: http://www.gnu.org/software/texinfo/
.SH COPYRIGHT
-Copyright \(co 2002 Free Software Foundation, Inc.
+Copyright \(co 2003 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 854fed8..32b9c3f 100644
--- a/contrib/texinfo/doc/texindex.1
+++ b/contrib/texinfo/doc/texindex.1
@@ -1,5 +1,5 @@
-.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.24.
-.TH TEXINDEX "1" "April 2002" "GNU texinfo 4.2" FSF
+.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.29.
+.TH TEXINDEX "1" "February 2003" "texindex 4.4" "User Commands"
.SH NAME
texindex \- sort Texinfo index files
.SH SYNOPSIS
@@ -29,7 +29,7 @@ Email bug reports to bug-texinfo@gnu.org,
general questions and discussion to help-texinfo@gnu.org.
Texinfo home page: http://www.gnu.org/software/texinfo/
.SH COPYRIGHT
-Copyright \(co 2002 Free Software Foundation, Inc.
+Copyright \(co 2003 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.5 b/contrib/texinfo/doc/texinfo.5
index cd29c1b..991c269 100644
--- a/contrib/texinfo/doc/texinfo.5
+++ b/contrib/texinfo/doc/texinfo.5
@@ -1,7 +1,7 @@
.\" texinfo(5)
-.\" $Id: texinfo.5,v 1.3 1999/03/25 21:28:25 karl Exp $
+.\" $Id: texinfo.5,v 1.1 2002/09/03 23:44:57 karl Exp $
.\"
-.\" Copyright (C) 1998, 99 Free Software Foundation, Inc.
+.\" Copyright (C) 1998, 1999, 2002 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
@@ -19,7 +19,7 @@
.\"
.TH TEXINFO 5 "GNU Texinfo" "FSF"
.SH NAME
-Texinfo \- software documentation system
+texinfo \- software documentation system
.SH DESCRIPTION
Texinfo is a documentation system that uses a single source file to
produce both online information and printed output. It is primarily
diff --git a/contrib/texinfo/doc/texinfo.txi b/contrib/texinfo/doc/texinfo.txi
index 144fef0..9e5dff4 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.219 2002/03/28 16:36:00 karl Exp $
+@c $Id: texinfo.txi,v 1.29 2003/02/04 15:17:21 karl Exp $
@c Ordinarily Texinfo files have the extension .texi. But texinfo.texi
@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
@@ -38,8 +38,8 @@ This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
a documentation system that can produce both online information and a
printed manual from a single source.
-Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
-Free Software Foundation, Inc.
+Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998,
+1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -99,6 +99,7 @@ Software Foundation raise funds for GNU development.''
@vskip 0pt plus 1filll
@insertcopying
+@sp 1
Published by the Free Software Foundation @*
59 Temple Place Suite 330 @*
Boston, MA 02111-1307 @*
@@ -106,8 +107,9 @@ USA @*
ISBN 1-882114-67-1 @c for version 4.0, September 1999.
@c ISBN 1-882114-65-5 is for version 3.12, March 1998.
@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
-@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
+@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
+@sp 1
Cover art by Etienne Suvasa.
@end titlepage
@@ -175,6 +177,7 @@ Overview of Texinfo
* Reporting Bugs:: Submitting effective bug reports.
* Using Texinfo:: Create printed or online output.
+* Output Formats:: Overview of the supported output formats.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Formatting Commands:: @@-commands are used for formatting.
@@ -209,13 +212,13 @@ Updating Nodes and Menus
Beginning a Texinfo File
* Sample Beginning:: A sample beginning for a Texinfo file.
-* Texinfo File Header::
-* Document Permissions::
+* Texinfo File Header:: The first lines.
+* Document Permissions:: Ensuring your manual is free.
* Titlepage & Copyright Page:: Creating the title and copyright pages.
* The Top Node:: Creating the `Top' node and master menu.
-* Global Document Commands::
+* Global Document Commands:: Affecting formatting throughout.
* Software Copying Permissions:: Ensure that you and others continue to
- have the right to use and share software.
+ have the right to use and share software.
Texinfo File Header
@@ -227,22 +230,22 @@ Texinfo File Header
Document Permissions
-* copying:: Declare the document's copying permissions.
-* insertcopying:: Where to insert the permissions.
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
Title and Copyright Pages
* titlepage:: Create a title for the printed document.
* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
- and @code{@@sp} commands.
+ and @code{@@sp} commands.
* title subtitle author:: The @code{@@title}, @code{@@subtitle},
- and @code{@@author} commands.
+ and @code{@@author} commands.
* Copyright:: How to write the copyright notice and
- include copying permissions.
+ include copying permissions.
* end titlepage:: Turn on page headings after the title and
- copyright pages.
+ copyright pages.
* headings on off:: An option for turning headings on and off
- and double or single sided printing.
+ and double or single sided printing.
The `Top' Node and Master Menu
@@ -259,7 +262,7 @@ Global Document Commands
Ending a Texinfo File
* Printing Indices & Menus:: How to print an index in hardcopy and
- generate index menus in Info.
+ generate index menus in Info.
* Contents:: How to create a table of contents.
* File End:: How to mark the end of a file.
@@ -281,7 +284,7 @@ Chapter Structuring
Nodes
* Two Paths:: Different commands to structure
- Info output and printed output.
+ Info output and printed output.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* node:: Creating nodes, in detail.
* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
@@ -363,7 +366,7 @@ Quotations and Examples
* verbatim:: Writing a verbatim example.
* verbatiminclude:: Including a file verbatim.
* lisp:: Illustrating Lisp code.
-* small:: Forms for @code{@@smallbook}.
+* small:: Examples in a smaller font.
* display:: Writing an example in the current font.
* format:: Writing an example without narrowed margins.
* exdent:: Undo indentation on a line.
@@ -394,7 +397,7 @@ Indices
* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
- of entry.
+ of entry.
* Indexing Commands:: How to make an index entry.
* Combining Indices:: How to combine indices.
* New Indices:: How to define your own indices.
@@ -402,24 +405,24 @@ Indices
Combining Indices
* syncodeindex:: How to merge two indices, using @code{@@code}
- font for the merged-from index.
+ font for the merged-from index.
* synindex:: How to merge two indices, using the
- default font of the merged-to index.
+ default font of the merged-to index.
Special Insertions
* Braces Atsigns:: How to insert braces, @samp{@@}.
* Inserting Space:: How to insert the right amount of space
- within a sentence.
+ within a sentence.
* Inserting Accents:: How to insert accents and special characters.
* Dots Bullets:: How to insert dots and bullets.
* TeX and copyright:: How to insert the @TeX{} logo
- and the copyright symbol.
+ and the copyright symbol.
* pounds:: How to insert the pounds currency symbol.
* minus:: How to insert a minus sign.
* math:: How to format a mathematical expression.
* Glyphs:: How to indicate results of evaluation,
- expansion of macros, errors, etc.
+ expansion of macros, errors, etc.
* Footnotes:: How to include footnotes.
* Images:: How to include graphics.
@@ -443,7 +446,7 @@ Inserting Ellipsis and Bullets
Inserting @TeX{} and the Copyright Symbol
* tex:: How to insert the @TeX{} logo.
-* copyright symbol:: How to use @code{@@copyright}@{@}.
+* copyright symbol:: How to use @code{@@copyright@{@}}.
Glyphs for Examples
@@ -471,19 +474,20 @@ Footnotes
Making and Preventing Breaks
-* Break Commands:: Cause and prevent splits.
-* Line Breaks:: How to force a single line to use two lines.
-* - and hyphenation:: How to tell @TeX{} about hyphenation points.
-* w:: How to prevent unwanted line breaks.
-* sp:: How to insert blank lines.
-* page:: How to force the start of a new page.
-* group:: How to prevent unwanted page breaks.
+* Break Commands:: Summary of break-related commands.
+* Line Breaks:: Forcing line breaks.
+* - and hyphenation:: Helping @TeX{} with hyphenation points.
+* w:: Preventing unwanted line breaks in text.
+* tie:: Inserting an unbreakable but varying space.
+* sp:: Inserting blank lines.
+* page:: Forcing the start of a new page.
+* group:: Preventing unwanted page breaks.
* need:: Another way to prevent unwanted page breaks.
Definition Commands
* Def Cmd Template:: How to structure a description using a
- definition command.
+ definition command.
* Optional Arguments:: How to handle optional and repeated arguments.
* deffnx:: How to group two or more `first' lines.
* Def Cmds in Detail:: All the definition commands.
@@ -505,8 +509,8 @@ Conditionally Visible Text
* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
* set clear value:: Designating which text to format (for
- all output formats); and how to set a
- flag to a string that you can insert.
+ all output formats); and how to set a
+ flag to a string that you can insert.
@code{@@set}, @code{@@clear}, and @code{@@value}
@@ -542,8 +546,8 @@ Formatting and Printing Hardcopy
* smallbook:: How to print small format books and manuals.
* A4 Paper:: How to print on A4 or A5 paper.
* pagesizes:: How to print with customized page sizes.
-* Cropmarks and Magnification:: How to print marks to indicate the size
- of pages and how to print scaled up output.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
* PDF Output:: Portable Document Format output.
Creating and Installing Info Files
@@ -559,38 +563,40 @@ Creating an Info File
* Pointer Validation:: How to check that pointers point somewhere.
* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
* texinfo-format commands:: Two Info formatting commands written
- in Emacs Lisp are an alternative
- to @code{makeinfo}.
+ in Emacs Lisp are an alternative
+ to @code{makeinfo}.
* Batch Formatting:: How to format for Info in Emacs Batch mode.
* Tag and Split Files:: How tagged and split files help Info
- to run better.
-* makeinfo html:: Generating HTML output.
+ to run better.
+* Generating HTML:: Generating HTML output with makeinfo.
Installing an Info File
* Directory File:: The top level menu for all Info files.
* New Info File:: Listing a new Info file.
* Other Info Directories:: How to specify Info files that are
- located in other directories.
+ located in other directories.
* Installing Dir Entries:: How to specify what menu entry to add
- to the Info directory.
+ to the Info directory.
* Invoking install-info:: @code{install-info} options.
Sample Texinfo Files
* Short Sample Texinfo File::
* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
Include Files
* Using Include Files:: How to use the @code{@@include} command.
* texinfo-multiple-files-update:: How to create and update nodes and
- menus when using included files.
-* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
+ menus when using included files.
+* Include Files Requirements:: What @code{texinfo-multiple-files-update} expects.
* Sample Include File:: A sample outer file with included files
- within it; and a sample included file.
+ within it; and a sample included file.
* Include Files Evolution:: How use of the @code{@@include} command
- has changed over time.
+ has changed over time.
Page Headings
@@ -694,6 +700,7 @@ that one document.
@menu
* Reporting Bugs:: Submitting effective bug reports.
* Using Texinfo:: Create printed or online output.
+* Output Formats:: Overview of the supported output formats.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Formatting Commands:: @@-commands are used for formatting.
@@ -763,18 +770,17 @@ 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
-and much stricter than @TeX{}'s usual language, plain @TeX{}). This
-creates a DVI file that you can typeset and print as a book or report
-(@pxref{Hardcopy}).
+from and much stricter than @TeX{}'s usual languages, plain @TeX{} and
+La@TeX{}). This creates a DVI file 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{Installing an Info
-File}).
+@code{makeinfo} utility. You can install the result in your Info tree
+(@pxref{Installing an Info File}).
To output an HTML file, run @code{makeinfo --html} on your Texinfo
-source. You can (for example) install the result on your web site.
+source. You can (for example) install the result on a web site.
@cindex Docbook, converting to Texinfo
@cindex Conversion, from Docbook to Texinfo
@@ -783,28 +789,18 @@ To output DocBook (a particular form of XML), 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 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
-excellent. But please do not write a separate translator texi2foo for
-your favorite format foo! That is the hard way to do the job, and makes
-extra work in subsequent maintenance, since the Texinfo language is
-continually being enhanced and updated. Instead, the best approach is
-modify @code{makeinfo} to generate the new format, as it does now for
-Info, plain text, HTML, XML, and DocBook.
-
@TeX{} works with virtually all printers; Info works with virtually all
computer terminals; the HTML output works with virtually all web
browsers. Thus Texinfo can be used by almost any computer user.
-@cindex Source file
-A Texinfo source file is a plain @sc{ascii} file containing text and
-@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
-typesetting and formatting programs what to do. You may edit a Texinfo
-file with any text editor; but it is especially convenient to use GNU
-Emacs since that editor has a special mode, called Texinfo mode, that
-provides various Texinfo-related features. (@xref{Texinfo Mode}.)
+@cindex Source file format
+A Texinfo source file is a plain @sc{ascii} file containing text
+interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
+that tell the typesetting and formatting programs what to do. You may
+edit a Texinfo file with any text editor; but it is especially
+convenient to use GNU Emacs since that editor has a special mode,
+called Texinfo mode, that provides various Texinfo-related features.
+(@xref{Texinfo Mode}.)
Before writing a Texinfo source file, you should learn about nodes,
menus, cross references, and the rest, for example by reading this
@@ -816,30 +812,125 @@ is the official documentation format of the GNU project. More
information is available at the @uref{http://www.gnu.org/doc/, GNU
documentation web page}.
+
+@node Output Formats
+@section Output Formats
+@cindex Output formats
+@cindex Back-end output formats
+
+Here is a brief overview of the output formats currently supported by
+Texinfo.
+
+@table @asis
+@item Info
+@cindex Info output
+(Generated via @command{makeinfo}.) This format is a plain text
+transliteration of the Texinfo source. It uses control characters to
+separate nodes and provide other navigational information. See the
+next section (@pxref{Info Files}) for more details on this format.
+The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}),
+and the standalone @command{info} program (@pxref{info
+standalone,,,info-stnd, GNU Info}), among others, can read these
+files. @xref{Creating and Installing Info Files}.
+
+@item Plain text
+@cindex Plain text output
+(Generated via @command{makeinfo --no-headers}.) This is almost the
+same as Info output, except the navigational control characters are
+omitted.
+
+@item HTML
+@cindex HTML output
+@cindex W3 consortium
+@cindex Mozilla
+@cindex Lynx
+@cindex Emacs-W3
+(Generated via @command{makeinfo --html}.) This is the Hyper Text
+Markup Language that has become the most commonly used language for
+writing documents on the World Wide Web. Web browsers, such as
+Mozilla, Lynx, and Emacs-W3, can render this language online. There
+are many versions of HTML; @command{makeinfo} tries to use a subset
+of the language that can be interpreted by any common browser. For
+details of the HTML language and much related information, see
+@uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}.
+
+@item DVI
+@cindex DVI output
+@pindex Dvips
+@pindex Xdvi
+(Generated via @command{texi2dvi}.) This DeVice Independent binary
+format is output by the @TeX{} typesetting program
+(@uref{http://tug.org}). It is then read by a DVI `driver', which
+writes the actual device-specific commands that can be viewed or
+printed, notably Dvips for translation to PostScript (@pxref{dvips
+invocation,,, dvips, Dvips}) and Xdvi for viewing on an X display
+(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}.
+
+@item PDF
+@cindex PDF output
+@cindex Beebe, Nelson
+@pindex pdftex
+(Generated via @command{texi2dvi --pdf}.) This format, based on
+PostScript, was developed by Adobe Systems for document interchange.
+It is intended to be platform-independent and easily viewable, among
+other design goals; for a discussion, see
+@uref{http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf}. Texinfo
+uses the @command{pdftex} program, a variant of @TeX{}, to output pdf;
+see @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
+
+@item XML
+@cindex XML output
+@cindex DTD, for Texinfo XML
+(Generated via @command{makeinfo --xml}.) XML is a generic syntax
+specification usable for any sort of content (see, for example,
+@uref{http://www.w3.org/XML/}). The @command{makeinfo} xml output,
+unlike all the formats above, interprets very little of the Texinfo
+source. Rather, it merely translates the Texinfo markup commands into
+XML syntax, for processing by further XML tools. The particular
+syntax output is defined in the file @file{texinfo.dtd} included in
+the Texinfo source distribution.
+
+@item DocBook
+@cindex DocBook output
+(Generated via @command{makeinfo --docbook}.) This is an XML format
+of long standing used primarily for technical documentation. See
+@uref{http://www.docbook.org/}.
+
+@end table
+
@cindex Man page output, not supported
From time to time, proposals are made to generate traditional Unix man
-pages from Texinfo source. This is not likely to ever be supported,
-because man pages have a very strict conventional format. Merely
-enhancing @command{makeinfo} to output troff format would be
-insufficient. Generating a good man page therefore requires a
+pages from Texinfo source. However, because man pages have a very
+strict conventional format, generating a good man page requires a
completely different source than the typical Texinfo applications of
-writing a good user tutorial or a good reference manual. This makes
-generating man pages incompatible with the Texinfo design goal of not
-having to document the same information in different ways for different
-output formats. You might as well just write the man page directly.
+writing a good user tutorial and/or a good reference manual. This
+makes generating man pages incompatible with the Texinfo design goal
+of not having to document the same information in different ways for
+different output formats. You might as well just write the man page
+directly.
@pindex help2man
@cindex O'Dea, Brendan
-Man pages still have their place, and if you wish to support them, 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 GNU software written by Brendan O'Dea, available from
-@uref{ftp://ftp.gnu.org/gnu/help2man/}.
+Man pages still have their place, and if you wish to support them, you
+may find the program @command{help2man} to 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 programs in
+the Texinfo distribution. It is GNU software written by Brendan
+O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}.
+
+@cindex Output formats, supporting more
+@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
+excellent. But please do not write a separate translator texi2foo for
+your favorite format foo! That is the hard way to do the job, and makes
+extra work in subsequent maintenance, since the Texinfo language is
+continually being enhanced and updated. Instead, the best approach is
+modify @code{makeinfo} to generate the new format.
@node Info Files
-@section Info files
+@section Info Files
@cindex Info files
An Info file is a Texinfo file formatted so that the Info documentation
@@ -975,7 +1066,7 @@ file @file{texinfo.tex} that contains information (definitions or
to @TeX{} commands, which @TeX{} can then process to create the typeset
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}.
+@uref{ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex}.
In the United States, documents are most often printed on 8.5 inch by 11
inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
@@ -1047,10 +1138,9 @@ sentences:
@itemize @bullet
@item
-Write a command such as @code{@@noindent} at the beginning of a line as
-the only text on the line. (@code{@@noindent} prevents the beginning of
-the next line from being indented as the beginning of a
-paragraph.)@refill
+Write a command such as @code{@@quotation} at the beginning of a line as
+the only text on the line. (@code{@@quotation} begins an indented
+environment.)
@item
Write a command such as @code{@@chapter} at the beginning of a line
@@ -1070,7 +1160,7 @@ marks text as being code.)@refill
@item
Write a command such as @code{@@example} on a line of its own; write the
body-text on following lines; and write the matching @code{@@end}
-command, @code{@@end example} in this case, at the on a line of its own
+command, @code{@@end example} in this case, on a line of its own
after the body-text. (@code{@@example} @dots{} @code{@@end example}
indents and typesets body-text as an example.) It's usually ok to
indent environment commands like this, but in complicated and
@@ -1102,21 +1192,33 @@ This section describes the general conventions used in all Texinfo documents.
@itemize @bullet
@item
+@cindex Source files, characters used
All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
@samp{@}} can appear in a Texinfo file and stand for themselves.
@samp{@@} is the escape character which introduces commands, while
@samp{@{} and @samp{@}} are used to surround arguments to certain
commands. To put one of these special characters into the document, put
-an @samp{@@} character in front of it, like this: @samp{@@@@},
+xan @samp{@@} character in front of it, like this: @samp{@@@@},
@samp{@@@{}, and @samp{@@@}}.
@item
-It is customary in @TeX{} to use doubled single-quote characters to
-begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}. This
-convention should be followed in Texinfo files. @TeX{} converts
-two single quotes to left- and right-hand doubled
-quotation marks,
-@c this comes out as "like this" in Info, of course, which is just confusing.
+@cindex Paragraph separator
+@cindex Blank lines, as paragraph separator
+@cindex Newlines, as blank lines
+Separate paragraphs with one or more blank lines. Currently Texinfo
+only recognizes newline characters as end of line, not the CRLF
+sequence used on some systems; so a @dfn{blank line} means exactly two
+consecutive newlines. Sometimes blank lines are useful or convenient
+in other cases as well; you can use the @code{@@noindent} to inhibit
+paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}).
+
+@item
+@cindex Quotation characters (`'), in source
+Use doubled single-quote characters to begin and end quotations:
+@w{@t{`@w{}`@dots{}'@w{}'}}. (Texinfo takes this convention from
+@TeX{}.) @TeX{} converts two single quotes to left- and right-hand
+doubled quotation marks,
+@c this comes out as "like this" in Info, which is just confusing.
@iftex
``like this'',
@end iftex
@@ -1124,17 +1226,13 @@ and Info converts doubled single-quote characters to @sc{ascii}
double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
@item
+@cindex Dashes, in source
Use three hyphens in a row, @samp{---}, for a dash---like this. In
@TeX{}, a single or double hyphen produces a printed dash that is
shorter than the usual typeset dash. Info reduces three hyphens to two
for display on the screen.
@item
-To prevent a paragraph from being indented in the printed manual, put
-the command @code{@@noindent} on a line by itself before the
-paragraph.
-
-@item
If you mark off a region of the Texinfo file with the @code{@@iftex}
and @w{@code{@@end iftex}} commands, that region will appear only in
the printed copy; in that region, you can use certain commands
@@ -1143,9 +1241,10 @@ text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
appear in all output formats @emph{except} @TeX{}.
Each of the other output formats (@code{html}, @code{info},
-@code{plaintext}) have an analogous pair of commands. @xref{Conditionals}.
-@end itemize
+@code{plaintext}, @code{xml}) have an analogous pair of commands.
+@xref{Conditionals}.
+@item
@cindex Tabs; don't use!
@quotation
@strong{Caution:} Do not use tab characters in a Texinfo file (except in
@@ -1164,6 +1263,7 @@ spaces when you press the @key{TAB} key.
Also, you can run @code{untabify} in Emacs to convert tabs in a region
to multiple spaces.
@end quotation
+@end itemize
@node Comments
@@ -1350,7 +1450,8 @@ boilerplate; when writing a manual, you simply change the names as
appropriate.
@xref{Beginning a File}, for full documentation on the commands listed
-here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
+here. @xref{GNU Sample Texts}, for the full texts to be used in GNU
+manuals.
In the following, the sample text is @emph{indented}; comments on it are
not. The complete file, without interspersed comments, is shown in
@@ -1384,7 +1485,7 @@ which it is distributed. @xref{GNU Sample Texts}.
@@copying
This is a short example of a complete Texinfo file, version 1.0.
-Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
+Copyright @@copyright@{@} 2003 Free Software Foundation, Inc.
@@end copying
@end group
@end example
@@ -1419,24 +1520,23 @@ writing it out again; it is output on the back of the title page. The
@subheading Part 4: `Top' Node and Master Menu
@noindent
-The `Top' node contains the master menu for the Info file. Since a
-printed manual uses a table of contents rather than a menu, the master
-menu appears only in online output. We also include the copying text
-again for the benefit of online readers. And since the copying text
-begins with a brief description of the manual, no other text is needed.
+The `Top' node contains the master menu for the Info file. Since the
+printed manual uses a table of contents rather than a menu, it
+excludes the `Top' node. We also include the copying text again for
+the benefit of online readers. Since the copying text begins with
+a brief description of the manual, no other text is needed in this
+case. The @samp{@@top} command itself helps @command{makeinfo}
+determine the relationships between nodes.
@example
-@group
@@ifnottex
@@node Top
-@@end ifnottex
-@end group
-@end example
+@@top Short Sample
-@example
-@group
@@insertcopying
+@@end ifnottex
+@group
@@menu
* First Chapter:: The first chapter is the
only chapter in this sample.
@@ -2388,8 +2488,8 @@ C-c C-c @} @r{Move out of enclosing braces.}
@group
C-c C-c C-d @r{Insert a node's section title}
- @r{in the space for the description}
- @r{in a menu entry line.}
+ @r{in the space for the description}
+ @r{in a menu entry line.}
@end group
@end example
@@ -2412,13 +2512,13 @@ be used to update every node and menu in a file as well.@refill
@group
C-c C-u m
M-x texinfo-master-menu
- @r{Create or update a master menu.}
+ @r{Create or update a master menu.}
@end group
@group
C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
- @r{create or update all nodes and regular}
- @r{menus, and then create a master menu.}
+ @r{create or update all nodes and regular}
+ @r{menus, and then create a master menu.}
@end group
@end example
@@ -2446,13 +2546,13 @@ C-c C-u C-m @r{Make or update a menu.}
@group
C-c C-u C-a @r{Make or update all}
- @r{menus in a buffer.}
+ @r{menus in a buffer.}
@end group
@group
C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
- @r{first create or update all nodes and}
- @r{then create or update all menus.}
+ @r{first create or update all nodes and}
+ @r{then create or update all menus.}
@end group
@end example
@@ -2515,27 +2615,27 @@ they are rarely used.
@example
@group
M-x texinfo-insert-node-lines
- @r{Insert missing @code{@@node} lines in region.}
- @r{With @kbd{C-u} as a prefix argument,}
- @r{use section titles as node names.}
+ @r{Insert missing @code{@@node} lines in region.}
+ @r{With @kbd{C-u} as a prefix argument,}
+ @r{use section titles as node names.}
@end group
@group
M-x texinfo-multiple-files-update
- @r{Update a multi-file document.}
- @r{With @kbd{C-u 2} as a prefix argument,}
- @r{create or update all nodes and menus}
- @r{in all included files first.}
+ @r{Update a multi-file document.}
+ @r{With @kbd{C-u 2} as a prefix argument,}
+ @r{create or update all nodes and menus}
+ @r{in all included files first.}
@end group
@group
M-x texinfo-indent-menu-description
- @r{Indent descriptions.}
+ @r{Indent descriptions.}
@end group
@group
M-x texinfo-sequential-node-update
- @r{Insert node pointers in strict sequence.}
+ @r{Insert node pointers in strict sequence.}
@end group
@end example
@@ -2561,7 +2661,7 @@ previously given (@pxref{Six Parts}).
* The Top Node:: Creating the `Top' node and master menu.
* Global Document Commands:: Affecting formatting throughout.
* Software Copying Permissions:: Ensure that you and others continue to
- have the right to use and share software.
+ have the right to use and share software.
@end menu
@@ -2629,7 +2729,7 @@ Published by @dots{}
@@menu
* First Chapter:: Getting started @dots{}
* Second Chapter:: @dots{}
- @dots{}
+ @dots{}
* Copying:: Your rights and freedoms.
@@end menu
@end group
@@ -2892,19 +2992,20 @@ insert the text at appropriate points.
@node copying
-@subsection @code{@@copying}: Declare copying permissions
+@subsection @code{@@copying}: Declare Copying Permissions
@findex copying
The @code{@@copying} command should be given very early in the document;
-right after the header material (@pxref{Texinfo File Header}) is the
-recommended location. It conventionally consists of a sentence or two
-about what the program is, the legal copyright line, and the copying
-permissions. Here is a skeletal example:
+the recommended location is right after the header material
+(@pxref{Texinfo File Header}). It conventionally consists of a sentence
+or two about what the program is, identification of the documentation
+itself, the legal copyright line, and the copying permissions. Here is
+a skeletal example:
@example
@@copying
-This manual is for @var{program} (version @var{version}),
-which @dots{}
+This manual is for @var{program} (version @var{version}, updated
+@var{date}), which @dots{}
Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
@@ -2919,7 +3020,8 @@ readability in some contexts.
@xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
@xref{GNU Free Documentation License}, for the license itself under
-which GNU and other free manuals are distributed.
+which GNU and other free manuals are distributed. You need to include
+the license as an appendix to your document.
The text of @code{@@copying} is output as a comment at the beginning of
Info, HTML, and XML output files. It is @emph{not} output implicitly in
@@ -2927,10 +3029,10 @@ plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
emit the copying information. See the next section for details.
@findex copyright
-In output formats that support it (print and HTML), the
-@code{@@copyright@{@}} command generates a @samp{c} inside a circle. In
-Info and plain text, it generates @samp{(C)}. The copyright notice
-itself has the following legally defined sequence:
+The @code{@@copyright@{@}} command generates a @samp{c} inside a circle
+in output formats that support this (print and HTML). In the other
+formats (Info and plain text), it generates @samp{(C)}. The copyright
+notice itself has the following legally defined sequence:
@example
Copyright @copyright{} @var{years} @var{copyright-owner}.
@@ -2938,26 +3040,33 @@ Copyright @copyright{} @var{years} @var{copyright-owner}.
@cindex Copyright word, always in English
The word `Copyright' must always be written in English, even if the
-manual is otherwise in another language. This is due to international
-law.
+document is otherwise written in another language. This is due to
+international law.
@cindex Years, in copyright line
The list of years should include all years in which a version was
completed (even if it was released in a subsequent year). Ranges are
-not allowed, each year must be written out individually, separated by
-commas.
+not allowed; each year must be written out individually and in full,
+separated by commas.
-@cindex Copyright owner for FSF works
+@cindex Copyright holder for FSF works
+@cindex Holder of copyright for FSF works
+@cindex Owner of copyright for FSF works
The copyright owner (or owners) is whoever holds legal copyright on the
work. In the case of works assigned to the FSF, the owner is `Free
Software Foundation, Inc.'.
+The copyright `line' may actually be split across multiple
+lines, both in the source document and in the output. This often
+happens for documents with a long history, having many different years
+of publication.
+
@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
additional information.
@node insertcopying
-@subsection @code{@@insertcopying}: Include permissions text
+@subsection @code{@@insertcopying}: Include Permissions Text
@findex insertcopying
@cindex Copying text, including
@cindex Permissions text, including
@@ -2970,13 +3079,13 @@ itself, like this:
@@insertcopying
@end example
-It inserts the text previously defined by @code{@@copying}. Legally, it
-must be used on the copyright page in the printed manual
-(@pxref{Copyright}).
+This inserts the text previously defined by @code{@@copying}. To meet
+legal requirements, it must be used on the copyright page in the printed
+manual (@pxref{Copyright}).
-Although it's not a legal requirement, we also strongly recommend using
-@code{@@insertcopying} in the Top node of your manual (@pxref{The Top
-Node}). Here's why:
+We also strongly recommend using @code{@@insertcopying} in the Top node
+of your manual (@pxref{The Top Node}), although it is not required
+legally. Here's why:
The @code{@@copying} command itself causes the permissions text to
appear in an Info file @emph{before} the first node. The text is also
@@ -3021,15 +3130,15 @@ an @code{@@insertcopying}.
@menu
* titlepage:: Create a title for the printed document.
* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
- and @code{@@sp} commands.
+ and @code{@@sp} commands.
* title subtitle author:: The @code{@@title}, @code{@@subtitle},
- and @code{@@author} commands.
+ and @code{@@author} commands.
* Copyright:: How to write the copyright notice and
- include copying permissions.
+ include copying permissions.
* end titlepage:: Turn on page headings after the title and
- copyright pages.
+ copyright pages.
* headings on off:: An option for turning headings on and off
- and double or single sided printing.
+ and double or single sided printing.
@end menu
@@ -3528,7 +3637,7 @@ For example, the master menu for this manual looks like the following
@group
@@detailmenu
- --- The Detailed Node Listing ---
+--- The Detailed Node Listing ---
Overview of Texinfo
@@ -3564,7 +3673,7 @@ generally all given before the Top node, if they are given at all.
@node documentdescription
-@subsection @code{@@documentdescription}: Summary text
+@subsection @code{@@documentdescription}: Summary Text
@cindex Document description
@cindex Description of document
@cindex Summary of document
@@ -3809,7 +3918,7 @@ For example:
@menu
* Printing Indices & Menus:: How to print an index in hardcopy and
- generate index menus in Info.
+ generate index menus in Info.
* Contents:: How to create a table of contents.
* File End:: How to mark the end of a file.
@end menu
@@ -3982,9 +4091,9 @@ texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
@section @code{@@bye} File Ending
@findex bye
-An @code{@@bye} command terminates @TeX{} or Info formatting. None of
-the formatting commands reading anything following @code{@@bye}. The
-@code{@@bye} command should be on a line by itself.
+An @code{@@bye} command terminates Texinfo processing. None of the
+formatters read anything following @code{@@bye}. The @code{@@bye}
+command should be on a line by itself.
If you wish, you may follow the @code{@@bye} line with notes. These
notes will not be formatted and will not appear in either Info or a
@@ -4050,16 +4159,16 @@ each of which has two sections.@refill
@example
@group
- Top
- |
- -------------------------------------
- | | |
- Chapter 1 Chapter 2 Chapter 3
- | | |
- -------- -------- --------
- | | | | | |
- Section Section Section Section Section Section
- 1.1 1.2 2.1 2.2 3.1 3.2
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
@end group
@end example
@@ -4447,12 +4556,12 @@ structuring hierarchy:@refill
@example
@group
- @r{Change} @r{To}
+ @r{Change} @r{To}
@@subsection @@section,
@@section @@chapter,
@@heading @@chapheading,
- @r{etc.}
+ @r{etc.}
@end group
@end example
@@ -4462,12 +4571,12 @@ structuring hierarchy:@refill
@example
@group
- @r{Change} @r{To}
+ @r{Change} @r{To}
@@chapter @@section,
@@subsection @@subsubsection,
@@heading @@subheading,
- @r{etc.}
+ @r{etc.}
@end group
@end example
@@ -4509,7 +4618,7 @@ books.@refill
@menu
* Two Paths:: Different commands to structure
- Info output and printed output.
+ Info output and printed output.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* node:: Creating nodes, in detail.
* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
@@ -4563,16 +4672,16 @@ root.@refill
@example
@group
- Top
- |
- -------------------------------------
- | | |
- Chapter 1 Chapter 2 Chapter 3
- | | |
- -------- -------- --------
- | | | | | |
- Section Section Section Section Section Section
- 1.1 1.2 2.1 2.2 3.1 3.2
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
@end group
@end example
@@ -4611,10 +4720,10 @@ before the beginning of Section 2.1, like this:@refill
@example
@group
- @@menu
- * Sect. 2.1:: Description of this section.
- * Sect. 2.2::
- @@end menu
+ @@menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2::
+ @@end menu
@end group
@end example
@@ -4622,8 +4731,8 @@ Write the node for Sect. 2.1 like this:@refill
@example
@group
- @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
- @@comment node-name, next, previous, up
+ @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+ @@comment node-name, next, previous, up
@end group
@end example
@@ -4673,7 +4782,7 @@ the @code{@@node} line. On the other hand, in printed output nodes
are used only for cross references, so a chapter or section may
contain any number of nodes. Indeed, a chapter usually contains
several nodes, one for each section, subsection, and
-subsubsection.@refill
+subsubsection.
To create a node, write an @code{@@node} command at the beginning of a
line, and follow it with up to four arguments, separated by commas, on
@@ -4684,10 +4793,10 @@ if your Texinfo document is hierarchically organized (@pxref{makeinfo
Pointer Creation}).
You may insert spaces before each name if you wish; the spaces are
-ignored. You must write the name of the node and the names of the
-`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
-the formatters fail. (@inforef{Top, info, info}, for more information
-about nodes in Info.)
+ignored. You must write the name of the node and (if present) the names
+of the `Next', `Previous', and `Up' pointers all on the same line.
+Otherwise, the formatters fail. (@inforef{Top, info, info}, for more
+information about nodes in Info.)
Usually, you write one of the chapter-structuring command lines
immediately after an @code{@@node} line---for example, an
@@ -4697,7 +4806,7 @@ Command Types}.)
@quotation
@strong{Please note:} The GNU Emacs Texinfo mode updating commands work
only with Texinfo files in which @code{@@node} lines are followed by chapter
-structuring lines. @xref{Updating Requirements}.@refill
+structuring lines. @xref{Updating Requirements}.
@end quotation
@TeX{} uses @code{@@node} lines to identify the names to use for cross
@@ -4705,7 +4814,7 @@ references. For this reason, you must write @code{@@node} lines in a
Texinfo file that you intend to format for printing, even if you do not
intend to format it for Info. (Cross references, such as the one at the
end of this sentence, are made with @code{@@xref} and related commands;
-see @ref{Cross References}.)@refill
+see @ref{Cross References}.)
@menu
* Node Names:: How to choose node and pointer names.
@@ -4722,23 +4831,23 @@ see @ref{Cross References}.)@refill
@cindex Node names, choosing
The name of a node identifies the node. The pointers enable
-you to reach other nodes and consist of the names of those nodes.@refill
+you to reach other nodes and consist simply of the names of those nodes.
Normally, a node's `Up' pointer contains the name of the node whose menu
mentions that node. The node's `Next' pointer contains the name of the
node that follows that node in that menu and its `Previous' pointer
contains the name of the node that precedes it in that menu. When a
node's `Previous' node is the same as its `Up' node, both node pointers
-name the same node.@refill
+name the same node.
Usually, the first node of a Texinfo file is the `Top' node, and its
`Up' and `Previous' pointers point to the @file{dir} file, which
-contains the main menu for all of Info.@refill
+contains the main menu for all of Info.
The `Top' node itself contains the main or master menu for the manual.
Also, it is helpful to include a brief description of the manual in the
`Top' node. @xref{First Node}, for information on how to write the
-first node of a Texinfo file.@refill
+first node of a Texinfo file.
Even when you explicitly specify all pointers, that does not mean you
can write the nodes in the Texinfo source file in an arbitrary order!
@@ -4823,7 +4932,7 @@ capitalized; others are not.@refill
@end itemize
-@node Node Line Requirements, First Node, Node Line Tips, node
+@node Node Line Requirements
@subsection @code{@@node} Line Requirements
@cindex Node line requirements
@@ -4834,7 +4943,7 @@ Here are several requirements for @code{@@node} lines:
@cindex Unique nodename requirement
@cindex Node name must be unique
@item
-All the node names for a single Info file must be unique.@refill
+All the node names for a single Info file must be unique.
Duplicates confuse the Info movement commands. This means, for
example, that if you end every chapter with a summary, you must name
@@ -4842,10 +4951,10 @@ each summary node differently. You cannot just call each one
``Summary''. You may, however, duplicate the titles of chapters, sections,
and the like. Thus you can end each chapter in a book with a section
called ``Summary'', so long as the node names for those sections are all
-different.@refill
+different.
@item
-A pointer name must be the name of a node.@refill
+A pointer name must be the name of a node.
The node to which a pointer points may come before or after the
node containing the pointer.
@@ -4853,50 +4962,32 @@ 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. 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
-this:@refill
-
-@smallexample
-@group
-@@node chapter, unnumbered & appendix, makeinfo top, Structuring
-@@comment node-name, next, previous, up
-@@section @@code@{@@@@chapter@}
-@@findex chapter
-@end group
-@end smallexample
-
-@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}.
+@@-commands in node names are not allowed. 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}.)
@item
-@cindex Apostrophe in nodename
@cindex Colon in nodename
@cindex Comma in nodename
+@cindex Parentheses in nodename
@cindex Period in nodename
@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.
+@cindex Node names, invalid characters in
+Unfortunately, you cannot use periods, commas, colons or parentheses
+within a node name; these confuse the Texinfo processors.
@need 700
-For example, the following is a section title:
+For example, the following is a section title in this manual:
@smallexample
@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
@end smallexample
@noindent
-The corresponding node name is:
+But the corresponding node name lacks the commas and the @@'s:
@smallexample
unnumberedsec appendixsec heading
@@ -5135,7 +5226,7 @@ For example, the preceding two paragraphs follow an Info-only menu,
* Less Cluttered Menu Entry:: Two part menu entry.
* Menu Example:: Two and three part entries.
* Other Info Files:: How to refer to a different
- Info file.
+ Info file.
@@end menu
@@node Menu Location, Writing a Menu, , Menus
@@ -5168,7 +5259,7 @@ Larger Units of Text
* Files:: All about handling files.
* Multiples: Buffers. Multiple buffers; editing
- several files at once.
+ several files at once.
@@end menu
@end group
@end example
@@ -5296,7 +5387,7 @@ Larger Units of Text
* Files:: All about handling files.
* Multiples: Buffers. Multiple buffers; editing
- several files at once.
+ several files at once.
@@end menu
@end group
@end example
@@ -5312,7 +5403,7 @@ Larger Units of Text
* Files:: All about handling files.
* Multiples: Buffers. Multiple buffers; editing
- several files at once.
+ several files at once.
@end group
@end example
@@ -5361,9 +5452,9 @@ menu like this:@refill
@group
@@menu
* Outlining: (emacs)Outline Mode. The major mode for
- editing outlines.
+ editing outlines.
* Rebinding: (emacs)Rebinding. How to redefine the
- meaning of a key.
+ meaning of a key.
@@end menu
@end group
@end example
@@ -5382,7 +5473,7 @@ For example:
@group
* Info: (info). Documentation browsing system.
* Emacs: (emacs). The extensible, self-documenting
- text editor.
+ text editor.
@end group
@end example
@@ -5901,7 +5992,7 @@ Here are several examples from @cite{The GNU Awk User's Guide}:@refill
@@xref@{Glossary@}.
@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
@@xref@{Close Output, , Closing Output Files and Pipes@},
- for more information.
+ for more information.
@@xref@{Regexp, , Regular Expressions as Patterns@}.
@end smallexample
@@ -7289,8 +7380,8 @@ produces:
@end ifinfo
@example
- *Caution*: `rm * .[^.]*' removes _all_
- files in the directory.
+ *Caution*: `rm * .[^.]*' removes _all_
+ files in the directory.
@end example
The @code{@@strong} command is seldom used except to mark what is, in
@@ -7419,7 +7510,7 @@ line.
* verbatim:: Writing a verbatim example.
* verbatiminclude:: Including a file verbatim.
* lisp:: Illustrating Lisp code.
-* small:: Forms for @code{@@smallbook}.
+* small:: Examples in a smaller font.
* display:: Writing an example in the current font.
* format:: Writing an example without narrowed margins.
* exdent:: Undo indentation on a line.
@@ -7547,36 +7638,32 @@ This is a foo.
@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.
-
-@example
-@group
-This is an example of text written between an
-@code{@@example} command
-and an @code{@@end example} command.
-The text is indented but not filled.
-@end group
-
-@group
-In the printed manual, the text is typeset in a
-fixed-width font, and extra spaces and blank lines are
-significant. In the Info file, an analogous result is
-obtained by indenting each line with five spaces.
-@end group
-@end example
-
-Write an @code{@@example} command at the beginning of a line by itself.
-Mark the end of the example
-with an @code{@@end example} command, also written at the beginning of a
-line by itself.@refill
+The @code{@@example} environment is used to indicate an example that
+is not part of the running text, such as computer input or output.
+Write an @code{@@example} command at the beginning of a line by
+itself. Mark the end of the example with an @code{@@end example}
+command, also written at the beginning of a line by itself.
+
+An @code{@@example} environment has the following characteristics:
+
+@itemize
+@item Each line in the input file is a line in the output; that is,
+the source text is not filled as it normally is.
+@item Extra spaces and blank lines are significant.
+@item The output is indented.
+@item The output uses a fixed-width font (for formats where this is
+possible and meaningful).
+@item Texinfo commands @emph{are} expanded; if you want the input to
+be the output verbatim, use the @code{@@verbatim} environment instead
+(@pxref{verbatim,,@code{@@verbatim}}).
+@end itemize
-@need 700
For example,
@example
@@example
-mv foo bar
+cp foo @@var@{dest1@}; \
+ cp foo @@var@{dest2@}
@@end example
@end example
@@ -7584,37 +7671,34 @@ mv foo bar
produces
@example
-mv foo bar
+cp foo @var{dest1}; \
+ cp foo @var{dest2}
@end example
-The lines containing @code{@@example} and @code{@@end example}
-will disappear from the output.
-To make the output look good,
-you should put a blank line before the
-@code{@@example} and another blank line after the @code{@@end example}.
-Note that blank lines inside the beginning
-@code{@@example} and the ending @code{@@end example} will appear in
-the output.@refill
+The lines containing @code{@@example} and @code{@@end example} will
+disappear from the output. To make the output look good, you should
+put a blank line before the @code{@@example} and another blank line
+after the @code{@@end example}. Blank lines inside the beginning
+@code{@@example} and the ending @code{@@end example}, on the other
+hand, do appear in the output.
@quotation
-@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
+@strong{Caution:} Do not use tabs in the lines of an example! (Or
+anywhere else in Texinfo, except in verbatim environments.) @TeX{}
+treats tabs as single spaces, and that is not what they look like. In
+Emacs, you can use @kbd{M-x untabify} to convert tabs in a region to
+multiple spaces.
@end quotation
Examples are often, logically speaking, ``in the middle'' of a
-paragraph, and the text that continues after an example should not be
-indented. The @code{@@noindent} command prevents a piece of text from
-being indented as if it were a new paragraph.
-@ifinfo
-(@xref{noindent}.)
-@end ifinfo
+paragraph, and the text that continues afterwards should not be
+indented, as in the example above. The @code{@@noindent} command
+prevents a piece of text from being indented as if it were a new
+paragraph (@pxref{noindent,,@code{@@noindent}}.
-(The @code{@@code} command is used for examples of code that are
-embedded within sentences, not set off from preceding and following
-text. @xref{code, , @code{@@code}}.)
+If you want to embed code fragments within sentences, instead of
+displaying them, use the @code{@@code} command or its relatives
+(@pxref{code,,@code{@@code}}).
@node verbatim
@@ -7663,7 +7747,7 @@ produces
@verbatim
{
- @command with strange characters: @'e
+ @command with strange characters: @'e
expand me
}
@end verbatim
@@ -7692,6 +7776,18 @@ 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.
+The name of the file is taken literally, with a single exception:
+@code{@@value@{@var{var}@}} references are expanded. This makes it
+possible to reliably include files in other directories in a
+distribution, for instance:
+
+@example
+@@include @@value@{top_srcdir@}/NEWS
+@end example
+
+@noindent (You still have to get @code{top_srcdir} defined in the
+first place.)
+
@node lisp
@section @code{@@lisp}: Marking a Lisp Example
@@ -7714,7 +7810,7 @@ library.@footnote{It would be straightforward to extend Texinfo to work
in a similar fashion for C, Fortran, or other languages.}
Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
-itself.@refill
+itself.
@node small
@@ -7732,65 +7828,37 @@ Texinfo has ``small'' example-style commands. These are
@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
@code{@@smalllisp}.
-In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
-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.
+In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in
+a smaller font than the non-small example commands. Consequently,
+many examples containing long lines fit on a page without needing to
+be shortened.
+
Mark the end of an @code{@@small@dots{}} block with a corresponding
@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
@code{@@end smallexample}.
-@iftex
-Here is an example written in the small font used by the
-@code{@@smallexample} and @code{@@smalllisp} commands:
+Here is an example of the font used by the @code{@@small@dots{}}
+commands (in Info, the output will be the same as usual):
-@ifclear smallbook
-@display
-@tex
-% Remove extra vskip; this is a kludge to counter the effect of display
-\vskip-3\baselineskip
-{\smalltt
-\dots{} to make sure that you have the freedom to
+@smallexample
+@dots{} to make sure that you have the freedom to
distribute copies of free software (and charge for
this service if you wish), that you receive source
code or can get it if you want it, that you can
change the software or use pieces of it in new free
-programs; and that you know you can do these things.}
-@end tex
-@end display
-@end ifclear
-@end iftex
-@ifset smallbook
-@iftex
-@smallexample
-This is an example of text written between @code{@@smallexample} and
-@code{@@end smallexample}. In Info this text appears in its normal size;
-but in printed manuals, this text appears in a smaller font.
+programs; and that you know you can do these things.
@end smallexample
-@end iftex
-@end ifset
-@ifinfo
-@smallexample
-This is an example of text written between @code{@@smallexample} and
-@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 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}
-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.
+As a general rule, a printed document looks much better if you use
+only one of (for instance) @code{@@example} or @code{@@smallexample}
+consistently within a chapter.
@node display
@@ -7949,9 +8017,15 @@ left end ragged.
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
+paragraph. You can prevent this on a case-by-case basis by writing
+@code{@@noindent} at the beginning of a line, preceding the continuation
+text. You can also disable indentation for all paragraphs globally with
+@code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}).
+
+It is best to write @code{@@noindent} on a line by itself, since in most
+environments, spaces following the command will not be ignored. It's ok
+to use it at the beginning of a line, with text following, outside of
+any environment.
@need 1500
For example:
@@ -7970,35 +8044,32 @@ that follows after it. (This whole example is between
@end group
@end example
-@noindent
-produces
+@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
+blank line, and neither does the @code{@@end example} line.
In the Texinfo source file for this manual, each line that says
-`produces' is preceded by a line containing @code{@@noindent}.@refill
+`produces' is preceded by @code{@@noindent}.
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
+paragraphs (@pxref{Command Syntax}).
@node cartouche
@@ -8367,7 +8438,7 @@ a letter, beginning with that lower case letter.@refill
You can also nest enumerated lists, as in an outline.@refill
-@node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
+@node Two-column Tables
@section Making a Two-column Table
@cindex Tables, making two-column
@findex table
@@ -8384,35 +8455,35 @@ exhibits, and command-line option summaries.
* itemx:: How to put more entries in the first column.
@end menu
-@node table, ftable vtable, Two-column Tables, Two-column Tables
-@ifinfo
-@subheading Using the @code{@@table} Command
+@node table
+@subsection Using the @code{@@table} Command
-Use the @code{@@table} command to produce two-column tables.@refill
-@end ifinfo
+@cindex Definition lists, typesetting
+Use the @code{@@table} command to produce two-column tables. It is
+usually listed for ``definition lists'' of various sorts, where you
+have a list of terms and a brief text with each one.
+
+Write the @code{@@table} command at the beginning of a line, after a
+blank line, and follow it on the same line with an argument that is a
+Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp},
+@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
-Write the @code{@@table} command at the beginning of a line and follow
-it on the same line with an argument that is a Texinfo ``indicating''
-command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
-@code{@@kbd} (@pxref{Indicating}). Although these commands are usually
-followed by arguments in braces, in this case you use the command name
-without an argument because @code{@@item} will supply the argument.
-This command will be applied to the text that goes into the first column
-of each item and determines how it will be highlighted. For example,
-@code{@@code} will cause the text in the first column to be highlighted
-with an @code{@@code} command. (We recommend @code{@@code} for
-@code{@@table}'s of command-line options.)
+This command will be applied to the text that goes into the first
+column of each item and thus determines how it will be highlighted.
+For example, @code{@@table @@code} will cause the text in the first
+column to be output as if it @code{@@code} command.
@findex asis
-You may also choose to use the @code{@@asis} command as an argument to
+You may also use the @code{@@asis} command as an argument to
@code{@@table}. @code{@@asis} is a command that does nothing; if you
-use this command after @code{@@table}, @TeX{} and the Info formatting
-commands output the first column entries without added highlighting
-(``as is'').@refill
+use this command after @code{@@table}, the first column entries are
+output without added highlighting (``as is'').
-(The @code{@@table} command may work with other commands besides those
-listed here. However, you can only use commands that normally take
-arguments in braces.)@refill
+The @code{@@table} command works with other commands besides those
+explicitly mentioned here. However, you can only use commands that
+normally take arguments in braces. (In this case, however, you use
+the command name without an argument, because the subsequent
+@code{@@item}'s will supply the argument.)
@findex item
Begin each table entry with an @code{@@item} command at the beginning
@@ -8421,16 +8492,20 @@ of a line. Write the first column text on the same line as the
following the @code{@@item} line and on subsequent lines. (You do not
need to type anything for an empty second column entry.) You may
write as many lines of supporting text as you wish, even several
-paragraphs. But only text on the same line as the @code{@@item} will
-be placed in the first column, including any footnote.
+paragraphs. But only the text on the same line as the @code{@@item}
+will be placed in the first column (including any footnotes).
Normally, you should put a blank line before an @code{@@item} line.
-This puts a blank like in the Info file. Except when the entries are
-very brief, a blank line looks better.@refill
+This puts a blank line in the Info file. Except when the entries are
+very brief, a blank line looks better.
+
+End the table with a line consisting of @code{@@end table}, followed
+by a blank line. @TeX{} will always start a new paragraph after the
+table, so the blank line is needed for the Info output to be analogous.
@need 1500
The following table, for example, highlights the text in the first
-column with an @code{@@samp} command:@refill
+column with an @code{@@samp} command:
@example
@group
@@ -8457,8 +8532,7 @@ Text for @samp{bar}.
@end table
If you want to list two or more named items with a single block of
-text, use the @code{@@itemx} command. (@xref{itemx, ,
-@code{@@itemx}}.)@refill
+text, use the @code{@@itemx} command. (@xref{itemx,,@code{@@itemx}}.)
@node ftable vtable
@@ -8670,7 +8744,7 @@ canonical purpose. If you wish, you can define your own indices.@refill
@menu
* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
- of entry.
+ of entry.
* Indexing Commands:: How to make an index entry.
* Combining Indices:: How to combine indices.
* New Indices:: How to define your own indices.
@@ -8874,9 +8948,9 @@ the braces of @code{@@code}.@refill
@menu
* syncodeindex:: How to merge two indices, using @code{@@code}
- font for the merged-from index.
+ font for the merged-from index.
* synindex:: How to merge two indices, using the
- default font of the merged-to index.
+ default font of the merged-to index.
@end menu
@node syncodeindex
@@ -9060,16 +9134,16 @@ These are:
@menu
* Braces Atsigns:: How to insert braces, @samp{@@}.
* Inserting Space:: How to insert the right amount of space
- within a sentence.
+ within a sentence.
* Inserting Accents:: How to insert accents and special characters.
* Dots Bullets:: How to insert dots and bullets.
* TeX and copyright:: How to insert the @TeX{} logo
- and the copyright symbol.
+ and the copyright symbol.
* pounds:: How to insert the pounds currency symbol.
* minus:: How to insert a minus sign.
* math:: How to format a mathematical expression.
* Glyphs:: How to indicate results of evaluation,
- expansion of macros, errors, etc.
+ expansion of macros, errors, etc.
* Footnotes:: How to include footnotes.
* Images:: How to include graphics.
@end menu
@@ -9233,7 +9307,7 @@ emacs, The GNU Emacs Manual}).
Do not put braces after any of these commands.
-@node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
+@node Multiple Spaces
@subsection Multiple Spaces
@cindex Multiple spaces
@@ -9278,7 +9352,7 @@ 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}.
+To produce a non-breakable space, see @ref{tie, @code{@@tie}}.
@node dmn
@@ -9507,7 +9581,7 @@ braces.@refill
@menu
* tex:: How to insert the @TeX{} logo.
-* copyright symbol:: How to use @code{@@copyright}@{@}.
+* copyright symbol:: How to use @code{@@copyright@{@}}.
@end menu
@@ -9523,12 +9597,12 @@ letters. In Info, it just looks like @samp{TeX}. The
@node copyright symbol
-@subsection @code{@@copyright}@{@} (@copyright{})
+@subsection @code{@@copyright@{@}} (@copyright{})
@findex copyright
Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
a printed manual, this is a @samp{c} inside a circle, and in Info,
-this is @samp{(C)}.@refill
+this is @samp{(C)}.
@node pounds, minus, TeX and copyright, Insertions
@@ -9603,7 +9677,9 @@ command. Write the mathematical expression between braces, like this:
(a + b)(a + b) = a^2 + 2ab + b^2
@end example
-Thus, the @code{@@math} command has no effect on the Info output.
+Thus, the @code{@@math} command has no effect on the Info output;
+@command{makeinfo} just reproduces the input, it does not try to
+interpret the mathematics in any way.
@code{@@math} implies @code{@@tex}. This not only makes it possible to
write superscripts and subscripts (as in the above example), but also
@@ -9730,7 +9806,7 @@ Thus, the following,
@lisp
(cdr '(1 2 3))
- @result{} (2 3)
+ @result{} (2 3)
@end lisp
@noindent
@@ -9762,8 +9838,8 @@ For example, the following
@group
@@lisp
(third '(a b c))
- @@expansion@{@} (car (cdr (cdr '(a b c))))
- @@result@{@} c
+ @@expansion@{@} (car (cdr (cdr '(a b c))))
+ @@result@{@} c
@@end lisp
@end group
@end example
@@ -9774,8 +9850,8 @@ produces
@lisp
@group
(third '(a b c))
- @expansion{} (car (cdr (cdr '(a b c))))
- @result{} c
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
@end group
@end lisp
@@ -9818,9 +9894,9 @@ last line.@refill
@lisp
@group
(progn (print 'foo) (print 'bar))
- @print{} foo
- @print{} bar
- @result{} bar
+ @print{} foo
+ @print{} bar
+ @result{} bar
@end group
@end lisp
@@ -9831,9 +9907,9 @@ In a Texinfo source file, this example is written as follows:
@group
@@lisp
(progn (print 'foo) (print 'bar))
- @@print@{@} foo
- @@print@{@} bar
- @@result@{@} bar
+ @@print@{@} foo
+ @@print@{@} bar
+ @@result@{@} bar
@@end lisp
@end group
@end lisp
@@ -9961,7 +10037,7 @@ This is the @point{}contents of foo.
@example
@group
(insert "changed ")
- @result{} nil
+ @result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@@ -9978,7 +10054,7 @@ This is the @@point@{@}contents of foo.
---------- Buffer: foo ----------
(insert "changed ")
- @@result@{@} nil
+ @@result@{@} nil
---------- Buffer: foo ----------
This is the changed @@point@{@}contents of foo.
---------- Buffer: foo ----------
@@ -10074,7 +10150,7 @@ Here is an example of a single footnote in the end of node style:@refill
@example
@group
- --------- Footnotes ---------
+--------- Footnotes ---------
(1) Here is a sample footnote.
@end group
@@ -10332,30 +10408,29 @@ arise. When they do, use the break, break prevention, or pagination
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.
-* w:: How to prevent unwanted line breaks.
-* sp:: How to insert blank lines.
-* page:: How to force the start of a new page.
-* group:: How to prevent unwanted page breaks.
+* Break Commands:: Summary of break-related commands.
+* Line Breaks:: Forcing line breaks.
+* - and hyphenation:: Helping @TeX{} with hyphenation points.
+* w:: Preventing unwanted line breaks in text.
+* tie:: Inserting an unbreakable but varying space.
+* sp:: Inserting blank lines.
+* page:: Forcing the start of a new page.
+* group:: Preventing unwanted page breaks.
* need:: Another way to prevent unwanted page breaks.
@end menu
-@node Break Commands, Line Breaks, Breaks, Breaks
-@ifinfo
-@heading Break Commands
-@end ifinfo
+@node Break Commands
+@section Break Commands
-The break commands create or allow line and paragraph breaks:@refill
+The break commands create or allow line and paragraph breaks:
@table @code
@item @@*
Force a line break.
@item @@sp @var{n}
-Skip @var{n} blank lines.@refill
+Skip @var{n} blank lines.
@item @@-
Insert a discretionary hyphen.
@@ -10364,31 +10439,33 @@ Insert a discretionary hyphen.
Define hyphen points in @var{hy-phen-a-ted words}.
@end table
-The line-break-prevention command holds text together all on one
-line:@refill
+These commands hold text together on a single line:
@table @code
@item @@w@{@var{text}@}
-Prevent @var{text} from being split and hyphenated across two lines.@refill
+Prevent @var{text} from being split and hyphenated across two lines.
+@item @@tie@{@}
+Insert a normal interword space at which a line break may not occur.
@end table
@iftex
@sp 1
@end iftex
The pagination commands apply only to printed output, since Info
-files do not have pages.@refill
+files do not have pages.
@table @code
@item @@page
-Start a new page in the printed manual.@refill
+Start a new page in the printed manual.
@item @@group
-Hold text together that must appear on one printed page.@refill
+Hold text together that must appear on one printed page.
@item @@need @var{mils}
-Start a new printed page if not enough space on this one.@refill
+Start a new printed page if not enough space on this one.
@end table
+
@node Line Breaks
@section @code{@@*}: Generate Line Breaks
@findex * @r{(force line break)}
@@ -10411,17 +10488,12 @@ produces
@example
@group
This line
- is broken
+is broken
in two places.
@end group
@end example
-@noindent
-(Note that the space after the first @code{@@*} command is faithfully
-carried down to the next line.)@refill
-
-@need 800
-The @code{@@*} command is often used in a file's copyright page:@refill
+The @code{@@*} command is often used in a file's copyright page:
@example
@group
@@ -10432,21 +10504,16 @@ and is for @dots{}
@noindent
In this case, the @code{@@*} command keeps @TeX{} from stretching the
-line across the whole page in an ugly manner.@refill
-
-@quotation
-@strong{Please note:} Do not write braces after an @code{@@*} command;
-they are not needed.@refill
+line across the whole page in an ugly manner.
Do not write an @code{@@refill} command at the end of a paragraph
containing an @code{@@*} command; it will cause the paragraph to be
refilled after the line break occurs, negating the effect of the line
break.@refill
-@end quotation
@node - and hyphenation
-@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
+@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
@findex - @r{(discretionary hyphen)}
@findex hyphenation
@@ -10486,7 +10553,7 @@ Info output is not hyphenated, so these commands have no effect there.
@cindex Hyphenation, preventing
@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
-within @var{text}.@refill
+within @var{text}.
You can use the @code{@@w} command to prevent @TeX{} from automatically
hyphenating a long name or phrase that happens to fall near the end of a
@@ -10503,15 +10570,66 @@ produces
You can copy GNU software from @w{@samp{ftp.gnu.org}}.
@end quotation
-@cindex Non-breakable space
-@cindex Unbreakable space
+@cindex Non-breakable space, fixed
+@cindex Unbreakable space, fixed
+You can also use @code{@@w} to produce a non-breakable space, fixed at
+the width of a normal interword space:
+
+@example
+@@w@{ @} @@w@{ @} @@w@{ @} indentation.
+@end example
+
+@noindent produces:
+
+@display
+@w{ } @w{ } @w{ } indentation.
+@end display
+
+The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, also
+will not stretch or shrink. Sometimes that is what you want, for
+instance if you're doing some manual indenting. However, usually you
+want a normal interword space that does stretch and shrink (in the
+printed output); see the @code{@@tie} command in the next section.
+
+
+@node tie
+@section @code{@@tie@{@}}: Inserting an Unbreakable Space
+@findex tie @r{(unbreakable interword space)}
@cindex Tied space
-You can also use @code{@@w} to produce a non-breakable space:
+@cindex Non-breakable space, variable
+@cindex Unbreakable space, variable
+
+The @code{@@tie@{@}} command produces a normal interword space at which
+a line break may not occur. Always write it with following (empty)
+braces, as usual for commands used within a paragraph. Here's an
+example:
@example
-None of the formatters will break at this@@w@{ @}space.
+@@TeX@{@} was written by Donald E.@@tie@{@}Knuth.
@end example
+@noindent produces:
+
+@display
+@TeX{} was written by Donald E.@tie{}Knuth.
+@end display
+
+There are two important differences between @code{@@tie@{@}} and
+@code{@@w@{@w{ }@}}:
+
+@itemize
+@item
+The space produced by @code{@@tie@{@}} will stretch and shrink slightly
+along with the normal interword spaces in the paragraph; the space
+produced by @code{@@w@{@w{ }@}} will not vary.
+
+@item
+@code{@@tie@{@}} allows hyphenation of the surrounding words, while
+@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical
+reasons, namely that it produces an @samp{\hbox}).
+
+@end itemize
+
@node sp
@section @code{@@sp} @var{n}: Insert Blank Lines
@@ -10698,7 +10816,7 @@ a given name. An appendix containing a summary should use
@menu
* Def Cmd Template:: How to structure a description using a
- definition command.
+ definition command.
* Optional Arguments:: How to handle optional and repeated arguments.
* deffnx:: How to group two or more `first' lines.
* Def Cmds in Detail:: All the definition commands.
@@ -10893,7 +11011,7 @@ example).@refill
@example
@group
@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
- [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
+ [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
@end group
@end example
@@ -11179,7 +11297,7 @@ For example,
@example
@group
@@deftypefn @{Library Function@} int foobar
- (int @@var@{foo@}, float @@var@{bar@})
+ (int @@var@{foo@}, float @@var@{bar@})
@dots{}
@@end deftypefn
@end group
@@ -11245,8 +11363,8 @@ For example:
@example
@group
@@deftypefn stacks private push
- (@@var@{s@}:in out stack;
- @@var@{n@}:in integer)
+ (@@var@{s@}:in out stack;
+ @@var@{n@}:in integer)
@dots{}
@@end deftypefn
@end group
@@ -11716,16 +11834,16 @@ do not make sense in @code{apply}.
@example
(setq f 'list)
- @result{} list
+ @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
- @result{} 10
+ @result{} 10
(apply '+ '(1 2 3 4))
- @result{} 10
+ @result{} 10
(apply 'append '((a b c) nil (x y z) nil))
- @result{} (a b c x y z)
+ @result{} (a b c x y z)
@end example
An interesting example of using @code{apply} is found in the description
@@ -11758,16 +11876,16 @@ sense in @@code@{apply@}.
@group
@@example
(setq f 'list)
- @@result@{@} list
+ @@result@{@} list
(apply f 'x 'y 'z)
@@error@{@} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
- @@result@{@} 10
+ @@result@{@} 10
(apply '+ '(1 2 3 4))
- @@result@{@} 10
+ @@result@{@} 10
(apply 'append '((a b c) nil (x y z) nil))
- @@result@{@} (a b c x y z)
+ @@result@{@} (a b c x y z)
@@end example
@end group
@@ -11814,16 +11932,16 @@ Substituting text for all formats, and testing if a flag is set or clear.
* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
* set clear value:: Designating which text to format (for
- all output formats); and how to set a
- flag to a string that you can insert.
+ all output formats); and how to set a
+ flag to a string that you can insert.
@end menu
@node Conditional Commands
@section Conditional Commands
-Texinfo has a pair of commands for each output format, to allow
-conditional inclusion of text for a particular output format.
+Texinfo has an @code{@@if@dots{}} environment for each output format, to
+allow conditional inclusion of text for a particular output format.
@findex ifinfo
@code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
@@ -11833,16 +11951,18 @@ output. The @code{@@ifinfo} command should appear on a line by itself;
end the Info-only text with a line containing @code{@@end ifinfo} by
itself.
-@findex iftex
@findex ifhtml
@findex ifplaintext
+@findex iftex
+@findex ifxml
The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
@code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
will appear in the printed manual but not in the Info file. Likewise
for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
appear only in HTML output. And for @code{@@ifplaintext} and
@code{@@end ifplaintext}, which specify text to appear only in plain
-text output.
+text output. And for @code{@@ifxml} and
+@code{@@end ifxml}, for the XML output.
For example,
@@ -11859,6 +11979,9 @@ And this text will only appear in HTML.
@@ifplaintext
Whereas this text will only appear in plain text.
@@end ifplaintext
+@@ifxml
+And this will only appear in XML output.
+@@end ifxml
@end example
@noindent
@@ -11875,6 +11998,9 @@ And this text will only appear in HTML.
@ifplaintext
Whereas this text will only appear in plain text.
@end ifplaintext
+@ifxml
+And this will only appear in XML output.
+@end ifxml
@noindent
Notice that you only see one of the input lines, depending on which
@@ -11887,6 +12013,7 @@ version of the manual you are reading.
@findex ifnotinfo
@findex ifnotplaintext
@findex ifnottex
+@findex ifnotxml
You can specify text to be included in any output format @emph{other}
than some given one with the @code{@@ifnot@dots{}} commands:
@@ -11895,24 +12022,25 @@ than some given one with the @code{@@ifnot@dots{}} commands:
@@ifnotinfo @dots{} @@end ifnotinfo
@@ifnotplaintext @dots{} @@end ifnotplaintext
@@ifnottex @dots{} @@end ifnottex
+@@ifnotxml @dots{} @@end ifnotxml
@end example
@noindent
-(The @code{@@ifnot@dots{}} command and the @code{@@end} command must
-appear on lines by themselves in your actual source file.)
+The @code{@@ifnot@dots{}} command and the @code{@@end} command must
+appear on lines by themselves in your actual source file.
-If the output file is @emph{not} being made for the given format, the
-region is included. Otherwise, it is ignored.
+If the output file is being made in the given format, the
+region is @emph{ignored}. Otherwise, it is included.
With one exception (for historical compatibility): @code{@@ifnotinfo}
text is omitted for both Info and plain text output, not just Info. To
specify text which appears only in Info and not in plain text, use
@code{@@ifnotplaintext}, like this:
@example
-@ifinfo
-@ifnotplaintext
+@@ifinfo
+@@ifnotplaintext
This will be in Info, but not plain text.
-@end ifnotplaintext
-@end ifinfo
+@@end ifnotplaintext
+@@end ifinfo
@end example
The regions delimited by these commands are ordinary Texinfo source as
@@ -11922,13 +12050,12 @@ with @code{@@iftex}, not raw formatter source as with @code{@@tex}
@node Raw Formatter Commands
@section Raw Formatter Commands
-@cindex @TeX{} commands, using ordinary
-@cindex HTML commands, using ordinary
@cindex Raw formatter commands
+@cindex @TeX{} commands, using ordinary
@cindex Ordinary @TeX{} commands, using
-@cindex Ordinary HTML commands, using
@cindex Commands using raw @TeX{}
-@cindex Commands using raw HTML
+@cindex HTML, including raw
+@cindex XML, including raw
@cindex plain @TeX{}
Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
@@ -11960,8 +12087,8 @@ plain @TeX{}:
@example
@@tex
$$ \chi^2 = \sum_@{i=1@}^N
- \left (y_i - (a + b x_i)
- \over \sigma_i\right)^2 $$
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
@@end tex
@end example
@@ -11976,8 +12103,8 @@ this:
@tex
$$ \chi^2 = \sum_{i=1}^N
- \left(y_i - (a + b x_i)
- \over \sigma_i\right)^2 $$
+ \left(y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
@end tex
@findex ifhtml
@@ -11988,6 +12115,14 @@ a region to be included in HTML output only, and @code{@@html @dots{}
still the escape character, so the @code{@@end} command can be
recognized.)
+@findex ifxml
+@findex xml
+Analogously, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
+a region to be included in XML output only, and @code{@@xml @dots{}
+@@end xml} for a region of raw XML (again, except that @code{@@} is
+still the escape character, so the @code{@@end} command can be
+recognized.)
+
@node set clear value
@section @code{@@set}, @code{@@clear}, and @code{@@value}
@@ -12526,7 +12661,7 @@ document encoding @var{enc} is specified, it is used in a
@example
<meta http-equiv="Content-Type" content="text/html;
- charset=@var{enc}">
+ charset=@var{enc}">
@end example
@@ -12754,13 +12889,16 @@ Twice: a,b & a,b.
@cindex Macro details
@cindex Details of macro usage
-Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
-implementations, Texinfo macros have the following limitations.
+Due to unavoidable limitations, certain macro-related constructs cause
+problems with @TeX{}. If you get macro-related errors when producing
+the printed version of a manual, try expanding the macros with
+@command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E}
+option (@ref{Format with texi2dvi}).
@itemize @bullet
@item
All macros are expanded inside at least one @TeX{} group. This means
-that @code{@@set} and other such commands will have no effect inside a
+that @code{@@set} and other such commands have no effect inside a
macro.
@item
@@ -12772,9 +12910,14 @@ 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:
+It is best to avoid comments inside macro definitions.
+
+@item
+Macro arguments cannot cross lines.
+
+@item
+Macros cannot define macros in the natural way. To do this, you must
+use conditionals and raw @TeX{}. For example:
@example
@@ifnottex
@@ -12790,15 +12933,8 @@ something involving \arg\ somehow
@@end tex
@end example
-@item
-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}}
@@ -12845,7 +12981,7 @@ 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.
-
+
Presumably, if you define a command with @code{@@definfoenclose} for Info,
you will create a corresponding command for @TeX{}, either in
@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
@@ -12866,7 +13002,7 @@ you intended as the start delimiter string.
If you do a @code{@@definfoenclose} on the name of a pre-defined macro
(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
enclosure definition will override the built-in definition.
-
+
An enclosure command defined this way takes one argument in braces; this
is intended for new markup commands (@pxref{Marking Text}).
@@ -12954,8 +13090,8 @@ print queue, and delete a job from the print queue.
* smallbook:: How to print small format books and manuals.
* A4 Paper:: How to print on A4 or A5 paper.
* pagesizes:: How to print with customized page sizes.
-* Cropmarks and Magnification:: How to print marks to indicate the size
- of pages and how to print scaled up output.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
* PDF Output:: Portable Document Format output.
@end menu
@@ -13328,7 +13464,7 @@ The default values are:@refill
@example
@group
- @r{Variable} @r{Default value}
+ @r{Variable} @r{Default value}
texinfo-texi2dvi-command "texi2dvi"
texinfo-tex-command "tex"
@@ -13638,7 +13774,8 @@ file, before the title page:@refill
@noindent
(Since many books are about 7 by 9.25 inches, this command might better
have been called the @code{@@regularbooksize} command, but it came to be
-called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
+called the @code{@@smallbook} command by comparison to the 8.5 by 11
+inch format.)
If you write the @code{@@smallbook} command between the
start-of-header and end-of-header lines, the Texinfo mode @TeX{}
@@ -13689,7 +13826,7 @@ You may or may not prefer the formatting that results from the command
wide format.
@node pagesizes
-@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
+@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
@findex pagesizes
@cindex Custom page sizes
@cindex Page sizes, customized
@@ -13800,17 +13937,16 @@ magnifications. Be prepared to experiment.
@pindex pdftex
You can generate a PDF output file from Texinfo source by using the
@command{pdftex} program to process your file instead of plain
-@command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex
+@command{tex}. That is, run @samp{pdftex foo.texi} instead of @samp{tex
foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
@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.
+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}. At present, 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) that
@@ -13855,12 +13991,12 @@ For information on installing the Info file in the Info system,
* Pointer Validation:: How to check that pointers point somewhere.
* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
* texinfo-format commands:: Two Info formatting commands written
- in Emacs Lisp are an alternative
- to @code{makeinfo}.
+ in Emacs Lisp are an alternative
+ to @code{makeinfo}.
* Batch Formatting:: How to format for Info in Emacs Batch mode.
* Tag and Split Files:: How tagged and split files help Info
- to run better.
-* makeinfo html:: Generating HTML output.
+ to run better.
+* Generating HTML:: Generating HTML output with makeinfo.
@end menu
@@ -13959,6 +14095,11 @@ details.
@opindex --docbook
Generate DocBook output rather than Info.
+@item --enable-encoding
+@opindex --enable-encoding
+Output accented and special characters in Info or plain text output
+based on @samp{@@documentencoding}.
+
@item --error-limit=@var{limit}
@itemx -e @var{limit}
@opindex --error-limit=@var{limit}
@@ -14006,7 +14147,7 @@ Print a usage message listing all available options, then exit successfully.
@item --html
@opindex --html
-Generate HTML output rather than Info. @xref{makeinfo html}. By
+Generate HTML output rather than Info. @xref{Generating 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.
@@ -14021,8 +14162,26 @@ not given, the current directory @file{.} is appended. Note that
usual path separator character (@samp{:} on Unix, @samp{;} on
MS-DOS/MS-Windows).
+@item --ifhtml
+@itemx --ifinfo
+@itemx --ifplaintext
+@itemx --iftex
+@itemx --ifxml
+@opindex --ifhtml
+@opindex --ifinfo
+@opindex --ifplaintext
+@opindex --iftex
+@opindex --ifxml
+For the specified format, process @samp{@@if@var{format}} and
+@samp{@@@var{format}} commands even if not generating the given output
+format. For instance, if @option{--iftex} is specified, then
+@samp{@@iftex} and @samp{@@tex} blocks will be read. This can be useful
+when postprocessing the output.
+
@item --macro-expand=@var{file}
@itemx -E @var{file}
+@opindex --macro-expand=@var{file}
+@opindex -E @var{file}
Output the Texinfo source with all the macros expanded to the named
file. Normally, the results of macro expansion are used internally by
@code{makeinfo} and then discarded. This option is used by
@@ -14046,11 +14205,26 @@ distribution (as in an @file{INSTALL} file).
For HTML output, likewise omit menus. And if @samp{--no-split} is also
specified, do not include a navigation links at the top of each node
(these are never included in the default case of split output).
-@xref{makeinfo html}.
+@xref{Generating HTML}.
In both cases, write to standard output by default (can still be
overridden by @option{-o}).
+@item --no-ifhtml
+@itemx --no-ifinfo
+@itemx --no-ifplaintext
+@itemx --no-iftex
+@itemx --no-ifxml
+@opindex --no-ifhtml
+@opindex --no-ifinfo
+@opindex --no-ifplaintext
+@opindex --no-iftex
+@opindex --no-ifxml
+Do not process @samp{@@if@var{format}} and @samp{@@@var{format}}
+commands even if generating the given format. For instance, if
+@option{--no-ifhtml} is specified, then @samp{@@ifhtml} and
+@samp{@@html} blocks will not be read.
+
@item --no-split
@opindex --no-split
@cindex Splitting of output files
@@ -14058,7 +14232,7 @@ overridden by @option{-o}).
Suppress the splitting stage of @code{makeinfo}. By default, large
output files (where the size is greater than 70k bytes) are split into
smaller subfiles. For Info output, each one is approximately 50k bytes.
-For HTML output, each file contains one node (@pxref{makeinfo html}).
+For HTML output, each file contains one node (@pxref{Generating HTML}).
@item --no-pointer-validate
@itemx --no-validate
@@ -14097,7 +14271,7 @@ 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 for the directory into which all
-HTML nodes are written (@pxref{makeinfo html}).
+HTML nodes are written (@pxref{Generating HTML}).
@item -P @var{dir}
@opindex -P @var{dir}
@@ -14134,6 +14308,10 @@ Set the value of the number of references to a node that
than this number of references in it, @code{makeinfo} will make the
references but also report a warning. The default is 1000.
+@item --split-size=@var{num}
+@opindex --split-size=@var{num}
+Keep Info files to at most @var{num} characters; default is 50,000.
+
@item -U @var{var}
Cause @var{var} to be undefined. This is equivalent to
@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
@@ -14248,7 +14426,7 @@ option is given.
@node makeinfo in Emacs
-@subsection Running @code{makeinfo} inside Emacs
+@subsection Running @code{makeinfo} Within Emacs
@cindex Running @code{makeinfo} in Emacs
@cindex @code{makeinfo} inside Emacs
@cindex Shell, running @code{makeinfo} in
@@ -14270,11 +14448,9 @@ Format the current buffer for Info.@refill
@findex makeinfo-buffer
@end table
-When you invoke either @code{makeinfo-region} or
-@code{makeinfo-buffer}, Emacs prompts for a file name, offering the
-name of the visited file as the default. You can edit the default
-file name in the minibuffer if you wish, before pressing @key{RET} to
-start the @code{makeinfo} process.@refill
+When you invoke @code{makeinfo-region} the output goes to a temporary
+buffer. When you invoke @code{makeinfo-buffer} output goes to the
+file set with @code{@@setfilename} (@pxref{setfilename}).
The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
run the @code{makeinfo} program in a temporary shell buffer. If
@@ -14324,8 +14500,8 @@ For example, you could write the following in your @file{.emacs} file:@refill
@example
@group
(setq makeinfo-options
- "--paragraph-indent=0 --no-split
- --fill-column=70 --verbose")
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
@end group
@end example
@@ -14505,7 +14681,7 @@ validate the structure of the nodes, see @ref{Using
Info-validate}.@refill
-@node makeinfo html
+@node Generating HTML
@subsection Generating HTML
@cindex HTML
@@ -14534,7 +14710,8 @@ Texinfo input marked up with the @code{@@ifhtml} command will produce
output only with the @samp{--html} option supplied. Input marked up
with the @code{@@html} is passed literally to the output (suppressing
the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
-which have special significance in HTML).
+which have special significance in HTML). Similarly for the
+@option{--xml} option and @code{@@ifxml} and @code{@@xml} sections.
The @samp{--footnote-style} option is currently ignored for HTML output;
footnotes are linked to the end of the output file.
@@ -14571,9 +14748,9 @@ into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
* Directory File:: The top level menu for all Info files.
* New Info File:: Listing a new Info file.
* Other Info Directories:: How to specify Info files that are
- located in other directories.
+ located in other directories.
* Installing Dir Entries:: How to specify what menu entry to add
- to the Info directory.
+ to the Info directory.
* Invoking install-info:: @code{install-info} options.
@end menu
@@ -14596,10 +14773,10 @@ this:@refill
* Menu:
* Info: (info). Documentation browsing system.
* Emacs: (emacs). The extensible, self-documenting
- text editor.
+ text editor.
* Texinfo: (texinfo). With one source file, make
- either a printed manual using
- @@TeX@{@} or an Info file.
+ either a printed manual using
+ @@TeX@{@} or an Info file.
@dots{}
@end group
@end example
@@ -14712,8 +14889,8 @@ Alternatively, you could write the following in your @file{.emacs} file:
@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
@@ -14850,26 +15027,33 @@ 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:
-
+@cindex Free Software Directory
+@cindex Dir categories, choosing
+@cindex Categories, choosing
+When choosing the categories for @code{@@dircategory}, we recommend
+consulting the @uref{Free Sofware Directory,
+http://www.gnu.org/directory}. If your program is not listed there, or
+listed incorrectly or incompletely, please report the situation to the
+directory maintainers (@email{bug-directory@@gnu.org}) so that the
+category names can be kept in sync.
+
+Here are a few examples:
@display
-GNU packages
-GNU programming tools
-GNU programming documentation
-GNU Emacs Lisp
-GNU libraries
-TeX
-Individual utilities
+Emacs
+Localization
+Printing
+Software Libraries
@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.
+@cindex Invoking nodes, including in dir file
+Each `Invoking' node for every program installed should have a
+corresponding @code{@@direntry}. This lets users easily find the
+documentation for the different programs they can run, as with the
+traditional @command{man} system.
@node Invoking install-info
-@subsection Invoking install-info
-
+@subsection Invoking @command{install-info}
@pindex install-info
@code{install-info} inserts menu entries from an Info file into the
@@ -14975,7 +15159,7 @@ information in the Info file itself.
@itemx -V
@opindex --version
@opindex -V
-@cindex version number, finding
+@cindex version number, for install-info
Display version information and exit successfully.
@end table
@@ -15210,8 +15394,7 @@ menus instead. @xref{Contents, , Generating a Table of
Contents}.@refill
@item @@copyright@{@}
-Generate a copyright symbol. @xref{copyright symbol, ,
-@code{@@copyright}}.@refill
+Generate a copyright symbol. @xref{copyright symbol,, @code{@@copyright@{@}}}.
@ignore
@item @@ctrl@{@var{ctrl-char}@}
@@ -15560,13 +15743,13 @@ resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
@itemx @@ifnotinfo
@itemx @@ifnotplaintext
@itemx @@ifnottex
+@itemx @@ifnotxml
Begin a stretch of text that will be ignored in one output format but
not the others. The text appears in the formats not specified:
@code{@@ifnothtml} text is omitted from html output, etc. The exception
is @code{@@ifnotinfo} text, which is omitted from plain text output as
-well as Info output. Pair with @code{@@end ifnothtml} resp.@:
-@code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
-@code{@@end ifnottex}. @xref{Conditionals}.
+well as Info output. Pair with the corresponding @code{@@end
+ifnot@var{format}}. @xref{Conditionals}.
@item @@ifplaintext
Begin a stretch of text that appears only in the plain text output.
@@ -15583,6 +15766,10 @@ Begin a stretch of text that will not appear in the Info file, but
will be processed only by @TeX{}. Pair with @code{@@end iftex}.
@xref{Conditionals, , Conditionally Visible Text}.@refill
+@item @@ifxml
+Begin a stretch of text that appears only in the XML output.
+Pair with @code{@@end ifxml}. @xref{Conditionals}.
+
@item @@ignore
Begin a stretch of text that will not appear in either the Info file
or the printed output. Pair with @code{@@end ignore}.
@@ -15977,6 +16164,10 @@ only, the filename, the current page number, and the title of the
document, respectively. @xref{Custom Headings, , How to Make Your Own
Headings}.@refill
+@item @@tie@{@}
+Generate a normal interword space at which a line break is not allowed.
+@xref{tie,, @code{@@tie@{@}}}.
+
@item @@tieaccent@{@var{cc}@}
Generate a tie-after accent over the next two characters @var{cc}, as in
`@tieaccent{oo}'. @xref{Inserting Accents}.
@@ -16323,11 +16514,11 @@ For example, @TeX{} fills the following:
@example
@group
- @@kbd@{C-x v@}
- @@kbd@{M-x vc-next-action@}
- Perform the next logical operation
- on the version-controlled file
- corresponding to the current buffer.
+ @@kbd@{C-x v@}
+ @@kbd@{M-x vc-next-action@}
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
@end group
@end example
@@ -16337,10 +16528,10 @@ so it looks like this:
@iftex
@quotation
- @kbd{C-x v}
- @kbd{M-x vc-next-action}
- Perform the next logical operation on the version-controlled file
- corresponding to the current buffer.
+ @kbd{C-x v}
+ @kbd{M-x vc-next-action}
+ Perform the next logical operation on the version-controlled file
+ corresponding to the current buffer.
@end quotation
@end iftex
@ifinfo
@@ -16531,12 +16722,14 @@ Write notes for yourself at the very end of a Texinfo file after the
@cindex Sample Texinfo files
The first example is from the first chapter (@pxref{Short Sample}),
-given here in its entirety, without commentary. The second sample
+given here in its entirety, without commentary. The second
includes the full texts to be used in GNU manuals.
@menu
* Short Sample Texinfo File::
* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
@end menu
@@ -16564,7 +16757,7 @@ it for a printed manual.
@@copying
This is a short example of a complete Texinfo file.
-Copyright (C) 2002 Free Software Foundation, Inc.
+Copyright (C) 2003 Free Software Foundation, Inc.
@@end copying
@@titlepage
@@ -16579,13 +16772,14 @@ Copyright (C) 2002 Free Software Foundation, Inc.
@@ifnottex
@@node Top
+@@top GNU Sample
@@insertcopying
@@end ifnottex
@@menu
* First Chapter:: The first chapter is the
- only chapter in this sample.
+ only chapter in this sample.
* Index:: Complete index.
@@end menu
@@ -16625,8 +16819,8 @@ This is the second item.
@cindex Sample texts, GNU
@cindex Full texts, GNU
-Here is a sample Texinfo document with the full texts that should be
-used in GNU manuals.
+Following is a sample Texinfo document with the full texts that should
+be used in GNU manuals.
As well as the legal texts, it also serves as a practical example of how
many elements in a GNU system can affect the manual. If you're not
@@ -16643,28 +16837,38 @@ Here are some notes on the example:
@itemize @bullet
@item
-@cindex $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ comment
-@cindex CVS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
-@cindex RCS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
-The @samp{$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $} comment is for CVS (@pxref{Top,, Overview, cvs,
+@cindex $Id:
+@cindex CVS $Id:
+@cindex RCS $Id:
+@cindex Documentation identification
+@cindex Identification of documentation
+The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
Concurrent Versions System}) or RCS (see rcsintro(1)) version control
systems, which expand it into a string such as:
@example
-$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
+$Id: texinfo.txi,v 1.29 2003/02/04 15:17:21 karl Exp $
@end example
(This is useful in all sources that use version control, not just manuals.)
+You may wish to include the @samp{$Id:} comment in the @code{@@copying}
+text, if you want a completely unambiguous reference to the
+documentation version.
@item
@pindex automake@r{, and version info}
+@vindex UPDATED @r{Automake variable}
+@vindex VERSION @r{Automake variable}
+@pindex time-stamp.el
The @file{version.texi} in the @code{@@include} command is maintained
automatically by Automake (@pxref{Top,, Introduction, automake, GNU
Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
-elsewhere. If your distribution doesn't use Automake, you can mimic
-these or equivalent settings.
+elsewhere. If your distribution doesn't use Automake, but you do use
+Emacs, you may find the time-stamp.el package helpful (@pxref{Time
+Stamps,,,emacs,The GNU Emacs Manual}).
@item
-The @code{@@syncodeindex} command reflects the recommendation to use only
-one index if at all possible, to make it easier for readers.
+The @code{@@syncodeindex} command reflects the recommendation to use
+only one index where possible, to make it easier for readers to look up
+index entries.
@item
The @code{@@dircategory} is for constructing the Info directory.
@@ -16677,12 +16881,14 @@ information about command-line usage of a given program. @xref{Manual
Structure Details,,,standards, GNU Coding Standards}.
@item
+@cindex GNU Free Documentation License, including entire
+@cindex Free Documentation License, including entire
It is best to include the entire GNU Free Documentation License in a GNU
manual, unless the manual is only a few pages long. Of course this
sample is even shorter than that, but it includes the FDL anyway in
-order to show one conventional way of doing so. The @file{fdl.texi}
-file is available on the GNU machines (and in the Texinfo and other GNU
-distributions).
+order to show one conventional way to do so. The @file{fdl.texi} file
+is available on the GNU machines and in the Texinfo and other GNU
+source distributions.
The FDL provides for omitting itself under certain conditions, but in
that case the sample texts given here have to be modified. @xref{GNU
@@ -16690,34 +16896,38 @@ Free Documentation License}.
@item
If your manual has invariant sections (again, see the license itself for
-details), then don't forget to include them.
+details), then don't forget to change the text here accordingly.
+
+@item
+For documents that express your personal views, feelings or experiences,
+it is more appropriate to use a license permitting only verbatim
+copying, rather than the FDL. @xref{Verbatim Copying License}.
+
@end itemize
Here is the sample document:
-@c We do the first part of this with @example instead of @verbatim
-@c because the literal @setfilename and @include confuse Automake. Argh.
-@example
-\input texinfo @@c -*-texinfo-*-
-@@comment $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
-@@comment %**start of header
-@@setfilename sample.info
-@@include version.texi
-@@settitle GNU Sample @@value@{VERSION@}
-@@syncodeindex pg cp
-@@comment %**end of header
-@@copying
+@verbatim
+\input texinfo @c -*-texinfo-*-
+@comment $Id: texinfo.txi,v 1.29 2003/02/04 15:17:21 karl Exp $
+@comment %**start of header
+@setfilename sample.info
+@include version.texi
+@settitle GNU Sample @value{VERSION}
+@syncodeindex pg cp
+@comment %**end of header
+@copying
This manual is for GNU Sample
-(version @@value@{VERSION@}, @@value@{UPDATED@}),
+(version @value{VERSION}, @value{UPDATED}),
which is an example in the Texinfo documentation.
-Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
+Copyright @copyright{} 2003 Free Software Foundation, Inc.
-@@quotation
+@quotation
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,''
+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.''
@@ -16725,66 +16935,127 @@ License.''
(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.''
-@@end quotation
-@@end copying
+@end quotation
+@end copying
-@@dircategory Texinfo documentation system
-@@direntry
+@dircategory Texinfo documentation system
+@direntry
* sample: (sample)Invoking sample.
-@@end direntry
+@end direntry
-@@titlepage
-@@title GNU Sample
-@@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
-@@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
-@@end titlepage
+@titlepage
+@title GNU Sample
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author A.U. Thor (@email{bug-texinfo@@gnu.org})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
-@@contents
+@contents
-@@ifnottex
-@@node Top
-@@top GNU Sample
+@ifnottex
+@node Top
+@top GNU Sample
-@@insertcopying
-@@end ifnottex
+@insertcopying
+@end ifnottex
-@@menu
+@menu
* Invoking sample::
* Copying This Manual::
* Index::
-@@end menu
+@end menu
-@@node Invoking sample
-@@chapter Invoking sample
+@node Invoking sample
+@chapter Invoking sample
-@@pindex sample
-@@cindex invoking @@command@{sample@}
+@pindex sample
+@cindex invoking @command{sample}
This is a sample manual. There is no sample program to
invoke, but if there was, you could see its basic usage
and command line options here.
-@@node Copying This Manual
-@@appendix Copying This Manual
+@node Copying This Manual
+@appendix Copying This Manual
-@@menu
+@menu
* GNU Free Documentation License:: License for copying this manual.
-@@end menu
+@end menu
-@@include fdl.texi
+@include fdl.texi
-@@node Index
-@@unnumbered Index
+@node Index
+@unnumbered Index
-@@printindex cp
+@printindex cp
-@@bye
+@bye
+@end verbatim
+
+
+@node Verbatim Copying License
+@section Verbatim Copying License
+
+@cindex Verbatim copying license
+@cindex License for verbatim copying
+
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+On the other hand, for documents that express your personal views,
+feelings or experiences, it is more appropriate to use a license
+permitting only verbatim copying.
+
+Here is sample text for such a license permitting verbatim copying only.
+This is just the license text itself. For a complete sample document,
+see the previous sections.
+
+@verbatim
+@copying
+This document is a sample for allowing verbatim copying only.
+
+Copyright @copyright{} 2003 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to make and distribute verbatim copies
+of this entire document without royalty provided the
+copyright notice and this permission notice are preserved.
+@end quotation
+@end copying
+@end verbatim
+
+
+@node All-permissive Copying License
+@section All-permissive Copying License
+
+@cindex All-permissive copying license
+@cindex License for all-permissive copying
+
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+On the other hand, for small supporting files, short manuals (under 300
+lines long) and rough documentation (README files, INSTALL files, etc.),
+the full FDL would be overkill. They can use a simple all-permissive
+license.
+
+Here is sample text for such an all-permissive license. This is just
+the license text itself. For a complete sample document, see the
+previous sections.
+
+@example
+Copyright @copyright{} 2003 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
@end example
@@ -16804,27 +17075,32 @@ conveniently small parts.
@menu
* Using Include Files:: How to use the @code{@@include} command.
* texinfo-multiple-files-update:: How to create and update nodes and
- menus when using included files.
-* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
+ menus when using included files.
+* Include Files Requirements:: What @code{texinfo-multiple-files-update} expects.
* Sample Include File:: A sample outer file with included files
- within it; and a sample included file.
+ within it; and a sample included file.
* Include Files Evolution:: How use of the @code{@@include} command
- has changed over time.
+ has changed over time.
@end menu
-@node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
+@node Using Include Files
@section How to Use Include Files
@findex include
To include another file within a Texinfo file, write the
@code{@@include} command at the beginning of a line and follow it on
-the same line by the name of a file to be included. For
-example:@refill
+the same line by the name of a file to be included. For example:
@example
@@include buffers.texi
@end example
+The name of the file is taken literally, with a single exception:
+@code{@@value@{@var{var}@}} references are expanded. This makes it
+possible to reliably include files in other directories in a
+distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
+an example.
+
An included file should simply be a segment of text that you expect to
be included as is into the overall or @dfn{outer} Texinfo file; it
should not contain the standard beginning and end parts of a Texinfo
@@ -16832,7 +17108,7 @@ file. In particular, you should not start an included file with a
line saying @samp{\input texinfo}; if you do, that phrase is inserted
into the output file as is. Likewise, you should not end an included
file with an @code{@@bye} command; nothing after @code{@@bye} is
-formatted.@refill
+formatted.
In the past, you were required to write an @code{@@setfilename} line at the
beginning of an included file, but no longer. Now, it does not matter
@@ -16853,7 +17129,8 @@ whole file. Either you must insert the menus and the `Next',
Texinfo mode command, @code{texinfo-multiple-files-update}, that is
designed for @code{@@include} files.@refill
-@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
+
+@node texinfo-multiple-files-update
@section @code{texinfo-multiple-files-update}
@findex texinfo-multiple-files-update
@@ -16930,9 +17207,9 @@ updates @strong{every} pointer and menu in @strong{all} the files and then inser
master menu.@refill
-@node Include File Requirements
-@section Include File Requirements
-@cindex Include file requirements
+@node Include Files Requirements
+@section Include Files Requirements
+@cindex Include files requirements
@cindex Requirements for include files
If you plan to use the @code{texinfo-multiple-files-update} command,
@@ -16956,58 +17233,40 @@ should @emph{not} contain any nodes besides the single `Top' node. The
@code{texinfo-multiple-files-update} command will not process
them.@refill
-@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
+
+@node Sample Include File
@section Sample File with @code{@@include}
@cindex Sample @code{@@include} file
@cindex Include file sample
@cindex @code{@@include} file sample
-Here is an example of a complete outer Texinfo file with @code{@@include} files
+Here is an example of an outer Texinfo file with @code{@@include} files
within it before running @code{texinfo-multiple-files-update}, which
-would insert a main or master menu:@refill
+would insert a main or master menu:
@example
@group
\input texinfo @@c -*-texinfo-*-
@c %**start of header
-@@setfilename include-example.info
+@@setfilename include-example.info
@@settitle Include Example
@c %**end of header
@end group
-@group
-@@setchapternewpage odd
-@@titlepage
-@@sp 12
-@@center @@titlefont@{Include Example@}
-@@sp 2
-@@center by Whom Ever
-@end group
-
-@group
-@@page
-@@vskip 0pt plus 1filll
-Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
-@@end titlepage
-@end group
+... @xref{Sample Texinfo Files}, for
+examples of the rest of the frontmatter ...
@group
-@@ifinfo
-@@node Top, First, , (dir)
-@@top Master Menu
-@@end ifinfo
+@@ifnottex
+@@node Top
+@@top Include Example
+@@end ifnottex
@end group
@group
@@include foo.texinfo
@@include bar.texinfo
@@include concept-index.texinfo
-@end group
-
-@group
-@@summarycontents
-@@contents
-
@@bye
@end group
@end example
@@ -17016,7 +17275,7 @@ An included file, such as @file{foo.texinfo}, might look like this:
@example
@group
-@@node First, Second, , Top
+@@node First
@@chapter First Chapter
Contents of first chapter @dots{}
@@ -17037,7 +17296,7 @@ The full contents of @file{concept-index.texinfo} might be as simple as this:
The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
Manual} is named @file{elisp.texi}. This outer file contains a master
menu with 417 entries and a list of 41 @code{@@include}
-files.@refill
+files.
@node Include Files Evolution
@@ -17158,13 +17417,13 @@ A single-sided page looks like this:
@example
@group
- _______________________
- | |
- | chapter page number |
- | |
- | Start of text ... |
- | ... |
- | |
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
@end group
@end example
@@ -17190,13 +17449,13 @@ Two pages, side by side as in an open book, look like this:@refill
@example
@group
- _______________________ _______________________
- | | | |
- | page number title | | chapter page number |
- | | | |
- | Start of text ... | | More text ... |
- | ... | | ... |
- | | | |
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
@end group
@end example
@@ -17484,10 +17743,10 @@ occurs, or not long after it. The buffer will look like this:@refill
* Menu:
* Using texinfo-show-structure:: How to use
- `texinfo-show-structure'
- to catch mistakes.
+ `texinfo-show-structure'
+ to catch mistakes.
* Running Info-Validate:: How to check for
- unreferenced nodes.
+ unreferenced nodes.
@@end menus
@point{}
---------- Buffer: *Info Region* ----------
@@ -17599,21 +17858,21 @@ invoked the debugger. This is the backtrace it produced:@refill
@example
---------- Buffer: *Backtrace* ----------
Signalling: (search-failed "[@},]")
- re-search-forward("[@},]")
- (while ...)
- (let ...)
- texinfo-format-parse-args()
- (let ...)
- texinfo-format-xref()
- funcall(texinfo-format-xref)
- (if ...)
- (let ...)
- (if ...)
- (while ...)
- texinfo-format-scan()
- (save-excursion ...)
- (let ...)
- texinfo-format-region(103370 103631)
+ re-search-forward("[@},]")
+ (while ...)
+ (let ...)
+ texinfo-format-parse-args()
+ (let ...)
+ texinfo-format-xref()
+ funcall(texinfo-format-xref)
+ (if ...)
+ (let ...)
+ (if ...)
+ (while ...)
+ texinfo-format-scan()
+ (save-excursion ...)
+ (let ...)
+ texinfo-format-region(103370 103631)
* call-interactively(texinfo-format-region)
---------- Buffer: *Backtrace* ----------
@end example
@@ -17668,7 +17927,7 @@ Runaway argument?
indices.) @@refill @@ETC.
! Paragraph ended before @@xref was complete.
<to be read again>
- @@par
+ @@par
l.27
?
@@ -17784,18 +18043,18 @@ produced by running @code{texinfo-show-structure} on this manual:@refill
@example
@group
- Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
- unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
- in buffer texinfo.texi.
- @dots{}
- 4177:@@chapter Nodes
- 4198: @@heading Two Paths
- 4231: @@section Node and Menu Illustration
- 4337: @@section The @@code@{@@@@node@} Command
- 4393: @@subheading Choosing Node and Pointer Names
- 4417: @@subsection How to Write an @@code@{@@@@node@} Line
- 4469: @@subsection @@code@{@@@@node@} Line Tips
- @dots{}
+Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
+unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+in buffer texinfo.texi.
+@dots{}
+4177:@@chapter Nodes
+4198: @@heading Two Paths
+4231: @@section Node and Menu Illustration
+4337: @@section The @@code@{@@@@node@} Command
+4393: @@subheading Choosing Node and Pointer Names
+4417: @@subsection How to Write an @@code@{@@@@node@} Line
+4469: @@subsection @@code@{@@@@node@} Line Tips
+@dots{}
@end group
@end example
@@ -18591,7 +18850,7 @@ For an example of Lisp code.
@item @@smallexample
@itemx @@smalllisp
-Like @@table and @@lisp @r{but for} @@smallbook.
+Like @@table and @@lisp, but for (originally) @@smallbook.
@end table
@c subheading Conditionals
diff --git a/contrib/texinfo/doc/version-stnd.texi b/contrib/texinfo/doc/version-stnd.texi
index cbc67f4..d706a46 100644
--- a/contrib/texinfo/doc/version-stnd.texi
+++ b/contrib/texinfo/doc/version-stnd.texi
@@ -1,4 +1,4 @@
-@set UPDATED 23 March 2002
-@set UPDATED-MONTH March 2002
-@set EDITION 4.2
-@set VERSION 4.2
+@set UPDATED 5 November 2002
+@set UPDATED-MONTH November 2002
+@set EDITION 4.5
+@set VERSION 4.5
diff --git a/contrib/texinfo/doc/version.texi b/contrib/texinfo/doc/version.texi
index c21b39a..90655a9 100644
--- a/contrib/texinfo/doc/version.texi
+++ b/contrib/texinfo/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 28 March 2002
-@set UPDATED-MONTH March 2002
-@set EDITION 4.2
-@set VERSION 4.2
+@set UPDATED 4 February 2003
+@set UPDATED-MONTH February 2003
+@set EDITION 4.5
+@set VERSION 4.5
OpenPOWER on IntegriCloud