Commit upstream/6.7.0.dfsg.2 - texinfo

New upstream version 6.7.0.dfsg.2 Norbert Preining 4 years ago

3 changed file(s) with 27212 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all

+505

-0

doc/fdl.texi less more

	0	@c The GNU Free Documentation License.
	1	@center Version 1.3, 3 November 2008
	2
	3	@c This file is intended to be included within another document,
	4	@c hence no sectioning command or @node.
	5
	6	@display
	7	Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
	8	@uref{https://fsf.org/}
	9
	10	Everyone is permitted to copy and distribute verbatim copies
	11	of this license document, but changing it is not allowed.
	12	@end display
	13
	14	@enumerate 0
	15	@item
	16	PREAMBLE
	17
	18	The purpose of this License is to make a manual, textbook, or other
	19	functional and useful document @dfn{free} in the sense of freedom: to
	20	assure everyone the effective freedom to copy and redistribute it,
	21	with or without modifying it, either commercially or noncommercially.
	22	Secondarily, this License preserves for the author and publisher a way
	23	to get credit for their work, while not being considered responsible
	24	for modifications made by others.
	25
	26	This License is a kind of ``copyleft'', which means that derivative
	27	works of the document must themselves be free in the same sense. It
	28	complements the GNU General Public License, which is a copyleft
	29	license designed for free software.
	30
	31	We have designed this License in order to use it for manuals for free
	32	software, because free software needs free documentation: a free
	33	program should come with manuals providing the same freedoms that the
	34	software does. But this License is not limited to software manuals;
	35	it can be used for any textual work, regardless of subject matter or
	36	whether it is published as a printed book. We recommend this License
	37	principally for works whose purpose is instruction or reference.
	38
	39	@item
	40	APPLICABILITY AND DEFINITIONS
	41
	42	This License applies to any manual or other work, in any medium, that
	43	contains a notice placed by the copyright holder saying it can be
	44	distributed under the terms of this License. Such a notice grants a
	45	world-wide, royalty-free license, unlimited in duration, to use that
	46	work under the conditions stated herein. The ``Document'', below,
	47	refers to any such manual or work. Any member of the public is a
	48	licensee, and is addressed as ``you''. You accept the license if you
	49	copy, modify or distribute the work in a way requiring permission
	50	under copyright law.
	51
	52	A ``Modified Version'' of the Document means any work containing the
	53	Document or a portion of it, either copied verbatim, or with
	54	modifications and/or translated into another language.
	55
	56	A ``Secondary Section'' is a named appendix or a front-matter section
	57	of the Document that deals exclusively with the relationship of the
	58	publishers or authors of the Document to the Document's overall
	59	subject (or to related matters) and contains nothing that could fall
	60	directly within that overall subject. (Thus, if the Document is in
	61	part a textbook of mathematics, a Secondary Section may not explain
	62	any mathematics.) The relationship could be a matter of historical
	63	connection with the subject or with related matters, or of legal,
	64	commercial, philosophical, ethical or political position regarding
	65	them.
	66
	67	The ``Invariant Sections'' are certain Secondary Sections whose titles
	68	are designated, as being those of Invariant Sections, in the notice
	69	that says that the Document is released under this License. If a
	70	section does not fit the above definition of Secondary then it is not
	71	allowed to be designated as Invariant. The Document may contain zero
	72	Invariant Sections. If the Document does not identify any Invariant
	73	Sections then there are none.
	74
	75	The ``Cover Texts'' are certain short passages of text that are listed,
	76	as Front-Cover Texts or Back-Cover Texts, in the notice that says that
	77	the Document is released under this License. A Front-Cover Text may
	78	be at most 5 words, and a Back-Cover Text may be at most 25 words.
	79
	80	A ``Transparent'' copy of the Document means a machine-readable copy,
	81	represented in a format whose specification is available to the
	82	general public, that is suitable for revising the document
	83	straightforwardly with generic text editors or (for images composed of
	84	pixels) generic paint programs or (for drawings) some widely available
	85	drawing editor, and that is suitable for input to text formatters or
	86	for automatic translation to a variety of formats suitable for input
	87	to text formatters. A copy made in an otherwise Transparent file
	88	format whose markup, or absence of markup, has been arranged to thwart
	89	or discourage subsequent modification by readers is not Transparent.
	90	An image format is not Transparent if used for any substantial amount
	91	of text. A copy that is not ``Transparent'' is called ``Opaque''.
	92
	93	Examples of suitable formats for Transparent copies include plain
	94	ASCII without markup, Texinfo input format, La@TeX{} input
	95	format, SGML or XML using a publicly available
	96	DTD, and standard-conforming simple HTML,
	97	PostScript or PDF designed for human modification. Examples
	98	of transparent image formats include PNG, XCF and
	99	JPG@. Opaque formats include proprietary formats that can be
	100	read and edited only by proprietary word processors, SGML or
	101	XML for which the DTD and/or processing tools are
	102	not generally available, and the machine-generated HTML,
	103	PostScript or PDF produced by some word processors for
	104	output purposes only.
	105
	106	The ``Title Page'' means, for a printed book, the title page itself,
	107	plus such following pages as are needed to hold, legibly, the material
	108	this License requires to appear in the title page. For works in
	109	formats which do not have any title page as such, ``Title Page'' means
	110	the text near the most prominent appearance of the work's title,
	111	preceding the beginning of the body of the text.
	112
	113	The ``publisher'' means any person or entity that distributes copies
	114	of the Document to the public.
	115
	116	A section ``Entitled XYZ'' means a named subunit of the Document whose
	117	title either is precisely XYZ or contains XYZ in parentheses following
	118	text that translates XYZ in another language. (Here XYZ stands for a
	119	specific section name mentioned below, such as ``Acknowledgements'',
	120	``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
	121	of such a section when you modify the Document means that it remains a
	122	section ``Entitled XYZ'' according to this definition.
	123
	124	The Document may include Warranty Disclaimers next to the notice which
	125	states that this License applies to the Document. These Warranty
	126	Disclaimers are considered to be included by reference in this
	127	License, but only as regards disclaiming warranties: any other
	128	implication that these Warranty Disclaimers may have is void and has
	129	no effect on the meaning of this License.
	130
	131	@item
	132	VERBATIM COPYING
	133
	134	You may copy and distribute the Document in any medium, either
	135	commercially or noncommercially, provided that this License, the
	136	copyright notices, and the license notice saying this License applies
	137	to the Document are reproduced in all copies, and that you add no other
	138	conditions whatsoever to those of this License. You may not use
	139	technical measures to obstruct or control the reading or further
	140	copying of the copies you make or distribute. However, you may accept
	141	compensation in exchange for copies. If you distribute a large enough
	142	number of copies you must also follow the conditions in section 3.
	143
	144	You may also lend copies, under the same conditions stated above, and
	145	you may publicly display copies.
	146
	147	@item
	148	COPYING IN QUANTITY
	149
	150	If you publish printed copies (or copies in media that commonly have
	151	printed covers) of the Document, numbering more than 100, and the
	152	Document's license notice requires Cover Texts, you must enclose the
	153	copies in covers that carry, clearly and legibly, all these Cover
	154	Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
	155	the back cover. Both covers must also clearly and legibly identify
	156	you as the publisher of these copies. The front cover must present
	157	the full title with all words of the title equally prominent and
	158	visible. You may add other material on the covers in addition.
	159	Copying with changes limited to the covers, as long as they preserve
	160	the title of the Document and satisfy these conditions, can be treated
	161	as verbatim copying in other respects.
	162
	163	If the required texts for either cover are too voluminous to fit
	164	legibly, you should put the first ones listed (as many as fit
	165	reasonably) on the actual cover, and continue the rest onto adjacent
	166	pages.
	167
	168	If you publish or distribute Opaque copies of the Document numbering
	169	more than 100, you must either include a machine-readable Transparent
	170	copy along with each Opaque copy, or state in or with each Opaque copy
	171	a computer-network location from which the general network-using
	172	public has access to download using public-standard network protocols
	173	a complete Transparent copy of the Document, free of added material.
	174	If you use the latter option, you must take reasonably prudent steps,
	175	when you begin distribution of Opaque copies in quantity, to ensure
	176	that this Transparent copy will remain thus accessible at the stated
	177	location until at least one year after the last time you distribute an
	178	Opaque copy (directly or through your agents or retailers) of that
	179	edition to the public.
	180
	181	It is requested, but not required, that you contact the authors of the
	182	Document well before redistributing any large number of copies, to give
	183	them a chance to provide you with an updated version of the Document.
	184
	185	@item
	186	MODIFICATIONS
	187
	188	You may copy and distribute a Modified Version of the Document under
	189	the conditions of sections 2 and 3 above, provided that you release
	190	the Modified Version under precisely this License, with the Modified
	191	Version filling the role of the Document, thus licensing distribution
	192	and modification of the Modified Version to whoever possesses a copy
	193	of it. In addition, you must do these things in the Modified Version:
	194
	195	@enumerate A
	196	@item
	197	Use in the Title Page (and on the covers, if any) a title distinct
	198	from that of the Document, and from those of previous versions
	199	(which should, if there were any, be listed in the History section
	200	of the Document). You may use the same title as a previous version
	201	if the original publisher of that version gives permission.
	202
	203	@item
	204	List on the Title Page, as authors, one or more persons or entities
	205	responsible for authorship of the modifications in the Modified
	206	Version, together with at least five of the principal authors of the
	207	Document (all of its principal authors, if it has fewer than five),
	208	unless they release you from this requirement.
	209
	210	@item
	211	State on the Title page the name of the publisher of the
	212	Modified Version, as the publisher.
	213
	214	@item
	215	Preserve all the copyright notices of the Document.
	216
	217	@item
	218	Add an appropriate copyright notice for your modifications
	219	adjacent to the other copyright notices.
	220
	221	@item
	222	Include, immediately after the copyright notices, a license notice
	223	giving the public permission to use the Modified Version under the
	224	terms of this License, in the form shown in the Addendum below.
	225
	226	@item
	227	Preserve in that license notice the full lists of Invariant Sections
	228	and required Cover Texts given in the Document's license notice.
	229
	230	@item
	231	Include an unaltered copy of this License.
	232
	233	@item
	234	Preserve the section Entitled ``History'', Preserve its Title, and add
	235	to it an item stating at least the title, year, new authors, and
	236	publisher of the Modified Version as given on the Title Page. If
	237	there is no section Entitled ``History'' in the Document, create one
	238	stating the title, year, authors, and publisher of the Document as
	239	given on its Title Page, then add an item describing the Modified
	240	Version as stated in the previous sentence.
	241
	242	@item
	243	Preserve the network location, if any, given in the Document for
	244	public access to a Transparent copy of the Document, and likewise
	245	the network locations given in the Document for previous versions
	246	it was based on. These may be placed in the ``History'' section.
	247	You may omit a network location for a work that was published at
	248	least four years before the Document itself, or if the original
	249	publisher of the version it refers to gives permission.
	250
	251	@item
	252	For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
	253	the Title of the section, and preserve in the section all the
	254	substance and tone of each of the contributor acknowledgements and/or
	255	dedications given therein.
	256
	257	@item
	258	Preserve all the Invariant Sections of the Document,
	259	unaltered in their text and in their titles. Section numbers
	260	or the equivalent are not considered part of the section titles.
	261
	262	@item
	263	Delete any section Entitled ``Endorsements''. Such a section
	264	may not be included in the Modified Version.
	265
	266	@item
	267	Do not retitle any existing section to be Entitled ``Endorsements'' or
	268	to conflict in title with any Invariant Section.
	269
	270	@item
	271	Preserve any Warranty Disclaimers.
	272	@end enumerate
	273
	274	If the Modified Version includes new front-matter sections or
	275	appendices that qualify as Secondary Sections and contain no material
	276	copied from the Document, you may at your option designate some or all
	277	of these sections as invariant. To do this, add their titles to the
	278	list of Invariant Sections in the Modified Version's license notice.
	279	These titles must be distinct from any other section titles.
	280
	281	You may add a section Entitled ``Endorsements'', provided it contains
	282	nothing but endorsements of your Modified Version by various
	283	parties---for example, statements of peer review or that the text has
	284	been approved by an organization as the authoritative definition of a
	285	standard.
	286
	287	You may add a passage of up to five words as a Front-Cover Text, and a
	288	passage of up to 25 words as a Back-Cover Text, to the end of the list
	289	of Cover Texts in the Modified Version. Only one passage of
	290	Front-Cover Text and one of Back-Cover Text may be added by (or
	291	through arrangements made by) any one entity. If the Document already
	292	includes a cover text for the same cover, previously added by you or
	293	by arrangement made by the same entity you are acting on behalf of,
	294	you may not add another; but you may replace the old one, on explicit
	295	permission from the previous publisher that added the old one.
	296
	297	The author(s) and publisher(s) of the Document do not by this License
	298	give permission to use their names for publicity for or to assert or
	299	imply endorsement of any Modified Version.
	300
	301	@item
	302	COMBINING DOCUMENTS
	303
	304	You may combine the Document with other documents released under this
	305	License, under the terms defined in section 4 above for modified
	306	versions, provided that you include in the combination all of the
	307	Invariant Sections of all of the original documents, unmodified, and
	308	list them all as Invariant Sections of your combined work in its
	309	license notice, and that you preserve all their Warranty Disclaimers.
	310
	311	The combined work need only contain one copy of this License, and
	312	multiple identical Invariant Sections may be replaced with a single
	313	copy. If there are multiple Invariant Sections with the same name but
	314	different contents, make the title of each such section unique by
	315	adding at the end of it, in parentheses, the name of the original
	316	author or publisher of that section if known, or else a unique number.
	317	Make the same adjustment to the section titles in the list of
	318	Invariant Sections in the license notice of the combined work.
	319
	320	In the combination, you must combine any sections Entitled ``History''
	321	in the various original documents, forming one section Entitled
	322	``History''; likewise combine any sections Entitled ``Acknowledgements'',
	323	and any sections Entitled ``Dedications''. You must delete all
	324	sections Entitled ``Endorsements.''
	325
	326	@item
	327	COLLECTIONS OF DOCUMENTS
	328
	329	You may make a collection consisting of the Document and other documents
	330	released under this License, and replace the individual copies of this
	331	License in the various documents with a single copy that is included in
	332	the collection, provided that you follow the rules of this License for
	333	verbatim copying of each of the documents in all other respects.
	334
	335	You may extract a single document from such a collection, and distribute
	336	it individually under this License, provided you insert a copy of this
	337	License into the extracted document, and follow this License in all
	338	other respects regarding verbatim copying of that document.
	339
	340	@item
	341	AGGREGATION WITH INDEPENDENT WORKS
	342
	343	A compilation of the Document or its derivatives with other separate
	344	and independent documents or works, in or on a volume of a storage or
	345	distribution medium, is called an ``aggregate'' if the copyright
	346	resulting from the compilation is not used to limit the legal rights
	347	of the compilation's users beyond what the individual works permit.
	348	When the Document is included in an aggregate, this License does not
	349	apply to the other works in the aggregate which are not themselves
	350	derivative works of the Document.
	351
	352	If the Cover Text requirement of section 3 is applicable to these
	353	copies of the Document, then if the Document is less than one half of
	354	the entire aggregate, the Document's Cover Texts may be placed on
	355	covers that bracket the Document within the aggregate, or the
	356	electronic equivalent of covers if the Document is in electronic form.
	357	Otherwise they must appear on printed covers that bracket the whole
	358	aggregate.
	359
	360	@item
	361	TRANSLATION
	362
	363	Translation is considered a kind of modification, so you may
	364	distribute translations of the Document under the terms of section 4.
	365	Replacing Invariant Sections with translations requires special
	366	permission from their copyright holders, but you may include
	367	translations of some or all Invariant Sections in addition to the
	368	original versions of these Invariant Sections. You may include a
	369	translation of this License, and all the license notices in the
	370	Document, and any Warranty Disclaimers, provided that you also include
	371	the original English version of this License and the original versions
	372	of those notices and disclaimers. In case of a disagreement between
	373	the translation and the original version of this License or a notice
	374	or disclaimer, the original version will prevail.
	375
	376	If a section in the Document is Entitled ``Acknowledgements'',
	377	``Dedications'', or ``History'', the requirement (section 4) to Preserve
	378	its Title (section 1) will typically require changing the actual
	379	title.
	380
	381	@item
	382	TERMINATION
	383
	384	You may not copy, modify, sublicense, or distribute the Document
	385	except as expressly provided under this License. Any attempt
	386	otherwise to copy, modify, sublicense, or distribute it is void, and
	387	will automatically terminate your rights under this License.
	388
	389	However, if you cease all violation of this License, then your license
	390	from a particular copyright holder is reinstated (a) provisionally,
	391	unless and until the copyright holder explicitly and finally
	392	terminates your license, and (b) permanently, if the copyright holder
	393	fails to notify you of the violation by some reasonable means prior to
	394	60 days after the cessation.
	395
	396	Moreover, your license from a particular copyright holder is
	397	reinstated permanently if the copyright holder notifies you of the
	398	violation by some reasonable means, this is the first time you have
	399	received notice of violation of this License (for any work) from that
	400	copyright holder, and you cure the violation prior to 30 days after
	401	your receipt of the notice.
	402
	403	Termination of your rights under this section does not terminate the
	404	licenses of parties who have received copies or rights from you under
	405	this License. If your rights have been terminated and not permanently
	406	reinstated, receipt of a copy of some or all of the same material does
	407	not give you any rights to use it.
	408
	409	@item
	410	FUTURE REVISIONS OF THIS LICENSE
	411
	412	The Free Software Foundation may publish new, revised versions
	413	of the GNU Free Documentation License from time to time. Such new
	414	versions will be similar in spirit to the present version, but may
	415	differ in detail to address new problems or concerns. See
	416	@uref{https://www.gnu.org/copyleft/}.
	417
	418	Each version of the License is given a distinguishing version number.
	419	If the Document specifies that a particular numbered version of this
	420	License ``or any later version'' applies to it, you have the option of
	421	following the terms and conditions either of that specified version or
	422	of any later version that has been published (not as a draft) by the
	423	Free Software Foundation. If the Document does not specify a version
	424	number of this License, you may choose any version ever published (not
	425	as a draft) by the Free Software Foundation. If the Document
	426	specifies that a proxy can decide which future versions of this
	427	License can be used, that proxy's public statement of acceptance of a
	428	version permanently authorizes you to choose that version for the
	429	Document.
	430
	431	@item
	432	RELICENSING
	433
	434	``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
	435	World Wide Web server that publishes copyrightable works and also
	436	provides prominent facilities for anybody to edit those works. A
	437	public wiki that anybody can edit is an example of such a server. A
	438	``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
	439	site means any set of copyrightable works thus published on the MMC
	440	site.
	441
	442	``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
	443	license published by Creative Commons Corporation, a not-for-profit
	444	corporation with a principal place of business in San Francisco,
	445	California, as well as future copyleft versions of that license
	446	published by that same organization.
	447
	448	``Incorporate'' means to publish or republish a Document, in whole or
	449	in part, as part of another Document.
	450
	451	An MMC is ``eligible for relicensing'' if it is licensed under this
	452	License, and if all works that were first published under this License
	453	somewhere other than this MMC, and subsequently incorporated in whole
	454	or in part into the MMC, (1) had no cover texts or invariant sections,
	455	and (2) were thus incorporated prior to November 1, 2008.
	456
	457	The operator of an MMC Site may republish an MMC contained in the site
	458	under CC-BY-SA on the same site at any time before August 1, 2009,
	459	provided the MMC is eligible for relicensing.
	460
	461	@end enumerate
	462
	463	@page
	464	@heading ADDENDUM: How to use this License for your documents
	465
	466	To use this License in a document you have written, include a copy of
	467	the License in the document and put the following copyright and
	468	license notices just after the title page:
	469
	470	@smallexample
	471	@group
	472	Copyright (C) @var{year} @var{your name}.
	473	Permission is granted to copy, distribute and/or modify this document
	474	under the terms of the GNU Free Documentation License, Version 1.3
	475	or any later version published by the Free Software Foundation;
	476	with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
	477	Texts. A copy of the license is included in the section entitled ``GNU
	478	Free Documentation License''.
	479	@end group
	480	@end smallexample
	481
	482	If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
	483	replace the ``with@dots{}Texts.''@: line with this:
	484
	485	@smallexample
	486	@group
	487	with the Invariant Sections being @var{list their titles}, with
	488	the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
	489	being @var{list}.
	490	@end group
	491	@end smallexample
	492
	493	If you have Invariant Sections without Cover Texts, or some other
	494	combination of the three, merge those two alternatives to suit the
	495	situation.
	496
	497	If your document contains nontrivial examples of program code, we
	498	recommend releasing these examples in parallel under your choice of
	499	free software license, such as the GNU General Public License,
	500	to permit their use in free software.
	501
	502	@c Local Variables:
	503	@c ispell-local-pdict: "ispell-dict"
	504	@c End:

+2547

-0

doc/info-stnd.texi less more

	0	\input texinfo.tex @c --texinfo--
	1	@c We must \input texinfo.tex instead of texinfo, otherwise make
	2	@c distcheck in the Texinfo distribution fails, because the texinfo Info
	3	@c file is made first, and texi2dvi must include . first in the path.
	4	@comment %**start of header
	5	@setfilename info-stnd.info
	6	@include version-stnd.texi
	7	@settitle Stand-alone GNU Info @value{VERSION}
	8	@syncodeindex vr cp
	9	@syncodeindex fn cp
	10	@syncodeindex ky cp
	11	@comment %**end of header
	12
	13	@copying
	14	This manual is for Stand-alone GNU Info (version @value{VERSION},
	15	@value{UPDATED}), a program for viewing documents in Info format
	16	(usually created from Texinfo source files).
	17
	18	Copyright @copyright{} 1992, 1993, 1996, 1997, 1998, 1999, 2001,
	19	2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012,
	20	2013, 2014, 2015, 2016, 2017, 2018, 2019 Free Software Foundation, Inc.
	21
	22	@quotation
	23	Permission is granted to copy, distribute and/or modify this document
	24	under the terms of the GNU Free Documentation License, Version 1.3 or
	25	any later version published by the Free Software Foundation; with no
	26	Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
	27	Texts. A copy of the license is included in the section entitled
	28	``GNU Free Documentation License'' in the Texinfo manual.
	29	@end quotation
	30
	31	This document is part of a collection distributed under the GNU Free
	32	Documentation License. If you want to distribute this document
	33	separately from the collection, you can do so by adding a copy of the
	34	license to the document, as described in section 6 of the license.
	35	@end copying
	36
	37	@dircategory Texinfo documentation system
	38	@direntry
	39	* info stand-alone: (info-stnd). Read Info documents without Emacs.
	40	@end direntry
	41
	42	@titlepage
	43	@title Stand-alone GNU Info
	44	@subtitle for version @value{VERSION}, @value{UPDATED}
	45	@author Brian J. Fox
	46	@author and Texinfo maintainers
	47	@page
	48	@vskip 0pt plus 1filll
	49	@insertcopying
	50	@end titlepage
	51
	52	@contents
	53
	54	@node Top
	55	@top Stand-alone GNU Info
	56
	57	This documentation describes the stand-alone Info reader which you can
	58	use to read Info documentation.
	59
	60	If you are new to the Info reader, then you can get started by typing
	61	@samp{H} for a list of basic key bindings. You can read through the
	62	rest of this manual by typing @key{SPC} and @key{DEL} (or @key{Space}
	63	and @key{Backspace}) to move forwards and backwards in it.
	64
	65
	66	@menu
	67	* Stand-alone Info:: What is Info?
	68	* Invoking Info:: Options you can pass on the command line.
	69	* Cursor Commands:: Commands which move the cursor within a node.
	70	* Scrolling Commands:: Commands for reading the text within a node.
	71	* Node Commands:: Commands for selecting a new node.
	72	* Searching Commands:: Commands for searching an Info file.
	73	* Index Commands:: Commands for looking up in indices.
	74	* Xref Commands:: Commands for selecting cross-references.
	75	* Window Commands:: Commands which manipulate multiple windows.
	76	* Printing Nodes:: How to print out the contents of a node.
	77	* Miscellaneous Commands:: A few commands that defy categorization.
	78	* Variables:: How to change the default behavior of Info.
	79	* Colors and Styles:: Customize the colors used by Info.
	80	* Custom Key Bindings:: How to define your own key-to-command bindings.
	81	* Index:: Global index.
	82	@end menu
	83
	84
	85	@node Stand-alone Info
	86	@chapter Stand-alone Info
	87
	88	The @dfn{Info} program described here is a stand-alone program, part
	89	of the Texinfo distribution, which is used to view Info files on a
	90	text terminal. @dfn{Info files} are typically the result of
	91	processing Texinfo files with the program @code{makeinfo} (also in the
	92	Texinfo distribution).
	93
	94	Texinfo itself (@pxref{Top,,, texinfo, Texinfo}) is a documentation
	95	system that uses a single source file to produce both on-line
	96	information and printed output. You can typeset and print the files
	97	that you read in Info.
	98
	99	@cindex Emacs Info reader
	100	@cindex Info files, reading in Emacs
	101	GNU Emacs also provides an Info reader (just type @kbd{M-x info} in
	102	Emacs). Emacs Info and stand-alone Info have nearly identical user
	103	interfaces, although customization and other details are different
	104	(this manual explains the stand-alone Info reader). The Emacs Info
	105	reader supports the X Window System and other such bitmapped
	106	interfaces, not just plain ASCII, so if you want a prettier display
	107	for Info files, you should try it. You can use Emacs Info without
	108	using Emacs for anything else. (Type @kbd{C-x C-c} to exit; this also
	109	works in the stand-alone Info reader.) @xref{Top,,, info, Info} for a
	110	tutorial and more background information about the Info system, as well
	111	as information about the Info reader that is part of GNU Emacs,
	112
	113	@cindex bugs, reporting
	114	Please report bugs in this stand-alone Info program to
	115	@email{bug-texinfo@@gnu.org}. Bugs in the Emacs Info reader should be
	116	sent to @email{bug-gnu-emacs@@gnu.org}.
	117
	118
	119	@node Invoking Info
	120	@chapter Invoking Info
	121
	122	@cindex Info, invoking
	123	@cindex invoking Info
	124	@cindex command line options
	125	@cindex options, command line
	126	@cindex arguments, command line
	127
	128	GNU Info accepts several options to control the initial node or nodes
	129	being viewed, and to specify which directories to search for Info files.
	130	Here is a template showing an invocation of GNU Info from the shell:
	131
	132	@example
	133	info [@var{option}@dots{}] [@var{manual}] [@var{menu-or-index-item}@dots{}]
	134	@end example
	135
	136	Info will look for an entry called @var{manual} in the directory
	137	files, which are named @file{dir}, that it finds in its search path.
	138	The search is case-insensitive and considers substrings.
	139	(If @var{manual} is not given, by default Info displays a composite
	140	directory listing, constructed by combining the @file{dir} files.)
	141	A basic example:
	142
	143	@example
	144	info coreutils
	145	@end example
	146
	147	This looks for an entry labelled @code{coreutils}, or
	148	@code{Coreutils}, etc., and if found, displays the referenced file
	149	(e.g., @file{coreutils.info}) at the location given.
	150	@code{info coreu} will find it too, if there is no better match.
	151
	152	Another example:
	153
	154	@example
	155	info ls
	156	@end example
	157
	158	Assuming the normal @code{dir} entry for @code{ls}, this will show the
	159	@code{ls} documentation, which happens to be within the
	160	@code{coreutils} manual rather than a separate manual. The @code{dir}
	161	entries can point to an any node within a manual, so that users don't
	162	have to be concerned with the exact structure used by different
	163	authors.
	164
	165	@cindex compressed Info files
	166	@cindex files, compressed
	167	@cindex Info files, compressed
	168	If no entry is found in the directories, Info looks for files in its
	169	search path with names based on @var{manual}. If @var{manual} is
	170	not found, Info looks for it with a number of known extensions of Info
	171	files, namely @file{.info}, @file{-info}, @file{/index}, and @file{.inf}.
	172	For every known extension, if a regular file is not found, Info looks
	173	for a compressed file. Info supports files compressed with @code{gzip},
	174	@code{xz}, @code{bzip2}, @code{lzip}, @code{lzma}, @code{compress} and
	175	@code{yabba} programs, assumed to have extensions @file{.z}, @file{.gz},
	176	@file{.xz}, @file{.bz2}, @file{.lz}, @file{.lzma}, @file{.Z}, and
	177	@file{.Y} respectively.@footnote{On MS-DOS, Info allows for the Info
	178	extension, such as @code{.inf}, and the short compressed file extensions,
	179	such as @file{.z} and @file{.gz}, to be merged into a single extension,
	180	since DOS doesn't allow more than a single dot in the basename of
	181	a file. Thus, on MS-DOS, if Info looks for @file{bison}, file names
	182	like @file{bison.igz} and @file{bison.inz} will be found and decompressed
	183	by @code{gunzip}.}
	184
	185	You can specify the name of a node to visit with the @code{--node} or
	186	@code{-n} option. Alternatively, you can specify the file and node
	187	together using the same format that occurs in Info cross-references.
	188	These two examples both load the @samp{Files} node within the
	189	@samp{emacs} manual:
	190
	191	@example
	192	info emacs -n Files
	193	info '(emacs)Files'
	194	@end example
	195
	196	@cindex absolute Info file names
	197	@cindex relative Info file names
	198	@cindex file names, relative
	199	@cindex Info files, relative
	200	If you want to load a file without looking in the search path, specify
	201	@var{manual} either as an absolute path, or as a path relative to the
	202	current directory which contains at least one slash character. (You
	203	can also use the @code{--file} option for similar behavior, described
	204	below.)
	205	Examples:
	206
	207	@example
	208	info /usr/local/share/info/bash.info
	209	info ./document.info
	210	@end example
	211
	212	@noindent
	213	Info looks for @var{manual} only in the explicitly specified
	214	directory, and adds that directory to its search path.
	215
	216	@anchor{command-line menu items}
	217	@cindex menu, following
	218	Info treats any remaining arguments as the names of menu items, or
	219	(see below) index entries. The first argument is a menu item in the
	220	@samp{Top} node of the file loaded, the second argument is a menu item
	221	in the first argument's node, etc. You can move to the node of your
	222	choice by specifying the menu names which describe the path to that
	223	node. For example,
	224
	225	@example
	226	info emacs buffers
	227	info texinfo Overview 'Using Texinfo'
	228	@end example
	229
	230	@noindent
	231	The first example selects the menu item @samp{Buffers} in the node
	232	@samp{(emacs)Top}. The second example loads the @file{texinfo} file and
	233	looks in its top-level menu for a @samp{Overview} item, looks in the menu
	234	of the node referenced, and finally displays the node referenced by the
	235	@samp{Using Texinfo} item.
	236
	237	If there was only one @var{menu-or-index-item} argument and it wasn't
	238	found as a menu item, Info looks for it as an index entry. For example:
	239
	240	@example
	241	info libc printf
	242	@end example
	243
	244	@noindent
	245	This loads the libc Info manual and first looks for @code{printf} in
	246	the top-level menu as usual; since it isn't there (at this writing),
	247	it then looks in the indices. If it's found there (which it is),
	248	the relevant node at the given location is displayed.
	249
	250	A complete list of options follows.
	251
	252	@table @code
	253	@anchor{--all}
	254	@item --all
	255	@itemx -a
	256	@cindex @code{--all} (@code{-a}) command line option
	257	Find all files matching @var{manual}. Three usage patterns are
	258	supported, as follows.
	259
	260	First, if @code{--all} is used together with @option{--where},
	261	@command{info} prints the names of all matching files found on
	262	standard output (including @samp{manpages} if relevant) and exits.
	263
	264	Second, if @code{--all} is used together with @option{--output}, the
	265	contents of all matched files are dumped to the specified output
	266	file.
	267
	268	Otherwise, an interactive session is initiated. If more than one file
	269	matches, a menu node is displayed listing the matches and allowing you
	270	to select one. This menu node can be brought back at any time by
	271	pressing @kbd{C-x f}. If there is only one match, @command{info}
	272	starts as usual.
	273
	274	When used with the @option{--index-search} option, @command{info}
	275	displays a menu of matching index entries (just as the
	276	@code{virtual-index} command does; see @ref{Index Commands}).
	277
	278	The @option{--node} option cannot be used together with this option.
	279
	280	@anchor{--apropos}
	281	@item --apropos=@var{string}
	282	@itemx -k @var{string}
	283	@cindex @code{--apropos} (@code{-k}) command line option
	284	@cindex Searching all indices
	285	@cindex Info files@r{, searching all indices}
	286	@cindex Apropos@r{, in Info files}
	287	Specify a string to search in every index of every Info file installed
	288	on your system. Info looks up the named @var{string} in all the
	289	indices it can find, prints the results to standard output, and then
	290	exits. If you are not sure which Info file explains certain issues,
	291	this option is your friend. (If your system has a lot of Info files
	292	installed, searching all of them might take some time!)
	293
	294	You can invoke the apropos command from inside Info; see
	295	@ref{Searching Commands}.
	296
	297	@item --debug=@var{number}
	298	@itemx -x @var{number}
	299	@cindex @code{--debug} (@code{-x}) command line option
	300	@cindex debugging
	301	Print additional debugging information. The argument specifies the
	302	verbosity level, so a higher level includes all the information from
	303	lower levels. For all available debugging output, use
	304	@option{-x@tie{}-1}. Info version @value{VERSION} has these levels:
	305
	306	@table @code
	307	@item 1
	308	Print information about file handling, such as looking for @file{dir}
	309	files and nodes written with @samp{--output}.
	310
	311	@item 2
	312	Print operations relating to @env{INFOPATH}.
	313
	314	@item 3
	315	Print information about node searching.
	316	@end table
	317
	318	Debugging output goes to standard error.
	319
	320	@item --directory @var{directory-path}
	321	@itemx -d @var{directory-path}
	322	@cindex @code{--directory} (@code{-d}) command line option
	323	@cindex directory path
	324	@cindex @env{INFOPATH}
	325	@anchor{INFOPATH}
	326	Add @var{directory-path} to the list of directory paths searched
	327	when Info needs to find a file. You may issue @code{--directory}
	328	multiple times; once for each directory which contains Info files,
	329	or with a list of such directories separated by a colon (or semicolon
	330	on MS-DOS/MS-Windows).
	331
	332	Directories specified in the environment variable @env{INFOPATH} are added
	333	to the directories specified with @code{--directory}, if any. The value of
	334	@code{INFOPATH} is a list of directories usually separated by a colon;
	335	on MS-DOS/MS-Windows systems, the semicolon is used. If the value of
	336	@code{INFOPATH} ends with a colon (or semicolon on MS-DOS/MS-Windows),
	337	the initial list of directories is constructed by appending the
	338	build-time default to the value of @code{INFOPATH}.
	339
	340	If you do not define @code{INFOPATH}, Info uses a default path defined
	341	when Info was built as the initial list of directories.
	342
	343	Regardless of whether @code{INFOPATH} is defined, the default
	344	documentation directory defined when Info was built is added to the
	345	search path. If you do not want this directory to be included, set
	346	the @code{infopath-no-defaults} variable to @code{On}
	347	(@pxref{infopath-no-defaults}).
	348
	349	If the list of directories contains the element @code{PATH}, that
	350	element is replaced by a list of directories derived from the value of
	351	the environment variable @code{PATH}. Each path element of the form
	352	@var{dir/base} is replaced by @var{dir}@code{/share/info} or
	353	@var{dir}@code{/info}, provided that directory exists.
	354
	355	@item --dribble=@var{file}
	356	@cindex @code{--dribble} command line option
	357	@cindex keystrokes, recording
	358	@cindex remembering user keystrokes
	359	Specify a file where all user keystrokes will be recorded. This file
	360	can be used later to replay the same sequence of commands, see the
	361	@samp{--restore} option below.
	362
	363	@item --file @var{manual}
	364	@itemx -f @var{manual}
	365	@cindex @code{--file} (@code{-f}) command line option
	366	@cindex Info manual, specifying initial
	367	@cindex initial node, specifying
	368	@cindex startup node, specifying
	369	Specify a particular manual to visit without looking its name up in any
	370	@file{dir} files.
	371
	372	With this option, it starts by trying to visit
	373	@code{(@var{manual})Top}, i.e., the @code{Top} node in (typically)
	374	@file{@var{manual}.info}. As above, it tries various file extensions
	375	to find the file. If no such file (or node) can be found, Info exits
	376	without doing anything. As with the @file{dir} lookup described above,
	377	any extra @var{menu-or-index-item} arguments are used to locate a node
	378	within the loaded file.
	379
	380	If @var{manual} is an absolute file name, or begins with @file{./} or
	381	@file{../}, or contains an intermediate directory, Info will only look
	382	for the file in the directory specified, and add this directory to
	383	@code{INFOPATH}. (This is the same as what happens when @code{--file}
	384	is not given.)
	385
	386	@item --help
	387	@itemx -h
	388	@cindex @code{--help} (@code{-h}) command line option
	389	Output a brief description of the available Info command-line options.
	390
	391	@item --index-search @var{string}
	392	@cindex @code{--index-search} command line option
	393	@cindex index search, selecting from the command line
	394	@cindex online help, using Info as
	395	After processing all command-line arguments, go to the index in the
	396	selected Info file and search for index entries which match
	397	@var{string}. If such an entry is found, the Info session begins with
	398	displaying the node pointed to by the first matching index entry;
	399	press @kbd{,} to step through the rest of the matching entries. If no
	400	such entry exists, print @samp{no entries found} and exit with nonzero
	401	status. This can be used from another program as a way to provide
	402	online help, or as a quick way of starting to read an Info file at a
	403	certain node when you don't know the exact name of that node.
	404
	405	When used with the @option{--all} option, @command{info}
	406	displays a menu of matching index entries (just as the
	407	@code{virtual-index} command does; see @ref{Index Commands}).
	408
	409	This command can also be invoked from inside Info; @pxref{Searching
	410	Commands}.
	411
	412	@item --init-file @var{INIT-FILE}
	413	@anchor{--init-file}
	414	@cindex @code{--init-file} command line option
	415	Read key bindings and variable settings from @var{INIT-FILE} instead
	416	of the @file{.infokey} file in your home directory. @xref{Custom Key
	417	Bindings}.
	418
	419	@item --node @var{nodename}
	420	@itemx -n @var{nodename}
	421	@cindex @code{--node} (@code{-n}) command line option
	422	@cindex node, selecting from the command line
	423	Specify a particular node to visit in the initial file that Info
	424	loads. You may specify @code{--node} multiple times: for an interactive
	425	Info, each @var{nodename} is visited in its own window; for a
	426	non-interactive Info (such as when @code{--output} is given) each
	427	@var{nodename} is processed sequentially.
	428
	429	You can specify both the file and node to the @code{--node} option
	430	using the usual Info syntax, but don't forget to escape the open and
	431	close parentheses and whitespace from the shell; for example:@*
	432	@t{info --node "(emacs)Buffers"}
	433
	434	@item --output @var{file}
	435	@itemx -o @var{file}
	436	@cindex @code{--output} (@code{-o}) command line option
	437	@cindex file, outputting to
	438	@cindex outputting to a file
	439	Direct output to @var{file}. Each node that Info visits will be
	440	output to @var{file} instead of interactively viewed. A value of
	441	@code{-} for @var{file} means standard output.
	442
	443	@item --no-raw-escapes
	444	@itemx --raw-escapes, -R
	445	@anchor {--raw-escapes}
	446	@cindex @code{--raw-escapes} (@code{-R}) command line option
	447	@cindex colors in documents
	448	@cindex ANSI escape sequences in documents
	449	By default, Info passes SGR terminal control sequences (also known as
	450	ANSI escape sequences) found in documents directly through to the
	451	terminal. If you use the @code{--no-raw-escapes} options, these
	452	sequences are displayed as other control characters are; for example, an
	453	@kbd{ESC} byte is displayed as @samp{^[}. The @code{--raw-escapes} and
	454	@code{-R} options do not do anything, but are included for completeness.
	455
	456	@cindex man pages, bold and underline
	457	@vindex GROFF_SGR
	458	Some versions of Groff (@pxref{Top,,,groff,Groff}) produce man pages
	459	with ANSI escape sequences for bold, italics, and underlined
	460	characters, and for colorized text. If your @command{man} command
	461	uses a version of Groff that does this (original GNU Groff does), and
	462	your terminal supports these sequences, Info will display any bold or
	463	underlined text in man pages. Some distributions have modified Groff
	464	to require setting the @code{GROFF_SGR} environment variable to get
	465	these sequences. @xref{Invoking grotty,,, groff, Groff}.
	466
	467	@item --restore=@var{dribble-file}
	468	@cindex @code{--restore} command line option
	469	@cindex replaying recorded keystrokes
	470	Read keystrokes from @var{dribble-file}, presumably recorded during
	471	previous Info session (see the description of the @samp{--dribble}
	472	option above). When the keystrokes in the files are all read, Info
	473	reverts its input to the usual interactive operation.
	474
	475	@item --show-malformed-multibytes
	476	@itemx --no-show-malformed-multibytes
	477	@cindex @code{--show-malformed-multibytes} command line option
	478	@cindex malformed multibyte sequences, showing
	479	Show malformed multibyte sequences in the output. By default, such
	480	sequences are dropped.
	481
	482	@anchor{--show-options}
	483	@item --show-options
	484	@itemx --usage
	485	@itemx -O
	486	@cindex @code{--show-options} (@code{--usage}, @code{-O}) command line option
	487	@cindex command-line options, how to find
	488	@cindex invocation description, how to find
	489	Tell Info to look for the node that describes how to invoke the
	490	program and its command-line options, and begin the session by
	491	displaying that node. It is provided to make it easier to find the
	492	most important usage information in a manual without navigating
	493	through menu hierarchies. The effect is similar to the @code{M-x
	494	goto-invocation} command (@pxref{goto-invocation}) from inside Info.
	495
	496	@item --speech-friendly
	497	@itemx -b
	498	@cindex @code{--speech-friendly} (@code{-b}) command line option
	499	@cindex speech synthesizers
	500	On MS-DOS/MS-Windows only, this option causes Info to use standard
	501	file I/O functions for screen writes. (By default, Info uses direct
	502	writes to the video memory on these systems, for faster operation and
	503	colored display support.) This allows the speech synthesizers used by
	504	blind persons to catch the output and convert it to audible speech.
	505
	506	@item --strict-node-location
	507	@cindex @code{--strict-node-location} command line option
	508	This option causes Info not to search ``nearby'' to locate nodes, and
	509	instead strictly use the information provided in the Info file. The
	510	practical use for this option is for debugging programs that write
	511	Info files, to check that they are outputting the correct locations.
	512	Due to bugs and malfeasances in the various Info writing programs over
	513	the years and versions, it is not advisable to ever use this option
	514	when just trying to read documentation.
	515
	516	@item --subnodes
	517	@cindex @code{--subnodes}, command line option
	518	This option only has meaning when given in conjunction with
	519	@code{--output}. It means to recursively output the nodes appearing in
	520	the menus of each node being output. Menu items which resolve to
	521	external Info files are not output, and neither are menu items which are
	522	members of an index. Each node is only output once.
	523
	524	@anchor{variable-assignment}
	525	@item -v @var{name}=@var{value}
	526	@itemx --variable=@var{name}=@var{value}
	527	@cindex @code{--variable} (@code{-v}) command line option
	528	@cindex variable assignment
	529	Set the @command{info} variable @var{name} to @var{value}.
	530	@xref{Variables}.
	531
	532	@item --version
	533	@cindex @code{--version} command line option
	534	@cindex version information
	535	Prints the version information of Info and exits.
	536
	537	@anchor{--vi-keys}
	538	@item --vi-keys
	539	@cindex @code{--vi-keys} command line option
	540	@cindex vi-like key bindings
	541	@cindex Less-like key bindings
	542	This option binds functions to keys differently, to emulate the key
	543	bindings of @code{vi} and Less. The bindings activated by this option
	544	are documented in @ref{@t{infokey} format}. (@xref{Custom Key Bindings}
	545	for a more general way of altering GNU Info's key bindings.)
	546
	547	@item --where
	548	@itemx --location
	549	@itemx -w
	550	@cindex @code{--where} (@code{--location}, @code{-w}) command line option
	551	@cindex Info manual location
	552	@cindex Where is an Info manual?
	553	Show the filename that would be read and exit, instead of actually
	554	reading it and starting Info.
	555	@end table
	556
	557	Finally, Info defines many default key bindings and variables.
	558	@xref{Custom Key Bindings} for information on how to customize these
	559	settings.
	560
	561	@c FIXME: the feature with lowercasing the file name isn't documented
	562
	563
	564	@node Cursor Commands
	565	@chapter Moving the Cursor
	566	@cindex cursor, moving
	567	@cindex moving the cursor
	568
	569	GNU Info has several commands which allow you to move the cursor about
	570	the screen.
	571	The notation used in this manual to describe keystrokes
	572	is the same as the notation used within the Emacs manual
	573	(@pxref{User Input,,, emacs, The GNU Emacs Manual}).
	574	@kbd{C-@var{x}} means press the @kbd{CTRL} key and the
	575	key @var{x}. @kbd{M-@var{x}} means press the @kbd{META} key and
	576	the key @var{x}. On many terminals the @kbd{META} key is known as
	577	the @kbd{ALT} key. @kbd{SPC} is the space bar. The other keys are
	578	usually called by the names printed on them.
	579
	580	The following table lists the basic cursor movement commands in Info.
	581	Each entry consists of the key sequence you should type to execute the
	582	cursor movement, the @code{M-x} command name (displayed
	583	in parentheses), and a short description of what the command
	584	does.@footnote{@code{M-x} is also a command;
	585	it invokes @code{execute-extended-command}, letting you run a command
	586	by name. @xref{M-x, , Executing an extended command, emacs, The GNU
	587	Emacs Manual}, for more detailed information.}
	588	All of the cursor motion commands can take a @dfn{numeric} argument
	589	(see @ref{Miscellaneous Commands, @code{universal-argument}} to find
	590	out how to supply them). With a numeric argument, the motion commands
	591	are simply executed that many times; for example, a numeric argument
	592	of 4 given to @code{next-line} causes the cursor to move down 4 lines.
	593	With a negative numeric argument, the motion is reversed; an argument
	594	of @minus{}4 given to the @code{next-line} command would cause the
	595	cursor to move @emph{up} 4 lines.
	596
	597	@table @asis
	598	@item @kbd{C-n} (@code{next-line})
	599	@itemx @key{DOWN} (an arrow key)
	600	@kindex C-n
	601	@kindex DOWN (an arrow key)
	602	@findex next-line
	603	Move the cursor down to the next line.
	604
	605	@item @kbd{C-p} (@code{prev-line})
	606	@itemx @key{UP} (an arrow key)
	607	@kindex C-p
	608	@kindex UP (an arrow key)
	609	@findex prev-line
	610	Move the cursor up to the previous line.
	611
	612	@item @kbd{C-a} (@code{beginning-of-line})
	613	@itemx @key{Home} (on DOS/Windows only)
	614	@kindex C-a, in Info windows
	615	@kindex Home
	616	@findex beginning-of-line
	617	Move the cursor to the start of the current line.
	618
	619	@item @kbd{C-e} (@code{end-of-line})
	620	@itemx @key{End} (on DOS/Windows only)
	621	@kindex C-e, in Info windows
	622	@kindex End
	623	@findex end-of-line
	624	Move the cursor to the end of the current line.
	625
	626	@item @kbd{C-f} (@code{forward-char})
	627	@itemx @key{RIGHT} (an arrow key)
	628	@kindex C-f, in Info windows
	629	@kindex RIGHT (an arrow key)
	630	@findex forward-char
	631	Move the cursor forward a character.
	632
	633	@item @kbd{C-b} (@code{backward-char})
	634	@itemx @key{LEFT} (an arrow key)
	635	@kindex C-b, in Info windows
	636	@kindex LEFT (an arrow key)
	637	@findex backward-char
	638	Move the cursor backward a character.
	639
	640	@item @kbd{M-f} (@code{forward-word})
	641	@itemx @kbd{C-@key{RIGHT}} (on DOS/Windows only)
	642	@kindex M-f, in Info windows
	643	@kindex C-RIGHT
	644	@findex forward-word
	645	Move the cursor forward a word.
	646
	647	@item @kbd{M-b} (@code{backward-word})
	648	@itemx @kbd{C-@key{LEFT}} (on DOS/Windows only)
	649	@kindex M-b, in Info windows
	650	@kindex C-LEFT
	651	@findex backward-word
	652	Move the cursor backward a word.
	653
	654	@item @kbd{M-<} (@code{beginning-of-node})
	655	@itemx @kbd{C-@key{Home}} (on DOS/Windows only)
	656	@itemx @kbd{b}
	657	@kindex b, in Info windows
	658	@kindex M-<
	659	@kindex C-Home
	660	@findex beginning-of-node
	661	Move the cursor to the start of the current node.
	662
	663	@item @kbd{M->} (@code{end-of-node})
	664	@itemx @kbd{C-@key{End}} (on DOS/Windows only)
	665	@itemx @kbd{e}
	666	@kindex M->
	667	@kindex e, in Info windows
	668	@kindex C-End
	669	@findex end-of-node
	670	Move the cursor to the end of the current node.
	671
	672	@item @kbd{M-r} (@code{move-to-window-line})
	673	@kindex M-r
	674	@findex move-to-window-line
	675	Move the cursor to a specific line of the window. Without a numeric
	676	argument, @code{M-r} moves the cursor to the start of the line in the
	677	center of the window. With a numeric argument of @var{n}, @code{M-r}
	678	moves the cursor to the start of the @var{n}th line in the window.
	679	@end table
	680
	681
	682	@node Scrolling Commands
	683	@chapter Moving Text Within a Window
	684	@cindex scrolling
	685
	686	Sometimes you are looking at a screenful of text, and only part of the
	687	current paragraph you are reading is visible on the screen. The
	688	commands detailed in this section are used to shift which part of the
	689	current node is visible on the screen.
	690
	691	@table @asis
	692	@item @key{SPC} (@code{scroll-forward})
	693	@kindex SPC, in Info windows
	694	@itemx @key{NEXT}
	695	@kindex NEXT
	696	@findex scroll-forward
	697	Shift the text in this window up. That is, show more of the node which
	698	is currently below the bottom of the window. With a numeric argument,
	699	show that many more lines at the bottom of the window; a numeric
	700	argument of 4 would shift all of the text in the window up 4 lines
	701	(discarding the top 4 lines), and show you four new lines at the bottom
	702	of the window. Without a numeric argument, @key{SPC} takes the bottom
	703	two lines of the window and places them at the top of the window,
	704	redisplaying almost a completely new screenful of lines. If you are at
	705	the end of a node, @key{SPC} takes you to the ``next'' node, so that you can
	706	read an entire manual from start to finish by repeating @key{SPC}.
	707
	708	@kindex PageDown
	709	The @key{NEXT} key is known as the @key{PageDown} key on some
	710	keyboards.
	711
	712	@item @kbd{C-v} (@code{scroll-forward-page-only})
	713	@kindex C-v
	714	@findex scroll-forward-page-only
	715	Shift the text in this window up. This is identical to the @key{SPC}
	716	operation above, except that it never scrolls beyond the end of the
	717	current node.
	718
	719	@item @code{M-x scroll-forward-page-only-set-window}
	720	@findex scroll-forward-page-only-set-window
	721	Scroll forward, like with @kbd{C-v}, but if a numeric argument is
	722	specified, it becomes the default scroll size for subsequent
	723	@code{scroll-forward} and @code{scroll-backward} commands and their
	724	ilk.
	725
	726	@item @key{DEL} (@code{scroll-backward})
	727	@kindex DEL, in Info windows
	728	@item @key{PREVIOUS}
	729	@kindex PREVIOUS
	730	@findex scroll-backward
	731	Shift the text in this window down. The inverse of
	732	@code{scroll-forward}.
	733	If you are at the start of a node, @key{DEL} takes you to the
	734	``previous'' node, so that you can read an entire manual from finish to
	735	start by repeating @key{DEL}. The default scroll size can be changed by
	736	invoking the (@code{scroll-backward-page-only-set-window}) command with
	737	a numeric argument.
	738
	739	@kindex BS (backspace)
	740	If your keyboard lacks the @key{DEL} key, look for a key called
	741	@key{BS}, or @samp{Backspace}, sometimes designated with an arrow which
	742	points to the left, which should perform the same function.
	743
	744	@kindex PageUp
	745	The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs
	746	refers to it by the name @key{PRIOR}.
	747
	748	@item @kbd{M-v} (@code{scroll-backward-page-only})
	749	@kindex M-v
	750	@findex scroll-backward-page-only
	751	Shift the text in this window down. The inverse of
	752	@code{scroll-forward-page-only}. Does not scroll beyond the start of
	753	the current node. The default scroll size can be changed by invoking
	754	the @code{scroll-backward-page-only-set-window} command with a numeric
	755	argument.
	756
	757	@item @code{M-x scroll-backward-page-only-set-window}
	758	@findex scroll-backward-page-only-set-window
	759	Scroll backward, like with @kbd{M-v}, but if a numeric argument is
	760	specified, it becomes the default scroll size for subsequent
	761	@code{scroll-forward} and @code{scroll-backward} commands.
	762
	763	@item @code{M-x down-line}
	764	@findex down-line
	765	Scroll forward by one line. With a numeric argument, scroll forward
	766	that many lines.
	767
	768	@item @code{M-x up-line}
	769	@findex up-line
	770	Scroll backward one line. With a numeric argument, scroll backward that
	771	many lines.
	772
	773	@item @code{M-x scroll-half-screen-down}
	774	@findex scroll-half-screen-down
	775	Scroll forward by half of the screen size. With a numeric argument,
	776	scroll that many lines. If an argument is specified, it becomes the new
	777	default number of lines to scroll for subsequent
	778	@code{scroll-half-screen-down} and @code{scroll-half-screen-up} commands.
	779
	780	@item @code{M-x scroll-half-screen-up}
	781	@findex scroll-half-screen-up
	782	Scroll back by half of the screen size. With a numeric argument,
	783	scroll that many lines. If an argument is specified, it becomes the new
	784	default number of lines to scroll for subsequent
	785	@code{scroll-half-screen-down} and @code{scroll-half-screen-up}
	786	commands.
	787	@end table
	788
	789	@cindex scrolling through node structure
	790	The @code{scroll-forward} and @code{scroll-backward} commands can also
	791	move forward and backward through the node structure of the file. If
	792	you press @key{SPC} while viewing the end of a node, or @key{DEL} while
	793	viewing the beginning of a node, what happens is controlled by the
	794	variable @code{scroll-behavior} (@pxref{scroll-behavior}).
	795
	796	The @code{scroll-forward-page-only} and @code{scroll-backward-page-only}
	797	commands never scroll beyond the current node.
	798
	799	@table @asis
	800	@item @kbd{C-l} (@code{redraw-display})
	801	@kindex C-l
	802	@findex redraw-display
	803	Redraw the display from scratch, or shift the line containing the cursor
	804	to a specified location. With no numeric argument, @samp{C-l} clears
	805	the screen, and then redraws its entire contents. Given a numeric
	806	argument of @var{n}, the line containing the cursor is shifted so that
	807	it is on the @var{n}th line of the window.
	808
	809	@item @kbd{C-x @kbd{w}} (@code{toggle-wrap})
	810	@kindex C-w
	811	@findex toggle-wrap
	812	Toggles the state of line wrapping in the current window. Normally,
	813	lines which are longer than the screen width @dfn{wrap}, i.e., they are
	814	continued on the next line. Lines which wrap have a @samp{\} appearing
	815	in the rightmost column of the screen. You can cause such lines to be
	816	terminated at the rightmost column by changing the state of line
	817	wrapping in the window with @code{C-x w}. When a line which needs more
	818	space than one screen width to display is displayed, a @samp{$} appears
	819	in the rightmost column of the screen, and the remainder of the line is
	820	invisible. When long lines are truncated, the mode line displays the
	821	@samp{$} character near its left edge.
	822	@end table
	823
	824
	825	@node Node Commands
	826	@chapter Selecting a Node
	827	@cindex nodes, selection of
	828
	829	This section details the numerous Info commands which select a new node
	830	to view in the current window.
	831
	832	The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and
	833	@samp{l}.
	834
	835	When you are viewing a node, the top line of the node contains some Info
	836	@dfn{pointers} which describe where the next, previous, and up nodes
	837	are. Info uses this line to move about the node structure of the file
	838	when you use the following commands:
	839
	840	@table @asis
	841	@item @kbd{n} (@code{next-node})
	842	@itemx @kbd{C-@key{NEXT}} (on DOS/Windows only)
	843	@kindex n
	844	@kindex C-NEXT
	845	@findex next-node
	846	Select the `Next' node.
	847
	848	@kindex C-PgDn
	849	The @key{NEXT} key is known as the @key{PgDn} key on some
	850	keyboards.
	851
	852	@item @kbd{p} (@code{prev-node})
	853	@itemx @kbd{C-@key{PREVIOUS}} (on DOS/Windows only)
	854	@kindex p
	855	@kindex C-PREVIOUS
	856	@findex prev-node
	857	Select the `Prev' node.
	858
	859	@kindex C-PgUp
	860	The @key{PREVIOUS} key is known as the @key{PgUp} key on some
	861	keyboards.
	862
	863	@item @kbd{u} (@code{up-node})
	864	@itemx @kbd{C-@key{UP}} (an arrow key on DOS/Windows only)
	865	@kindex u
	866	@kindex C-UP
	867	@findex up-node
	868	Select the `Up' node.
	869	@end table
	870
	871	You can easily select a node that you have already viewed in this window
	872	by using the @samp{l} command---this name stands for ``last'', and
	873	actually moves backwards through the history of visited nodes for this
	874	window. This is handy when you followed a reference to another node,
	875	possibly to read about a related issue, and would like then to resume
	876	reading at the same place where you started the excursion.
	877
	878	Each node where you press @samp{l} is discarded from the history. Thus,
	879	by the time you get to the first node you visited in a window, the
	880	entire history of that window is discarded.
	881
	882	@table @asis
	883	@item @kbd{l} (@code{history-node})
	884	@itemx @kbd{C-@key{CENTER}} (on DOS/Windows only)
	885	@kindex l
	886	@kindex C-CENTER
	887	@findex history-node
	888	Pop the most recently selected node in this window from the node
	889	history.
	890	@end table
	891
	892	Two additional commands make it easy to select the most commonly
	893	selected nodes; they are @samp{t} and @samp{d}.
	894
	895	@table @asis
	896	@item @kbd{t} (@code{top-node})
	897	@kindex t
	898	@findex top-node
	899	Select the node @samp{Top} in the current Info file.
	900
	901	@item @kbd{d} (@code{dir-node})
	902	@kindex d
	903	@findex dir-node
	904	Select the directory node (i.e., the node @samp{(dir)}).
	905	@end table
	906
	907	Here are some other commands which immediately result in the selection
	908	of a different node in the current window:
	909
	910	@table @asis
	911	@item @kbd{<} (@code{first-node})
	912	@kindex <
	913	@findex first-node
	914	Selects the first node which appears in this file. This node is most
	915	often @samp{Top}, but it does not have to be. With a numeric argument
	916	@var{N}, select the @var{N}th node (the first node is node 1). An
	917	argument of zero is the same as the argument of 1.
	918
	919	@item @kbd{>} (@code{last-node})
	920	@kindex >
	921	@findex last-node
	922	Select the last node which appears in this file. With a numeric argument
	923	@var{N}, select the @var{N}th node (the first node is node 1). An
	924	argument of zero is the same as no argument, i.e., it selects the last
	925	node.
	926
	927	@item @kbd{]} (@code{global-next-node})
	928	@kindex ]
	929	@findex global-next-node
	930	Move forward through the node structure. If the node that you are
	931	currently viewing has a menu, select the first menu item. Otherwise,
	932	if this node has a @samp{Next} pointer, follow it. If there is no menu
	933	and no @samp{Next} pointer, then follow @samp{Up} pointers until there
	934	is a @samp{Next} pointer, and then follow it.
	935
	936	@item @kbd{[} (@code{global-prev-node})
	937	@kindex [
	938	@findex global-prev-node
	939	Move backward through the node structure. If the node that you are
	940	currently viewing has a @samp{Prev} pointer, that node is selected.
	941	Otherwise, if the node has an @samp{Up} pointer, that node is selected,
	942	and if it has a menu, the last item in the menu is selected.
	943	@end table
	944
	945	You can get the same behavior as @code{global-next-node} and
	946	@code{global-prev-node} while simply scrolling through the file with
	947	@key{SPC} and @key{DEL} (@pxref{scroll-behavior}).
	948
	949	@table @asis
	950	@anchor{goto-node}
	951	@item @kbd{g} (@code{goto-node})
	952	@kindex g
	953	@findex goto-node
	954	Read the name of a node and select it. If the desired node resides in
	955	some other file, you must type the node as it appears in that Info file,
	956	and include the name of the other file. For example,
	957
	958	@example
	959	@code{g(emacs)Buffers}
	960	@end example
	961
	962	@noindent
	963	finds the node @samp{Buffers} in the Info file @file{emacs}.
	964
	965	While reading the node name, completion (@pxref{The Echo Area,
	966	completion}) is only done for the nodes which reside in one of the Info
	967	files that were loaded in the current Info session.
	968
	969	@anchor{goto-invocation}
	970	@item @kbd{O} (@code{goto-invocation})
	971	@kindex O
	972	@findex goto-invocation
	973	@cindex finding the Invocation node
	974	Read the name of a program and look for a node in the current Info file
	975	which describes the invocation and the command-line options for that
	976	program. The default program name is derived from the name of the
	977	current Info file. This command does the same as the
	978	@samp{--show-options} command-line option (@pxref{--show-options}), but
	979	it also allows to specify the program name; this is important for those
	980	manuals which describe several programs.
	981
	982	If you need to find the Invocation node of a program that is documented
	983	in another Info file, you need to visit that file before invoking
	984	@samp{O}. For example, if you are reading the Emacs manual and want to
	985	see the command-line options of the @code{makeinfo} program, type @kbd{g
	986	(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't
	987	know what Info file documents the command, or if invoking @samp{O}
	988	doesn't display the right node, go to the @samp{(dir)} node (using the
	989	@samp{d} command) and invoke @samp{O} from there.
	990
	991	@item @kbd{G} (@code{menu-sequence})
	992	@kindex G
	993	@findex menu-sequence
	994	@cindex menu, following, from inside Info
	995	Read a sequence of menu entries and follow it. Info prompts for a
	996	sequence of menu items separated by commas. (Since commas are not
	997	allowed in a node name, they are a natural choice for a delimiter in a
	998	list of menu items.) Info then looks up the first item in the menu of
	999	the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info
	1000	uses @samp{Top}). If such an entry is found, Info goes to the node it
	1001	points to and looks up the second item in the menu of that node, etc.
	1002	In other words, you can specify a complete path which descends through
	1003	the menu hierarchy of a particular Info file starting at the
	1004	@samp{(dir)} node. This has the same effect as if you typed the menu
	1005	item sequence on Info's command line, see @ref{command-line menu items,,
	1006	Info command-line arguments processing}. For example,
	1007
	1008	@example
	1009	@kbd{G Texinfo,Overview,Reporting Bugs @key{RET}}
	1010	@end example
	1011
	1012	@noindent
	1013	displays the node @samp{Reporting Bugs} in the Texinfo manual. (You
	1014	don't actually need to type the menu items in their full length, or in
	1015	their exact letter-case. However, if you do type the menu items
	1016	exactly, Info will find it faster.)
	1017
	1018	If any of the menu items you type are not found, Info stops at the last
	1019	entry it did find and reports an error.
	1020
	1021	@item @kbd{C-x C-f} (@code{view-file})
	1022	@kindex C-x C-f
	1023	@findex view-file
	1024	Read the name of a file and selects the entire file. The command
	1025	@example
	1026	@code{C-x C-f @var{filename}}
	1027	@end example
	1028	is equivalent to typing
	1029	@example
	1030	@code{g(@var{filename})*}
	1031	@end example
	1032
	1033	@item @kbd{C-x C-b} (@code{list-visited-nodes})
	1034	@kindex C-x C-b
	1035	@findex list-visited-nodes
	1036	Make a window containing a menu of all of the currently visited nodes.
	1037	This window becomes the selected window, and you may use the standard
	1038	Info commands within it.
	1039
	1040	@item @kbd{C-x @kbd{b}} (@code{select-visited-node})
	1041	@kindex C-x b
	1042	@findex select-visited-node
	1043	Select a node which has been previously visited in a visible window.
	1044	This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is
	1045	created.
	1046
	1047	@item @code{M-x man}
	1048	@findex man
	1049	@cindex man pages, displaying
	1050	Read the name of a man page to load and display. This uses the @command{man}
	1051	command on your system to retrieve the contents of the requested man page.
	1052	See also @pxref{--raw-escapes}.
	1053
	1054	@end table
	1055
	1056
	1057	@node Searching Commands
	1058	@chapter Searching an Info File
	1059	@cindex searching
	1060
	1061	GNU Info allows you to search for a sequence of characters throughout an
	1062	entire Info file. Here are the commands to do this:
	1063
	1064	@table @asis
	1065	@item @kbd{s} (@code{search})
	1066	@itemx @kbd{/}
	1067	@kindex s
	1068	@kindex /
	1069	@findex search
	1070	@cindex regular expression search
	1071	Read a string in the echo area and search for it, either as a regular
	1072	expression (by default) or a literal string. If the string includes
	1073	upper-case characters, the Info file is searched case-sensitively;
	1074	otherwise Info ignores the letter case. With a numeric argument of
	1075	@var{N}, search for @var{N}th occurrence of the string. Negative
	1076	arguments search backwards.
	1077
	1078	@item @kbd{?} (@code{search-backward})
	1079	@kindex ?
	1080	@findex search-backward
	1081	Read a string in the echo area and search backward through the Info file
	1082	for that string. If the string includes upper-case characters, the Info
	1083	file is searched case-sensitively; otherwise Info ignores the letter
	1084	case. With a numeric argument of @var{N}, search for @var{N}th
	1085	occurrence of the string. Negative arguments search forward.
	1086
	1087	@anchor{repeated-search}
	1088	@item @kbd{C-x @kbd{n}} (@code{search-next})
	1089	@itemx @kbd{@}}
	1090	@kindex C-x n
	1091	@kindex @}
	1092	@findex search-next
	1093	@cindex repeated search
	1094	Search forwards for the string used for the last search command.
	1095	Case sensitivity and use of regular expressions are kept the same. With
	1096	a numeric argument of @var{n}, search for @var{n}th next occurrence.
	1097
	1098	By default, the search starts at the position immediately following
	1099	the cursor. However, if the variable @code{search-skip-screen}
	1100	(@pxref{Variables,, @code{search-skip-screen}}) is set, it starts at
	1101	the beginning of the next page, thereby skipping all visibly displayed
	1102	lines.
	1103
	1104	@item @kbd{C-x @kbd{N}} (@code{search-previous})
	1105	@itemx @kbd{@{}
	1106	@kindex C-x N
	1107	@kindex @{
	1108	@findex search-previous
	1109	Just like @code{search-next}, but in reverse. You can use
	1110	@code{search-next} and @code{search-previous} together to move forward
	1111	and backward through matches. @code{search-previous} usually goes to
	1112	the place in the file that was displayed before an immediately preceding
	1113	@code{search-next}, and vice versa.@footnote{This sometimes doesn't
	1114	happen when @code{search-skip-screen} is @code{On}, and the search goes
	1115	across nodes.}
	1116
	1117
	1118	@item @kbd{R} (@code{toggle-regexp})
	1119	@kindex R
	1120	@findex toggle-regexp
	1121	Toggle between using regular expressions and literal strings for
	1122	searching. Info uses so-called `extended' regular expression syntax
	1123	(@pxref{Regular Expressions,,, grep, GNU Grep}).
	1124
	1125	@item @kbd{S} (@code{search-case-sensitively})
	1126	@kindex S
	1127	@findex search-case-sensitively
	1128	@cindex search, case-sensitive
	1129	@cindex case-sensitive search
	1130	Read a string in the echo area and search for it case-sensitively, even
	1131	if the string includes only lower-case letters. With a numeric argument
	1132	of @var{N}, search for @var{N}th occurrence of the string. Negative
	1133	arguments search backwards.
	1134
	1135	@item @kbd{C-s} (@code{isearch-forward})
	1136	@kindex C-s
	1137	@findex isearch-forward
	1138	@cindex incremental search
	1139	Interactively search forward through the Info file for a string as you
	1140	type it. If the string includes upper-case characters, the search is
	1141	case-sensitive; otherwise Info ignores the letter case.
	1142
	1143	@item @kbd{C-r} (@code{isearch-backward})
	1144	@kindex C-r
	1145	@findex isearch-backward
	1146	Interactively search backward through the Info file for a string as
	1147	you type it. If the string includes upper-case characters, the search
	1148	is case-sensitive; otherwise Info ignores the letter case.
	1149
	1150	@item @kbd{M-/} (@code{tree-search})
	1151	@findex tree-search
	1152	Recursively search this node and any subnodes listed in menus for a
	1153	string.
	1154
	1155	@item @kbd{M-@}} (@code{tree-search-next})
	1156	@itemx @kbd{M-@{} (@code{tree-search-previous})
	1157	@findex tree-search-next
	1158	@findex tree-search-previous
	1159	Go forwards and backwards through the matches for an active tree search.
	1160	@end table
	1161
	1162	The most basic searching command is @samp{s} or @samp{/}
	1163	(@code{search}). The @samp{s} command prompts you for a string in the
	1164	echo area, and then searches the remainder of the Info file for an
	1165	occurrence of that string. If the string is found, the node containing
	1166	it is selected, and the cursor is left positioned at the start of the
	1167	found string. Subsequent @samp{s} commands show you the default search
	1168	string; pressing @key{RET} instead of typing a new string will use the
	1169	default search string.
	1170
	1171	@dfn{Incremental searching} is similar to basic searching, but the
	1172	string is looked up while you are typing it, instead of waiting until
	1173	the entire search string has been specified.
	1174
	1175	The tree search can be used from the @code{dir} node to search through
	1176	all Info files installed on the system. It can also be used to search
	1177	through a particular chapter of a manual when you are not interested in
	1178	matches in other chapters.
	1179
	1180	@vindex highlight-searches
	1181	@findex clear-search
	1182	If the @code{highlight-searches} variable is set, matches from search
	1183	commands will be highlighted. @xref{Variables,, @code{highlight-searches}}.
	1184	Use the @kbd{M-x clear-search} command to clear any search highlights.
	1185
	1186	@cindex search, and case-sensitivity
	1187	@cindex case-sensitivity, and search
	1188	Both incremental and non-incremental search by default ignore the case
	1189	of letters when comparing the Info file text with the search string.
	1190	However, an uppercase letter in the search string makes the search
	1191	case-sensitive. You can force a case-sensitive non-incremental search,
	1192	even for a string that includes only lower-case letters, by using the
	1193	@samp{S} command (@code{search-case-sensitively}). The @samp{n} and
	1194	@samp{N} commands operate case-sensitively if the last search command
	1195	was @samp{S}.
	1196
	1197	Normally, the search pattern should not be shorter than some
	1198	predefined limit. By default, this limit is set to 1 character.
	1199	@xref{min-search-length} for more information on this.
	1200
	1201
	1202	@node Index Commands
	1203	@chapter Index Commands
	1204	@cindex index
	1205	@cindex indices
	1206	@cindex indexes
	1207
	1208	GNU Info has commands to search through the indices of an Info file,
	1209	which helps you find areas within an Info file which discuss a
	1210	particular topic.
	1211
	1212	@table @asis
	1213	@item @kbd{i} (@code{index-search})
	1214	@kindex i
	1215	@findex index-search
	1216	@cindex index, searching
	1217	@cindex searching, in the indices
	1218	Look up a string in the indices for this Info file, and select a node
	1219	to which the found index entry points.
	1220
	1221	@item @kbd{I} (@code{virtual-index})
	1222	@kindex I
	1223	@findex virtual-index
	1224	@cindex index, virtual
	1225	Look up a string in the indices for this Info file, and show all the
	1226	matches in a new virtual node, synthesized on the fly.
	1227
	1228	@item @kbd{,} (@code{next-index-match})
	1229	@kindex ,
	1230	@findex next-index-match
	1231	Move to the node containing the next matching index item from the last
	1232	@samp{i} command.
	1233
	1234	@item @kbd{M-x index-apropos}
	1235	@findex index-apropos
	1236	Grovel the indices of all the known Info files on your system for a
	1237	string, and build a menu of the possible matches.
	1238	@end table
	1239
	1240	The most efficient means of finding something quickly in a manual is
	1241	the @samp{i} command (@code{index-search}). This command prompts for
	1242	a string, and then looks for that string in all the indices of the
	1243	current Info manual. If it finds a matching index entry, it displays
	1244	the node to which that entry refers and prints the full text of the
	1245	entry in the echo area. You can press @samp{,}
	1246	(@code{next-index-match}) to find more matches. A good Info manual
	1247	has all of its important concepts indexed, so the @samp{i} command
	1248	lets you use a manual as a reference.
	1249
	1250	If you don't know what manual documents something, try the @kbd{M-x
	1251	index-apropos} command. It prompts for a string and then looks up
	1252	that string in all the indices of all the Info documents installed on
	1253	your system. It can also be invoked from the command line; see
	1254	@ref{--apropos}.
	1255
	1256
	1257	@node Xref Commands
	1258	@chapter Selecting Cross-references
	1259
	1260	We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up}
	1261	pointers which appear at the top of a node. In addition to these
	1262	pointers, a node may contain other pointers which refer you to a
	1263	different node, perhaps in another Info file. Such pointers are called
	1264	@dfn{cross-references}, or @dfn{xrefs} for short.
	1265
	1266	@menu
	1267	* Parts of an Xref:: What a cross-reference is made of.
	1268	* Selecting Xrefs:: Commands for selecting menu or note items.
	1269	@end menu
	1270
	1271	@node Parts of an Xref
	1272	@section Parts of an Xref
	1273
	1274	Cross-references have two major parts: the first part is called the
	1275	@dfn{label}; it is the name that you can use to refer to the cross
	1276	reference, and the second is the @dfn{target}; it is the full name of
	1277	the node that the cross-reference points to.
	1278
	1279	The target is separated from the label by a colon @samp{:}; first the
	1280	label appears, and then the target. For example, in the sample menu
	1281	cross-reference below, the single colon separates the label from the
	1282	target.
	1283
	1284	@example
	1285	* Foo Label: Foo Target. More information about Foo.
	1286	@end example
	1287
	1288	Note the @samp{.} which ends the name of the target. The @samp{.} is
	1289	not part of the target; it serves only to let Info know where the target
	1290	name ends.
	1291
	1292	A shorthand way of specifying references allows two adjacent colons to
	1293	stand for a target name which is the same as the label name:
	1294
	1295	@example
	1296	* Foo Commands:: Commands pertaining to Foo.
	1297	@end example
	1298
	1299	In the above example, the name of the target is the same as the name of
	1300	the label, in this case @code{Foo Commands}.
	1301
	1302	You will normally see two types of cross-reference while viewing nodes:
	1303	@dfn{menu} references, and @dfn{note} references. Menu references
	1304	appear within a node's menu; they begin with a @samp{*} at the beginning
	1305	of a line, and continue with a label, a target, and a comment which
	1306	describes what the contents of the node pointed to contains.
	1307
	1308	Note references appear within the body of the node text; they begin with
	1309	@code{*Note}, and continue with a label and a target.
	1310
	1311	Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross-references
	1312	can point to any valid node. They are used to refer you to a place
	1313	where more detailed information can be found on a particular subject.
	1314	Here is a cross-reference which points to a node within the Texinfo
	1315	documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo
	1316	Manual}, for more information on creating your own texinfo cross
	1317	references.
	1318
	1319	@node Selecting Xrefs
	1320	@section Selecting Xrefs
	1321
	1322	The following table lists the Info commands which operate on menu items.
	1323
	1324	@table @asis
	1325	@item @kbd{1} (@code{menu-digit})
	1326	@itemx @kbd{2} @dots{} @kbd{9}
	1327	@itemx @kbd{M-1}, vi-like operation
	1328	@itemx @kbd{M-2} @dots{} @kbd{M-9}, vi-like operation
	1329	@cindex 1 @dots{} 9, in Info windows
	1330	@cindex M-1 @dots{} M-9, vi-like operation
	1331	@kindex 1 @dots{} 9, in Info windows
	1332	@kindex M-1 @dots{} M-9, vi-like operation
	1333	@findex menu-digit
	1334	Within an Info window, pressing a single digit, (such as @samp{1}),
	1335	selects that menu item, and places its node in the current window.
	1336	For convenience, there is one exception; pressing @samp{0} selects the
	1337	@emph{last} item in the node's menu. When @samp{--vi-keys} is in
	1338	effect, digits set the numeric argument, so these commands are remapped
	1339	to their @samp{M-} varieties. For example, to select the last menu
	1340	item, press @kbd{M-0}.
	1341
	1342	@item @kbd{0} (@code{last-menu-item})
	1343	@itemx @kbd{M-0}, vi-like operation
	1344	@kindex 0, in Info windows
	1345	@kindex M-0, vi-like operation
	1346	@findex last-menu-item
	1347	Select the last item in the current node's menu.
	1348
	1349	@item @kbd{m} (@code{menu-item})
	1350	@kindex m
	1351	@findex menu-item
	1352	Reads the name of a menu item in the echo area and selects its node.
	1353	Completion is available while reading the menu label. @xref{The Echo
	1354	Area, completion}.
	1355
	1356	@item @kbd{M-x find-menu}
	1357	@findex find-menu
	1358	Move the cursor to the start of this node's menu.
	1359	@end table
	1360
	1361	This table lists the Info commands which operate on cross-references.
	1362
	1363	@table @asis
	1364	@item @kbd{f} (@code{xref-item})
	1365	@itemx @kbd{r}
	1366	@kindex f
	1367	@kindex r
	1368	@findex xref-item
	1369	Reads the name of a note cross-reference in the echo area and selects
	1370	its node. Completion is available while reading the cross-reference
	1371	label. @xref{The Echo Area, completion}.
	1372	@end table
	1373
	1374	Finally, the next few commands operate on menu or note references alike:
	1375
	1376	@table @asis
	1377	@item @key{TAB} (@code{move-to-next-xref})
	1378	@kindex TAB, in Info windows
	1379	@findex move-to-next-xref
	1380	Move the cursor to the start of the next nearest menu item or note
	1381	reference in this node. You can then use @key{RET}
	1382	(@code{select-reference-this-line}) to select the menu or note reference.
	1383
	1384	@item @kbd{M-TAB} (@code{move-to-prev-xref})
	1385	@itemx @kbd{BackTab}
	1386	@itemx @kbd{Shift-@key{TAB}} (on DOS/Windows only)
	1387	@kindex M-TAB, in Info windows
	1388	@findex move-to-prev-xref
	1389	Move the cursor the start of the nearest previous menu item or note
	1390	reference in this node.
	1391
	1392	@kindex Shift-TAB, in Info windows
	1393	@kindex BackTab, in Info windows
	1394	The @kbd{BackTab} key can be produced on some terminals with
	1395	@kbd{Shift-@key{TAB}}.
	1396
	1397	@item @key{RET} (@code{select-reference-this-line})
	1398	@kindex RET, in Info windows
	1399	@findex select-reference-this-line
	1400	Select the menu item or note reference appearing on this line.
	1401	@end table
	1402
	1403
	1404	@node Window Commands
	1405	@chapter Manipulating Multiple Windows
	1406	@cindex windows, manipulating
	1407
	1408	A @dfn{window} is a place to show the text of a node. Windows have a
	1409	view area where the text of the node is displayed, and an associated
	1410	@dfn{mode line}, which briefly describes the node being viewed.
	1411
	1412	GNU Info supports multiple windows appearing in a single screen; each
	1413	window is separated from the next by its mode line. At any time, there
	1414	is only one @dfn{active} window, that is, the window in which the cursor
	1415	appears. There are commands available for creating windows, changing
	1416	the size of windows, selecting which window is active, and for deleting
	1417	windows.
	1418
	1419	@menu
	1420	* The Mode Line:: What appears in the mode line?
	1421	* Basic Windows:: Manipulating windows in Info.
	1422	* The Echo Area:: Used for displaying errors and reading input.
	1423	@end menu
	1424
	1425	@node The Mode Line
	1426	@section The Mode Line
	1427
	1428	A @dfn{mode line} is a line of inverse video which appears at the bottom
	1429	of an Info window. It describes the contents of the window just above
	1430	it; this information includes the name of the file and node appearing in
	1431	that window, the number of screen lines it takes to display the node,
	1432	and the percentage of text that is above the top of the window.
	1433
	1434	Here is a sample mode line for a window containing a file
	1435	named @file{dir}, showing the node @samp{Top}.
	1436
	1437	@example
	1438	@group
	1439	-----Info: (dir)Top, 40 lines --Top-------------------------------------
	1440	^^ ^ ^^^ ^^
	1441	(file)Node #lines where
	1442	@end group
	1443	@end example
	1444
	1445	Truncation of long lines (as opposed to wrapping them to the next
	1446	display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a
	1447	@samp{$} at the left edge of the mode line:
	1448
	1449	@example
	1450	--$--Info: (texinfo)Top, 480 lines --Top--------------------------------
	1451	@end example
	1452
	1453	When Info makes a node internally, such that there is no corresponding
	1454	info file on disk, the name of the node is surrounded by asterisks
	1455	(@samp{*}). The name itself tells you what the contents of the window
	1456	are; the sample mode line below shows an internally constructed node
	1457	showing possible completions:
	1458
	1459	@example
	1460	-----Info: Completions, 7 lines --All---------------------------------
	1461	@end example
	1462
	1463	@node Basic Windows
	1464	@section Window Commands
	1465
	1466	It can be convenient to view more than one node at a time. To allow
	1467	this, Info can display more than one @dfn{window}. Each window has its
	1468	own mode line (@pxref{The Mode Line}) and history of nodes viewed in that
	1469	window (@pxref{Node Commands, , @code{history-node}}).
	1470
	1471	@table @asis
	1472	@item @kbd{C-x @kbd{o}} (@code{next-window})
	1473	@cindex windows, selecting
	1474	@kindex C-x o
	1475	@findex next-window
	1476	Select the next window on the screen. Note that the echo area can only be
	1477	selected if it is already in use, and you have left it temporarily.
	1478	Normally, @samp{C-x o} simply moves the cursor into the next window on
	1479	the screen, or if you are already within the last window, into the first
	1480	window on the screen. Given a numeric argument, @samp{C-x o} moves over
	1481	that many windows. A negative argument causes @samp{C-x o} to select
	1482	the previous window on the screen.
	1483
	1484	@item @kbd{M-x prev-window}
	1485	@findex prev-window
	1486	Select the previous window on the screen. This is identical to
	1487	@samp{C-x o} with a negative argument.
	1488
	1489	@item @kbd{C-x @kbd{2}} (@code{split-window})
	1490	@cindex windows, creating
	1491	@kindex C-x 2
	1492	@findex split-window
	1493	Split the current window into two windows, both showing the same node.
	1494	Each window is one half the size of the original window, and the
	1495	cursor remains in the original window. The variable
	1496	@code{automatic-tiling} can cause all of the windows on the screen to
	1497	be resized for you automatically (@pxref{Variables,,
	1498	@code{automatic-tiling}}).
	1499
	1500	@item @kbd{C-x @kbd{0}} (@code{delete-window})
	1501	@cindex windows, deleting
	1502	@kindex C-x 0
	1503	@findex delete-window
	1504	Delete the current window from the screen. If you have made too many
	1505	windows and your screen appears cluttered, this is the way to get rid of
	1506	some of them.
	1507
	1508	@item @kbd{C-x @kbd{1}} (@code{keep-one-window})
	1509	@kindex C-x 1
	1510	@findex keep-one-window
	1511	Delete all of the windows excepting the current one.
	1512
	1513	@item @kbd{ESC @kbd{C-v}} (@code{scroll-other-window})
	1514	@kindex ESC C-v, in Info windows
	1515	@findex scroll-other-window
	1516	Scroll the other window, in the same fashion that @samp{C-v} might
	1517	scroll the current window. Given a negative argument, scroll the
	1518	``other'' window backward.
	1519
	1520	@item @kbd{C-x @kbd{^}} (@code{grow-window})
	1521	@kindex C-x ^
	1522	@findex grow-window
	1523	Grow (or shrink) the current window. Given a numeric argument, grow
	1524	the current window that many lines; with a negative numeric argument,
	1525	shrink the window instead.
	1526
	1527	@item @kbd{C-x @kbd{t}} (@code{tile-windows})
	1528	@cindex tiling
	1529	@kindex C-x t
	1530	@findex tile-windows
	1531	Divide the available screen space among all of the visible windows.
	1532	Each window is given an equal portion of the screen in which to
	1533	display its contents. The variable @code{automatic-tiling} can cause
	1534	@code{tile-windows} to be called when a window is created or deleted.
	1535	@xref{Variables,, @code{automatic-tiling}}.
	1536	@end table
	1537
	1538	@node The Echo Area
	1539	@section The Echo Area
	1540	@cindex echo area
	1541
	1542	The @dfn{echo area} is a one line window which appears at the bottom of
	1543	the screen. It is used to display informative or error messages, and to
	1544	read lines of input from you when that is necessary. Almost all of the
	1545	commands available in the echo area are identical to their Emacs
	1546	counterparts, so please refer to that documentation for greater depth of
	1547	discussion on the concepts of editing a line of text. The following
	1548	table briefly lists the commands that are available while input is being
	1549	read in the echo area:
	1550
	1551	@table @asis
	1552	@item @kbd{C-f} (@code{echo-area-forward})
	1553	@itemx @key{RIGHT} (an arrow key)
	1554	@kindex C-f, in the echo area
	1555	@kindex RIGHT, in the echo area
	1556	@findex echo-area-forward
	1557	Move forward a character.
	1558
	1559	@item @kbd{C-b} (@code{echo-area-backward})
	1560	@itemx @key{LEFT} (an arrow key)
	1561	@kindex LEFT, in the echo area
	1562	@kindex C-b, in the echo area
	1563	@findex echo-area-backward
	1564	Move backward a character.
	1565
	1566	@item @kbd{C-a} (@code{echo-area-beg-of-line})
	1567	@kindex C-a, in the echo area
	1568	@findex echo-area-beg-of-line
	1569	Move to the start of the input line.
	1570
	1571	@item @kbd{C-e} (@code{echo-area-end-of-line})
	1572	@kindex C-e, in the echo area
	1573	@findex echo-area-end-of-line
	1574	Move to the end of the input line.
	1575
	1576	@item @kbd{M-f} (@code{echo-area-forward-word})
	1577	@itemx @kbd{C-@key{RIGHT}} (DOS/Windows only)
	1578	@kindex M-f, in the echo area
	1579	@findex echo-area-forward-word
	1580	Move forward a word.
	1581
	1582	@kindex C-RIGHT, in the echo area
	1583	On DOS/Windows, @kbd{C-@key{RIGHT}} moves forward by words.
	1584
	1585	@item @kbd{M-b} (@code{echo-area-backward-word})
	1586	@itemx @kbd{C-@key{LEFT}} (DOS/Windows only)
	1587	@kindex M-b, in the echo area
	1588	@findex echo-area-backward-word
	1589	Move backward a word.
	1590
	1591	@kindex C-LEFT, in the echo area
	1592	On DOS/Windows, @kbd{C-@key{LEFT}} moves backward by words.
	1593
	1594	@item @kbd{C-d} (@code{echo-area-delete})
	1595	@kindex C-d, in the echo area
	1596	@findex echo-area-delete
	1597	Delete the character under the cursor.
	1598
	1599	@item @key{DEL} (@code{echo-area-rubout})
	1600	@kindex DEL, in the echo area
	1601	@findex echo-area-rubout
	1602	Delete the character behind the cursor.
	1603
	1604	On some keyboards, this key is designated @key{BS}, for
	1605	@samp{Backspace}. Those keyboards will usually bind @key{DEL} in the
	1606	echo area to @code{echo-area-delete}.
	1607
	1608	@item @kbd{C-g} (@code{echo-area-abort})
	1609	@kindex C-g, in the echo area
	1610	@findex echo-area-abort
	1611	Cancel or quit the current operation. If completion is being read, this
	1612	command discards the text of the input line which does not match any
	1613	completion. If the input line is empty, it aborts the calling function.
	1614
	1615	@item @key{RET} (@code{echo-area-newline})
	1616	@kindex RET, in the echo area
	1617	@findex echo-area-newline
	1618	Accept (or forces completion of) the current input line.
	1619
	1620	@item @kbd{C-q} (@code{echo-area-quoted-insert})
	1621	@kindex C-q, in the echo area
	1622	@findex echo-area-quoted-insert
	1623	Insert the next character verbatim. This is how you can insert control
	1624	characters into a search string, for example, or the @samp{?} character
	1625	when Info prompts with completion.
	1626
	1627	@item @kbd{M-TAB} (@code{echo-area-tab-insert})
	1628	@itemx @kbd{Shift-@key{TAB}} (on DOS/Windows only)
	1629	@kindex M-TAB, in the echo area
	1630	@kindex Shift-TAB, in the echo area
	1631	@findex echo-area-tab-insert
	1632	Insert a TAB character.
	1633
	1634	@kindex Shift-TAB, in the echo area
	1635	@kindex BackTab, in the echo area
	1636	On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for
	1637	@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}.
	1638
	1639	@item @kbd{C-t} (@code{echo-area-transpose-chars})
	1640	@kindex C-t, in the echo area
	1641	@findex echo-area-transpose-chars
	1642	Transpose the characters at the cursor.
	1643
	1644	@item @var{printing character}
	1645	@kindex printing characters, in the echo area
	1646	Insert the character.
	1647
	1648	@end table
	1649
	1650	The next group of commands deal with @dfn{killing}, and @dfn{yanking}
	1651	text. (Sometimes these operations are called @dfn{cut} and
	1652	@dfn{paste}, respectively.) For an in-depth discussion, see
	1653	@ref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual}.
	1654
	1655	@table @asis
	1656	@item @kbd{M-d} (@code{echo-area-kill-word})
	1657	@kindex M-d, in the echo area
	1658	@findex echo-area-kill-word
	1659	Kill the word following the cursor.
	1660
	1661	@item @kbd{M-@key{DEL}} (@code{echo-area-backward-kill-word})
	1662	@itemx @kbd{M-@key{BS}}
	1663	@kindex M-DEL, in the echo area
	1664	@findex echo-area-backward-kill-word
	1665	Kill the word preceding the cursor.
	1666
	1667	@kindex M-BS, in the echo area
	1668	On some keyboards, the @samp{Backspace} key is used instead of
	1669	@code{DEL}, so @code{M-@key{Backspace}} has the same effect as
	1670	@code{M-@key{DEL}}.
	1671
	1672	@item @kbd{C-k} (@code{echo-area-kill-line})
	1673	@kindex C-k, in the echo area
	1674	@findex echo-area-kill-line
	1675	Kill the text from the cursor to the end of the line.
	1676
	1677	@item @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line})
	1678	@kindex C-x DEL, in the echo area
	1679	@findex echo-area-backward-kill-line
	1680	Kill the text from the cursor to the beginning of the line.
	1681
	1682	@item @kbd{C-y} (@code{echo-area-yank})
	1683	@kindex C-y, in the echo area
	1684	@findex echo-area-yank
	1685	Yank back the contents of the last kill.
	1686
	1687	@item @kbd{M-y} (@code{echo-area-yank-pop})
	1688	@kindex M-y, in the echo area
	1689	@findex echo-area-yank-pop
	1690	Yank back a previous kill, removing the last yanked text first.
	1691	@end table
	1692
	1693	@cindex completion
	1694	Sometimes when reading input in the echo area, the command that needed
	1695	input will only accept one of a list of several choices. The choices
	1696	represent the @dfn{possible completions}, and you must respond with one
	1697	of them. Since there are a limited number of responses you can make,
	1698	Info allows you to abbreviate what you type, only typing as much of the
	1699	response as is necessary to uniquely identify it. In addition, you can
	1700	request Info to fill in as much of the response as is possible; this
	1701	is called @dfn{completion}.
	1702
	1703	The following commands are available when completing in the echo area:
	1704
	1705	@table @asis
	1706	@item @key{TAB} (@code{echo-area-complete})
	1707	@kindex TAB, in the echo area
	1708	@findex echo-area-complete
	1709	Insert as much of a completion as is possible. Otherwise,
	1710	display a window containing a list of the possible completions of what
	1711	you have typed so far. For example, if the available choices are:
	1712
	1713	@example
	1714	@group
	1715	bar
	1716	foliate
	1717	food
	1718	forget
	1719	@end group
	1720	@end example
	1721
	1722	@noindent
	1723	and you have typed an @samp{f}, followed by @key{TAB}, this
	1724	would result in @samp{fo} appearing in the echo area, since
	1725	all of the choices which begin with @samp{f} continue with @samp{o}.
	1726
	1727	Now if you type @key{TAB} again, Info will pop
	1728	up a window showing a node called @samp{Completions} which lists the
	1729	possible completions like this:
	1730
	1731	@example
	1732	@group
	1733	3 completions:
	1734	foliate food
	1735	forget
	1736	@end group
	1737	@end example
	1738
	1739	@noindent
	1740	i.e., all of the choices which begin with @samp{fo}.
	1741
	1742	Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate}
	1743	appearing in the echo area, since that is the only choice which begins
	1744	with @samp{fol}.
	1745
	1746	@item @key{ESC C-v} (@code{echo-area-scroll-completions-window})
	1747	@kindex ESC C-v, in the echo area
	1748	@findex echo-area-scroll-completions-window
	1749	Scroll the completions window, if that is visible, or the ``other''
	1750	window if not.
	1751	@end table
	1752
	1753
	1754	@node Printing Nodes
	1755	@chapter Printing Nodes
	1756	@cindex printing
	1757
	1758	In general, we recommend that you use @TeX{} to format the document and
	1759	print sections of it, by running @code{tex} on the Texinfo source file.
	1760	However, you may wish to print out the contents of a node as a quick
	1761	reference document for later use, or if you don't have @TeX{} installed.
	1762	Info provides you with a command for doing this.
	1763
	1764	@table @asis
	1765	@item @kbd{M-x print-node}
	1766	@findex print-node
	1767	@cindex @env{INFO_PRINT_COMMAND}, environment variable
	1768	Pipe the contents of the current node through the command in the
	1769	environment variable @env{INFO_PRINT_COMMAND}. If the variable does not
	1770	exist, the node is simply piped to @code{lpr} (on DOS/Windows, the
	1771	default is to print the node to the local printer device, @file{PRN}).
	1772
	1773	@cindex printing nodes to the local printer
	1774	@cindex local printer device
	1775	The value of @env{INFO_PRINT_COMMAND} may begin with the @samp{>}
	1776	character, as in @samp{>/dev/printer}, in which case Info treats the
	1777	rest as the name of a file or a device. Instead of piping to a command,
	1778	Info opens the file, writes the node contents, and closes the file,
	1779	under the assumption that text written to that file will be printed by
	1780	the underlying OS.
	1781	@end table
	1782
	1783
	1784	@node Miscellaneous Commands
	1785	@chapter Miscellaneous Commands
	1786
	1787	GNU Info contains several commands which self-document GNU Info:
	1788
	1789	@table @asis
	1790	@item @kbd{M-x describe-command}
	1791	@cindex functions, describing
	1792	@cindex commands, describing
	1793	@findex describe-command
	1794	Read the name of an Info command in the echo area and then display a
	1795	brief description of what that command does.
	1796
	1797	@item @kbd{M-x describe-key}
	1798	@cindex keys, describing
	1799	@findex describe-key
	1800	Read a key sequence in the echo area, and then display the name and
	1801	documentation of the Info command that the key sequence invokes.
	1802
	1803	@item @kbd{M-x describe-variable}
	1804	Read the name of a variable in the echo area and then display a brief
	1805	description of what the variable affects.
	1806
	1807	@item @kbd{M-x where-is}
	1808	@findex where-is
	1809	Read the name of an Info command in the echo area, and then display
	1810	a key sequence which can be typed in order to invoke that command.
	1811
	1812	@item @kbd{H} (@code{get-help-window})
	1813	@itemx @key{F1} (on DOS/Windows only)
	1814	@kindex C-h
	1815	@kindex ?, in Info windows
	1816	@kindex F1
	1817	@findex get-help-window
	1818	Create (or Move into) the window displaying @code{Help}, and place
	1819	a node containing a quick reference card into it. This window displays
	1820	the most concise information about GNU Info available.
	1821
	1822	@item @kbd{h} (@code{get-info-help-node})
	1823	@kindex h
	1824	@findex get-info-help-node
	1825	Try hard to visit the node @code{(info)Help}. The Info file
	1826	@file{info.texi} distributed with GNU Emacs contains
	1827	this node. Of course, the file must first be processed with
	1828	@code{makeinfo}, and then placed into the location of your Info directory.
	1829
	1830	@item @kbd{=} (@code{display-file-info})
	1831	@cindex current file, information about
	1832	@findex display-file-info
	1833	@kindex =, in Info windows
	1834	Show information about what's currently being viewed in the echo area:
	1835	the Info file name, and current line number and percentage within the
	1836	current node.
	1837
	1838	@item @kbd{M-x info-version}
	1839	@findex info-version
	1840	Display the name and version of the currently running Info program.
	1841
	1842	@end table
	1843
	1844	Here are the commands for creating a numeric argument:
	1845
	1846	@table @asis
	1847	@item @kbd{C-u} (@code{universal-argument})
	1848	@cindex numeric arguments
	1849	@kindex C-u
	1850	@findex universal-argument
	1851	Start (or multiply by 4) the current numeric argument. @samp{C-u} is
	1852	a good way to give a small numeric argument to cursor movement or
	1853	scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while
	1854	@samp{C-u C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed
	1855	by digit keys sets the numeric argument to the number thus typed:
	1856	@kbd{C-u 1 2 0} sets the argument to 120.
	1857
	1858	@item @kbd{M-1} (@code{add-digit-to-numeric-arg})
	1859	@itemx @kbd{1}, vi-like operation
	1860	@itemx @kbd{M-2} @dots{} @kbd{M-9}
	1861	@itemx @kbd{2} @dots{} @kbd{9}, vi-like operation
	1862	@itemx @kbd{M-0}
	1863	@itemx @kbd{0}, vi-like operation
	1864	@kindex M-0 @dots{} M-9
	1865	@kindex 0 @dots{} 9, vi-like operation
	1866	@findex add-digit-to-numeric-arg
	1867	Add the digit value of the invoking key to the current numeric
	1868	argument. Once Info is reading a numeric argument, you may just type
	1869	the digits of the argument, without the Meta prefix. For example, you
	1870	might give @samp{C-l} a numeric argument of 32 by typing:
	1871
	1872	@example
	1873	@kbd{C-u 3 2 C-l}
	1874	@end example
	1875
	1876	@noindent
	1877	or
	1878
	1879	@example
	1880	@kbd{M-3 2 C-l}
	1881	@end example
	1882
	1883	@item @kbd{M--} (@code{add-digit-to-numeric-arg})
	1884	@itemx @kbd{-}
	1885	@kindex M--
	1886	@kindex -
	1887	@cindex negative arguments
	1888	@cindex arguments, negative
	1889	@cindex numeric arguments, negative
	1890	To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes
	1891	a negative argument with a value of @minus{}1. If you continue to
	1892	type digit or Meta-digit keys after @kbd{-}, the result is a negative
	1893	number produced by those digits.
	1894
	1895	@kbd{-} doesn't work when you type in the echo area, because you need to
	1896	be able to insert the @samp{-} character itself; use @kbd{M--} instead,
	1897	if you need to specify negative arguments in the echo area.
	1898	@end table
	1899
	1900	@key{C-g} is used to abort the reading of a multi-character key
	1901	sequence, to cancel lengthy operations (such as multi-file searches) and
	1902	to cancel reading input in the echo area.
	1903
	1904	@table @asis
	1905	@item @kbd{C-g} (@code{abort-key})
	1906	@cindex cancelling typeahead
	1907	@cindex cancelling the current operation
	1908	@kindex C-g, in Info windows
	1909	@findex abort-key
	1910	Cancel current operation.
	1911	@end table
	1912
	1913	The @samp{q} command of Info simply quits running Info.
	1914
	1915	@table @asis
	1916	@item @kbd{q} (@code{quit})
	1917	@itemx @kbd{C-x C-c}
	1918	@cindex quitting
	1919	@kindex q
	1920	@kindex C-x C-c
	1921	@findex quit
	1922	Exit GNU Info.
	1923	@end table
	1924
	1925	If the operating system tells GNU Info that the screen is 60 lines tall,
	1926	and it is actually only 40 lines tall, here is a way to tell Info that
	1927	the operating system is correct.
	1928
	1929	@table @asis
	1930	@item @kbd{M-x set-screen-height}
	1931	@findex set-screen-height
	1932	@cindex screen, changing the height of
	1933	Read a height value in the echo area and set the height of the
	1934	displayed screen to that value.
	1935	@end table
	1936
	1937	On MS-DOS/MS-Windows, this command actually tries to change the
	1938	dimensions of the visible screen to the value you type in the echo
	1939	area.
	1940
	1941	Finally, Info provides a convenient way to display footnotes which might
	1942	be associated with the current node that you are viewing:
	1943
	1944	@table @asis
	1945	@item @kbd{ESC C-f} (@code{show-footnotes})
	1946	@kindex ESC C-f
	1947	@findex show-footnotes
	1948	@cindex footnotes, displaying
	1949	Show the footnotes (if any) associated with the current node in
	1950	another window. You can have Info automatically display the footnotes
	1951	associated with a node when the node is selected by setting the
	1952	variable @code{automatic-footnotes}. @xref{Variables,,
	1953	@code{automatic-footnotes}}.
	1954	@end table
	1955
	1956
	1957	@node Variables
	1958	@chapter Manipulating Variables
	1959
	1960	GNU Info uses several internal @dfn{variables} whose values are looked
	1961	at by various Info commands. You can change the values of these
	1962	variables, and thus change the behavior of Info, if desired.
	1963
	1964	There are three ways to set the value of a variable, listed here in
	1965	order of precedence:
	1966
	1967	@enumerate
	1968	@item
	1969	interactively, using the @code{set-variable} command described below;
	1970	@item
	1971	on the command line, using the @option{-v} (@option{--variable})
	1972	command line option (@pxref{variable-assignment});
	1973	@item
	1974	in the @code{#var} section of the @code{.infokey} file (@pxref{Custom
	1975	Key Bindings}).
	1976	@end enumerate
	1977
	1978	@table @asis
	1979	@item @kbd{M-x set-variable}
	1980	@cindex variables, setting
	1981	@findex set-variable
	1982	Read the name of a variable, and the value for it, in the echo area
	1983	and then set the variable to that value. Completion is available when
	1984	reading the variable name (@pxref{The Echo Area}); completion is also
	1985	available when reading the value when that makes sense.
	1986
	1987	@item @kbd{M-x describe-variable}
	1988	@cindex variables, describing
	1989	@findex describe-variable
	1990	Read the name of a variable in the echo area and display its value and
	1991	a brief description.
	1992	@end table
	1993
	1994	Here is a list of the variables that you can set in Info.
	1995
	1996	@vtable @code
	1997	@item automatic-footnotes
	1998	@cindex @code{Footnotes} window
	1999	@cindex footnotes window
	2000	When set to @code{On}, footnotes appear and disappear automatically;
	2001	else, they appear at the bottom of the node text. This variable is
	2002	@code{Off} by default. When a node is selected, a window containing
	2003	the footnotes which appear in that node is created, and the footnotes
	2004	are displayed within the new window. The window that Info creates to
	2005	contain the footnotes is called @code{Footnotes}. If a node is
	2006	selected which contains no footnotes, and a @code{Footnotes} window
	2007	is on the screen, the @code{Footnotes} window is deleted. Footnote
	2008	windows created in this fashion are not automatically tiled so that
	2009	they can use as little of the display as is possible.
	2010
	2011	@item automatic-tiling
	2012	When set to @code{On}, creating or deleting a window resizes other
	2013	windows. This variable is @code{Off} by default. Normally, typing
	2014	@samp{C-x 2} divides the current window into two equal parts. When
	2015	@code{automatic-tiling} is set to @code{On}, all of the windows are
	2016	resized automatically, keeping an equal number of lines visible in
	2017	each window. Any @code{Completions} and @code{Footnotes} windows
	2018	are exceptions to the automatic tiling; they retain their original
	2019	size.
	2020
	2021	@anchor{cursor-movement-scrolls}
	2022	@item cursor-movement-scrolls
	2023	When set to @code{On}, when cursor movement commands reach the
	2024	top or bottom of a node, another node is loaded depending on the
	2025	value of @code{scroll-behavior} (see below). This is the default.
	2026	When this variable is set to @code{Off}, cursor movements stop at the
	2027	top or bottom of a node.
	2028
	2029	@item errors-ring-bell
	2030	When set to @code{On} (the default), errors cause the bell to ring.
	2031
	2032	@item follow-strategy
	2033	When set to @code{remain} (the default), Info tries to remain within the
	2034	directory containing the currently displayed Info file when following a
	2035	cross-reference to an external manual, before looking for the referenced
	2036	manual in the search path. The alternative value is @code{path}, which
	2037	means to look through the search path right away.
	2038
	2039	@code{remain} is intended to be useful for several Texinfo manuals that
	2040	all reference each other and whose versions should match each other.
	2041	(For example, various manuals relating to a particular version of
	2042	Emacs.)
	2043
	2044	The alternative behavior, with @code{path}, may be useful when your
	2045	Info file search path parallels your command shell's search path, and
	2046	you always want to find documentation of the version of the program that
	2047	the shell would execute.
	2048
	2049	@item gc-compressed-files
	2050	When set to @code{On}, Info garbage collects files which had to be
	2051	uncompressed. The default value of this variable is @code{Off}.
	2052	Whenever a node is visited in Info, the Info file containing that node
	2053	is read into memory, and Info reads information about the tags and
	2054	nodes contained in that file. Once the tags information is read by
	2055	Info, it is never forgotten. However, the actual text of the nodes
	2056	does not need to be retained unless a particular Info window needs it.
	2057	For non-compressed files, node text is not remembered when it is no
	2058	longer in use. But de-compressing a file can be a time-consuming
	2059	operation, and so Info tries hard not to do it twice. This variable
	2060	tells Info it is okay to garbage collect the text of the nodes of a
	2061	file which was compressed on disk.
	2062
	2063	@item hide-note-references
	2064	By default, Info displays the contents of Info files mostly verbatim,
	2065	including text that is used by Info readers for navigation (for example,
	2066	marking the location of menus or cross-references). If you set this
	2067	variable to @code{On}, some of this text is hidden, in a similar way to
	2068	the @code{Info-hide-note-references} variable in Emacs
	2069	(@pxref{Emacs Info Variables, , , info, Info}).
	2070
	2071	@item highlight-searches
	2072	When set to @code{On}, highlight matches from searching commands
	2073	(@pxref{Searching Commands}).
	2074
	2075	@item infopath-no-defaults
	2076	@anchor{infopath-no-defaults}
	2077	Used in conjunction with the @env{INFOPATH} environment variable
	2078	(@pxref{INFOPATH}). When set to @code{On}, the default documentation
	2079	directory defined when Info was built (e.g., @file{/usr/share/info})
	2080	is not added to the search path for Info files.
	2081
	2082	@item ISO-Latin
	2083	@cindex ISO Latin characters
	2084	@cindex Meta key sets eighth bit
	2085	The default is @code{On}, which means that Info accepts and displays
	2086	characters represented by bytes with values 128 and above, such as
	2087	characters in the UTF-8 encoding or in various 8-bit ISO Latin
	2088	characters, as well as allowing you to input such characters.
	2089
	2090	The only reason to set this variable to @code{Off} would be if your
	2091	terminal set the eighth bit of a byte to represent the Meta key being
	2092	pressed.
	2093
	2094	@item key-time
	2095	@cindex slow network connections
	2096	Length of time in milliseconds to wait for the next byte of a byte
	2097	sequence generated by a key (or key chord) on the keyboard. For
	2098	example, if the @kbd{down} key generates the byte sequence
	2099	@kbd{@key{ESC} O B}, and the two bytes @kbd{@key{ESC} O} have been
	2100	received, then a @kbd{B} byte would have to be received within this
	2101	length of time for a key press of @kbd{down} to be registered. You
	2102	may wish to set this variable to a larger value for slow terminals or
	2103	network connections.
	2104
	2105	If you set this variable to 0, it's unspecified whether a recognized
	2106	byte sequence representing a key takes precedence over another
	2107	recognized sequence representing a key that is an initial subsequence of
	2108	the first sequence. In some cases, you may be able to make pressing a
	2109	special key on the keyboard that Info doesn't know about (for example, a
	2110	function key) cause a command to be executed by setting this variable to
	2111	0, and giving the byte sequence the key sends in @file{.infokey}.
	2112	(@xref{Custom Key Bindings}.)
	2113
	2114	@anchor{min-search-length}
	2115	@item min-search-length
	2116	Minimum length of a search string (default 1). Attempts to initiate a
	2117	search for a string (or regular expression) shorter than this value,
	2118	result in an error.
	2119
	2120	@item mouse
	2121	What method to use to get input from a mouse device. The default value is
	2122	@samp{Off}. Set this variable to @code{normal-tracking} to make Info use
	2123	``normal tracking mode'' if it detects that the terminal supports it. This
	2124	enables you to scroll the contents of the active window with a mouse
	2125	scrollwheel.
	2126
	2127	@cindex Selecting text with the mouse
	2128	@cindex xterm mouse selections
	2129	On terminal emulators running under the X Window System, such as
	2130	@command{xterm}, you can usually select text with the mouse. However,
	2131	mouse tracking mode may interfere with this. When this happens, you may
	2132	be able to select text by holding down the @kbd{Shift} key while
	2133	clicking and dragging.
	2134
	2135	@item nodeline
	2136	@cindex node header line
	2137	How to print the node header line that appears at the top of each node.
	2138	By default only the pointers to neighbouring nodes are displayed
	2139	(the ``Next'', ``Prev'', and ``Up'' pointers): this corresponds to
	2140	the @code{pointers} value for this variable. To print the entire line,
	2141	set @code{nodeline} to the value @code{print}, which will include the
	2142	filename and name of the node. To not display the header line at all,
	2143	use the value @code{no}.
	2144
	2145	@anchor{scroll-behavior}
	2146	@item scroll-behavior
	2147	@itemx scroll-behaviour
	2148	The two variable names are synonymous. Control what happens when
	2149	scrolling commands are used at the end or beginning of a node
	2150	(@pxref{Scrolling Commands}). The default value for this variable is
	2151	@code{Continuous}. Possible values:
	2152
	2153	@table @code
	2154	@item Continuous
	2155	Try to get the first item in this node's menu, or failing that, the
	2156	@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}
	2157	node. This behavior is identical to using the @samp{]}
	2158	(@code{global-next-node}) and @samp{[} (@code{global-prev-node})
	2159	commands.
	2160
	2161	@item Next Only
	2162	Only try to get the @samp{Next} node.
	2163
	2164	@item Page Only
	2165	Just stop, changing nothing. With this value, no scrolling command
	2166	can change the node that is being viewed.
	2167	@end table
	2168
	2169	This variable also affects cursor movement commands (@pxref{Cursor
	2170	Commands}) unless the @code{cursor-movement-scrolls} variable is set to
	2171	@code{Off}. @xref{cursor-movement-scrolls}.
	2172
	2173	@item scroll-last-node
	2174	Control what happens when a scrolling command is issued at the end of
	2175	the last node. Possible values are:
	2176
	2177	@table @code
	2178	@item Stop
	2179	Do not scroll. Display the @samp{No more nodes within this document}
	2180	message. This is the default.
	2181
	2182	@item Top
	2183	Go to the top node of the document.
	2184	@end table
	2185
	2186	This variable is in effect only if @code{scroll-behavior} is set to
	2187	@code{Continuous}.
	2188
	2189	@item scroll-step
	2190	The number of lines to scroll to bring the cursor back into the window.
	2191	The default value of this variable is 1, which causes a kind of ``smooth
	2192	scrolling'' which some people prefer. Scrolling happens automatically
	2193	if the cursor has moved out of the visible portion of the node text.
	2194
	2195	If the variable @code{scroll-step} is 0, the cursor (and the
	2196	text it is attached to) is placed in the centre of the window.
	2197
	2198	@item search-skip-screen
	2199	Set the starting point of repeated searches (@pxref{repeated-search}).
	2200	When set to @code{Off} (the default), repeated searches start at the
	2201	position immediately following (when searching in forward direction),
	2202	or immediately preceding (when searching backwards) the cursor. When
	2203	set to @code{On}, repeated searches omit lines visibly displayed on
	2204	the screen. In other words, forward searches (@kbd{@}}) start at the
	2205	beginning of the next page, and backward searches (@kbd{@{}) start at
	2206	the end of the previous page.
	2207
	2208	@item show-index-match
	2209	When set to @code{On} (the default), the portion of the matched search
	2210	string that you typed is indicated (by displaying it in the
	2211	``opposite'' case) in the result message (@pxref{Searching Commands,,
	2212	@code{next-index-match}}).
	2213
	2214	@item visible-bell
	2215	When set to @code{On}, Info attempts to flash the screen instead of
	2216	ringing the bell. This variable is @code{Off} by default. If the
	2217	terminal does not allow flashing, this variable has no effect. (But
	2218	you can still make Info perform quietly by setting the
	2219	@code{errors-ring-bell} variable to @code{Off}; or using an external
	2220	command to mute the bell, e.g., @code{xset b 0 0 0}.)
	2221
	2222	@end vtable
	2223
	2224
	2225	@node Colors and Styles
	2226	@chapter Colors and Styles
	2227
	2228	You can choose to highlight parts of Info's display, such as
	2229	cross-references and search matches, using a variety of styles,
	2230	including colors, boldface and underline. Here are the variables that
	2231	are available to do this:
	2232
	2233	@vtable @code
	2234	@item link-style
	2235	Used for cross-references and menu entries.
	2236
	2237	@item active-link-style
	2238	Used for a cross-reference or menu entry when typing @key{RET} would
	2239	have the effect of following said cross-reference or menu entry.
	2240
	2241	@item match-style
	2242	Used for matches from a search command. (@xref{Searching Commands}.)
	2243	@end vtable
	2244
	2245	Each of these is given in the @file{.infokey} file just as the variables
	2246	in the previous chapter. Their values are a comma-separated list of
	2247	values in the following table:
	2248
	2249	@table @code
	2250	@item black
	2251	@itemx red
	2252	@itemx green
	2253	@itemx yellow
	2254	@itemx blue
	2255	@itemx magenta
	2256	@itemx cyan
	2257	@itemx white
	2258	@cindex Colored foreground
	2259	Use the color specified for text.
	2260
	2261	@item nocolor
	2262	@itemx nocolour
	2263	Turn off any color that was in effect, using the terminal's default color.
	2264
	2265	@item bgblack
	2266	@itemx bgred
	2267	@itemx bggreen
	2268	@itemx bgyellow
	2269	@itemx bgblue
	2270	@itemx bgmagenta
	2271	@itemx bgcyan
	2272	@itemx bgwhite
	2273	@cindex Colored background
	2274	Use the color specified for the background.
	2275
	2276	@item bgnocolor
	2277	@itemx bgnocolour
	2278	Use the terminal's default background color.
	2279
	2280	@item underline
	2281	@itemx nounderline
	2282	@cindex Underlined text
	2283	Turn text underline on or off.
	2284
	2285	@item standout
	2286	@itemx nostandout
	2287	Turn `standout mode' on or off. Standout mode entails the use of appearance
	2288	modes that make text stand out, and varies between terminals.
	2289
	2290	@item bold
	2291	@itemx regular
	2292	@itemx nobold
	2293	@cindex Bold text
	2294	Turn boldface on or off.
	2295
	2296	@item blink
	2297	@itemx noblink
	2298	@cindex Blinking text
	2299	Make the text blink, or not.
	2300
	2301	@end table
	2302
	2303	Here is an sample excerpt from an @file{.infokey} file:
	2304
	2305	@example
	2306	#var
	2307	link-style=yellow
	2308	active-link-style=yellow,bold
	2309	match-style=underline,bold,nocolor
	2310	@end example
	2311
	2312	@noindent With this, cross-references are all yellow, and active
	2313	cross-references are additionally displayed in bold. Any search
	2314	matches will be shown in bold, and underlined. Moreover, if there is a
	2315	search match inside a cross-reference, the @samp{nocolor} rendition
	2316	style will cancel the yellow color, leaving the text in the match the
	2317	terminal's default color. (Note, however, that the rendition styles for
	2318	active cross-references take priority over those for search matches,
	2319	so search matches there will still be displayed in yellow.)
	2320
	2321
	2322	@node Custom Key Bindings
	2323	@chapter Customizing Key Bindings and Variables
	2324
	2325	@cindex default key bindings, overriding
	2326	@cindex overriding default key bindings
	2327	@cindex customizing key bindings
	2328	@cindex key bindings, customizing
	2329	@cindex @command{infokey}, program for customizing key bindings
	2330	@cindex @file{_info} file (MS-DOS)
	2331
	2332	Info allows you to override the default key-to-command bindings and
	2333	variable settings described in this document. (The @option{--vi-keys}
	2334	option rebinds many keys at once; @pxref{--vi-keys}.)
	2335
	2336	On startup, GNU Info looks for a configuration file in the invoker's
	2337	@env{HOME} directory called @file{.infokey}, i.e.,
	2338	@file{~/.infokey}.@footnote{Due to the limitations of DOS filesystems,
	2339	the MS-DOS version of Info looks for a file @file{_infokey} instead. If
	2340	the @env{HOME} variable is not defined, Info additionally looks in the
	2341	current directory.} If it is present, then Info adopts the key bindings
	2342	and variable settings contained therein. To use an alternative
	2343	configuration file, use the @option{--init-file} option
	2344	(@pxref{--init-file}).
	2345
	2346	Variables may also be set on the command line with the
	2347	@option{--variable} option (@pxref{variable-assignment}). Variable
	2348	settings on the command line override settings from the @file{.infokey}
	2349	file.
	2350
	2351	@menu
	2352	* @t{infokey} format::
	2353	@end menu
	2354
	2355	@node @t{infokey} format
	2356	@section @command{infokey} format
	2357
	2358	@cindex @command{infokey} format
	2359	@cindex @file{.infokey} format
	2360	@cindex format of @file{.infokey}
	2361
	2362	Here is an example @file{.infokey} file which specifies the key
	2363	bindings that are activated by the @option{--vi-keys} option to Info
	2364	(@pxref{--vi-keys}).
	2365
	2366	@example
	2367	#info
	2368	g first-node
	2369	G last-node
	2370	\mb beginning-of-node
	2371	\me end-of-node
	2372	j next-line
	2373	k prev-line
	2374
	2375	f scroll-forward-page-only
	2376	^f scroll-forward-page-only
	2377	\m\ scroll-forward-page-only
	2378	z scroll-forward-page-only-set-window
	2379
	2380	b scroll-backward-page-only
	2381	^b scroll-backward-page-only
	2382	w scroll-backward-page-only-set-window
	2383
	2384	\kd down-line
	2385	^e down-line
	2386	^j down-line
	2387	^m down-line
	2388	\ku up-line
	2389	^y up-line
	2390	^k up-line
	2391
	2392	d scroll-half-screen-down
	2393	^d scroll-half-screen-down
	2394	u scroll-half-screen-up
	2395	^u scroll-half-screen-up
	2396
	2397	^xn next-node
	2398	^xp prev-node
	2399	^xu up-node
	2400	' last-node
	2401	\mt top-node
	2402	\md dir-node
	2403
	2404	^xg goto-node
	2405	I goto-invocation-node
	2406
	2407	n search-next
	2408	N search-previous
	2409
	2410	\mf xref-item
	2411	^xr xref-item
	2412
	2413	\mg select-reference-this-line
	2414	^x^j select-reference-this-line
	2415	^x^m select-reference-this-line
	2416
	2417	^c abort-key
	2418
	2419	\mh get-info-help-node
	2420
	2421	:q quit
	2422	ZZ quit
	2423
	2424	#echo-area
	2425	\mh echo-area-backward
	2426	\ml echo-area-forward
	2427	\m0 echo-area-beg-of-line
	2428	\m$ echo-area-end-of-line
	2429	\mw echo-area-forward-word
	2430	\mx echo-area-delete
	2431	\mu echo-area-abort
	2432	^v echo-area-quoted-insert
	2433	\mX echo-area-kill-word
	2434	@end example
	2435
	2436	The file consists of one or more @dfn{sections}. Each section starts with
	2437	a line that identifies the type of section. The possible sections are:
	2438
	2439	@table @code
	2440	@item #info
	2441	Key bindings for Info windows.
	2442	The start of this section is indicated by a line containing just
	2443	@code{#info} by itself. If this is the first section in the source
	2444	file, the @code{#info} line can be omitted. The rest of this section
	2445	consists of lines of the form:
	2446
	2447	@example
	2448	@var{string} whitespace @var{action} [ whitespace [ # comment ] ] newline
	2449	@end example
	2450
	2451	Whitespace is any sequence of one or more spaces and/or tabs. Comment
	2452	is any sequence of any characters, excluding newline. @var{string} is
	2453	the key sequence which invokes the action. @var{action} is the name of
	2454	an Info command. The characters in @var{string} are interpreted
	2455	literally or prefixed by a caret (@code{^}) to indicate a control
	2456	character. A backslash followed by certain characters specifies input
	2457	keystrokes as follows:
	2458
	2459	@table @code
	2460	@item \b
	2461	Backspace
	2462	@item \e
	2463	Escape (ESC)
	2464	@item \n
	2465	Newline
	2466	@item \r
	2467	Return
	2468	@item \t
	2469	Tab
	2470	@item \ku
	2471	Up arrow
	2472	@item \kd
	2473	Down arrow
	2474	@item \kl
	2475	Left arrow
	2476	@item \kr
	2477	Right arrow
	2478	@item \kU
	2479	Page Up
	2480	@item \kD
	2481	Page Down
	2482	@item \kh
	2483	HOME
	2484	@item \ke
	2485	END
	2486	@item \kx
	2487	Delete (DEL)
	2488	@item \m@var{x}
	2489	Meta-@var{x} where @var{x} is any character as described above.
	2490	@end table
	2491
	2492	Backslash followed by any other character indicates that character is to
	2493	be taken literally. Characters which must be preceded by a backslash
	2494	include caret, space, tab, and backslash itself.
	2495
	2496	@item #echo-area
	2497	Key bindings for the echo area.
	2498	The start of this section is indicated by a line containing just
	2499	@code{#echo-area} by itself. The rest of this section has a syntax
	2500	identical to that for the key definitions for the Info area, described
	2501	above.
	2502
	2503	@item #var
	2504	Variable initializations. The start of this section is indicated by a
	2505	line containing just @code{#var} by itself. Following this line is a
	2506	list of variable assignments, one per line. Each line consists of a
	2507	variable name (@pxref{Variables}) followed by @code{=} followed by a
	2508	value. There may be no white space between the variable name and the
	2509	@code{=}, and all characters following the @code{=}, including white
	2510	space, are included in the value.
	2511	@end table
	2512
	2513	Blank lines and lines starting with @code{#} are ignored, except for
	2514	the special section header lines.
	2515
	2516	Key bindings defined in the @file{.infokey} file take precedence over GNU
	2517	Info's default key bindings, whether or not @samp{--vi-keys} is used. A
	2518	default key binding may be disabled by overriding it in the @file{.infokey}
	2519	file with the action @code{invalid}. In addition, @emph{all} default
	2520	key bindings can be disabled by adding this line @emph{anywhere} in the
	2521	relevant section:
	2522
	2523	@example
	2524	#stop
	2525	@end example
	2526
	2527	This will cause GNU Info to ignore all the default key commands for that
	2528	section.
	2529
	2530	Beware: @code{#stop} can be dangerous. Since it disables all default
	2531	key bindings, you must supply enough new key bindings to enable all
	2532	necessary actions. Failure to bind any key to the @code{quit} command,
	2533	for example, can lead to frustration.
	2534
	2535	The order in which key bindings are defined in the @file{.infokey} file is
	2536	not important, except that the command summary produced by the
	2537	@code{get-help-window} command only displays the @emph{first} key that
	2538	is bound to each command.
	2539
	2540
	2541	@node Index
	2542	@appendix Index
	2543
	2544	@printindex cp
	2545
	2546	@bye

+24160

-0

doc/texinfo.texi less more

	0	\input texinfo.tex @c --texinfo--
	1
	2	@c Everything between the start/end of header lines will be passed by
	3	@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of
	4	@c header' node for more info.
	5	@c %**start of header
	6
	7	@c Automake requires this
	8	@setfilename texinfo.info
	9
	10	@c Automake automatically updates version.texi to @set VERSION and
	11	@c @set UPDATED to appropriate values.
	12	@include version.texi
	13	@settitle GNU Texinfo @value{VERSION}
	14
	15	@c Define a new index for command-line options.
	16	@defcodeindex op
	17
	18	@c Put everything except function (command, in this case) names in one
	19	@c index (arbitrarily chosen to be the concept index).
	20	@syncodeindex op cp
	21	@syncodeindex vr cp
	22	@syncodeindex pg cp
	23
	24	@c finalout
	25
	26	@comment %**end of header
	27
	28	@copying
	29	This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
	30	a documentation system that can produce both online information and a
	31	printed manual from a single source using semantic markup.
	32
	33	Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
	34	1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
	35	2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Free Software
	36	Foundation, Inc.
	37
	38	@quotation
	39	Permission is granted to copy, distribute and/or modify this document
	40	under the terms of the GNU Free Documentation License, Version 1.3 or
	41	any later version published by the Free Software Foundation; with no
	42	Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
	43	Texts. A copy of the license is included in the section entitled
	44	``GNU Free Documentation License''.
	45	@end quotation
	46	@end copying
	47
	48	@dircategory Texinfo documentation system
	49	@direntry
	50	* Texinfo: (texinfo). The GNU documentation format.
	51	* install-info: (texinfo)Invoking install-info. Update info/dir entries.
	52	* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
	53	* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo.
	54	* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
	55	* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
	56	* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
	57	* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
	58	@end direntry
	59
	60	@c Set smallbook if printing in smallbook format so the example of the
	61	@c smallbook font is actually written using smallbook; in bigbook, a kludge
	62	@c is used for TeX output. Do this through the -t option to texi2dvi,
	63	@c so this same source can be used for other paper sizes as well.
	64	@c smallbook
	65	@c set smallbook
	66	@c @@clear smallbook
	67
	68	@c If you like blank pages, add through texi2dvi -t.
	69	@c setchapternewpage odd
	70
	71	@set txiindexatsignignore
	72	@set txiindexbackslashignore
	73	@set txiindexlessthanignore
	74	@set txiindexhyphenignore
	75
	76
	77	@titlepage
	78	@title Texinfo
	79	@subtitle The GNU Documentation Format
	80	@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
	81
	82	@author Robert J. Chassell
	83	@author Richard M. Stallman
	84
	85	@c Include the Distribution inside the titlepage so
	86	@c that headings are turned off.
	87
	88	@page
	89	@vskip 0pt plus 1filll
	90	@insertcopying
	91
	92	@sp 1
	93	Published by the Free Software Foundation @*
	94	51 Franklin St, Fifth Floor @*
	95	Boston, MA 02110-1301 @*
	96	USA @*
	97	ISBN 1-882114-67-1 @c for version 4.0, September 1999.
	98	@c ISBN 1-882114-65-5 is for version 3.12, March 1998.
	99	@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
	100	@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
	101
	102	@sp 1
	103	Cover art by Etienne Suvasa.
	104	@end titlepage
	105
	106
	107	@summarycontents
	108	@contents
	109
	110
	111	@node Top
	112	@top Texinfo
	113
	114	This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
	115	a documentation system that can produce both online information and a
	116	printed manual from a single source using semantic markup.
	117
	118	@ifinfo
	119	The first part of this master menu lists the major nodes in this Info
	120	document, including the @@-command and concept indices. The rest of
	121	the menu lists all the lower-level nodes in the document.
	122	@end ifinfo
	123
	124
	125	@menu
	126	* Copying Conditions:: Your rights.
	127	* Overview:: Texinfo in brief.
	128	* Writing a Texinfo File:: Format of a Texinfo source file.
	129	* Beginning and Ending a File:: Beginning and end of a Texinfo file.
	130	* Nodes:: Writing nodes, the basic unit of Texinfo.
	131	* Chapter Structuring:: Creating chapters, sections, appendices, etc.
	132	* Cross References:: Writing cross-references.
	133	* Marking Text:: Marking words and phrases as code,
	134	keyboard input, meta-syntactic
	135	variables, and the like.
	136	* Quotations and Examples:: Block quotations, examples, etc.
	137	* Lists and Tables:: Itemized or numbered lists, and tables.
	138	* Special Displays:: Floating figures and footnotes.
	139	* Indices:: Creating indices.
	140	* Insertions:: Inserting @@-signs, braces, etc.
	141	* Breaks:: Forcing or preventing line and page breaks.
	142	* Definition Commands:: Describing functions and the like uniformly.
	143	* Internationalization:: Supporting languages other than English.
	144	* Conditionals:: Specifying text for only some output cases.
	145	* Defining New Texinfo Commands:: User-defined macros and aliases.
	146	* Include Files:: How to incorporate other Texinfo files.
	147	* Hardcopy:: Output for paper, with @TeX{}.
	148	* Generic Translator @command{texi2any}:: @command{texi2any}, an all-purpose converter.
	149	* Creating and Installing Info Files:: Details on Info output.
	150	* Generating HTML:: Details on HTML output.
	151	@c * texi2any Output Customization:: Fine tuning with initialization files.
	152
	153	Appendices
	154
	155	* @@-Command Details:: Details of the Texinfo @@-commands.
	156	* Tips:: Hints on how to write a Texinfo document.
	157	* Sample Texinfo Files:: Complete examples, including full texts.
	158	* Texinfo Mode:: Using the GNU Emacs Texinfo mode.
	159	* Headings:: How to write page headings and footings.
	160	* Catching Mistakes:: How to find mistakes in formatting.
	161	* Info Format Specification:: Technical details of the Info file format.
	162	* GNU Free Documentation License:: Copying this manual.
	163	* Command and Variable Index:: A menu containing commands and variables.
	164	* General Index:: A menu covering many topics.
	165
	166	@detailmenu
	167	--- The Detailed Node Listing ---
	168
	169	Overview of Texinfo
	170
	171	* Reporting Bugs:: Submitting effective bug reports.
	172	* Output Formats:: Overview of the supported output formats.
	173	* Info Files:: What is an Info file?
	174	* Printed Books:: Characteristics of a printed book or manual.
	175	* Adding Output Formats:: Man pages and implementing new formats.
	176	* History:: Acknowledgements, contributors and genesis.
	177
	178	Writing a Texinfo File
	179
	180	* Command Syntax:: @@-commands are used for formatting.
	181	* Conventions:: General rules for writing a Texinfo file.
	182	* Comments:: Writing comments and ignored text in general.
	183	* Minimum:: What a Texinfo file must have.
	184	* Short Sample:: A short sample Texinfo file.
	185
	186	Beginning and Ending a Texinfo File
	187
	188	* Sample Beginning:: A sample beginning for a Texinfo file.
	189	* Texinfo File Header:: The first lines.
	190	* Document Permissions:: Ensuring your manual is free.
	191	* Titlepage & Copyright Page:: Creating the title and copyright pages.
	192	* Contents:: How to create a table of contents.
	193	* The Top Node:: Creating the `Top' node and master menu.
	194	* Global Document Commands:: Affecting formatting throughout.
	195	* Ending a File:: What is at the end of a Texinfo file?
	196
	197	Texinfo File Header
	198
	199	* First Line:: The first line of a Texinfo file.
	200	* Start of Header:: Formatting a region requires this.
	201	* @code{@@setfilename}:: Tell Info the name of the Info file.
	202	* @code{@@settitle}:: Create a title for the printed work.
	203	* End of Header:: Formatting a region requires this.
	204
	205	Document Permissions
	206
	207	* @code{@@copying}:: Declare the document's copying permissions.
	208	* @code{@@insertcopying}:: Where to insert the permissions.
	209
	210	Title and Copyright Pages
	211
	212	* @code{@@titlepage}:: Create a title for the printed document.
	213	* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
	214	and @code{@@sp} commands.
	215	* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
	216	and @code{@@author} commands.
	217	* Copyright:: How to write the copyright notice and
	218	include copying permissions.
	219	* Heading Generation:: Turn on page headings after the title and
	220	copyright pages.
	221
	222	The `Top' Node and Master Menu
	223
	224	* Top Node Example::
	225	* Master Menu Parts::
	226
	227	Global Document Commands
	228
	229	* @code{@@documentdescription}:: Document summary for the HTML output.
	230	* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
	231	* @code{@@headings}:: An option for turning headings on and off
	232	and double or single sided printing.
	233	* @code{@@paragraphindent}:: Specify paragraph indentation.
	234	* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
	235	* @code{@@exampleindent}:: Specify environment indentation.
	236
	237	Nodes
	238
	239	* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
	240	* Node Names:: How to choose node names.
	241	* Writing a Node:: How to write an @code{@@node} line.
	242	* Node Line Requirements:: Keep names unique.
	243	* First Node:: How to write a `Top' node.
	244	* @code{@@top} Command:: How to use the @code{@@top} command.
	245	* Node Menu Illustration:: A diagram, and sample nodes and menus.
	246	* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
	247	* Menus:: Listing subordinate nodes.
	248
	249	Menus
	250
	251	* Writing a Menu:: What is a menu?
	252	* Menu Example:: Two and three part menu entries.
	253	* Menu Location:: Menus go at the ends of nodes.
	254	* Menu Parts:: A menu entry has three parts.
	255	* Less Cluttered Menu Entry:: Two part menu entry.
	256	* Other Info Files:: How to refer to a different Info file.
	257
	258	Chapter Structuring
	259
	260	* Tree Structuring:: A manual is like an upside down tree @dots{}
	261	* Structuring Command Types:: How to divide a manual into parts.
	262	* @code{@@chapter}:: Chapter structuring.
	263	* @code{@@unnumbered @@appendix}::
	264	* @code{@@majorheading @@chapheading}::
	265	* @code{@@section}::
	266	* @code{@@unnumberedsec @@appendixsec @@heading}::
	267	* @code{@@subsection}::
	268	* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
	269	* @code{@@subsubsection}:: Commands for the lowest level sections.
	270	* @code{@@part}:: Collections of chapters.
	271	* Raise/lower sections:: How to change commands' hierarchical level.
	272
	273	Cross-references
	274
	275	* References:: What cross-references are for.
	276	* Cross Reference Commands:: A summary of the different commands.
	277	* Cross Reference Parts:: A cross-reference has several parts.
	278	* @code{@@xref}:: Begin a reference with `See' @dots{}
	279	* Referring to a Manual as a Whole:: Refer to an entire manual.
	280	* @code{@@ref}:: A reference for the last part of a sentence.
	281	* @code{@@pxref}:: How to write a parenthetical cross-reference.
	282	* @code{@@anchor}:: Defining arbitrary cross-reference targets
	283	* @code{@@inforef}:: How to refer to an Info-only file.
	284	* @code{@@url}:: How to refer to a uniform resource locator.
	285	* @code{@@cite}:: How to refer to books not in the Info system.
	286
	287	@code{@@xref}
	288
	289	* One Argument:: @code{@@xref} with one argument.
	290	* Two Arguments:: @code{@@xref} with two arguments.
	291	* Three Arguments:: @code{@@xref} with three arguments.
	292	* Four and Five Arguments:: @code{@@xref} with four and five arguments.
	293
	294	@code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
	295
	296	* @code{@@url} Examples:: Examples of using all the forms of @code{@@url}.
	297	* URL Line Breaking:: How lines are broken within @code{@@url} text.
	298	* @code{@@url} PDF Output Format:: A special option to hide links in PDF output.
	299	* PDF Colors:: Colorizing urls and other links in PDF output.
	300
	301	Marking Text, Words and Phrases
	302
	303	* Indicating:: How to indicate definitions, files, etc.
	304	* Emphasis:: How to emphasize text.
	305
	306	Indicating Definitions, Commands, etc.
	307
	308	* Useful Highlighting:: Highlighting provides useful information.
	309	* @code{@@code}:: Indicating program code.
	310	* @code{@@kbd}:: Showing keyboard input.
	311	* @code{@@key}:: Specifying keys.
	312	* @code{@@samp}:: Indicating a literal sequence of characters.
	313	* @code{@@verb}:: Indicating a verbatim sequence of characters.
	314	* @code{@@var}:: Indicating metasyntactic variables.
	315	* @code{@@env}:: Indicating environment variables.
	316	* @code{@@file}:: Indicating file names.
	317	* @code{@@command}:: Indicating command names.
	318	* @code{@@option}:: Indicating option names.
	319	* @code{@@dfn}:: Specifying definitions.
	320	* @code{@@abbr}:: Indicating abbreviations.
	321	* @code{@@acronym}:: Indicating acronyms.
	322	* @code{@@indicateurl}:: Indicating an example url.
	323	* @code{@@email}:: Indicating an electronic mail address.
	324
	325	Emphasizing Text
	326
	327	* @code{@@emph @@strong}:: How to emphasize text in Texinfo.
	328	* Smallcaps:: How to use the small caps font.
	329	* Fonts:: Various font commands for printed output.
	330
	331	Quotations and Examples
	332
	333	* Block Enclosing Commands:: Different constructs for different purposes.
	334	* @code{@@quotation}:: Writing a quotation.
	335	* @code{@@indentedblock}:: Block of text indented on left.
	336	* @code{@@example}:: Writing an example in a fixed-width font.
	337	* @code{@@verbatim}:: Writing a verbatim example.
	338	* @code{@@verbatiminclude}:: Including a file verbatim.
	339	* @code{@@lisp}:: Illustrating Lisp code.
	340	* @code{@@small@dots{}}:: Examples in a smaller font.
	341	* @code{@@display}:: Writing an example in the current font.
	342	* @code{@@format}:: Writing an example without narrowed margins.
	343	* @code{@@exdent}:: Undo indentation on a line.
	344	* @code{@@flushleft @@flushright}:: Pushing text flush left or flush right.
	345	* @code{@@raggedright}:: Avoiding justification on the right.
	346	* @code{@@noindent}:: Preventing paragraph indentation.
	347	* @code{@@indent}:: Forcing paragraph indentation.
	348	* @code{@@cartouche}:: Drawing rounded rectangles around text.
	349
	350	Lists and Tables
	351
	352	* Introducing Lists:: Texinfo formats lists for you.
	353	* @code{@@itemize}:: How to construct a simple list.
	354	* @code{@@enumerate}:: How to construct a numbered list.
	355	* Two-column Tables:: How to construct a two-column table.
	356	* Multi-column Tables:: How to construct generalized tables.
	357
	358	Making a Two-column Table
	359
	360	* @code{@@table}:: How to construct a two-column table.
	361	* @code{@@ftable @@vtable}:: Automatic indexing for two-column tables.
	362	* @code{@@itemx}:: How to put more entries in the first column.
	363
	364	@code{@@multitable}: Multi-column Tables
	365
	366	* Multitable Column Widths:: Defining multitable column widths.
	367	* Multitable Rows:: Defining multitable rows, with examples.
	368
	369	Special Displays
	370
	371	* Floats:: Figures, tables, and the like.
	372	* Images:: Including graphics and images.
	373	* Footnotes:: Writing footnotes.
	374
	375	Floats
	376
	377	* @code{@@float}:: Producing floating material.
	378	* @code{@@caption @@shortcaption}:: Specifying descriptions for floats.
	379	* @code{@@listoffloats}:: A table of contents for floats.
	380
	381	Inserting Images
	382
	383	* Image Syntax::
	384	* Image Scaling::
	385
	386	Footnotes
	387
	388	* Footnote Commands:: How to write a footnote in Texinfo.
	389	* Footnote Styles:: Controlling how footnotes appear in Info.
	390
	391	Indices
	392
	393	* Index Entries:: Choose different words for index entries.
	394	* Predefined Indices:: Use different indices for different kinds
	395	of entries.
	396	* Indexing Commands:: How to make an index entry.
	397	* Advanced Indexing:: Advanced indexing commands.
	398	* Printing Indices & Menus:: How to print an index in hardcopy and
	399	generate index menus in Info.
	400	* Combining Indices:: How to combine indices.
	401	* New Indices:: How to define your own indices.
	402
	403	Combining Indices
	404
	405	* @code{@@syncodeindex}:: How to merge two indices, using @code{@@code}
	406	font for the merged-from index.
	407	* @code{@@synindex}:: How to merge two indices, using the
	408	roman font for the merged-from index.
	409
	410	Special Insertions
	411
	412	* Special Characters:: Inserting @@ @{@} , \ # &
	413	* Inserting Quote Characters:: Inserting left and right quotes, in code.
	414	* Inserting Space:: Inserting the right amount of whitespace.
	415	* Inserting Accents:: Inserting accents and special characters.
	416	* Inserting Quotation Marks:: Inserting quotation marks.
	417	* Inserting Subscripts and Superscripts:: Inserting sub/superscripts.
	418	* Inserting Math:: Formatting mathematical expressions.
	419	* Glyphs for Text:: Inserting dots, bullets, currencies, etc.
	420	* Glyphs for Programming:: Indicating results of evaluation,
	421	expansion of macros, errors, etc.
	422	* Inserting Unicode:: Inserting a Unicode character by code point.
	423
	424	Special Characters: Inserting @@ @{@} , \ # &
	425
	426	* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}.
	427	* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}.
	428	* Inserting a Comma:: , and @code{@@comma@{@}}.
	429	* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}.
	430	* Inserting a Hashsign:: # and @code{@@hashchar@{@}}.
	431	* Inserting an Ampersand:: & and @code{@@ampchar@{@}}.
	432
	433	Inserting Space
	434
	435	* Multiple Spaces:: Inserting multiple spaces.
	436	* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
	437	* Ending a Sentence:: Sometimes it does.
	438	* @code{@@frenchspacing}:: Specifying end-of-sentence spacing.
	439	* @code{@@dmn}:: Formatting a dimension.
	440
	441	Glyphs for Text
	442
	443	* @code{@@TeX @@LaTeX}:: The @TeX{} logos.
	444	* @code{@@copyright}:: The copyright symbol (c in a circle).
	445	* @code{@@registeredsymbol}:: The registered symbol (R in a circle).
	446	* @code{@@dots}:: How to insert ellipses: @dots{} and @enddots{}
	447	* @code{@@bullet}:: How to insert a bullet: @bullet{}
	448	* @code{@@euro}:: How to insert the euro currency symbol.
	449	* @code{@@pounds}:: How to insert the pounds currency symbol.
	450	* @code{@@textdegree}:: How to insert the degrees symbol.
	451	* @code{@@minus}:: How to insert a minus sign.
	452	* @code{@@geq @@leq}:: How to insert greater/less-than-or-equal signs.
	453
	454	Glyphs for Programming
	455
	456	* Glyphs Summary::
	457	* @code{@@result}:: How to show the result of expression.
	458	* @code{@@expansion}:: How to indicate an expansion.
	459	* @code{@@print}:: How to indicate generated output.
	460	* @code{@@error}:: How to indicate an error message.
	461	* @code{@@equiv}:: How to indicate equivalence.
	462	* @code{@@point}:: How to indicate the location of point.
	463	* Click Sequences:: Inserting GUI usage sequences.
	464
	465	Forcing and Preventing Breaks
	466
	467	* Break Commands:: Summary of break-related commands.
	468	* Line Breaks:: Forcing line breaks.
	469	* @code{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
	470	* @code{@@allowcodebreaks}:: Controlling line breaks within @@code text.
	471	* @code{@@w}:: Preventing unwanted line breaks in text.
	472	* @code{@@tie}:: Inserting an unbreakable but varying space.
	473	* @code{@@sp}:: Inserting blank lines.
	474	* @code{@@page}:: Forcing the start of a new page.
	475	* @code{@@group}:: Preventing unwanted page breaks.
	476	* @code{@@need}:: Another way to prevent unwanted page breaks.
	477
	478	Definition Commands
	479
	480	* Def Cmd Template:: Writing descriptions using definition commands.
	481	* Def Cmd Continuation Lines:: Continuing the heading over source lines.
	482	* Optional Arguments:: Handling optional and repeated arguments.
	483	* @code{@@deffnx}:: Group two or more `first' lines.
	484	* Def Cmds in Detail:: Reference for all the definition commands.
	485	* Def Cmd Conventions:: Conventions for writing definitions.
	486	* Sample Function Definition:: An example.
	487
	488	The Definition Commands
	489
	490	* Functions Commands:: Commands for functions and similar entities.
	491	* Variables Commands:: Commands for variables and similar entities.
	492	* Typed Functions:: Commands for functions in typed languages.
	493	* Typed Variables:: Commands for variables in typed languages.
	494	* Data Types:: The definition command for data types.
	495	* Abstract Objects:: Commands for object-oriented programming.
	496
	497	Object-Oriented Programming
	498
	499	* Variables: Object-Oriented Variables.
	500	* Methods: Object-Oriented Methods.
	501
	502	Internationalization
	503
	504	* @code{@@documentlanguage}:: Declaring the current language.
	505	* @code{@@documentencoding}:: Declaring the input encoding.
	506
	507	Conditionally Visible Text
	508
	509	* Conditional Commands:: Text for a given format.
	510	* Conditional Not Commands:: Text for any format other than a given one.
	511	* Raw Formatter Commands:: Using raw formatter commands.
	512	* Inline Conditionals:: Brace-delimited conditional text.
	513	* @code{@@set @@clear @@value}:: Variable tests and substitutions.
	514	* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
	515	* Conditional Nesting:: Using conditionals inside conditionals.
	516
	517	Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value}
	518
	519	* @code{@@set @@value}:: Expand a flag variable to a string.
	520	* @code{@@ifset @@ifclear}:: Format a region if a flag is set.
	521	* @code{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals.
	522	* @code{@@value} Example:: An easy way to update edition information.
	523
	524	Defining New Texinfo Commands
	525
	526	* Defining Macros:: Defining and undefining new commands.
	527	* Invoking Macros:: Using a macro, once you've defined it.
	528	* Macro Details:: Limitations of Texinfo macros.
	529	* @code{@@alias}:: Command aliases.
	530	* @code{@@definfoenclose}:: Customized highlighting.
	531	* External Macro Processors:: @code{#line} directives.
	532
	533	External Macro Processors: Line Directives
	534
	535	* @samp{#line} Directive::
	536	* TeX: @samp{#line} and @TeX{}.
	537	* Syntax: @samp{#line} Syntax Details.
	538
	539	Include Files
	540
	541	* Using Include Files:: How to use the @code{@@include} command.
	542	* @code{texinfo-multiple-files-update}:: How to create and update nodes and
	543	menus when using included files.
	544	* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
	545	* Sample Include File:: A sample outer file with included files
	546	within it; and a sample included file.
	547	* Include Files Evolution:: How use of the @code{@@include} command
	548	has changed over time.
	549
	550	Formatting and Printing Hardcopy
	551
	552	* Use @TeX{}:: Use @TeX{} to format for hardcopy.
	553	* Format with @command{texi2dvi}:: The simplest way to format.
	554	* Format with @command{tex}/@command{texindex}:: Formatting with explicit shell commands.
	555	* Print with @command{lpr}:: How to print.
	556	* Within Emacs:: How to format and print from an Emacs shell.
	557	* Texinfo Mode Printing:: How to format and print in Texinfo mode.
	558	* Compile-Command:: How to print using Emacs's compile command.
	559	* Requirements Summary:: @TeX{} formatting requirements summary.
	560	* Preparing for @TeX{}:: What to do before you use @TeX{}.
	561	* Overfull hboxes:: What are and what to do with overfull hboxes.
	562	* @code{@@smallbook}:: How to print small format books and manuals.
	563	* A4 Paper:: How to print on A4 or A5 paper.
	564	* @code{@@pagesizes}:: How to print with customized page sizes.
	565	* Magnification:: How to print scaled up output.
	566	* PDF Output:: Portable Document Format output.
	567	* Obtaining @TeX{}:: How to obtain @TeX{}.
	568
	569	Format with @command{tex}/@command{texindex}
	570
	571	* Formatting Partial Documents::
	572	* Details of @command{texindex}::
	573
	574	@command{texi2any}: The Generic Translator for Texinfo
	575
	576	* Reference Implementation:: @command{texi2any}: the reference implementation.
	577	* Invoking @command{texi2any}:: Running the translator from a shell.
	578	* @command{texi2any} Environment Variables::
	579	* @command{texi2any} Printed Output:: Calling @command{texi2dvi}.
	580	* Pointer Validation:: How to check that pointers point somewhere.
	581	* Customization Variables:: Configuring @command{texi2any}.
	582	* Internationalization of Document Strings:: Translating program-inserted text.
	583	* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo.
	584	* @command{texi2html}:: An ancestor of @command{texi2any}.
	585
	586	Customization Variables
	587
	588	* Commands: Customization Variables for @@-Commands.
	589	* Options: Customization Variables and Options.
	590	* HTML: HTML Customization Variables.
	591	* Other: Other Customization Variables.
	592
	593	Creating and Installing Info Files
	594
	595	* Creating an Info File::
	596	* Installing an Info File::
	597
	598	Creating an Info File
	599
	600	* @command{makeinfo} Advantages:: @command{makeinfo} provides better error checking.
	601	* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
	602	* @code{texinfo-format} commands:: Two Info formatting commands written
	603	in Emacs Lisp are an alternative
	604	to @code{makeinfo}.
	605	* Batch Formatting:: How to format for Info in Emacs batch mode.
	606	* Tag and Split Files:: How tagged and split files help Info
	607	to run better.
	608
	609	Installing an Info File
	610
	611	* Directory File:: The top level menu for all Info files.
	612	* New Info File:: Listing a new Info file.
	613	* Other Info Directories:: How to specify Info files that are
	614	located in other directories.
	615	* Installing Dir Entries:: How to specify what menu entry to add
	616	to the Info directory.
	617	* Invoking @command{install-info}:: @code{install-info} options.
	618
	619	Generating HTML
	620
	621	* HTML Translation:: Details of the HTML output.
	622	* HTML Splitting:: How HTML output is split.
	623	* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
	624	* HTML Xref:: Cross-references in HTML output.
	625
	626	HTML Cross-references
	627
	628	* Link Basics: HTML Xref Link Basics.
	629	* Node Expansion: HTML Xref Node Name Expansion.
	630	* Command Expansion: HTML Xref Command Expansion.
	631	* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
	632	* Mismatch: HTML Xref Mismatch.
	633	* Configuration: HTML Xref Configuration. htmlxref.cnf.
	634
	635	Sample Texinfo Files
	636
	637	* Short Sample Texinfo File::
	638	* GNU Sample Texts::
	639	* Verbatim Copying License::
	640	* All-permissive Copying License::
	641
	642	Using Texinfo Mode
	643
	644	* Texinfo Mode Overview:: How Texinfo mode can help you.
	645	* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
	646	purpose editing features.
	647	* Inserting:: How to insert frequently used @@-commands.
	648	* Showing the Structure:: How to show the structure of a file.
	649	* Updating Nodes and Menus:: How to update or create new nodes and menus.
	650	* Info Formatting:: How to format for Info.
	651	* Printing:: How to format and print part or all of a file.
	652	* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
	653
	654	Updating Nodes and Menus
	655
	656	* Updating Commands:: Five major updating commands.
	657	* Updating Requirements:: How to structure a Texinfo file for
	658	using the updating command.
	659	* Other Updating Commands:: How to indent descriptions, insert
	660	missing nodes lines, and update
	661	nodes in sequence.
	662
	663	Page Headings
	664
	665	* Headings Introduced:: Conventions for using page headings.
	666	* Heading Format:: Standard page heading formats.
	667	* Heading Choice:: How to specify the type of page heading.
	668	* Custom Headings:: How to create your own headings and footings.
	669
	670	Catching Mistakes
	671
	672	* @command{makeinfo} Preferred:: @code{makeinfo} finds errors.
	673	* Debugging with Info:: How to catch errors with Info formatting.
	674	* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
	675	* Using @code{texinfo-show-structure}:: How to use @code{texinfo-show-structure}.
	676	* Using @code{occur}:: How to list all lines containing a pattern.
	677	* Running @code{Info-validate}:: How to find badly referenced nodes.
	678
	679	Finding Badly Referenced Nodes
	680
	681	* Using @code{Info-validate}:: How to run @code{Info-validate}.
	682	* Unsplit:: How to create an unsplit file.
	683	* Tagifying:: How to tagify a file.
	684	* Splitting:: How to split a file manually.
	685
	686	Info Format Specification
	687
	688	* General: Info Format General Layout.
	689	* Text: Info Format Text Constructs.
	690
	691	Info Format General Layout
	692
	693	* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals.
	694	* Preamble: Info Format Preamble.
	695	* Indirect: Info Format Indirect Table.
	696	* Tag table: Info Format Tag Table.
	697	* Local variables: Info Format Local Variables.
	698	* Regular nodes: Info Format Regular Nodes.
	699
	700	Info Format Text Constructs
	701
	702	* Info Format Menu::
	703	* Info Format Image::
	704	* Info Format Printindex::
	705	* Info Format Cross Reference::
	706
	707	@end detailmenu
	708	@end menu
	709
	710	@c Reward readers for getting to the end of the menu :).
	711	@c Contributed by Arnold Robbins.
	712	@quotation
	713	Documentation is like sex: when it is good, it is very, very good; and
	714	when it is bad, it is better than nothing.
	715	---Dick Brandon
	716	@end quotation
	717
	718
	719	@node Copying Conditions
	720	@unnumbered Texinfo Copying Conditions
	721	@cindex Copying conditions
	722	@cindex Conditions for copying Texinfo
	723	@cindex Free software
	724	@cindex Libre software
	725
	726	GNU Texinfo is @dfn{free software}; this means that everyone is free
	727	to use it and free to redistribute it on certain conditions. Texinfo
	728	is not in the public domain; it is copyrighted and there are
	729	restrictions on its distribution, but these restrictions are designed
	730	to permit everything that a good cooperating citizen would want to do.
	731	What is not allowed is to try to prevent others from further sharing
	732	any version of Texinfo that they might get from you.
	733
	734	Specifically, we want to make sure that you have the right to give away
	735	copies of the programs that relate to Texinfo, that you receive source
	736	code or else can get it if you want it, that you can change these
	737	programs or use pieces of them in new free programs, and that you know
	738	you can do these things.
	739
	740	To make sure that everyone has such rights, we have to forbid you to
	741	deprive anyone else of these rights. For example, if you distribute
	742	copies of the Texinfo related programs, you must give the recipients all
	743	the rights that you have. You must make sure that they, too, receive or
	744	can get the source code. And you must tell them their rights.
	745
	746	Also, for our own protection, we must make certain that everyone finds
	747	out that there is no warranty for the programs that relate to Texinfo.
	748	If these programs are modified by someone else and passed on, we want
	749	their recipients to know that what they have is not what we distributed,
	750	so that any problems introduced by others will not reflect on our
	751	reputation.
	752
	753	The precise conditions of the licenses for the programs currently
	754	being distributed that relate to Texinfo are found in the General
	755	Public Licenses that accompany them. This manual is covered by the
	756	GNU Free Documentation License (@pxref{GNU Free Documentation
	757	License}).
	758
	759
	760	@node Overview
	761	@chapter Overview of Texinfo
	762	@cindex Overview of Texinfo
	763	@cindex Texinfo overview
	764	@cindex Using Texinfo in general
	765	@cindex Texinfo, introduction to
	766	@cindex Introduction to Texinfo
	767	@anchor{Using Texinfo} @c merged node
	768
	769	@dfn{Texinfo} is a documentation system that uses a single source file
	770	to produce both online information and printed output. This means
	771	that instead of writing several different documents, one for each output
	772	format, you need only write one document.
	773
	774	Using Texinfo, you can create a printed document (via the @TeX{}
	775	typesetting system) in PDF or PostScript format, including chapters,
	776	sections, cross-references, and indices. From the same Texinfo source
	777	file, you can create an HTML output file suitable for use with a web
	778	browser, you can create an Info file with special features to make
	779	browsing documentation easy, and also create a Docbook file or a
	780	transliteration to XML format.
	781
	782	@cindex Source file format
	783	@cindex Semantic markup
	784	A Texinfo source file is a plain text file containing text interspersed
	785	with @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
	786	Texinfo processors what to do. Texinfo's markup commands are almost
	787	entirely @dfn{semantic}; that is, they specify the intended meaning
	788	of text in the document, rather than physical formatting instructions.
	789	You can edit a Texinfo file with any text editor, but it is especially
	790	convenient to use GNU Emacs since that editor has a special mode,
	791	called Texinfo mode, that provides various Texinfo-related features.
	792	(@xref{Texinfo Mode}.)
	793
	794	@cindex Limited scope of Texinfo
	795	Texinfo was devised specifically for the purpose of writing software
	796	documentation and manuals. If you want to write a good manual for
	797	your program, Texinfo has many features which we hope will make your
	798	job easier. However, it provides almost no commands for controlling
	799	the final formatting. Texinfo is not intended to be a general-purpose
	800	formatting program, so if you need to lay out a newspaper, devise a
	801	glossy magazine ad, or follow the exact formatting requirements of
	802	a publishing house, Texinfo may not be the simplest tool.
	803
	804	@cindex Spelling of Texinfo
	805	@cindex Pronunciation of Texinfo
	806	Spell ``Texinfo'' with a capital ``T'' and the other letters in
	807	lowercase. The first syllable of ``Texinfo'' is pronounced like
	808	``speck'', not ``hex''. This odd pronunciation is derived from the
	809	pronunciation of @TeX{}. Pronounce @TeX{} as if the @samp{X} were
	810	the last sound in the name `Bach'. In the word @TeX{}, the @samp{X}
	811	is, rather than the English letter ``ex'', actually the Greek letter
	812	``chi''.
	813
	814	Texinfo is the official documentation format of the GNU project.
	815	More information, including manuals for GNU packages, is available
	816	at the @uref{http://www.gnu.org/doc/, GNU documentation web page}.
	817
	818	@menu
	819	* Reporting Bugs:: Submitting effective bug reports.
	820	* Output Formats:: Overview of the supported output formats.
	821	* Info Files:: What is an Info file?
	822	* Printed Books:: Characteristics of a printed book or manual.
	823	* Adding Output Formats:: Man pages and implementing new formats.
	824	* History:: Acknowledgements, contributors and genesis.
	825	@end menu
	826
	827
	828	@node Reporting Bugs
	829	@section Reporting Bugs
	830
	831	@cindex Bugs, reporting
	832	@cindex Suggestions for Texinfo, making
	833	@cindex Reporting bugs
	834	We welcome bug reports and suggestions for any aspect of the Texinfo
	835	system: programs, documentation, installation, etc. Please email them
	836	to @email{bug-texinfo@@gnu.org}. You can get the latest version of
	837	Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}.
	838
	839	@cindex Checklist for bug reports
	840	For bug reports, please include enough information for the maintainers
	841	to reproduce the problem. Generally speaking, that means:
	842
	843	@itemize @bullet
	844	@item The version number of Texinfo and the program(s) or manual(s) involved.
	845	@item The contents of any input files necessary to reproduce the bug.
	846	@item Precisely how you ran any program(s) involved.
	847	@item A description of the problem and samples of any erroneous output.
	848	@item Hardware and operating system names and versions.
	849	@item Anything else that you think would be helpful.
	850	@end itemize
	851
	852	When in doubt whether something is needed or not, include it. It's
	853	better to include too much than to leave out something important.
	854
	855	It is critical to send an actual input file that reproduces the
	856	problem. What's not critical is to ``narrow down'' the example to the
	857	smallest possible input---the actual input with which you discovered
	858	the bug will suffice. (Of course, if you do do experiments, the
	859	smaller the input file, the better.)
	860
	861	@cindex Patches, contributing
	862	Patches are most welcome; if possible, please make them with
	863	@samp{@w{diff -c}} (@pxref{Top,,, diffutils, Comparing and Merging
	864	Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,,
	865	emacs, The GNU Emacs Manual}), and follow the existing coding style.
	866
	867
	868	@node Output Formats
	869	@section Output Formats
	870	@cindex Output formats
	871	@cindex Back-end output formats
	872
	873	Here is a brief overview of the output formats currently supported by
	874	Texinfo.
	875
	876	@table @asis
	877	@item Info
	878	@cindex Info output, overview
	879	(Generated via @command{makeinfo}.) Info format is mostly a plain
	880	text transliteration of the Texinfo source. It adds a few control
	881	characters to provide navigational information for cross-references,
	882	indices, and so on. The Emacs Info subsystem (@pxref{Top,,, info,
	883	Info}), and the standalone @command{info} program (@pxref{Top,,,
	884	info-stnd, GNU Info}), among others, can read these files. @xref{Info
	885	Files}, and @ref{Creating and Installing Info Files}.
	886
	887	@item Plain text
	888	@cindex Plain text output, overview
	889	(Generated via @command{makeinfo --plaintext}.) This is almost the
	890	same as Info output with the navigational control characters are
	891	omitted.
	892
	893	@item HTML
	894	@cindex HTML output, overview
	895	@cindex W3 consortium
	896	@cindex Mozilla
	897	@cindex Lynx
	898	@cindex Emacs-W3
	899	(Generated via @command{makeinfo --html}.) HTML, standing for Hyper
	900	Text Markup Language, has become the most commonly used language for
	901	writing documents on the World Wide Web. Web browsers, such as
	902	Mozilla, Lynx, and Emacs-W3, can render this language online. There
	903	are many versions of HTML, both different standards and
	904	browser-specific variations. @command{makeinfo} tries to use a subset
	905	of the language that can be interpreted by any common browser,
	906	intentionally not using many newer or less widely-supported tags.
	907	Although the native output is thus rather plain, it can be customized
	908	at various levels, if desired. For details of the HTML language and
	909	much related information, see @uref{http://www.w3.org/MarkUp/}.
	910	@xref{Generating HTML}.
	911
	912	@item DVI
	913	@cindex DVI output, overview
	914	@pindex dvips
	915	@pindex xdvi
	916	(Generated via @command{texi2dvi}.) The DeVIce Independent binary
	917	format is output by the @TeX{} typesetting program
	918	(@uref{http://tug.org}). This is then read by a DVI `driver', which
	919	knows the actual device-specific commands that can be viewed or
	920	printed, notably Dvips for translation to PostScript (@pxref{Top,,,
	921	dvips, Dvips}) and Xdvi for viewing on an X display
	922	(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}.
	923	(Be aware that the Texinfo language is very different from and much
	924	stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{},
	925	Con@TeX{}t, etc.)
	926
	927	@item PostScript
	928	@cindex PostScript output, overview
	929	(Generated via @command{texi2dvi --ps}.) PostScript is a page
	930	description language that became widely used around 1985 and is still
	931	used today. @uref{http://en.wikipedia.org/wiki/PostScript} gives a
	932	basic description and more preferences. By default, Texinfo uses the
	933	@command{dvips} program to convert @TeX{}'s DVI output to PostScript.
	934	@xref{Top,,, dvips, Dvips}.
	935
	936	@item PDF
	937	@cindex PDF output, overview
	938	@cindex Beebe, Nelson
	939	(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
	940	format was developed by Adobe Systems for portable document
	941	interchange, based on their previous PostScript language. It can
	942	represent the exact appearance of a document, including fonts and
	943	graphics, and supporting arbitrary scaling. It is intended to be
	944	platform-independent and easily viewable, among other design goals;
	945	@uref{http://en.wikipedia.org/wiki/Portable_Document_Format} and
	946	@uref{http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some
	947	background. By default, Texinfo uses the @command{pdftex} program, an
	948	extension of @TeX{}, to output PDF; see
	949	@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
	950
	951	@item Docbook
	952	@cindex Docbook output, overview
	953	@cindex XML Docbook output, overview
	954	(Generated via @command{makeinfo --docbook}.) This is an XML-based
	955	format developed some years ago, primarily for technical
	956	documentation. It therefore bears some resemblance, in broad
	957	outline, to Texinfo. See @uref{http://www.docbook.org}. Various
	958	converters from Docbook @emph{to} Texinfo have also been developed;
	959	see the Texinfo web pages.
	960
	961	@item XML
	962	@cindex XML Texinfo output, overview
	963	@cindex Texinfo XML output, overview
	964	@cindex DTD, for Texinfo XML
	965	@pindex texinfo.dtd
	966	@pindex txixml2texi
	967	(Generated via @command{makeinfo --xml}.) XML is a generic syntax
	968	specification usable for any sort of content (a reference is at
	969	@uref{http://www.w3.org/XML}). The @command{makeinfo} XML output,
	970	unlike all the other output formats, is a transliteration of the
	971	Texinfo source rather than processed output. That is, it translates
	972	the Texinfo markup commands into XML syntax, for further processing by
	973	XML tools. The XML contains enough information to recreate the
	974	original content, except for syntactic constructs such as Texinfo
	975	macros and conditionals. The Texinfo source distribution includes a
	976	utility script @file{txixml2texi} to do that backward transformation.
	977
	978	The details of the output syntax are defined in an XML DTD as usual,
	979	which is contained in a file @file{texinfo.dtd} included in the
	980	Texinfo source distribution and available via the Texinfo web pages.
	981	Texinfo XML files, and XML files in general, cannot be viewed in
	982	typical web browsers; they won't follow the DTD reference and as a
	983	result will simply report a (misleading) syntax error.
	984	@end table
	985
	986
	987	@node Info Files
	988	@section Info Files
	989	@cindex Info files
	990
	991	As mentioned above, Info format is mostly a plain text transliteration
	992	of the Texinfo source, with the addition of a few control characters
	993	to separate nodes and provide navigational information, so that
	994	Info-reading programs can operate on it.
	995
	996	Info files are nearly always created by processing a Texinfo source
	997	document. @command{makeinfo}, also known as @command{texi2any}, is
	998	the principal command that converts a Texinfo file into an Info file;
	999	@pxref{Generic Translator @command{texi2any}}.
	1000
	1001	Generally, you enter an Info file through a node that by convention is
	1002	named `Top'. This node normally contains just a brief summary of the
	1003	file's purpose, and a large menu through which the rest of the file is
	1004	reached. From this node, you can either traverse the file
	1005	systematically by going from node to node, or you can go to a specific
	1006	node listed in the main menu, or you can search the index menus and then
	1007	go directly to the node that has the information you want. Alternatively,
	1008	with the standalone Info program, you can specify specific menu items on
	1009	the command line (@pxref{Top,,, info, Info}).
	1010
	1011	If you want to read through an Info file in sequence, as if it were a
	1012	printed manual, you can hit @key{SPC} repeatedly, or you get the whole
	1013	file with the advanced Info command @kbd{g *}. (@xref{Advanced,,
	1014	Advanced Info commands, info, Info}.)
	1015
	1016	The @file{dir} file in the @file{info} directory serves as the
	1017	departure point for the whole Info system. From it, you can reach the
	1018	`Top' nodes of each of the documents in a complete Info system.
	1019
	1020	@cindex URI syntax for Info
	1021	If you wish to refer to an Info file via a URI, you can use the
	1022	(unofficial) syntax exemplified by the following. This works with
	1023	Emacs/W3, for example:
	1024	@example
	1025	info:emacs#Dissociated%20Press
	1026	info:///usr/info/emacs#Dissociated%20Press
	1027	info://localhost/usr/info/emacs#Dissociated%20Press
	1028	@end example
	1029
	1030	The @command{info} program itself does not follow URIs of any kind.
	1031
	1032
	1033	@node Printed Books
	1034	@section Printed Books
	1035	@cindex Printed book and manual characteristics
	1036	@cindex Manual characteristics, printed
	1037	@cindex Book characteristics, printed
	1038	@cindex Texinfo printed book characteristics
	1039	@cindex Characteristics, printed books or manuals
	1040
	1041	@cindex Knuth, Donald
	1042	A Texinfo file can be formatted and typeset as a printed book or
	1043	manual. To do this, you need @TeX{}, a sophisticated typesetting
	1044	program written by Donald Knuth of Stanford University.
	1045
	1046	A Texinfo-based book is similar to any other typeset, printed work: it
	1047	can have a title page, copyright page, table of contents, and preface,
	1048	as well as chapters, numbered or unnumbered sections and subsections,
	1049	page headers, cross-references, footnotes, and indices.
	1050
	1051	@TeX{} is a general purpose typesetting program. Texinfo provides a
	1052	file @file{texinfo.tex} that contains information (definitions or
	1053	@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
	1054	(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
	1055	to @TeX{} commands, which @TeX{} can then process to create the typeset
	1056	document.) @file{texinfo.tex} contains the specifications for printing
	1057	a document. You can get the latest version of @file{texinfo.tex} from
	1058	the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
	1059
	1060	In the United States, documents are most often printed on 8.5 inch by
	1061	11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size.
	1062	But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
	1063	235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
	1064	(@code{@@afourpaper}, @code{@@afivepaper}).
	1065	@xref{@code{@@smallbook}}, and @ref{A4 Paper}.
	1066
	1067	@cindex Literate programming
	1068	@TeX{} is freely distributable. It is written in a superset of Pascal
	1069	for literate programming called WEB and can be compiled either in
	1070	Pascal or (by using a conversion program that comes with the @TeX{}
	1071	distribution) in C.
	1072
	1073	@TeX{} is very powerful and has a great many features. Because a
	1074	Texinfo file must be able to present information both on a
	1075	character-only terminal in Info form and in a typeset book, the
	1076	formatting commands that Texinfo supports are necessarily limited.
	1077
	1078	@xref{Obtaining @TeX{}}, for information on acquiring @TeX{}. It is
	1079	not part of the Texinfo distribution.
	1080
	1081
	1082	@node Adding Output Formats
	1083	@section Adding Output Formats
	1084	@cindex Additional output formats
	1085
	1086	The output formats in the previous sections handle a wide variety of
	1087	usage, but of course there is always room for more.
	1088
	1089	@cindex Output formats, supporting more
	1090	@cindex SGML-tools output format
	1091	If you are a programmer and would like to contribute to the GNU
	1092	project by implementing additional output formats for Texinfo, that
	1093	would be excellent. The way to do this that would be most useful is
	1094	to write a new back-end for @command{texi2any}, our reference
	1095	implementation of a Texinfo parser; it creates a tree representation
	1096	of the Texinfo input that you can use for the conversion. The
	1097	documentation in the source file
	1098	@file{tp/Texinfo/Convert/Converter.pm} is a good place to start.
	1099	@xref{Generic Translator @command{texi2any}}.
	1100
	1101	Another viable approach is use the Texinfo XML output from
	1102	@command{texi2any} as your input. This XML is an essentially complete
	1103	representation of the input, but without the Texinfo syntax and option
	1104	peculiarities, as described above.
	1105
	1106	@cindex Texinfo parsers, discouraging more
	1107	If you still cannot resist the temptation of writing a new program
	1108	that reads Texinfo source directly, let us give some more caveats:
	1109	please do not underestimate the amount of work required. Texinfo is
	1110	by no means a simple language to parse correctly, and remains under
	1111	development, so you would be committing to an ongoing task. You
	1112	are advised to check that the tests of the language that come with
	1113	@command{texi2any} give correct results with your new program.
	1114
	1115	@cindex Man page output, not supported
	1116	From time to time, proposals are made to generate traditional Unix man
	1117	pages from Texinfo source. However, because man pages have a strict
	1118	conventional format, creating a good man page requires a completely
	1119	different source from that needed for the typical Texinfo applications
	1120	of writing a good user tutorial and/or a good reference manual. This
	1121	makes generating man pages incompatible with the Texinfo design
	1122	goal of not having to document the same information in different
	1123	ways for different output formats. You might as well write the man
	1124	page directly.
	1125
	1126	@pindex help2man
	1127	@cindex O'Dea, Brendan
	1128	As an alternative way to support man pages, you may find the program
	1129	@command{help2man} to be useful. It generates a traditional man page
	1130	from the @samp{--help} output of a program. In fact, the man pages
	1131	for the programs in the Texinfo distribution are generated with this.
	1132	It is GNU software written by Brendan O'Dea, available from
	1133	@uref{http://www.gnu.org/software/help2man}.
	1134
	1135
	1136
	1137	@node History
	1138	@section History
	1139
	1140	@cindex Stallman, Richard M.
	1141	@cindex Chassell, Robert J.
	1142	@cindex Fox, Brian
	1143	@cindex Berry, Karl
	1144	Richard M. Stallman invented the Texinfo format, wrote the initial
	1145	processors, and created Edition 1.0 of this manual. Robert@tie{}J.
	1146	Chassell greatly revised and extended the manual, starting with
	1147	Edition 1.1. Brian Fox was responsible for the standalone Texinfo
	1148	distribution until version 3.8, and originally wrote the standalone
	1149	@command{makeinfo} and @command{info} programs. Karl Berry has
	1150	continued maintenance since Texinfo 3.8 (manual edition 2.22).
	1151
	1152	@cindex Pinard, Fran@,{c}ois
	1153	@cindex Schwab, Andreas
	1154	@cindex Weinberg, Zack
	1155	@cindex Weisshaus, Melissa
	1156	@cindex Zaretskii, Eli
	1157	@cindex Zuhn, David D.
	1158	Our thanks go out to all who helped improve this work, particularly
	1159	the indefatigable Eli Zaretskii and Andreas Schwab, who have provided
	1160	patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn,
	1161	tirelessly recorded and reported mistakes and obscurities. Zack
	1162	Weinberg did the impossible by implementing the macro syntax in
	1163	@file{texinfo.tex}. Thanks to Melissa Weisshaus for her frequent
	1164	reviews of nearly similar editions. Dozens of others have contributed
	1165	patches and suggestions, they are gratefully acknowledged in the
	1166	@file{ChangeLog} file. Our mistakes are our own.
	1167
	1168	@cindex History of Texinfo
	1169	@cindex Texinfo history
	1170	@subheading Beginnings
	1171
	1172	@cindex Scribe
	1173	@cindex Reid, Brian
	1174	In the 1970's at CMU, Brian Reid developed a program and format named
	1175	Scribe to mark up documents for printing. It used the @code{@@}
	1176	character to introduce commands, as Texinfo does. Much more
	1177	consequentially, it strove to describe document contents rather than
	1178	formatting, an idea wholeheartedly adopted by Texinfo.
	1179
	1180	@cindex Bolio
	1181	@cindex Bo@TeX{}
	1182	Meanwhile, people at MIT developed another, not too dissimilar format
	1183	called Bolio. This then was converted to using @TeX{} as its typesetting
	1184	language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been
	1185	0.02 on October 31, 1984.
	1186
	1187	Bo@TeX{} could only be used as a markup language for documents to be
	1188	printed, not for online documents. Richard Stallman (RMS) worked on
	1189	both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
	1190	called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
	1191	mark up language for text that is intended to be read both online and
	1192	as printed hard copy.
	1193
	1194	Moving forward, the original translator to create Info was written
	1195	(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
	1196	@code{texinfo-format-buffer} and other functions. In the early 1990s,
	1197	Brian Fox reimplemented the conversion program in C, now called
	1198	@command{makeinfo}.
	1199
	1200	@subheading Reimplementing in Perl
	1201
	1202	@cindex Cons, Lionel
	1203	@cindex Dumas, Patrice
	1204	In 2012, the C @command{makeinfo} was itself replaced by a Perl
	1205	implementation generically called @command{texi2any}. This version
	1206	supports the same level of output customization as
	1207	@command{texi2html}, an independent program originally written by
	1208	Lionel Cons, later with substantial work by many others. The many
	1209	additional features needed to make @command{texi2html} a replacement
	1210	for @command{makeinfo} were implemented by Patrice Dumas. The first
	1211	never-released version of @command{texi2any} was based on the
	1212	@command{texi2html} code. That implementation, however, was abandoned
	1213	in favor of the current program, which parses the Texinfo input into a
	1214	tree for processing. It still supports nearly all the features of
	1215	@command{texi2html}.
	1216
	1217	The new Perl program is much slower than the old C program. We hope
	1218	the speed gap will close in the future, but it may not ever be
	1219	entirely comparable. So why did we switch? In short, we intend and
	1220	hope that the present program will be much easier than the previous C
	1221	implementation of @command{makeinfo} to extend to different output
	1222	styles, back-end output formats, and all other customizations.
	1223	In more detail:
	1224
	1225	@itemize @bullet
	1226	@item HTML customization. Many GNU and other free software packages
	1227	had been happily using the HTML customization features in
	1228	@command{texi2html} for years. Thus, in effect two independent
	1229	implementations of the Texinfo language had developed, and keeping
	1230	them in sync was not simple. Adding the HTML customization possible
	1231	in @command{texi2html} to a C program would have been an
	1232	enormous effort.
	1233
	1234	@item Unicode, and multilingual support generally, especially of east
	1235	Asian languages. Although of course it's perfectly plausible to write
	1236	such support in C, in the particular case of @command{makeinfo}, it
	1237	would have been tantamount to rewriting the entire program. In Perl,
	1238	much of that comes essentially for free.
	1239
	1240	@item Additional back-ends. The @command{makeinfo} code had become
	1241	convoluted to the point where adding a new back-end was quite complex,
	1242	requiring complex interactions with existing back-ends. In contrast,
	1243	our Perl implementation provides a clean tree-based representation for
	1244	all back-ends to work from. People have requested numerous different
	1245	back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now
	1246	be much more feasible to implement. Which leads to the last item:
	1247
	1248	@item Making contributions easier. In general, due to the cleaner
	1249	structure, the Perl program should be considerably easier than the C
	1250	for anyone to read and contribute to, with the resulting obvious
	1251	benefits.
	1252	@end itemize
	1253
	1254	@xref{Reference Implementation}, for more on the rationale for and
	1255	role of @command{texi2any}.
	1256
	1257
	1258	@node Writing a Texinfo File
	1259	@chapter Writing a Texinfo File
	1260
	1261	This chapter describes Texinfo syntax and what is required in a Texinfo
	1262	file, and gives a short sample file.
	1263
	1264	@menu
	1265	* Conventions:: General rules for writing a Texinfo file.
	1266	* Comments:: Writing comments and ignored text in general.
	1267	* Minimum:: What a Texinfo file must have.
	1268	* Short Sample:: A short sample Texinfo file.
	1269	@end menu
	1270
	1271
	1272	@node Conventions
	1273	@section General Syntactic Conventions
	1274	@cindex General syntactic conventions
	1275	@cindex Syntactic conventions
	1276	@cindex Conventions, syntactic
	1277	@cindex Characters, basic input
	1278	@anchor{Formatting Commands} @c old name
	1279
	1280	This section describes the general conventions used in all Texinfo documents.
	1281
	1282	@itemize @bullet
	1283	@item
	1284	@cindex Source files, characters used
	1285	All printable ASCII characters except @samp{@@}, @samp{@{} and
	1286	@samp{@}} can appear in a Texinfo file and stand for themselves.
	1287	@samp{@@} is the escape character which introduces commands, while
	1288	@samp{@{} and @samp{@}} are used to surround arguments to certain
	1289	commands. To put one of these special characters into the document, put
	1290	an @samp{@@} character in front of it, like this: @samp{@@@@},
	1291	@samp{@@@{}, and @samp{@@@}}.
	1292
	1293	@item
	1294	@cindex @@-commands
	1295	@cindex Formatting commands
	1296	In a Texinfo file, the commands you write to describe the contents of
	1297	the manual are preceded by an @samp{@@} character; they are called
	1298	@dfn{@@-commands}. (The @samp{@@} in Texinfo has the same meaning that
	1299	@samp{\} has in plain @TeX{}.)
	1300
	1301	@cindex Braces, when to use
	1302	Depending on what they do or what arguments@footnote{The word
	1303	@dfn{argument} comes from the way it is used in mathematics and does not
	1304	refer to a dispute between two people; it refers to the information
	1305	presented to the command. According to the @cite{Oxford English
	1306	Dictionary}, the word derives from the Latin for @dfn{to make clear,
	1307	prove}; thus it came to mean `the evidence offered as proof', which is
	1308	to say, `the information offered', which led to its mathematical
	1309	meaning. In its other thread of derivation, the word came to mean `to
	1310	assert in a manner against which others may make counter assertions',
	1311	which led to the meaning of `argument' as a dispute.} they take, you
	1312	need to write @@-commands on lines of their own, or as part of
	1313	sentences. As a general rule, a command requires braces if it mingles
	1314	among other text; but it does not need braces if it is on a line of its
	1315	own. For more details of Texinfo command syntax, see @ref{Command
	1316	Syntax}.
	1317
	1318
	1319	@item
	1320	Whitespace following an @@-command name is optional and (usually)
	1321	ignored if present. The exceptions are contexts when whitespace is
	1322	significant, e.g., an @code{@@example} environment.
	1323
	1324
	1325	@item
	1326	Texinfo supports the usual quotation marks used in English and in
	1327	other languages; see @ref{Inserting Quotation Marks}.
	1328
	1329	@item
	1330	@cindex Multiple dashes in source
	1331	@cindex Dashes in source
	1332	@cindex Hyphens in source, two or three in a row
	1333	@cindex Em dash, producing
	1334	@cindex En dash, producing
	1335	Use three hyphens in a row, @samp{---}, to produce a long dash---like
	1336	this (called an @dfn{em dash}), used for punctuation in sentences.
	1337	Use two hyphens, @samp{--}, to produce a medium dash (called an
	1338	@dfn{en dash}), used primarily for numeric ranges, as in ``June
	1339	25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen
	1340	used in compound words. For display on the screen, Info reduces three
	1341	hyphens to two and two hyphens to one (not transitively!). Of course,
	1342	any number of hyphens in the source remain as they are in literal
	1343	contexts, such as @code{@@code} and @code{@@example}.
	1344
	1345	@item
	1346	@cindex Form feed characters
	1347	@cindex @kbd{CTRL-l}
	1348	Form feed (@kbd{CTRL-l}) characters in the input are handled as
	1349	follows:
	1350
	1351	@table @asis
	1352	@item PDF/DVI
	1353	In normal text, treated as ending any open paragraph; essentially
	1354	ignored between paragraphs.
	1355
	1356	@item Info
	1357	Output as-is between paragraphs (their most common use); in other
	1358	contexts, they may be treated as regular spaces (and thus consolidated
	1359	with surrounding whitespace).
	1360
	1361	@item HTML
	1362	Written as a numeric entity except contexts where spaces are ignored;
	1363	for example, in @samp{@@footnote@{ ^L foo@}}, the form feed is
	1364	ignored.
	1365
	1366	@item XML
	1367	Keep them everywhere; in attributes, escaped as @samp{\f}; also,
	1368	@samp{\} is escaped as @samp{\\} and newline as @samp{\n}.
	1369
	1370	@item Docbook
	1371	Completely removed, as they are not allowed.
	1372	@end table
	1373
	1374	As you can see, because of these differing requirements of the output
	1375	formats, it's not possible to use form feeds completely portably.
	1376
	1377	@item
	1378	@cindex Tabs; don't use!
	1379	@strong{Caution:} Last, do not use tab characters in a Texinfo file!
	1380	(Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts,
	1381	which means that it is impractical at best to define a tab to work in
	1382	all circumstances. Consequently, @TeX{} treats tabs like single
	1383	spaces, and that is not what they look like in the source.
	1384	Furthermore, @code{makeinfo} does nothing special with tabs, and thus
	1385	a tab character in your input file will usually have a different
	1386	appearance in the output.
	1387
	1388	@noindent
	1389	To avoid this problem, Texinfo mode in GNU Emacs inserts
	1390	multiple spaces when you press the @key{TAB} key. Also, you can run
	1391	@code{untabify} in Emacs to convert tabs in a region to multiple
	1392	spaces, or use the @code{unexpand} command from the shell.
	1393	@end itemize
	1394
	1395
	1396	@node Comments
	1397	@section Comments
	1398
	1399	@cindex Comments
	1400	@findex comment
	1401	@findex c
	1402
	1403	You can write comments in a Texinfo file by using the @code{@@comment}
	1404	command, which may be abbreviated to @code{@@c}. Such comments are
	1405	for a person looking at the Texinfo source file. All the text on a
	1406	line that follows either @code{@@comment} or @code{@@c} is a comment;
	1407	the rest of the line does not appear in the visible output. (To be
	1408	precise, the character after the @code{@@c} or @code{@@comment} must
	1409	be something other than a dash or alphanumeric, or it will be taken as
	1410	part of the command.)
	1411
	1412	Often, you can write the @code{@@comment} or @code{@@c} in the middle
	1413	of a line, and only the text that follows after the @code{@@comment}
	1414	or @code{@@c} command does not appear; but some commands, such as
	1415	@code{@@settitle}, work on a whole line. You cannot use @code{@@comment}
	1416	or @code{@@c} within a line beginning with such a command.
	1417
	1418	@findex DEL @r{(comment character)}
	1419	@cindex Catcode for comments in @TeX{}
	1420	In cases of nested command invocations, complicated macro definitions,
	1421	etc., @code{@@c} and @code{@@comment} may provoke an error when
	1422	processing with @TeX{}. Therefore, you can also use the @kbd{DEL}
	1423	character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{}
	1424	comment character (catcode 14, in @TeX{} internals). Everything on
	1425	the line after the @kbd{DEL} will be ignored.
	1426
	1427	@cindex Ignored text
	1428	@cindex Unprocessed text
	1429	@findex ignore
	1430	You can also have long stretches of text ignored by the Texinfo
	1431	processors with the @code{@@ignore} and @code{@@end ignore} commands.
	1432	Write each of these commands on a line of its own, starting each
	1433	command at the beginning of the line. Text between these two commands
	1434	does not appear in the processed output. You can use @code{@@ignore}
	1435	and @code{@@end ignore} for writing comments. (For some caveats
	1436	regarding nesting of such commands, @pxref{Conditional Nesting}.)
	1437
	1438
	1439	@node Minimum
	1440	@section What a Texinfo File Must Have
	1441	@cindex Minimal Texinfo file (requirements)
	1442	@cindex Must have in Texinfo file
	1443	@cindex Required in Texinfo file
	1444	@cindex Texinfo file minimum
	1445
	1446	By convention, the name of a Texinfo file ends with one of the
	1447	extensions @file{.texi}, @file{.texinfo}, @file{.txi}, or
	1448	@file{.tex}.
	1449
	1450	In order to be made into a printed manual and other output
	1451	formats, a Texinfo file must begin with lines like this:
	1452
	1453	@example
	1454	@group
	1455	\input texinfo
	1456	@@settitle @var{name-of-manual}
	1457	@end group
	1458	@end example
	1459
	1460	@noindent
	1461	The contents of the file follow this beginning, and then you
	1462	must end the Texinfo source with a line like this:
	1463
	1464	@example
	1465	@@bye
	1466	@end example
	1467
	1468	@findex \input @r{(raw @TeX{} startup)}
	1469	@noindent
	1470	Here's an explanation:
	1471
	1472	@itemize @bullet
	1473	@item
	1474	The @samp{\input texinfo} line tells @TeX{} to use the
	1475	@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
	1476	@@-commands into @TeX{} typesetting commands. (Note the use of the
	1477	backslash, @samp{\}; this is correct for @TeX{}.)
	1478
	1479	@item
	1480	The @code{@@settitle} line specifies a title for the page headers (or
	1481	footers) of the printed manual, and the default title and document
	1482	description for the @samp{<head>} in HTML@. Strictly speaking,
	1483	@code{@@settitle} is optional---if you don't mind your document being
	1484	titled `Untitled'.
	1485
	1486	@item
	1487	The @code{@@bye} line at the end of the file on a line of its own tells
	1488	the formatters that the file is ended and to stop formatting. If you
	1489	leave this out, you'll be dumped at @TeX{}'s prompt at the end of the
	1490	run.
	1491	@end itemize
	1492
	1493	Furthermore, you will usually provide a Texinfo file with a title page,
	1494	indices, and the like, all of which are explained in this manual. But
	1495	the minimum, which can be useful for short documents, is just the two
	1496	lines at the beginning and the one line at the end.
	1497
	1498
	1499
	1500	@node Short Sample
	1501	@section A Short Sample Texinfo File
	1502	@cindex Sample Texinfo file, with comments
	1503
	1504	Here is a short but complete Texinfo file, so you can see how Texinfo
	1505	source appears in practice. The first three parts of the file are
	1506	mostly boilerplate: when writing a manual, you simply change
	1507	the names as appropriate.
	1508
	1509	The complete file, without interspersed comments, is shown in
	1510	@ref{Short Sample Texinfo File}.
	1511
	1512	@xref{Beginning and Ending a File}, for more documentation on the
	1513	commands listed here.
	1514
	1515
	1516	@subheading Header
	1517
	1518	@noindent
	1519	The header tells @TeX{} which definitions file to
	1520	use, names the manual, and carries out other such housekeeping tasks.
	1521
	1522	@example
	1523	@group
	1524	\input texinfo
	1525	@@settitle Sample Manual 1.0
	1526	@end group
	1527	@end example
	1528
	1529
	1530	@subheading Summary Description and Copyright
	1531
	1532	This segment describes the document and contains the copyright notice
	1533	and copying permissions. This is done with the @code{@@copying} command.
	1534
	1535	@noindent
	1536	A real manual includes more text here, according to the license under
	1537	which it is distributed. @xref{GNU Sample Texts}.
	1538
	1539	@example
	1540	@group
	1541	@@copying
	1542	This is a short example of a complete Texinfo file, version 1.0.
	1543
	1544	Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
	1545	@@end copying
	1546	@end group
	1547	@end example
	1548
	1549	@subheading Titlepage, Copyright, Contents
	1550
	1551	The title and copyright segment contains the title and copyright
	1552	pages for the printed manual. The segment must be enclosed between
	1553	@code{@@titlepage} and @code{@@end titlepage} commands. The title and
	1554	copyright page does not appear in the online output.
	1555
	1556	@noindent
	1557	We use the @code{@@insertcopying} command to
	1558	include the permission text from the previous section, instead of
	1559	writing it out again; it is output on the back of the title page. The
	1560	@code{@@contents} command generates a table of contents.
	1561
	1562	@example
	1563	@group
	1564	@@titlepage
	1565	@@title Sample Title
	1566	@end group
	1567
	1568	@group
	1569	@@c The following two commands start the copyright page.
	1570	@@page
	1571	@@vskip 0pt plus 1filll
	1572	@@insertcopying
	1573	@@end titlepage
	1574	@end group
	1575
	1576	@@c Output the table of contents at the beginning.
	1577	@@contents
	1578	@end example
	1579
	1580	@subheading `Top' Node and Master Menu
	1581
	1582	The `Top' node starts off the online output; it does not appear in the
	1583	printed manual. We repeat the short description from the beginning of
	1584	the @samp{@@copying} text, but there's no need to repeat the copyright
	1585	information, so we don't use @samp{@@insertcopying} here.
	1586
	1587	The @samp{@@top} command itself helps @command{makeinfo} determine
	1588	the relationships between nodes. The `Top' node contains at least a
	1589	top-level @dfn{menu} listing the chapters, and possibly a @dfn{Master
	1590	Menu} listing all the nodes in the entire document.
	1591
	1592
	1593	@example
	1594	@@ifnottex
	1595	@@node Top
	1596	@@top Short Sample
	1597
	1598	This is a short sample Texinfo file.
	1599	@@end ifnottex
	1600
	1601	@group
	1602	@@menu
	1603	* First Chapter:: The first chapter is the
	1604	only chapter in this sample.
	1605	* Index:: Complete index.
	1606	@@end menu
	1607	@end group
	1608	@end example
	1609
	1610
	1611	@subheading The Body of the Document
	1612
	1613	@noindent
	1614	The body segment contains all the text of the document, but not the
	1615	indices or table of contents. This example illustrates a node and a
	1616	chapter containing an enumerated list.
	1617
	1618	@example
	1619	@group
	1620	@@node First Chapter
	1621	@@chapter First Chapter
	1622
	1623	@@cindex chapter, first
	1624	@end group
	1625
	1626	@group
	1627	This is the first chapter.
	1628	@@cindex index entry, another
	1629	@end group
	1630
	1631	@group
	1632	Here is a numbered list.
	1633
	1634	@@enumerate
	1635	@@item
	1636	This is the first item.
	1637
	1638	@@item
	1639	This is the second item.
	1640	@@end enumerate
	1641	@end group
	1642	@end example
	1643
	1644
	1645	@subheading The End of the Document
	1646
	1647	This may contain commands for printing indices, and
	1648	closes with the @code{@@bye} command, which marks the end of the document.
	1649
	1650	@example
	1651	@group
	1652	@@node Index
	1653	@@unnumbered Index
	1654	@end group
	1655
	1656	@group
	1657	@@printindex cp
	1658
	1659	@@bye
	1660	@end group
	1661	@end example
	1662
	1663
	1664	@subheading Some Results
	1665
	1666	Here is what the contents of the first chapter of the sample look like:
	1667
	1668	@sp 1
	1669	@need 700
	1670	@quotation
	1671	This is the first chapter.
	1672
	1673	Here is a numbered list.
	1674
	1675	@enumerate
	1676	@item
	1677	This is the first item.
	1678
	1679	@item
	1680	This is the second item.
	1681	@end enumerate
	1682	@end quotation
	1683
	1684
	1685	@node Beginning and Ending a File
	1686	@anchor{Beginning a File} @c old name
	1687	@chapter Beginning and Ending a Texinfo File
	1688	@cindex Beginning a Texinfo file
	1689	@cindex Texinfo file beginning
	1690	@cindex File beginning
	1691
	1692	This chapter expands on the minimal complete Texinfo source file
	1693	previously given (@pxref{Short Sample}).
	1694
	1695	Certain pieces of information must be provided at the beginning of a
	1696	Texinfo file, such as the title of the document and the Top node. A table
	1697	of contents is also generally produced here.
	1698
	1699	@cindex Frontmatter, text in
	1700	Straight text outside of any command before the Top node should be
	1701	avoided. Such text is treated differently in the different output
	1702	formats: at the time of writing, it is visible in @TeX{} and HTML, by
	1703	default not shown in Info readers, and so on.
	1704
	1705	@menu
	1706	* Sample Beginning:: A sample beginning for a Texinfo file.
	1707	* Texinfo File Header:: The first lines.
	1708	* Document Permissions:: Ensuring your manual is free.
	1709	* Titlepage & Copyright Page:: Creating the title and copyright pages.
	1710	* Contents:: How to create a table of contents.
	1711	* The Top Node:: Creating the `Top' node and master menu.
	1712	* Global Document Commands:: Affecting formatting throughout.
	1713	* Ending a File:: What is at the end of a Texinfo file?
	1714	@end menu
	1715
	1716
	1717	@node Sample Beginning
	1718	@section Sample Texinfo File Beginning
	1719
	1720	@cindex Example beginning of Texinfo file
	1721
	1722	The following sample shows what is needed. The elements given here are
	1723	explained in more detail in the following sections. Other commands are
	1724	often included at the beginning of Texinfo files, but the ones here are
	1725	the most critical.
	1726
	1727	@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
	1728
	1729	@example
	1730	\input texinfo
	1731	@@settitle @var{name-of-manual} @var{version}
	1732
	1733	@@copying
	1734	This manual is for @var{program}, version @var{version}.
	1735
	1736	Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
	1737
	1738	@group
	1739	@@quotation
	1740	Permission is granted to @dots{}
	1741	@@end quotation
	1742	@@end copying
	1743	@end group
	1744
	1745	@group
	1746	@@titlepage
	1747	@@title @var{name-of-manual-when-printed}
	1748	@@subtitle @var{subtitle-if-any}
	1749	@@subtitle @var{second-subtitle}
	1750	@@author @var{author}
	1751	@end group
	1752
	1753	@group
	1754	@@c The following two commands
	1755	@@c start the copyright page.
	1756	@@page
	1757	@@vskip 0pt plus 1filll
	1758	@@insertcopying
	1759	@end group
	1760
	1761	Published by @dots{}
	1762	@@end titlepage
	1763
	1764	@@c So the toc is printed at the start.
	1765	@@contents
	1766
	1767	@@ifnottex
	1768	@@node Top
	1769	@@top @var{title}
	1770
	1771	This manual is for @var{program}, version @var{version}.
	1772	@@end ifnottex
	1773
	1774	@group
	1775	@@menu
	1776	* First Chapter:: Getting started @dots{}
	1777	* Second Chapter:: @dots{}
	1778	@dots{}
	1779	* Copying:: Your rights and freedoms.
	1780	@@end menu
	1781	@end group
	1782
	1783	@group
	1784	@@node First Chapter
	1785	@@chapter First Chapter
	1786
	1787	@@cindex first chapter
	1788	@@cindex chapter, first
	1789	@dots{}
	1790	@end group
	1791	@end example
	1792
	1793
	1794	@node Texinfo File Header
	1795	@section Texinfo File Header
	1796	@cindex Header for Texinfo files
	1797	@cindex Texinfo file header
	1798
	1799	Texinfo files start with at least two lines. These are the
	1800	@code{\input texinfo} line and the @code{@@settitle} line.
	1801
	1802	Also, if you want to format just part of the Texinfo file in Emacs,
	1803	you must write the @code{@@settitle} line between start-of-header and
	1804	end-of-header lines. These start- and end-of-header lines are optional,
	1805	but they do no harm, so you might as well always include them.
	1806
	1807	Any command that affects document formatting as a whole makes sense to
	1808	include in the header. @code{@@synindex} (@pxref{@code{@@synindex}}),
	1809	for instance, is another command often included in the header.
	1810
	1811	Thus, the beginning of a Texinfo file looks approximately
	1812	like this:
	1813
	1814	@example
	1815	@group
	1816	\input texinfo
	1817	@@settitle Sample Manual 1.0
	1818	@end group
	1819	@end example
	1820
	1821	(@xref{GNU Sample Texts} for complete sample texts.)
	1822
	1823	@menu
	1824	* First Line:: The first line of a Texinfo file.
	1825	* Start of Header:: Formatting a region requires this.
	1826	* @code{@@setfilename}:: Tell Info the name of the Info file.
	1827	* @code{@@settitle}:: Create a title for the printed work.
	1828	* End of Header:: Formatting a region requires this.
	1829	@end menu
	1830
	1831
	1832	@node First Line
	1833	@subsection The First Line of a Texinfo File
	1834	@cindex First line of a Texinfo file
	1835	@cindex Beginning line of a Texinfo file
	1836	@cindex Header of a Texinfo file
	1837
	1838	Every Texinfo file that is to be the top-level input to @TeX{} must begin
	1839	with a line that looks like this:
	1840
	1841	@example
	1842	\input texinfo
	1843	@end example
	1844
	1845	When the file is processed by @TeX{}, the @samp{\input texinfo} command
	1846	tells @TeX{} to load the macros needed for processing a Texinfo file.
	1847	These are in a file called @file{texinfo.tex}, which should have been
	1848	installed on your system along with either the @TeX{} or Texinfo
	1849	software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
	1850	a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
	1851	file causes the switch from @samp{\} to @samp{@@}; before the switch
	1852	occurs, @TeX{} requires @samp{\}, which is why it appears at the
	1853	beginning of the file.
	1854
	1855	You may optionally follow this line with a comment to tell GNU Emacs
	1856	to use Texinfo mode when the file is edited:
	1857
	1858	@example
	1859	\input texinfo @@c --texinfo--
	1860	@end example
	1861
	1862	@noindent This may be useful when Emacs doesn't detect the file type
	1863	from the file extension automatically.
	1864
	1865	@node Start of Header
	1866	@subsection Start of Header
	1867	@cindex Start of header line
	1868
	1869	A start-of-header line is a Texinfo comment that looks like this:
	1870
	1871	@example
	1872	@@c %**start of header
	1873	@end example
	1874
	1875	Write the start-of-header line on the second line of a Texinfo file.
	1876	Follow the start-of-header line with an @code{@@settitle} line and,
	1877	optionally, with other commands that globally affect the document
	1878	formatting, such as @code{@@synindex} or @code{@@footnotestyle}; and
	1879	then by an end-of-header line (@pxref{End of Header}).
	1880
	1881	The start- and end-of-header lines allow you to format only part of a
	1882	Texinfo file for Info or printing. @xref{@code{texinfo-format} commands}.
	1883
	1884	The odd string of characters, @samp{%**}, is to ensure that no other
	1885	comment is accidentally taken for a start-of-header line. You can
	1886	change it if you wish by setting the @code{tex-start-of-header} and/or
	1887	@code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}.
	1888
	1889
	1890	@node @code{@@setfilename}
	1891	@subsection @code{@@setfilename}: Set the Output File Name
	1892
	1893	@anchor{setfilename}@c old name
	1894	@findex setfilename
	1895	@cindex Texinfo requires @code{@@setfilename}
	1896	@cindex Output file name, required
	1897
	1898	The @code{@@setfilename} line specifies the name of the output file to
	1899	be generated.
	1900	When present, it should be the first Texinfo command (that is, after
	1901	@samp{\input texinfo}).
	1902	Write the @code{@@setfilename} command at the beginning of a line and
	1903	follow it on the same line by the Info file name.
	1904
	1905	@example
	1906	@@setfilename @var{info-file-name}
	1907	@end example
	1908
	1909	The name must be different from the name of the
	1910	Texinfo file. There are two conventions for choosing the name: you
	1911	can either remove the extension (such as @samp{.texi}) entirely from
	1912	the input file name, or (recommended) replace it with the @samp{.info}
	1913	extension.
	1914
	1915	@cindex Ignored before @code{@@setfilename}
	1916	@cindex @samp{\input} source line ignored
	1917	When a @code{@@setfilename} line is present, the Texinfo processors
	1918	ignore everything written before the @code{@@setfilename} line. This
	1919	is why the very first line of the file (the @code{\input} line) does
	1920	not show up in the output.
	1921
	1922	If there is no @code{@@setfilename} line, @code{makeinfo} uses the
	1923	input file name to determine the output name: first, any of the
	1924	extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo}
	1925	is removed from the input file name; then, the output format specific
	1926	extension is added---@code{.html} when generating HTML, @code{.info}
	1927	when generating Info, etc. The @code{\input} line is still ignored in
	1928	this processing, as well as leading blank lines.
	1929
	1930	When producing another output format, @code{makeinfo} will replace any
	1931	final extension with the output format-specific extension (@samp{html}
	1932	when generating HTML, for example), or add a dot followed by the
	1933	extension (@samp{.html} for HTML) if the given name has no extension.
	1934
	1935	@code{@@setfilename} used to be required by the Texinfo processors, and
	1936	some other programs may still expect it to be present; for example,
	1937	Automake (@pxref{Texinfo,,,automake, GNU Automake}).
	1938
	1939	@cindex Length of file names
	1940	@cindex File name collision
	1941	@cindex Info file name, choosing
	1942	Although an explicit @samp{.info} extension is preferable, some
	1943	operating systems cannot handle long file names. You can run into a
	1944	problem even when the file name you specify is itself short enough.
	1945	This occurs because the Info formatters split a long Info file into
	1946	short indirect subfiles, and name them by appending @samp{-1},
	1947	@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
	1948	file name. (@xref{Tag and Split Files}.) The subfile name
	1949	@file{texinfo.info-10}, for example, is too long for old systems with
	1950	a 14-character limit on filenames; so the Info file name for this
	1951	document is @file{texinfo} rather than @file{texinfo.info}. When
	1952	@code{makeinfo} is running on operating systems such as MS-DOS which
	1953	impose severe limits on file names, it may remove some characters from
	1954	the original file name to leave enough space for the subfile suffix,
	1955	thus producing files named @file{texin-10}, @file{gcc.i12}, etc.
	1956
	1957	See also the @option{--output} option in @ref{Invoking @command{texi2any}}.
	1958
	1959
	1960	@node @code{@@settitle}
	1961	@subsection @code{@@settitle}: Set the Document Title
	1962
	1963	@anchor{settitle}@c old name
	1964	@findex settitle
	1965	@cindex Document title, specifying
	1966
	1967	A Texinfo file should contain a line that looks like this:
	1968
	1969	@example
	1970	@@settitle @var{title}
	1971	@end example
	1972
	1973	Write the @code{@@settitle} command at the beginning of a line and
	1974	follow it on the same line by the title. Do not write anything else
	1975	on the line. The @code{@@settitle} command should precede everything
	1976	that generates actual output. The best place for it is right after
	1977	the @code{@@setfilename} command (described in the previous section).
	1978
	1979	This command tells @TeX{} the title to use in a header or footer
	1980	for double-sided output, in case such headings are output. For
	1981	more on headings for @TeX{}, see @ref{Heading Generation}.
	1982
	1983	@cindex @code{<title>} HTML tag
	1984	In the HTML file produced by @command{makeinfo}, @var{title} serves as
	1985	the document @samp{<title>}. It also becomes the default document
	1986	description in the @samp{<head>} part
	1987	(@pxref{@code{@@documentdescription}}).
	1988
	1989	When the title page is used in the output, the title in the
	1990	@code{@@settitle} command does not affect the title as it appears on
	1991	the title page. Thus, the two do not need not to match exactly. A
	1992	practice we recommend is to include the version or edition number of
	1993	the manual in the @code{@@settitle} title; on the title page, the
	1994	version number generally appears as a @code{@@subtitle} so it would
	1995	be omitted from the @code{@@title}. @xref{@code{@@titlepage}}.
	1996
	1997
	1998	@node End of Header
	1999	@subsection End of Header
	2000	@cindex End of header line
	2001
	2002	Follow the header lines with an @w{end-of-header} line, which is a
	2003	Texinfo comment that looks like this:
	2004
	2005	@example
	2006	@@c %**end of header
	2007	@end example
	2008
	2009	@xref{Start of Header}.
	2010
	2011
	2012	@node Document Permissions
	2013	@section Document Permissions
	2014	@cindex Document Permissions
	2015	@cindex Copying Permissions
	2016
	2017	The copyright notice and copying permissions for a document need to
	2018	appear in several places in the various Texinfo output formats.
	2019	Therefore, Texinfo provides a command (@code{@@copying}) to declare
	2020	this text once, and another command (@code{@@insertcopying}) to
	2021	insert the text at appropriate points.
	2022
	2023	@anchor{Software Copying Permissions}@c old node name
	2024	This section is about the license of the Texinfo document. If the
	2025	document is a software manual, the software is typically under a
	2026	different license---for GNU and many other free software packages,
	2027	software is usually released under the GNU GPL, and manuals are
	2028	released under the GNU FDL@. It is helpful to state the license of
	2029	the software of the manual, but giving the complete text of the
	2030	software license is not necessarily required.
	2031
	2032	@menu
	2033	* @code{@@copying}:: Declare the document's copying permissions.
	2034	* @code{@@insertcopying}:: Where to insert the permissions.
	2035	@end menu
	2036
	2037
	2038	@node @code{@@copying}
	2039	@subsection @code{@@copying}: Declare Copying Permissions
	2040
	2041	@anchor{copying}@c old name
	2042	@findex copying
	2043
	2044	The @code{@@copying} command should be given very early in the document;
	2045	the recommended location is right after the header material
	2046	(@pxref{Texinfo File Header}). It conventionally consists of a sentence
	2047	or two about what the program is, identification of the documentation
	2048	itself, the legal copyright line, and the copying permissions. Here is
	2049	a skeletal example:
	2050
	2051	@example
	2052	@@copying
	2053	This manual is for @var{program} (version @var{version}, updated
	2054	@var{date}), which @dots{}
	2055
	2056	Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
	2057
	2058	@@quotation
	2059	Permission is granted to @dots{}
	2060	@@end quotation
	2061	@@end copying
	2062	@end example
	2063
	2064	The @code{@@quotation} has no legal significance; it's there to improve
	2065	readability in some contexts.
	2066
	2067	The text of @code{@@copying} is output as a comment at the beginning
	2068	of Info, HTML, XML, and Docbook output files. It is @emph{not} output
	2069	implicitly in plain text or @TeX{}; it's up to you to use
	2070	@code{@@insertcopying} to emit the copying information. See the next
	2071	section for details.
	2072
	2073	@findex copyright
	2074	The @code{@@copyright@{@}} command generates a @samp{c} inside a
	2075	circle when the output format supports this glyph (print and HTML
	2076	always do, for instance). When the glyph is not supported in the
	2077	output, it generates the three-character sequence @samp{(C)}.
	2078
	2079	The copyright notice itself has the following legally-prescribed
	2080	form:
	2081
	2082	@example
	2083	Copyright @copyright{} @var{years} @var{copyright-owner}.
	2084	@end example
	2085
	2086	@cindex Copyright word, always in English
	2087	The word `Copyright' must always be written in English, even if the
	2088	document is otherwise written in another language. This is due to
	2089	international law.
	2090
	2091	@cindex Years, in copyright line
	2092	The list of years should include all years in which a version was
	2093	completed (even if it was released in a subsequent year). It is
	2094	simplest for each year to be written out individually and in full,
	2095	separated by commas.
	2096
	2097	@cindex Copyright holder for FSF works
	2098	@cindex Holder of copyright for FSF works
	2099	@cindex Owner of copyright for FSF works
	2100	The copyright owner (or owners) is whoever holds legal copyright on the
	2101	work. In the case of works assigned to the FSF, the owner is `Free
	2102	Software Foundation, Inc.'.
	2103
	2104	The copyright `line' may actually be split across multiple lines, both
	2105	in the source document and in the output. This often happens for
	2106	documents with a long history, having many different years of
	2107	publication. If you do use several lines, do not indent any of them
	2108	(or anything else in the @code{@@copying} block) in the source file.
	2109
	2110	@xref{Copyright Notices,,, maintain, GNU Maintainer Information}, for
	2111	additional information. @xref{GNU Sample Texts}, for the full text to
	2112	be used in GNU manuals. @xref{GNU Free Documentation License}, for
	2113	the license itself under which GNU and other free manuals are
	2114	distributed.
	2115
	2116
	2117	@node @code{@@insertcopying}
	2118	@subsection @code{@@insertcopying}: Include Permissions Text
	2119
	2120	@anchor{insertcopying}@c old name
	2121	@findex insertcopying
	2122	@cindex Copying text, including
	2123	@cindex Permissions text, including
	2124	@cindex Including permissions text
	2125
	2126	The @code{@@insertcopying} command is simply written on a line by
	2127	itself, like this:
	2128
	2129	@example
	2130	@@insertcopying
	2131	@end example
	2132
	2133	This inserts the text previously defined by @code{@@copying}. To meet
	2134	legal requirements, it must be used on the copyright page in the printed
	2135	manual (@pxref{Copyright}).
	2136
	2137	The @code{@@copying} command itself causes the permissions text to
	2138	appear in an Info file @emph{before} the first node. The text is also
	2139	copied into the beginning of each split Info output file, as is legally
	2140	necessary. This location implies a human reading the manual using Info
	2141	does @emph{not} see this text (except when using the advanced Info
	2142	command @kbd{g *}), but this does not matter for legal purposes,
	2143	because the text is present.
	2144
	2145	Similarly, the @code{@@copying} text is automatically included at the
	2146	beginning of each HTML output file, as an HTML comment. Again, this
	2147	text is not visible (unless the reader views the HTML source).
	2148
	2149	The permissions text defined by @code{@@copying} also appears
	2150	automatically at the beginning of the XML and Docbook output files.
	2151
	2152
	2153	@node Titlepage & Copyright Page
	2154	@section Title and Copyright Pages
	2155
	2156	In hard copy output, the manual's name and author are usually printed on
	2157	a title page. Copyright information is usually printed on the back of
	2158	the title page.
	2159
	2160	The title and copyright pages appear in printed manuals, but not in
	2161	most other output formats. Because of this, it is possible to use
	2162	several slightly obscure typesetting commands that are not to be used
	2163	in the main text. In addition, this part of the beginning of a
	2164	Texinfo file contains the text of the copying permissions that appears
	2165	in the printed manual.
	2166
	2167	@menu
	2168	* @code{@@titlepage}:: Create a title for the printed document.
	2169	* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
	2170	and @code{@@sp} commands.
	2171	* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
	2172	and @code{@@author} commands.
	2173	* Copyright:: How to write the copyright notice and
	2174	include copying permissions.
	2175	* Heading Generation:: Turn on page headings after the title and
	2176	copyright pages.
	2177	@end menu
	2178
	2179
	2180	@node @code{@@titlepage}
	2181	@subsection @code{@@titlepage}
	2182
	2183	@anchor{titlepage}@c old name
	2184	@cindex Title page
	2185	@findex titlepage
	2186
	2187	Start the material for the title page and following copyright page
	2188	with @code{@@titlepage} on a line by itself and end it with
	2189	@code{@@end titlepage} on a line by itself.
	2190
	2191	The @code{@@end titlepage} command starts a new page and turns on page
	2192	numbering (@pxref{Heading Generation}). All the
	2193	material that you want to appear on unnumbered pages should be put
	2194	between the @code{@@titlepage} and @code{@@end titlepage} commands.
	2195
	2196	@findex page@r{, within @code{@@titlepage}}
	2197	By using the @code{@@page} command you can force a page break within the
	2198	region delineated by the @code{@@titlepage} and @code{@@end titlepage}
	2199	commands and thereby create more than one unnumbered page. This is how
	2200	the copyright page is produced. (The @code{@@titlepage} command might
	2201	perhaps have been better named the @code{@@titleandadditionalpages}
	2202	command, but that would have been rather long!)
	2203
	2204	When you write a manual about a computer program, you should write the
	2205	version of the program to which the manual applies on the title page.
	2206	If the manual changes more frequently than the program or is independent
	2207	of it, you should also include an edition number@footnote{We have found
	2208	that it is helpful to refer to versions of independent manuals as
	2209	`editions' and versions of programs as `versions'; otherwise, we find we
	2210	are liable to confuse each other in conversation by referring to both
	2211	the documentation and the software with the same words.} for the manual.
	2212	This helps readers keep track of which manual is for which version of
	2213	the program. (The `Top' node should also contain this information; see
	2214	@ref{The Top Node}.)
	2215
	2216	Texinfo provides two main methods for creating a title page. One method
	2217	uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
	2218	to generate a title page in which the words on the page are
	2219	centered.
	2220
	2221	The second method uses the @code{@@title}, @code{@@subtitle}, and
	2222	@code{@@author} commands to create a title page with black rules under
	2223	the title and author lines and the subtitle text set flush to the
	2224	right hand side of the page. With this method, you do not specify any
	2225	of the actual formatting of the title page. You specify the text
	2226	you want, and Texinfo does the formatting.
	2227
	2228	You may use either method, or you may combine them; see the examples in
	2229	the sections below.
	2230
	2231	@findex shorttitlepage
	2232	@cindex Bastard title page
	2233	@cindex Title page, bastard
	2234	For sufficiently simple documents, and for the bastard title page in
	2235	traditional book frontmatter, Texinfo also provides a command
	2236	@code{@@shorttitlepage} which takes the rest of the line as the title.
	2237	The argument is typeset on a page by itself and followed by a blank
	2238	page.
	2239
	2240
	2241	@node @code{@@titlefont @@center @@sp}
	2242	@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
	2243
	2244	@anchor{titlefont center sp}@c old name
	2245	@findex titlefont
	2246	@findex center
	2247	@findex sp @r{(titlepage line spacing)}
	2248
	2249	You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
	2250	commands to create a title page for a printed document. (This is the
	2251	first of the two methods for creating a title page in Texinfo.)
	2252
	2253	Use the @code{@@titlefont} command to select a large font suitable for
	2254	the title itself. You can use @code{@@titlefont} more than once if you
	2255	have an especially long title.
	2256
	2257	For HTML output, each @code{@@titlefont} command produces an
	2258	@code{<h1>} heading, but the HTML document @code{<title>} is not
	2259	affected. For that, you must put a @code{@@settitle} command before
	2260	the @code{@@titlefont} command (@pxref{@code{@@settitle}}).
	2261
	2262	@need 700
	2263	For example:
	2264
	2265	@example
	2266	@@titlefont@{Texinfo@}
	2267	@end example
	2268
	2269	Use the @code{@@center} command at the beginning of a line to center
	2270	the remaining text on that line. Thus,
	2271
	2272	@example
	2273	@@center @@titlefont@{Texinfo@}
	2274	@end example
	2275
	2276	@noindent
	2277	centers the title, which in this example is ``Texinfo'' printed
	2278	in the title font.
	2279
	2280	Use the @code{@@sp} command to insert vertical space. For example:
	2281
	2282	@example
	2283	@@sp 2
	2284	@end example
	2285
	2286	@noindent
	2287	This inserts two blank lines on the printed page.
	2288	(@xref{@code{@@sp}}, for more information about the @code{@@sp}
	2289	command.)
	2290
	2291	A template for this method looks like this:
	2292
	2293	@example
	2294	@group
	2295	@@titlepage
	2296	@@sp 10
	2297	@@center @@titlefont@{@var{name-of-manual-when-printed}@}
	2298	@@sp 2
	2299	@@center @var{subtitle-if-any}
	2300	@@sp 2
	2301	@@center @var{author}
	2302	@dots{}
	2303	@@end titlepage
	2304	@end group
	2305	@end example
	2306
	2307	The spacing of the example fits an 8.5 by 11 inch manual.
	2308
	2309
	2310	@node @code{@@title @@subtitle @@author}
	2311	@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
	2312
	2313	@anchor{title subtitle author}@c old name
	2314	@findex title
	2315	@findex subtitle
	2316	@findex author
	2317
	2318	You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
	2319	commands to create a title page in which the vertical and horizontal
	2320	spacing is done for you automatically. This contrasts with the method
	2321	described in the previous section, in which the @code{@@sp} command is
	2322	needed to adjust vertical spacing.
	2323
	2324	Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
	2325	commands at the beginning of a line followed by the title, subtitle,
	2326	or author. The @code{@@author} command may be used for a quotation in
	2327	an @code{@@quotation} block (@pxref{@code{@@quotation}});
	2328	except for that, it is an error to use any of these commands outside
	2329	of @code{@@titlepage}.
	2330
	2331	The @code{@@title} command produces a line in which the title is set
	2332	flush to the left-hand side of the page in a larger than normal font.
	2333	The title is underlined with a black rule. The title must be given on
	2334	a single line in the source file; it will be broken into multiple
	2335	lines of output is needed.
	2336
	2337	For long titles, the @code{@@*} command may be used to specify the
	2338	line breaks in long titles if the automatic breaks do not suit. Such
	2339	explicit line breaks are generally reflected in all output formats; if
	2340	you only want to specify them for the printed output, use a
	2341	conditional (@pxref{Conditionals}). For example:
	2342
	2343	@example
	2344	@@title This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
	2345	@end example
	2346
	2347	The @code{@@subtitle} command sets subtitles in a normal-sized font
	2348	flush to the right-hand side of the page.
	2349
	2350	The @code{@@author} command sets the names of the author or authors in
	2351	a middle-sized font flush to the left-hand side of the page on a line
	2352	near the bottom of the title page. The names are followed by a black
	2353	rule that is thinner than the rule that underlines the title.
	2354
	2355	There are two ways to use the @code{@@author} command: you can write
	2356	the name or names on the remaining part of the line that starts with
	2357	an @code{@@author} command:
	2358
	2359	@example
	2360	@@author by Jane Smith and John Doe
	2361	@end example
	2362
	2363	@noindent
	2364	or you can write the names one above each other by using multiple
	2365	@code{@@author} commands:
	2366
	2367	@example
	2368	@group
	2369	@@author Jane Smith
	2370	@@author John Doe
	2371	@end group
	2372	@end example
	2373
	2374	@need 950
	2375	A template for this method looks like this:
	2376
	2377	@example
	2378	@group
	2379	@@titlepage
	2380	@@title @var{name-of-manual-when-printed}
	2381	@@subtitle @var{subtitle-if-any}
	2382	@@subtitle @var{second-subtitle}
	2383	@@author @var{author}
	2384	@@page
	2385	@dots{}
	2386	@@end titlepage
	2387	@end group
	2388	@end example
	2389
	2390
	2391	@node Copyright
	2392	@subsection Copyright Page
	2393	@cindex Copyright page
	2394	@cindex Printed permissions
	2395	@cindex Permissions, printed
	2396
	2397	By international treaty, the copyright notice for a book must be either
	2398	on the title page or on the back of the title page. When the copyright
	2399	notice is on the back of the title page, that page is customarily not
	2400	numbered. Therefore, in Texinfo, the information on the copyright page
	2401	should be within @code{@@titlepage} and @code{@@end titlepage}
	2402	commands.
	2403
	2404	@findex vskip @r{@TeX{} vertical skip}
	2405	@cindex filll @r{@TeX{} dimension}
	2406	Use the @code{@@page} command to cause a page break. To push the
	2407	copyright notice and the other text on the copyright page towards the
	2408	bottom of the page, use the following incantation after @code{@@page}:
	2409
	2410	@example
	2411	@@vskip 0pt plus 1filll
	2412	@end example
	2413
	2414	@noindent
	2415	The @code{@@vskip} command inserts whitespace in the @TeX{} output; it
	2416	is ignored in all other output formats. The @samp{0pt plus 1filll}
	2417	means to put in zero points of mandatory whitespace, and as much
	2418	optional whitespace as needed to push the following text to the bottom
	2419	of the page. Note the use of three @samp{l}s in the word
	2420	@samp{filll}; this is correct.
	2421
	2422	To insert the copyright text itself, write @code{@@insertcopying}
	2423	next (@pxref{Document Permissions}):
	2424
	2425	@example
	2426	@@insertcopying
	2427	@end example
	2428
	2429	Follow the copying text by the publisher, ISBN numbers, cover art
	2430	credits, and other such information.
	2431
	2432	Here is an example putting all this together:
	2433
	2434	@example
	2435	@@titlepage
	2436	@dots{}
	2437	@@page
	2438	@@vskip 0pt plus 1filll
	2439	@@insertcopying
	2440
	2441	Published by @dots{}
	2442
	2443	Cover art by @dots{}
	2444	@@end titlepage
	2445	@end example
	2446
	2447	We have one more special case to consider: for plain text output, you
	2448	must insert the copyright information explicitly if you want it to
	2449	appear. For instance, you could have the following after the copyright
	2450	page:
	2451
	2452	@example
	2453	@@ifplaintext
	2454	@@insertcopying
	2455	@@end ifplaintext
	2456	@end example
	2457
	2458	You could include other title-like information for the plain text
	2459	output in the same place.
	2460
	2461
	2462
	2463	@node Heading Generation
	2464	@subsection Heading Generation
	2465
	2466	@anchor{end titlepage}@c old name
	2467	@cindex Headings, page, begin to appear
	2468	@cindex Titlepage end starts headings
	2469	@cindex End titlepage starts headings
	2470	@cindex Generating page headings
	2471
	2472	Like all @code{@@end} commands (@pxref{Quotations and Examples}), the
	2473	@code{@@end titlepage} command must be written at the beginning of a
	2474	line by itself, with only one space between the @code{@@end} and the
	2475	@code{titlepage}. It not only marks the end of the title and
	2476	copyright pages, but also causes @TeX{} to start generating page
	2477	headings and page numbers.
	2478
	2479	Texinfo has two standard page heading formats, one for documents
	2480	printed on one side of each sheet of paper (single-sided printing),
	2481	and the other for documents printed on both sides of each sheet
	2482	(double-sided printing).
	2483
	2484	In full generality, you can control the headings in different ways:
	2485
	2486	@itemize @bullet
	2487	@item
	2488	The conventional way is to write a @code{@@setchapternewpage} command
	2489	before the title page commands, if required, and then have the
	2490	@code{@@end titlepage} command start generating page headings in the
	2491	manner desired.
	2492
	2493	Most documents are formatted with the standard single-sided or
	2494	double-sided headings, (sometimes) using @code{@@setchapternewpage
	2495	odd} for double-sided printing and (almost always) no
	2496	@code{@@setchapternewpage} command for single-sided printing
	2497	(@pxref{@code{@@setchapternewpage}}).
	2498
	2499	@item
	2500	Alternatively, you can use the @code{@@headings} command to prevent
	2501	page headings from being generated or to start them for either single
	2502	or double-sided printing. Write a @code{@@headings} command
	2503	immediately after the @code{@@end titlepage} command. To turn off
	2504	headings, write @code{@@headings off}. @xref{@code{@@headings}}.
	2505
	2506	@item
	2507	Or, you may specify your own page heading and footing format.
	2508	@xref{Headings}.
	2509	@end itemize
	2510
	2511
	2512	@node Contents
	2513	@section Generating a Table of Contents
	2514	@cindex Table of contents
	2515	@cindex Contents, table of
	2516	@cindex Short table of contents
	2517	@findex contents
	2518	@findex summarycontents
	2519	@findex shortcontents
	2520
	2521	The @code{@@chapter}, @code{@@section}, and other structuring commands
	2522	(@pxref{Chapter Structuring}) supply the information to make up a
	2523	table of contents, but they do not cause an actual table to appear in
	2524	the manual. To do this, you must use the @code{@@contents} and/or
	2525	@code{@@summarycontents} command(s).
	2526
	2527	@table @code
	2528	@item @@contents
	2529	Generates a table of contents in a printed manual, including all
	2530	chapters, sections, subsections, etc., as well as appendices and
	2531	unnumbered chapters. Headings generated by @code{@@majorheading},
	2532	@code{@@chapheading}, and the other @code{@@@dots{}heading} commands
	2533	do not appear in the table of contents (@pxref{Structuring Command
	2534	Types}).
	2535
	2536	@item @@shortcontents
	2537	@itemx @@summarycontents
	2538	(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
	2539
	2540	Generates a short or summary table of contents that lists only the
	2541	chapters, appendices, and unnumbered chapters. Sections, subsections
	2542	and subsubsections are omitted. Only a long manual needs a short
	2543	table of contents in addition to the full table of contents.
	2544	@end table
	2545
	2546	Both contents commands should be written on a line by themselves, and
	2547	placed near the beginning of the file, after the @code{@@end
	2548	titlepage} (@pxref{@code{@@titlepage}}), before any sectioning
	2549	command. The contents commands automatically generate a chapter-like
	2550	heading at the top of the first table of contents page, so don't
	2551	include any sectioning command such as @code{@@unnumbered} before
	2552	them.
	2553
	2554	Since an Info file uses menus instead of tables of contents, the Info
	2555	formatting commands ignore the contents commands. But the contents
	2556	are included in plain text output (generated by @code{makeinfo
	2557	--plaintext}) and in other output formats, such as HTML.
	2558
	2559	When @code{makeinfo} writes a short table of contents while producing
	2560	HTML output, the links in the short table of contents point to
	2561	corresponding entries in the full table of contents rather than the text
	2562	of the document. The links in the full table of contents point to the
	2563	main text of the document.
	2564
	2565
	2566	@node The Top Node
	2567	@section The `Top' Node and Master Menu
	2568	@cindex Top node
	2569	@cindex Node, `Top'
	2570
	2571	The `Top' node is the node in which a reader enters an Info manual.
	2572	As such, it should begin with a brief description of the manual
	2573	(including the version number), and end with a master menu for the
	2574	whole manual. Of course you should include any other general
	2575	information you feel a reader would find helpful.
	2576
	2577	@findex top
	2578	It is conventional and desirable to write a @code{@@top} sectioning
	2579	command line containing the title of the document immediately after
	2580	the @code{@@node Top} line (@pxref{@code{@@top} Command}).
	2581
	2582	The contents of the `Top' node should appear only in the online output;
	2583	none of it should appear in printed output, so enclose it between
	2584	@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
	2585	print either an @code{@@node} line or a menu; they appear only in Info;
	2586	strictly speaking, you are not required to enclose these parts between
	2587	@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
	2588	so. @xref{Conditionals, , Conditionally Visible Text}.)
	2589
	2590	@menu
	2591	* Top Node Example::
	2592	* Master Menu Parts::
	2593	@end menu
	2594
	2595
	2596	@node Top Node Example
	2597	@subsection Top Node Example
	2598
	2599	@cindex Top node example
	2600
	2601	Here is an example of a Top node.
	2602
	2603	@example
	2604	@group
	2605	@@ifnottex
	2606	@@node Top
	2607	@@top Sample Title
	2608
	2609	This is the text of the top node.
	2610	@@end ifnottex
	2611	@end group
	2612
	2613	Additional general information.
	2614
	2615	@group
	2616	@@menu
	2617	* First Chapter::
	2618	* Second Chapter::
	2619	@dots{}
	2620	* Index::
	2621	@end group
	2622	@@end menu
	2623	@end example
	2624
	2625
	2626	@node Master Menu Parts
	2627	@subsection Parts of a Master Menu
	2628	@cindex Master menu
	2629	@cindex Menu, master
	2630	@cindex Parts of a master menu
	2631
	2632	A @dfn{master menu} is the main menu. It is customary to include a
	2633	detailed menu listing all the nodes in the document in this menu.
	2634
	2635	Like any other menu, a master menu is enclosed in @code{@@menu} and
	2636	@code{@@end menu} and does not appear in the printed output.
	2637
	2638	Generally, a master menu is divided into parts.
	2639
	2640	@itemize @bullet
	2641	@item
	2642	The first part contains the major nodes in the Texinfo file: the nodes
	2643	for the chapters, chapter-like sections, and the appendices.
	2644
	2645	@item
	2646	The second part contains nodes for the indices.
	2647
	2648	@item
	2649	@findex detailmenu
	2650	@cindex Detailed menu
	2651	The third and subsequent parts contain a listing of the other,
	2652	lower-level nodes, often ordered by chapter. This way, rather than go
	2653	through an intermediary menu, an inquirer can go directly to a
	2654	particular node when searching for specific information. These menu
	2655	items are not required; add them if you think they are a convenience.
	2656	If you do use them, put @code{@@detailmenu} before the first one, and
	2657	@code{@@end detailmenu} after the last; otherwise, @code{makeinfo}
	2658	will get confused.
	2659	@end itemize
	2660
	2661	Each section in the menu can be introduced by a descriptive line. So
	2662	long as the line does not begin with an asterisk, it will not be
	2663	treated as a menu entry. (@xref{Writing a Menu}, for more
	2664	information.)
	2665
	2666	For example, the master menu for this manual looks like the following
	2667	(but has many more entries):
	2668
	2669	@example
	2670	@group
	2671	@@menu
	2672	* Copying Conditions:: Your rights.
	2673	* Overview:: Texinfo in brief.
	2674	@dots{}
	2675	@end group
	2676	@group
	2677	* Command and Variable Index::
	2678	* General Index::
	2679	@end group
	2680
	2681	@group
	2682	@@detailmenu
	2683	--- The Detailed Node Listing ---
	2684
	2685	Overview of Texinfo
	2686
	2687	* Reporting Bugs:: @dots{}
	2688	@dots{}
	2689	@end group
	2690
	2691	@group
	2692	Beginning a Texinfo File
	2693
	2694	* Sample Beginning:: @dots{}
	2695	@dots{}
	2696	@@end detailmenu
	2697	@@end menu
	2698	@end group
	2699	@end example
	2700
	2701
	2702	@node Global Document Commands
	2703	@section Global Document Commands
	2704	@cindex Global Document Commands
	2705
	2706	Besides the basic commands mentioned in the previous sections, here are
	2707	additional commands which affect the document as a whole. They are
	2708	generally all given before the Top node, if they are given at all.
	2709
	2710	@menu
	2711	* @code{@@documentdescription}:: Document summary for the HTML output.
	2712	* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
	2713	* @code{@@headings}:: An option for turning headings on and off
	2714	and double or single sided printing.
	2715	* @code{@@paragraphindent}:: Specify paragraph indentation.
	2716	* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
	2717	* @code{@@exampleindent}:: Specify environment indentation.
	2718	@end menu
	2719
	2720
	2721	@node @code{@@documentdescription}
	2722	@subsection @code{@@documentdescription}: Summary Text
	2723	@anchor{documentdescription}@c old name
	2724
	2725	@cindex Document description
	2726	@cindex Description of document
	2727	@cindex Summary of document
	2728	@cindex Abstract of document
	2729	@cindex @code{<meta>} HTML tag, and document description
	2730	@findex documentdescription
	2731
	2732	When producing HTML output for a document, @command{makeinfo} writes a
	2733	@samp{<meta>} element in the @samp{<head>} to give some idea of the
	2734	content of the document. By default, this @dfn{description} is the
	2735	title of the document, taken from the @code{@@settitle} command
	2736	(@pxref{@code{@@settitle}}). To change this, use the
	2737	@code{@@documentdescription} environment, as in:
	2738
	2739	@example
	2740	@@documentdescription
	2741	descriptive text.
	2742	@@end documentdescription
	2743	@end example
	2744
	2745	@noindent
	2746	This will produce the following output in the @samp{<head>} of the HTML:
	2747
	2748	@example
	2749	<meta name=description content="descriptive text.">
	2750	@end example
	2751
	2752	@code{@@documentdescription} must be specified before the first node of
	2753	the document.
	2754
	2755
	2756	@node @code{@@setchapternewpage}
	2757	@subsection @code{@@setchapternewpage}: Blank Pages Before Chapters
	2758
	2759	@anchor{setchapternewpage}@c old name
	2760	@findex setchapternewpage
	2761	@cindex Starting chapters
	2762	@cindex Pages, starting odd
	2763
	2764	In an officially bound book, text is usually printed on both sides of
	2765	the paper, chapters start on right-hand pages, and right-hand pages have
	2766	odd numbers. But in short reports, text often is printed only on one
	2767	side of the paper. Also in short reports, chapters sometimes do not
	2768	start on new pages, but are printed on the same page as the end of the
	2769	preceding chapter, after a small amount of vertical whitespace.
	2770
	2771	You can use the @code{@@setchapternewpage} command with various
	2772	arguments to specify how @TeX{} should start chapters and whether it
	2773	should format headers for printing on one or both sides of the paper
	2774	(single-sided or double-sided printing).
	2775
	2776	Write the @code{@@setchapternewpage} command at the beginning of a
	2777	line followed by its argument.
	2778
	2779	For example, you would write the following to cause each chapter to
	2780	start on a fresh odd-numbered page:
	2781
	2782	@example
	2783	@@setchapternewpage odd
	2784	@end example
	2785
	2786	You can specify one of three alternatives with the
	2787	@code{@@setchapternewpage} command:
	2788
	2789	@table @asis
	2790
	2791	@item @code{@@setchapternewpage off}
	2792	Cause @TeX{} to typeset a new chapter on the same page as the last
	2793	chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
	2794	format page headers for single-sided printing.
	2795
	2796	@item @code{@@setchapternewpage on}
	2797	Cause @TeX{} to start new chapters on new pages and to format page
	2798	headers for single-sided printing. This is the form most often used for
	2799	short reports or personal printing. This is the default.
	2800
	2801	@item @code{@@setchapternewpage odd}
	2802	Cause @TeX{} to start new chapters on new, odd-numbered pages
	2803	(right-handed pages) and to typeset for double-sided printing. This is
	2804	the form most often used for books and manuals.
	2805	@end table
	2806
	2807	Texinfo does not have a @code{@@setchapternewpage even} command,
	2808	because there is no printing tradition of starting chapters or books on
	2809	an even-numbered page.
	2810
	2811	If you don't like the default headers that @code{@@setchapternewpage}
	2812	sets, you can explicit control them with the @code{@@headings} command.
	2813	@xref{@code{@@headings}}.
	2814
	2815	At the beginning of a manual or book, pages are not numbered---for
	2816	example, the title and copyright pages of a book are not numbered. By
	2817	convention, table of contents and frontmatter pages are numbered with
	2818	roman numerals and not in sequence with the rest of the document.
	2819
	2820	The @code{@@setchapternewpage} has no effect in output formats that do
	2821	not have pages, such as Info and HTML.
	2822
	2823	We recommend not including any @code{@@setchapternewpage} command in
	2824	your document source at all, since such desired pagination is not
	2825	intrinsic to the document. For a particular hard copy run, if you
	2826	don't want the default output (no blank pages, same headers on all
	2827	pages) use the @option{--texinfo} option to @command{texi2dvi} to
	2828	specify the output you want.
	2829
	2830
	2831	@node @code{@@headings}
	2832	@subsection The @code{@@headings} Command
	2833
	2834	@anchor{headings on off}@c old name
	2835	@findex headings
	2836
	2837	The @code{@@headings} command is rarely used. It specifies what kind of
	2838	page headings and footings to print on each page. Usually, this is
	2839	controlled by the @code{@@setchapternewpage} command. You need the
	2840	@code{@@headings} command only if the @code{@@setchapternewpage} command
	2841	does not do what you want, or if you want to turn off predefined page
	2842	headings prior to defining your own. Write a @code{@@headings} command
	2843	immediately after the @code{@@end titlepage} command.
	2844
	2845	You can use @code{@@headings} as follows:
	2846
	2847	@table @code
	2848	@item @@headings off
	2849	Turn off printing of page headings.
	2850
	2851	@item @@headings single
	2852	Turn on page headings appropriate for single-sided printing.
	2853
	2854	@item @@headings double
	2855	Turn on page headings appropriate for double-sided printing.
	2856
	2857	@item @@headings singleafter
	2858	@itemx @@headings doubleafter
	2859	Turn on @code{single} or @code{double} headings, respectively, after the
	2860	current page is output.
	2861
	2862	@item @@headings on
	2863	Turn on page headings: @code{single} if @samp{@@setchapternewpage
	2864	on}, @code{double} otherwise.
	2865	@end table
	2866
	2867	For example, suppose you write @code{@@setchapternewpage off} before the
	2868	@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
	2869	same page as the end of the last chapter. This command also causes
	2870	@TeX{} to typeset page headers for single-sided printing. To cause
	2871	@TeX{} to typeset for double sided printing, write @code{@@headings
	2872	double} after the @code{@@end titlepage} command.
	2873
	2874	You can stop @TeX{} from generating any page headings at all by
	2875	writing @code{@@headings off} on a line of its own immediately after the
	2876	line containing the @code{@@end titlepage} command, like this:
	2877
	2878	@example
	2879	@@end titlepage
	2880	@@headings off
	2881	@end example
	2882
	2883	@noindent
	2884	The @code{@@headings off} command overrides the @code{@@end titlepage}
	2885	command, which would otherwise cause @TeX{} to print page headings.
	2886
	2887	You can also specify your own style of page heading and footing.
	2888	@xref{Headings, , Page Headings}, for more information.
	2889
	2890
	2891	@node @code{@@paragraphindent}
	2892	@subsection @code{@@paragraphindent}: Controlling Paragraph Indentation
	2893
	2894	@anchor{paragraphindent}@c old name
	2895	@findex paragraphindent
	2896	@cindex Indenting paragraphs, control of
	2897	@cindex Paragraph indentation control
	2898
	2899	The Texinfo processors may insert whitespace at the beginning of the
	2900	first line of each paragraph, thereby indenting that paragraph. You can
	2901	use the @code{@@paragraphindent} command to specify this indentation.
	2902	Write a @code{@@paragraphindent} command at the beginning of a line
	2903	followed by either @samp{asis} or a number:
	2904
	2905	@example
	2906	@@paragraphindent @var{indent}
	2907	@end example
	2908
	2909	The indentation is according to the value of @var{indent}:
	2910
	2911	@table @asis
	2912	@item @code{asis}
	2913	Do not change the existing indentation (not implemented in @TeX{}).
	2914
	2915	@item @code{none}
	2916	@itemx 0
	2917	Omit all indentation.
	2918
	2919	@item @var{n}
	2920	Indent by @var{n} space characters in Info output, by @var{n} ems in
	2921	@TeX{}.
	2922
	2923	@end table
	2924
	2925	The default value of @var{indent} is 3. @code{@@paragraphindent} is
	2926	ignored for HTML output.
	2927
	2928	It is best to write the @code{@@paragraphindent} command before the
	2929	end-of-header line at the beginning of a Texinfo file, so the region
	2930	formatting commands indent paragraphs as specified. @xref{Start of
	2931	Header}.
	2932
	2933
	2934	@node @code{@@firstparagraphindent}
	2935	@subsection @code{@@firstparagraphindent}: Indenting After Headings
	2936
	2937	@anchor{firstparagraphindent}@c old name
	2938	@findex firstparagraphindent
	2939	@cindex First paragraph, suppressing indentation of
	2940	@cindex Suppressing first paragraph indentation
	2941	@cindex Preventing first paragraph indentation
	2942	@cindex Indenting, suppressing of first paragraph
	2943	@cindex Headings, indentation after
	2944
	2945	As you can see in the present manual, the first paragraph in any
	2946	section is not indented by default. Typographically, indentation is a
	2947	paragraph separator, which means that it is unnecessary when a new
	2948	section begins. This indentation is controlled with the
	2949	@code{@@firstparagraphindent} command:
	2950
	2951	@example
	2952	@@firstparagraphindent @var{word}
	2953	@end example
	2954
	2955	The first paragraph after a heading is indented according to the value
	2956	of @var{word}:
	2957
	2958	@table @asis
	2959	@item @code{none}
	2960	Prevents the first paragraph from being indented (default).
	2961	This option is ignored by @command{makeinfo} if
	2962	@code{@@paragraphindent asis} is in effect.
	2963
	2964	@item @code{insert}
	2965	Include normal paragraph indentation. This respects the paragraph
	2966	indentation set by a @code{@@paragraphindent} command
	2967	(@pxref{@code{@@paragraphindent}}).
	2968	@end table
	2969
	2970	@code{@@firstparagraphindent} is ignored for HTML and Docbook output.
	2971
	2972	It is best to write the @code{@@firstparagraphindent} command before the
	2973	end-of-header line at the beginning of a Texinfo file, so the region
	2974	formatting commands indent paragraphs as specified. @xref{Start of
	2975	Header}.
	2976
	2977
	2978	@node @code{@@exampleindent}
	2979	@subsection @code{@@exampleindent}: Environment Indenting
	2980
	2981	@anchor{exampleindent}@c old name
	2982	@findex exampleindent
	2983	@cindex Indenting environments
	2984	@cindex Environment indentation
	2985	@cindex Example indentation
	2986
	2987	The Texinfo processors indent each line of @code{@@example} and similar
	2988	environments. You can use the @code{@@exampleindent} command to specify
	2989	this indentation. Write an @code{@@exampleindent} command at the
	2990	beginning of a line followed by either @samp{asis} or a number:
	2991
	2992	@example
	2993	@@exampleindent @var{indent}
	2994	@end example
	2995
	2996	The indentation is according to the value of @var{indent}:
	2997
	2998	@table @asis
	2999	@item @code{asis}
	3000	Do not change the existing indentation (not implemented in @TeX{}).
	3001
	3002	@item 0
	3003	Omit all indentation.
	3004
	3005	@item @var{n}
	3006	Indent environments by @var{n} space characters in Info output, by
	3007	@var{n} ems in @TeX{}.
	3008
	3009	@end table
	3010
	3011	The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in}
	3012	in @TeX{}, which is somewhat less. (The reduction is to help @TeX{}
	3013	fit more characters onto physical lines.)
	3014
	3015	It is best to write the @code{@@exampleindent} command before the
	3016	end-of-header line at the beginning of a Texinfo file, so the region
	3017	formatting commands indent paragraphs as specified. @xref{Start of
	3018	Header}.
	3019
	3020
	3021	@node Ending a File
	3022	@section Ending a Texinfo File
	3023	@cindex Ending a Texinfo file
	3024	@cindex Texinfo file ending
	3025	@cindex File ending
	3026	@findex bye
	3027
	3028	The end of a Texinfo file should include commands to create indices
	3029	(@pxref{Printing Indices & Menus}), and the @code{@@bye} command to mark
	3030	the last line to be processed. For example:
	3031
	3032	@example
	3033	@@node Index
	3034	@@unnumbered Index
	3035
	3036	@@printindex cp
	3037
	3038	@@bye
	3039	@end example
	3040
	3041	@findex bye
	3042	@anchor{File End}
	3043	An @code{@@bye} command terminates Texinfo processing. None of the
	3044	formatters process anything following @code{@@bye}; any such text is
	3045	completely ignored. The @code{@@bye} command should be on a line by
	3046	itself.
	3047
	3048	Thus, if you wish, you may follow the @code{@@bye} line with arbitrary
	3049	notes. Also, you may follow the @code{@@bye} line with a local
	3050	variables list for Emacs, most typically a @samp{compile-command}
	3051	(@pxref{Compile-Command,, Using the Local Variables List}).
	3052
	3053
	3054	@node Nodes
	3055	@chapter Nodes
	3056	@anchor{node}@anchor{@@node} @c old names
	3057
	3058	@cindex Node, defined
	3059	A @dfn{node} is a region of text that begins at a @code{@@node}
	3060	command, and continues until the next @code{@@node} command.
	3061	To specify a node, write a @code{@@node} command at the beginning of
	3062	a line, and follow it with the name of the node.
	3063	Each node contains the discussion of one topic. Info readers
	3064	display one node at a time, and provide commands for the user to move
	3065	to related nodes. The HTML output can be similarly navigated.
	3066
	3067	Nodes are used as the targets of cross-references. Cross-references,
	3068	such as the one at the end of this sentence, are made with @code{@@xref}
	3069	and related commands; see @ref{Cross References}. Cross-references can
	3070	be sprinkled throughout the text, and provide a way to represent links
	3071	that do not fit a hierarchical structure.
	3072
	3073	Normally, you put a node command immediately before each chapter
	3074	structuring command---for example, an @code{@@section} or
	3075	@code{@@subsection} line. (@xref{Chapter Structuring}.).
	3076	You must do this even if you do not intend to format the file for Info.
	3077	This is because @TeX{} uses both @code{@@node} names and
	3078	chapter-structuring names in the output for cross-references. The only
	3079	time you are likely to use the chapter structuring commands without also
	3080	using nodes is if you are writing a document that contains no cross
	3081	references and will only be printed, not transformed into Info, HTML, or
	3082	other formats.
	3083
	3084
	3085	@menu
	3086	* Texinfo Document Structure:: Double structure of documents.
	3087	* Node Names:: How to choose node names.
	3088	* Writing a Node:: How to write an @code{@@node} line.
	3089	* Node Line Requirements:: Keep names unique.
	3090	* First Node:: How to write a `Top' node.
	3091	* @code{@@top} Command:: How to use the @code{@@top} command.
	3092	* Node Menu Illustration:: A diagram, and sample nodes and menus.
	3093	* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
	3094	* Menus:: Listing subordinate nodes.
	3095	@end menu
	3096
	3097
	3098	@node Texinfo Document Structure
	3099	@section Texinfo Document Structure
	3100	@cindex Texinfo document structure
	3101	@cindex Document structure, of Texinfo
	3102	@cindex Structure, of Texinfo documents
	3103	@cindex Double structure, of Texinfo documents
	3104
	3105	@anchor{Two Paths}@c node name
	3106
	3107	Nodes can contain @dfn{menus}, which contain the names of @dfn{child
	3108	nodes} within the parent node; for example, a node corresponding to a
	3109	chapter would have a menu of the sections in that chapter. The menus
	3110	allow the user to move to the child nodes in a natural way in the online
	3111	output.
	3112
	3113	In addition, nodes contain @dfn{node pointers} that name other nodes.
	3114	The `Next' and `Previous' pointers form nodes at the same sectioning
	3115	level into a chain. As you might imagine, the `Next' pointer links to
	3116	the next node, and the `Previous' pointer links to the previous node.
	3117	Thus, for example, all the nodes that are at the level of sections
	3118	within a chapter are linked together, and the order in this chain
	3119	is the same as the order of the children in the menu of the parent
	3120	chapter. Each child node records the parent node name as its `Up'
	3121	pointer.
	3122
	3123	@opindex accesskey@r{, in HTML output of nodes}
	3124	The Info and HTML output from @command{makeinfo} for each node includes
	3125	links to the `Next', `Previous', and `Up' nodes. The HTML also uses
	3126	the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
	3127	@samp{u} respectively. This allows people using web browsers to
	3128	follow the navigation using (typically) @kbd{M-@var{letter}}, e.g.,
	3129	@kbd{M-n} for the `Next' node, from anywhere within the node.
	3130	Node pointers and menus provide structure for Info files just as
	3131	chapters, sections, subsections, and the like provide structure for
	3132	printed books. The two structures are theoretically distinct; in
	3133	practice, however, the tree structure of printed books is essentially
	3134	always used for the node and menu structure also, as this leads to a
	3135	document which is easiest to follow. @xref{Texinfo Document
	3136	Structure}.
	3137
	3138	Typically, the sectioning structure and the node structure are
	3139	completely parallel, with one node for each chapter, section, etc.,
	3140	and with the nodes following the same hierarchical arrangement as the
	3141	sectioning. Thus, if a node is at the logical level of a chapter, its
	3142	child nodes are at the level of sections; similarly, the child nodes
	3143	of sections are at the level of subsections.
	3144
	3145	Although it is technically possible to create Texinfo documents with
	3146	only one structure or the other, or for the two structures not to be
	3147	parallel, or for either the sectioning or node structure to be
	3148	abnormally formed, etc., this is @emph{not at all recommended}. To
	3149	the best of our knowledge, all the Texinfo manuals currently in
	3150	general use do follow the conventional parallel structure.
	3151
	3152
	3153	@node Node Names
	3154	@section Choosing Node Names
	3155
	3156	@cindex Node names, choosing
	3157	The name of a node identifies the node. For all the details of node
	3158	names, @pxref{Node Line Requirements}).
	3159
	3160	@anchor{Node Line Tips}@c previous node name
	3161	Here are some suggestions for node names:
	3162
	3163	@itemize @bullet
	3164	@item
	3165	Try to pick node names that are informative but short.
	3166
	3167	In the Info file, the file name, node name, and pointer names are all
	3168	inserted on one line, which may run into the right edge of the window.
	3169	(This does not cause a problem with Info, but is ugly.)
	3170
	3171	@item
	3172	Try to pick node names that differ from each other near the beginnings
	3173	of their names. This way, it is easy to use automatic name completion in
	3174	Info.
	3175
	3176	@item
	3177	Conventionally, node names are capitalized in the same way as section
	3178	and chapter titles. In this manual, initial and significant words are
	3179	capitalized; others are not. In other manuals, just initial words and
	3180	proper nouns are capitalized. Either way is fine; we recommend just
	3181	being consistent.
	3182
	3183	@item
	3184	In HTML output, any characters in the node name other than plain ASCII
	3185	letters, numbers or spaces will be changed in the file name.
	3186	(@xref{HTML Xref Node Name Expansion}.)
	3187	This can make the URL's for the pages in your manual less user-friendly;
	3188	for example in this manual the @samp{@@dots} node is output as
	3189	@file{__0040dots.html}.
	3190	@end itemize
	3191
	3192	Because node names are used in cross-references, it is not desirable
	3193	to casually change them once published. Such name changes invalidate
	3194	references from other manuals, from mail archives, and so on.
	3195
	3196	The pointers from a given node enable you to reach other nodes and
	3197	consist simply of the names of those nodes. The pointers are usually
	3198	not specified explicitly, as @command{makeinfo} can determine them
	3199	(@pxref{@command{makeinfo} Pointer Creation}).
	3200
	3201	Normally, a node's `Up' pointer contains the name of the node whose
	3202	menu mentions that node. The node's `Next' pointer contains the name
	3203	of the node that follows the present node in that menu and its
	3204	`Previous' pointer contains the name of the node that precedes it in
	3205	that menu. When a node's `Previous' node is the same as its `Up'
	3206	node, both pointers name the same node.
	3207
	3208	Usually, the first node of a Texinfo file is the `Top' node, and its
	3209	`Up' pointer points to the @file{dir} file, which contains the main menu
	3210	for all of Info.
	3211
	3212
	3213	@node Writing a Node
	3214	@section Writing an @code{@@node} Line
	3215	@cindex Writing an @code{@@node} line
	3216	@cindex @code{@@node} line writing
	3217	@cindex Node line writing
	3218
	3219	@findex node
	3220	The easiest way to write an @code{@@node} line is to write @code{@@node}
	3221	at the beginning of a line and then the name of the node, like this:
	3222
	3223	@example
	3224	@@node @var{node-name}
	3225	@end example
	3226
	3227	After you have inserted an @code{@@node} line, you should immediately
	3228	write an @@-command for the chapter or section and insert its name.
	3229	Next (and this is important!), put in several index entries. Usually,
	3230	you will find at least two and often as many as four or five ways of
	3231	referring to the node in the index. Use them all. This will make it
	3232	much easier for people to find the node.
	3233
	3234	If you wish, you can ignore @code{@@node} lines altogether in your
	3235	first draft and then use the @code{texinfo-insert-node-lines} command
	3236	to create @code{@@node} lines for you. However, we do not recommend
	3237	this practice. It is better to name the node itself at the same time
	3238	that you write a segment so you can easily make cross-references.
	3239	Useful cross-references are an especially important feature of a good
	3240	Texinfo manual.
	3241
	3242	Even when you explicitly specify all pointers, you cannot write the
	3243	nodes in the Texinfo source file in an arbitrary order! Because
	3244	formatters must process the file sequentially, irrespective of node
	3245	pointers, you must write the nodes in the order you wish them to
	3246	appear in the output. For Info format one can imagine that the order
	3247	may not matter, but it matters for the other formats.
	3248
	3249	You may optionally follow the node name argument to @code{@@node}
	3250	with up to three optional arguments on the rest of the same line,
	3251	separating the arguments with commas. These are the names of the
	3252	`Next', `Previous', and `Up' pointers, in that order. We recommend
	3253	omitting them if your Texinfo document is hierarchically organized,
	3254	as virtually all are (@pxref{@command{makeinfo} Pointer Creation}).
	3255
	3256	Any spaces before or after each name on the @code{@@node} line are
	3257	ignored.
	3258
	3259	The template for a fully-written-out node line with `Next', `Previous',
	3260	and `Up' pointers looks like this:
	3261
	3262	@example
	3263	@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
	3264	@end example
	3265
	3266	The @var{node-name} argument must be present, but the others are
	3267	optional. If you wish to specify some but not others, just insert
	3268	commas as needed, as in: @samp{@@node mynode,,,uppernode}. However,
	3269	we recommend leaving off all the pointers and letting @code{makeinfo}
	3270	determine them.
	3271
	3272	If you are using GNU Emacs, you can use the update node commands
	3273	provided by Texinfo mode to insert the names of the pointers; or
	3274	(recommended), you can leave the pointers out of the Texinfo file and
	3275	let @code{makeinfo} insert node pointers into the Info file it
	3276	creates. (@xref{Texinfo Mode}, and @ref{@command{makeinfo} Pointer
	3277	Creation}.)
	3278
	3279	Alternatively, you can insert the `Next', `Previous', and `Up'
	3280	pointers yourself. If you do this, you may find it helpful to use the
	3281	Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
	3282	@samp{@@node} and a comment line listing the names of the pointers in
	3283	their proper order. The comment line helps you keep track of which
	3284	arguments are for which pointers. This comment line is especially useful
	3285	if you are not familiar with Texinfo.
	3286
	3287
	3288	@node Node Line Requirements
	3289	@section @code{@@node} Line Requirements
	3290
	3291	@cindex Node line requirements
	3292	@cindex Restrictions on node names
	3293
	3294	Names used with @code{@@node} have several requirements:
	3295
	3296	@itemize @bullet
	3297	@item
	3298	@cindex Unique node names requirement
	3299	@cindex Node names must be unique
	3300	All the node names in a single Texinfo file must be unique.
	3301
	3302	This means, for example, that if you end every chapter with a summary,
	3303	you must name each summary node differently. You cannot just call
	3304	them all ``Summary''. You may, however, duplicate the titles of
	3305	chapters, sections, and the like. Thus you can end each chapter with
	3306	a section called ``Summary'', so long as the node names for those
	3307	sections are all different.
	3308
	3309	@item
	3310	@cindex Commands in node names
	3311	@cindex @@-commands in node names
	3312	Node names can contain @@-commands. The output is generally the
	3313	natural result of the command; for example, using @code{@@TeX@{@}} in a
	3314	node name results in the @TeX{} logo being output, as it would be in
	3315	normal text. Cross-references should use @code{@@TeX@{@}} just as the
	3316	node name does.
	3317
	3318	For Info and HTML output, especially, it is necessary to expand
	3319	commands to some sequence of plain characters; for instance,
	3320	@code{@@TeX@{@}} expands to the three letters @samp{TeX} in the Info
	3321	node name. However, cross-references to the node should not take the
	3322	``shortcut'' of using @samp{TeX}; stick to the actual node name,
	3323	commands and all.
	3324
	3325	Some commands do not make sense in node names; for instance,
	3326	environments (e.g., @code{@@quotation}), commands that read a whole
	3327	line as their argument (e.g., @code{@@sp}), and plenty of others.
	3328
	3329	For the complete list of commands that are allowed, and their
	3330	expansion for HTML identifiers and file names, @pxref{HTML Xref
	3331	Command Expansion}. The expansions for Info are generally given with
	3332	main the description of the command.
	3333
	3334	Prior to the Texinfo 5 release in 2013, this feature was supported in
	3335	an ad hoc way (the @option{--commands-in-node-names} option to
	3336	@command{makeinfo}). Now it is part of the language.
	3337
	3338	@item
	3339	@cindex Colon in node name
	3340	@cindex Comma in node name
	3341	@cindex Parentheses in node name
	3342	@cindex Period in node name
	3343	@cindex Characters, invalid in node name
	3344	@cindex Invalid characters in node names
	3345	@cindex Node names, invalid characters in
	3346	Unfortunately, you cannot reliably use periods, commas, or colons
	3347	within a node name; these can confuse the Info reader. Also, a node
	3348	name may not start with a left parenthesis preceding a right
	3349	parenthesis, as in @code{(not)allowed}, since this syntax is used to
	3350	specify an external manual. (Perhaps these limitations will be
	3351	removed some day.)
	3352
	3353	@command{makeinfo} warns about such problematic usage in node names,
	3354	menu items, and cross-references. If you don't want to see the
	3355	warnings, you can set the customization variable
	3356	@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other
	3357	Customization Variables}).
	3358
	3359	Also, if you insist on using these characters in node names (accepting
	3360	the resulting substandard Info output), in order not to confuse the
	3361	Texinfo processors you must still escape those characters, by using
	3362	either special insertions (@pxref{Inserting a Comma}) or @code{@@asis}
	3363	(@pxref{@code{@@asis}}). For example:
	3364
	3365	@example
	3366	@@node foo@@asis@{::@}bar
	3367	@end example
	3368
	3369	As an example of avoiding the special characters, the following is a
	3370	section title in this manual:
	3371
	3372	@smallexample
	3373	@@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: ...
	3374	@end smallexample
	3375
	3376	@noindent
	3377	But the corresponding node name lacks the commas and the subtitle:
	3378
	3379	@smallexample
	3380	@@node @code{@@unnumbered @@appendix}
	3381	@end smallexample
	3382
	3383	@cindex Case in node name
	3384	@item
	3385	Case is significant in node names.
	3386
	3387	@cindex White space in node name
	3388	@cindex Spaces in node name
	3389	@item
	3390	Spaces before and after names on the @samp{@@node} line are ignored.
	3391	Multiple whitespace characters ``inside'' a name are collapsed to a
	3392	single space. For example:
	3393
	3394	@example
	3395	@@node foo bar
	3396	@@node foo bar,
	3397	@@node foo bar ,
	3398	@@node foo bar,
	3399	@@node foo bar ,
	3400	@end example
	3401
	3402	@noindent all define the same node, namely @samp{foo bar}.
	3403	In menu entries, this is the name that should be used: no leading or
	3404	trailing spaces, and a single internal space. (For cross-references,
	3405	the node name used in the Texinfo sources is automatically normalized
	3406	in this way.)
	3407
	3408	@item
	3409	The next/previous/up pointers on @code{@@node} lines must be the names
	3410	of nodes. (It's recommended to leave out these explicit node pointer
	3411	names, which automatically avoids any problem here; @pxref{@command{makeinfo}
	3412	Pointer Creation}.)
	3413	@end itemize
	3414
	3415
	3416	@node First Node
	3417	@section The First Node
	3418	@cindex Top node is first
	3419	@cindex First node
	3420
	3421	The first node of a Texinfo file is the @dfn{Top} node, except in an
	3422	included file (@pxref{Include Files}). The Top node should contain a
	3423	short summary, copying permissions, and a master menu. @xref{The Top
	3424	Node}, for more information on the Top node contents and examples.
	3425
	3426	Here is a description of the node pointers to be used in the Top node:
	3427
	3428	@itemize @bullet
	3429	@item
	3430	@cindex Up node of Top node
	3431	@cindex (dir) as Up node of Top node
	3432	The Top node (which must be named @samp{top} or @samp{Top}) should have
	3433	as its `Up' node the name of a node in another file, where there is a
	3434	menu that leads to this file. Specify the file name in parentheses.
	3435
	3436	Usually, all Info files are available through a single virtual Info
	3437	tree, constructed from multiple directories. In this case, use
	3438	@samp{(dir)} as the parent of the Top node; this specifies the
	3439	top-level node in the @file{dir} file, which contains the main menu
	3440	for the Info system as a whole. (Each directory with Info files is
	3441	intended to contain a file named @file{dir}.)
	3442
	3443	That's fine for Info, but for HTML output, one might well want the Up
	3444	link from the Top node to go to some specific place.
	3445	For example, for GNU the natural place would be
	3446	@url{http://www.gnu.org/manual/} (a web page collecting links to most
	3447	GNU manuals), better specified as just @code{/manual/} if the manual
	3448	will be installed on @code{www.gnu.org}. This can be specified with
	3449	the @code{TOP_NODE_UP_URL} customization variable (@pxref{HTML
	3450	Customization Variables}), as in
	3451
	3452	@example
	3453	$ @kbd{makeinfo --html -c TOP_NODE_UP_URL=/manual/} ...
	3454	@end example
	3455
	3456	@c the following line is not true anymore
	3457	@c All links to @code{(dir)} will be replaced by the given url.
	3458
	3459	@item
	3460	@cindex Prev node of Top node
	3461	The `Prev' node of the Top node is usually either omitted or also set
	3462	to @file{(dir)}. Either is fine.
	3463
	3464	@item
	3465	@cindex Next node of Top node
	3466	The `Next' node of the Top node should be the first chapter in your
	3467	document.
	3468
	3469	@end itemize
	3470
	3471	@xref{Installing an Info File}, for more information about installing
	3472	an Info file in the @file{info} directory.
	3473
	3474	It is usually best to leave the pointers off entirely and let the
	3475	tools implicitly define them, with this simple result:
	3476
	3477	@example
	3478	@@node Top
	3479	@end example
	3480
	3481
	3482	@node @code{@@top} Command
	3483	@section The @code{@@top} Sectioning Command
	3484
	3485	@anchor{top command}@c old name
	3486	@anchor{makeinfo top}@c another old name
	3487	@anchor{makeinfo top command}@c yet another name
	3488	@findex top
	3489
	3490	The @code{@@top} command is a special sectioning command that you
	3491	should only use after a @samp{@@node Top} line at the beginning of a
	3492	Texinfo file. The @code{@@top} command tells the @code{makeinfo}
	3493	formatter which node is to be used as the root of the node tree.
	3494
	3495	It produces the same sort of output as @code{@@unnumbered}
	3496	(@pxref{@code{@@unnumbered @@appendix}}).
	3497
	3498	The @code{@@top} node is conventionally wrapped in an
	3499	@code{@@ifnottex} conditional so that it will not appear in @TeX{}
	3500	output (@pxref{Conditionals}).
	3501	Thus, in practice, a Top node usually looks like this:
	3502
	3503	@example
	3504	@@ifnottex
	3505	@@node Top
	3506	@@top @var{your-manual-title}
	3507
	3508	@var{very-high-level-summary}
	3509	@@end ifnottex
	3510	@end example
	3511
	3512	@code{@@top} is ignored when raising or lowering sections. That is,
	3513	it is never lowered and nothing can be raised to it
	3514	(@pxref{Raise/lower sections}).
	3515
	3516
	3517	@node Node Menu Illustration
	3518	@section Node and Menu Illustration
	3519
	3520	Here is a diagram that illustrates a Texinfo file with three chapters,
	3521	each of which contains two sections.
	3522
	3523	The ``root'' is at the top of the diagram and the ``leaves'' are at
	3524	the bottom. This is how such a diagram is drawn conventionally; it
	3525	illustrates an upside-down tree. For this reason, the root node is
	3526	called the `Top' node, and `Up' node pointers carry you closer to the
	3527	root.
	3528
	3529	@example
	3530	@group
	3531	Top
	3532	\|
	3533	-------------------------------------
	3534	\| \| \|
	3535	Chapter 1 Chapter 2 Chapter 3
	3536	\| \| \|
	3537	-------- -------- --------
	3538	\| \| \| \| \| \|
	3539	Section Section Section Section Section Section
	3540	1.1 1.2 2.1 2.2 3.1 3.2
	3541	@end group
	3542	@end example
	3543
	3544	Using explicit pointers (not recommended, but shown for purposes
	3545	of the example), the fully-written command to start Chapter@tie{}2
	3546	would be this:
	3547
	3548	@example
	3549	@group
	3550	@@node Chapter 2, Chapter 3, Chapter 1, Top
	3551	@@comment node-name, next, previous, up
	3552	@end group
	3553	@end example
	3554
	3555	@noindent
	3556	This @code{@@node} line says that the name of this node is
	3557	``Chapter@tie{}2'', the name of the `Next' node is ``Chapter 3'', the
	3558	name of the `Previous' node is ``Chapter@tie{}1'', and the name of the
	3559	`Up' node is ``Top''. You can (and should) omit writing out these
	3560	node names if your document is hierarchically organized
	3561	(@pxref{@command{makeinfo} Pointer Creation}), but the pointer
	3562	relationships still obtain.
	3563
	3564	@quotation Note
	3565	`Next' and `Previous' refer to nodes at the @emph{same hierarchical
	3566	level} in the manual, not necessarily to the next node within the
	3567	Texinfo file. In the Texinfo file, the subsequent node may be at a
	3568	lower level---a section-level node most often follows a chapter-level
	3569	node, for example. (The `Top' node contains the exception to this
	3570	rule. Since the `Top' node is the only node at that level, `Next'
	3571	refers to the first following node, which is almost always a chapter
	3572	or chapter-level node.)
	3573	@end quotation
	3574
	3575	To go to Sections 2.1 and 2.2 using Info, you need a menu inside
	3576	Chapter 2. (@xref{Menus}.) You would write the menu just before the
	3577	beginning of Section 2.1, like this:
	3578
	3579	@example
	3580	@group
	3581	@@menu
	3582	* Sect. 2.1:: Description of this section.
	3583	* Sect. 2.2:: Description.
	3584	@@end menu
	3585	@end group
	3586	@end example
	3587
	3588	Using explicit pointers, the node for Sect.@: 2.1 is written like this:
	3589
	3590	@example
	3591	@group
	3592	@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
	3593	@@comment node-name, next, previous, up
	3594	@end group
	3595	@end example
	3596
	3597	In Info format, the `Next' and `Previous' pointers of a node usually
	3598	lead to other nodes at the same level---from chapter to chapter or
	3599	from section to section (sometimes, as shown, the `Previous' pointer
	3600	points up); an `Up' pointer usually leads to a node at the level above
	3601	(closer to the `Top' node); and a `Menu' leads to nodes at a level
	3602	below (closer to `leaves'). (A cross-reference can point to a node at
	3603	any level; see @ref{Cross References}.)
	3604
	3605	A @code{@@node} command and a chapter structuring command are
	3606	conventionally used together, in that order, often followed by
	3607	indexing commands. (As shown in the example above, you may follow the
	3608	@code{@@node} line with a comment line, e.g., to show which pointer is
	3609	which if explicit pointers are used.) The Texinfo processors use this
	3610	construct to determine the relationships between nodes and sectioning
	3611	commands.
	3612
	3613	Here is the beginning of the chapter in this manual called ``Ending a
	3614	Texinfo File''. This shows an @code{@@node} line followed by an
	3615	@code{@@chapter} line, and then by indexing lines.
	3616
	3617	@example
	3618	@group
	3619	@@node Ending a File
	3620	@@chapter Ending a Texinfo File
	3621	@@cindex Ending a Texinfo file
	3622	@@cindex Texinfo file ending
	3623	@@cindex File ending
	3624	@end group
	3625	@end example
	3626
	3627	An earlier version of the manual used explicit node pointers. Here is
	3628	the beginning of the same chapter for that case. This shows an
	3629	@code{@@node} line followed by a comment line, a @code{@@chapter}
	3630	line, and then by indexing lines.
	3631
	3632	@example
	3633	@group
	3634	@@node Ending a File, Structuring, Beginning a File, Top
	3635	@@comment node-name, next, previous, up
	3636	@@chapter Ending a Texinfo File
	3637	@@cindex Ending a Texinfo file
	3638	@dots{}
	3639	@end group
	3640	@end example
	3641
	3642
	3643	@node @command{makeinfo} Pointer Creation
	3644	@section @code{makeinfo} Pointer Creation
	3645
	3646	@cindex Creating pointers with @code{makeinfo}
	3647	@cindex Pointer creation with @code{makeinfo}
	3648	@cindex Automatic pointer creation with @code{makeinfo}
	3649	@cindex Implicit pointer creation with @code{makeinfo}
	3650
	3651	The @code{makeinfo} program can automatically determine node pointers
	3652	for a hierarchically organized document. This implicit node pointer
	3653	creation feature in @code{makeinfo} relieves you from the need to
	3654	update menus and pointers manually or with Texinfo mode commands.
	3655	(@xref{Updating Nodes and Menus}.) We highly recommend taking
	3656	advantage of this.
	3657
	3658	To do so, write your @code{@@node} lines with just the name of the
	3659	node:
	3660
	3661	@example
	3662	@@node My Node
	3663	@end example
	3664
	3665	@noindent
	3666	You do not need to write out the `Next', `Previous', and `Up'
	3667	pointers.
	3668
	3669	Then, you must write a sectioning command, such as @code{@@chapter}
	3670	or @code{@@section}, on the line immediately following each truncated
	3671	@code{@@node} line (except that comment lines may intervene). This is
	3672	where it normally goes.
	3673
	3674	Also, you must write the name of each node (except for the `Top' node)
	3675	in a menu that is one or more hierarchical levels above the node's
	3676	level.
	3677
	3678	Finally, you must follow the `Top' @code{@@node} line with a line
	3679	beginning with @code{@@top} to mark the top-level node in the file.
	3680	@xref{@code{@@top} Command}.
	3681
	3682	@cindex Detail menu
	3683	@findex detailmenu
	3684	If you use a detailed menu in your master menu (@pxref{Master Menu
	3685	Parts}), mark it with the @code{@@detailmenu @dots{} @@end
	3686	detailmenu} environment, or @command{makeinfo} will get confused,
	3687	typically about the last and/or first node in the document.
	3688
	3689	In most cases, you will want to take advantage of this feature and not
	3690	redundantly specify node pointers that the programs can determine.
	3691	However, Texinfo documents are not required to be organized
	3692	hierarchically or in fact to contain sectioning commands at all (for
	3693	example, if you never intend the document to be printed), so node
	3694	pointers may still be specified explicitly, in full generality.
	3695
	3696
	3697	@node Menus
	3698	@section Menus
	3699	@cindex Menus
	3700	@findex menu
	3701
	3702	@dfn{Menus} contain pointers to subordinate nodes. In online output,
	3703	you use menus to go to such nodes. Menus have no effect in printed
	3704	manuals and do not appear in them.
	3705
	3706	@menu
	3707	* Writing a Menu:: What is a menu?
	3708	* Menu Example:: Two and three part menu entries.
	3709	* Menu Location:: Menus go at the ends of nodes.
	3710	* Menu Parts:: A menu entry has three parts.
	3711	* Less Cluttered Menu Entry:: Two part menu entry.
	3712	* Other Info Files:: How to refer to a different Info file.
	3713	@end menu
	3714
	3715
	3716	@node Writing a Menu
	3717	@subsection Writing a Menu
	3718	@cindex Writing a menu
	3719	@cindex Menu writing
	3720
	3721	A menu consists of a @code{@@menu} command on a line by itself,
	3722	followed by menu entry lines or menu comment lines, and then followed
	3723	by an @code{@@end menu} command on a line by itself.
	3724
	3725	A menu looks like this:
	3726
	3727	@example
	3728	@group
	3729	@@menu
	3730	Larger Units of Text
	3731
	3732	* Files:: All about handling files.
	3733	* Multiples: Buffers. Multiple buffers; editing
	3734	several files at once.
	3735	@@end menu
	3736	@end group
	3737	@end example
	3738
	3739	@cindex Spaces, in menus
	3740	In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
	3741	entry}. (Note the space after the asterisk.)
	3742
	3743	A line that does not start with an @w{@samp{* }} may also appear in a
	3744	menu. Such a line is not a menu entry but rather a @dfn{menu comment}
	3745	line that appears in the Info file. In the example above, the line
	3746	@samp{Larger Units of Text} is such a menu comment line; the two lines
	3747	starting with @w{@samp{* }} are menu entries.
	3748
	3749	@cindex Hierarchical documents, and menus
	3750	Technically, menus can carry you to any node, regardless of the
	3751	structure of the document; even to nodes in a different Info file.
	3752	However, we do not recommend making use of this, because it is hard
	3753	for readers to follow. Also, the @command{makeinfo} implicit pointer
	3754	creation feature (@pxref{@command{makeinfo} Pointer Creation}) and GNU
	3755	Emacs Texinfo mode updating commands work only to create menus of
	3756	subordinate nodes in a hierarchically structured document. It is much
	3757	better to use cross-references to refer to arbitrary nodes.
	3758
	3759	@cindex Menus, automatically generating
	3760	@findex validatemenus
	3761	@command{makeinfo} can automatically generate menus in nodes for Info
	3762	and HTML output, based on the chapter structure of the document. To
	3763	specify that you want it to do this, place the line
	3764	@samp{@@validatemenus off} near the beginning of the document.
	3765
	3766	In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
	3767	command. The menu entry name is what the user types after the @kbd{m}
	3768	command.
	3769	@opindex accesskey@r{, in HTML output of menus}
	3770	In the HTML output from @command{makeinfo}, the @code{accesskey}
	3771	attribute is used with the values @samp{1}@dots{}@samp{9} for the
	3772	first nine entries. This allows people using web browsers to follow
	3773	the first menu entries using (typically) @kbd{M-@var{digit}}, e.g.,
	3774	@kbd{M-1} for the first entry.
	3775
	3776	@node Menu Example
	3777	@subsection A Menu Example
	3778	@cindex Menu example
	3779	@cindex Example menu
	3780
	3781	@c merge with Writing a Menu node?
	3782
	3783	A menu looks like this in Texinfo:
	3784
	3785	@example
	3786	@group
	3787	@@menu
	3788	* menu entry name: Node name. A short description.
	3789	* Node name:: This form is preferred.
	3790	@@end menu
	3791	@end group
	3792	@end example
	3793
	3794	@need 800
	3795	@noindent
	3796	This produces:
	3797
	3798	@example
	3799	@group
	3800	* menu:
	3801
	3802	* menu entry name: Node name. A short description.
	3803	* Node name:: This form is preferred.
	3804	@end group
	3805	@end example
	3806
	3807	@need 700
	3808	Here is an example as you might see it in a Texinfo file:
	3809
	3810	@example
	3811	@group
	3812	@@menu
	3813	Larger Units of Text
	3814
	3815	* Files:: All about handling files.
	3816	* Multiples: Buffers. Multiple buffers; editing
	3817	several files at once.
	3818	@@end menu
	3819	@end group
	3820	@end example
	3821
	3822	@need 800
	3823	@noindent
	3824	This produces:
	3825
	3826	@example
	3827	@group
	3828	* menu:
	3829	Larger Units of Text
	3830
	3831	* Files:: All about handling files.
	3832	* Multiples: Buffers. Multiple buffers; editing
	3833	several files at once.
	3834	@end group
	3835	@end example
	3836
	3837	In this example, the menu has two entries. @samp{Files} is both a menu
	3838	entry name and the name of the node referred to by that name.
	3839	@samp{Multiples} is the menu entry name; it refers to the node named
	3840	@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
	3841	appears in the menu, but is not an entry.
	3842
	3843	Since no file name is specified with either @samp{Files} or
	3844	@samp{Buffers}, they must be the names of nodes in the same Info file
	3845	(@pxref{Other Info Files, , Referring to Other Info Files}).
	3846
	3847
	3848	@node Menu Location
	3849	@subsection Menu Location
	3850	@cindex Menu location
	3851	@cindex Location of menus
	3852
	3853	There may be at most one menu in a node. A menu is conventionally
	3854	located at the end of a node, without any regular text or additional
	3855	commands between the @code{@@end menu} and the beginning of the next
	3856	node.
	3857
	3858	@cindex Info format, and menus
	3859	This convention is useful, since a reader who uses the menu could
	3860	easily miss any such text. Also, any such post-menu text will be
	3861	considered part of the menu in Info output (which has no marker for
	3862	the end of a menu). Thus, a line beginning with @samp{* } will likely
	3863	be incorrectly handled.
	3864
	3865	It's usually best if a node with a menu does not contain much text.
	3866	If you find yourself with a lot of text before a menu, we generally
	3867	recommend moving all but a couple of paragraphs into a new subnode.
	3868	Otherwise, it is easy for readers to miss the menu.
	3869
	3870	@ignore
	3871	Years ago, we recommended using a @samp{@@heading} command within an
	3872	@code{@@ifinfo} conditional instead of the normal sectioning commands
	3873	after a very short node with a menu. This had the advantage of making
	3874	the printed output look better, because there was no very short text
	3875	between two headings on the page. But it does not work with
	3876	@command{makeinfo}'s implicit pointer creation, and it also makes the
	3877	XML output incorrect, since it does not reflect the true document
	3878	structure. So, we no longer recommend this.
	3879	@end ignore
	3880
	3881
	3882	@node Menu Parts
	3883	@subsection The Parts of a Menu
	3884	@cindex Parts of a menu
	3885	@cindex Menu parts
	3886	@cindex @code{@@menu} parts
	3887
	3888	A menu entry has three parts, only the second of which is required:
	3889
	3890	@enumerate
	3891	@item
	3892	The menu entry name (optional).
	3893
	3894	@item
	3895	The name of the node (required).
	3896
	3897	@item
	3898	A description of the item (optional).
	3899	@end enumerate
	3900
	3901	The template for a generic menu entry looks like this (but see the
	3902	next section for one more possibility):
	3903
	3904	@example
	3905	* @var{menu-entry-name}: @var{node-name}. @var{description}
	3906	@end example
	3907
	3908	Follow the menu entry name with a single colon, and follow the node
	3909	name with tab, comma, newline, or the two characters period and space
	3910	(@samp{. }).
	3911
	3912	The third part of a menu entry is a descriptive phrase or sentence.
	3913	Menu entry names and node names are often short; the description
	3914	explains to the reader what the node is about. A useful description
	3915	complements the node name rather than repeats it. The description,
	3916	which is optional, can spread over multiple lines; if it does, some
	3917	authors prefer to indent the second line while others prefer to align
	3918	it with the first (and all others). It's up to you. An empty line,
	3919	or the next menu entry, ends a description.
	3920
	3921	Space characters in a menu are preserved as-is in the Info output; this
	3922	allows you to format the menu as you wish. Unfortunately you must type
	3923	node names without any extra spaces or some versions of some Info
	3924	readers will not find the node (@pxref{Node Line Requirements}).
	3925
	3926
	3927	@command{makeinfo} warns when the text of a menu item (and node names
	3928	and cross-references) contains a problematic construct that will
	3929	interfere with its parsing in Info. If you don't want to see the
	3930	warnings, you can set the customization variable
	3931	@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other
	3932	Customization Variables}).
	3933
	3934
	3935
	3936	@node Less Cluttered Menu Entry
	3937	@subsection Less Cluttered Menu Entry
	3938	@cindex Two part menu entry
	3939	@cindex Double-colon menu entries
	3940	@cindex Menu entries with two colons
	3941	@cindex Less cluttered menu entry
	3942	@cindex Uncluttered menu entry
	3943
	3944	When the menu entry name and node name are the same, you can write
	3945	the name immediately after the asterisk and space at the beginning of
	3946	the line and follow the name with two colons.
	3947
	3948	@need 800
	3949	For example, write
	3950
	3951	@example
	3952	* Name:: @var{description}
	3953	@end example
	3954
	3955	@need 800
	3956	@noindent
	3957	instead of
	3958
	3959	@example
	3960	* Name: Name. @var{description}
	3961	@end example
	3962
	3963	We recommend using the node name for the menu entry name whenever
	3964	possible, since it reduces visual clutter in the menu.
	3965
	3966
	3967	@node Other Info Files
	3968	@subsection Referring to Other Info Files
	3969	@cindex Referring to other Info files
	3970	@cindex Nodes in other Info files
	3971	@cindex Other Info files' nodes
	3972	@cindex Going to other Info files' nodes
	3973	@cindex Info; other files' nodes
	3974
	3975	You can create a menu entry that enables a reader in Info to go to a
	3976	node in another Info file by writing the file name in parentheses just
	3977	before the node name. Some examples:
	3978
	3979	@example
	3980	@group
	3981	@@menu
	3982	* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
	3983	* (@var{filename})@var{second-node}:: @var{description}
	3984	@@end menu
	3985	@end group
	3986	@end example
	3987
	3988	For example, to refer directly to the @samp{Outlining} and
	3989	@samp{Rebinding} nodes in the @cite{Emacs Manual}, you could write a
	3990	menu like this:
	3991
	3992	@example
	3993	@group
	3994	@@menu
	3995	* Outlining: (emacs)Outline Mode. The major mode for
	3996	editing outlines.
	3997	* (emacs)Rebinding:: How to redefine the
	3998	meaning of a key.
	3999	@@end menu
	4000	@end group
	4001	@end example
	4002
	4003	If you do not list the node name, but only name the file, then Info
	4004	presumes that you are referring to the `Top' node. Examples:
	4005
	4006	@example
	4007	@group
	4008	* Info: (info). Documentation browsing system.
	4009	* (emacs):: The extensible, self-documenting
	4010	text editor.
	4011	@end group
	4012	@end example
	4013
	4014	The GNU Emacs Texinfo mode menu updating commands only work with nodes
	4015	within the current buffer, so you cannot use them to create menus that
	4016	refer to other files. You must write such menus by hand.
	4017
	4018
	4019	@node Chapter Structuring
	4020	@chapter Chapter Structuring
	4021	@anchor{Structuring}@c old name
	4022	@cindex Chapter structuring
	4023	@cindex Structuring of chapters
	4024	@cindex Sectioning
	4025
	4026	Texinfo's @dfn{chapter structuring} commands divide a document into a
	4027	hierarchy of chapters, sections, subsections, and subsubsections. These
	4028	commands generate large headings in the text, like the one above. They
	4029	also provide information for generating the table of contents
	4030	(@pxref{Contents,, Generating a Table of Contents}).
	4031
	4032	Normally you put a @code{@@node} command immediately before each
	4033	chapter structuring command. @xref{Nodes}.
	4034
	4035	@menu
	4036	* Tree Structuring:: A manual is like an upside down tree @dots{}
	4037	* Structuring Command Types:: How to divide a manual into parts.
	4038	* @code{@@chapter}:: Chapter structuring.
	4039	* @code{@@unnumbered @@appendix}::
	4040	* @code{@@majorheading @@chapheading}::
	4041	* @code{@@section}::
	4042	* @code{@@unnumberedsec @@appendixsec @@heading}::
	4043	* @code{@@subsection}::
	4044	* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
	4045	* @code{@@subsubsection}:: Commands for the lowest level sections.
	4046	* @code{@@part}:: Collections of chapters.
	4047	* Raise/lower sections:: How to change commands' hierarchical level.
	4048	@end menu
	4049
	4050
	4051	@node Tree Structuring
	4052	@section Tree Structure of Sections
	4053	@cindex Tree structuring
	4054
	4055	A Texinfo file is usually structured like a book with chapters,
	4056	sections, subsections, and the like. This structure can be visualized
	4057	as a tree (or rather as an upside-down tree) with the root at the top
	4058	and the levels corresponding to chapters, sections, subsection, and
	4059	subsubsections.
	4060
	4061	Here is a diagram that shows a Texinfo file with three chapters, each
	4062	with two sections.
	4063
	4064	@example
	4065	@group
	4066	Top
	4067	\|
	4068	-------------------------------------
	4069	\| \| \|
	4070	Chapter 1 Chapter 2 Chapter 3
	4071	\| \| \|
	4072	-------- -------- --------
	4073	\| \| \| \| \| \|
	4074	Section Section Section Section Section Section
	4075	1.1 1.2 2.1 2.2 3.1 3.2
	4076
	4077	@end group
	4078	@end example
	4079
	4080	In a Texinfo file that has this structure, the beginning of Chapter 2
	4081	would be written like this:
	4082
	4083	@example
	4084	@group
	4085	@@node Chapter 2
	4086	@@chapter Chapter 2
	4087	@end group
	4088	@end example
	4089
	4090	@noindent
	4091	For purposes of example, here is how it would be written with
	4092	explicit node pointers:
	4093
	4094	@example
	4095	@group
	4096	@@node Chapter 2, Chapter 3, Chapter 1, Top
	4097	@@chapter Chapter 2
	4098	@end group
	4099	@end example
	4100
	4101	The chapter structuring commands are described in the sections that
	4102	follow; the @code{@@node} command is described in
	4103	the previous chapter (@pxref{Nodes}).
	4104
	4105
	4106	@node Structuring Command Types
	4107	@section Structuring Command Types
	4108
	4109	The chapter structuring commands fall into four groups or series, each
	4110	of which contains structuring commands corresponding to the
	4111	hierarchical levels of chapters, sections, subsections, and
	4112	subsubsections.
	4113
	4114	The four groups of commands are the @code{@@chapter} series, the
	4115	@code{@@unnumbered} series, the @code{@@appendix} series, and the
	4116	@code{@@heading} series. Each command produces a title with a
	4117	different appearance in the body of the document. Some of the
	4118	commands list their titles in the tables of contents, while others do
	4119	not. Here are the details:
	4120
	4121	@itemize @bullet
	4122	@item
	4123	The @code{@@chapter} and @code{@@appendix} series of commands produce
	4124	numbered or lettered entries both in the body of a document and in its
	4125	table of contents.
	4126
	4127	@item
	4128	The @code{@@unnumbered} series of commands produce unnumbered entries
	4129	both in the body of a document and in its table of contents. The
	4130	@code{@@top} command, which has a special use, is a member of this
	4131	series (@pxref{@code{@@top} Command}). An @code{@@unnumbered} section
	4132	is a normal part of the document structure.
	4133
	4134	@item
	4135	The @code{@@heading} series of commands produce simple unnumbered
	4136	headings that do not appear in a table of contents, are not associated
	4137	with nodes, and cannot be cross-referenced. These heading commands
	4138	never start a new page.
	4139	@end itemize
	4140
	4141	When a @code{@@setchapternewpage} command says to do so, the
	4142	@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
	4143	start new pages in the printed manual; the @code{@@heading} commands
	4144	do not. @xref{@code{@@setchapternewpage}}.
	4145
	4146	Here is a summary:
	4147
	4148	@tex
	4149	{\globaldefs=1 \smallfonts \rm}
	4150	@end tex
	4151
	4152	@multitable @columnfractions .19 .30 .29 .22
	4153	@item @tab @tab @tab No new page
	4154	@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered}
	4155	@item In contents @tab In contents @tab In contents @tab Not in contents
	4156	@item @tab @code{@@top} @tab @tab @code{@@majorheading}
	4157	@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading}
	4158	@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading}
	4159	@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading}
	4160	@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
	4161	@end multitable
	4162	@tex
	4163	{\globaldefs=1 \textfonts \rm}
	4164	@end tex
	4165
	4166
	4167	@node @code{@@chapter}
	4168	@section @code{@@chapter}: Chapter Structuring
	4169
	4170	@anchor{chapter}@c old name
	4171	@findex chapter
	4172
	4173	@code{@@chapter} identifies a chapter in the document--the highest
	4174	level of the normal document structuring hierarchy. Write the command
	4175	at the beginning of a line and follow it on the same line by the title
	4176	of the chapter. The chapter is numbered automatically, starting
	4177	from@tie{}1.
	4178
	4179	For example, the present chapter in this manual is entitled
	4180	``@code{@@chapter}: Chapter Structuring''; the @code{@@chapter} line
	4181	looks like this:
	4182
	4183	@example
	4184	@@chapter @@code@{@@@@chapter@}: Chapter Structuring
	4185	@end example
	4186
	4187	In @TeX{}, the @code{@@chapter} command produces a chapter heading in
	4188	the document.
	4189
	4190	In Info and plain text output, the @code{@@chapter} command causes the
	4191	title to appear on a line by itself, with a line of asterisks inserted
	4192	underneath. So, the above example produces the following output:
	4193
	4194	@example
	4195	@group
	4196	5 Chapter Structuring
	4197	*********************
	4198	@end group
	4199	@end example
	4200
	4201	In HTML, the @code{@@chapter} command produces an @code{<h2>}-level
	4202	header by default (controlled by the @code{CHAPTER_HEADER_LEVEL}
	4203	customization variable, @pxref{Other Customization Variables}).
	4204
	4205	In the XML and Docbook output, a @code{<chapter>} element is produced
	4206	that includes all the following sections, up to the next chapter.
	4207
	4208
	4209	@node @code{@@unnumbered @@appendix}
	4210	@section @code{@@unnumbered}, @code{@@appendix}: Chapters with Other Labeling
	4211
	4212	@anchor{unnumbered & appendix}@c old name
	4213	@findex unnumbered
	4214	@findex appendix
	4215
	4216	Use the @code{@@unnumbered} command to start a chapter-level element
	4217	that appears without chapter numbers of any kind. Use the
	4218	@code{@@appendix} command to start an appendix that is labeled by
	4219	letter (`A', `B', @dots{}) instead of by number; appendices are also
	4220	at the chapter level of structuring.
	4221
	4222	Write an @code{@@appendix} or @code{@@unnumbered} command at the
	4223	beginning of a line and follow it on the same line by the title,
	4224	just as with @code{@@chapter}.
	4225
	4226	@findex centerchap
	4227	Texinfo also provides a command @code{@@centerchap}, which is analogous
	4228	to @code{@@unnumbered}, but centers its argument in the printed and HTML
	4229	outputs. This kind of stylistic choice is not usually offered by
	4230	Texinfo. It may be suitable for short documents.
	4231	@c but the Hacker's Dictionary wanted it, before they quit Texinfo.
	4232
	4233	@cindex Docbook and prefatory sections
	4234	@cindex Preface, etc., and Docbook
	4235	With @code{@@unnumbered}, if the name of the associated node is one of
	4236	these English words (case-insensitive):
	4237
	4238	@example
	4239	Acknowledgements Colophon Dedication Preface
	4240	@end example
	4241
	4242	@cindex @code{<acknowledgements>} Docbook tag
	4243	@cindex @code{<colophon>} Docbook tag
	4244	@cindex @code{<dedication>} Docbook tag
	4245	@cindex @code{<preface>} Docbook tag
	4246	@cindex @code{<chapter>} Docbook tag
	4247	@cindex @code{<title>} Docbook tag
	4248	@noindent then the Docbook output uses corresponding special tags
	4249	(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}.
	4250	The argument to @code{@@unnumbered} itself can be anything, and is
	4251	output as the following @code{<title>} text as usual.
	4252
	4253
	4254	@node @code{@@majorheading @@chapheading}
	4255	@section @code{@@majorheading}, @code{@@chapheading}: Chapter-level Headings
	4256
	4257	@anchor{majorheading & chapheading}@c old name
	4258	@findex majorheading
	4259	@findex chapheading
	4260
	4261	The @code{@@majorheading} and @code{@@chapheading} commands produce
	4262	chapter-like headings in the body of a document.
	4263
	4264	However, neither command produces an entry in the table of contents,
	4265	and neither command causes @TeX{} to start a new page in a printed
	4266	manual.
	4267
	4268	In @TeX{}, a @code{@@majorheading} command generates a larger vertical
	4269	whitespace before the heading than a @code{@@chapheading} command but
	4270	is otherwise the same.
	4271
	4272	In Info and plain text, the @code{@@majorheading} and
	4273	@code{@@chapheading} commands produce the same output as
	4274	@code{@@chapter}: the title is printed on a line by itself with a line
	4275	of asterisks underneath. Similarly for HTML@. The only difference is
	4276	the lack of numbering and the lack of any association with nodes.
	4277	@xref{@code{@@chapter}}.
	4278
	4279
	4280	@node @code{@@section}
	4281	@section @code{@@section}: Sections Below Chapters
	4282
	4283	@anchor{section}@c old name
	4284	@findex section
	4285
	4286	An @code{@@section} command identifies a section within a chapter
	4287	unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or
	4288	@code{@@appendix}, following the numbering scheme of the chapter-level
	4289	command. Thus, within a @code{@@chapter} chapter numbered `1', the
	4290	sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix}
	4291	``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.;
	4292	within an @code{@@unnumbered} chapter, the section gets no number.
	4293	The output is underlined with @samp{=} in Info and plain text.
	4294
	4295	To make a section, write the @code{@@section} command at the
	4296	beginning of a line and follow it on the same line by the section
	4297	title. For example,
	4298
	4299	@example
	4300	@@section This is a section
	4301	@end example
	4302
	4303	@noindent
	4304	might produce the following in Info:
	4305
	4306	@example
	4307	@group
	4308	5.7 This is a section
	4309	=====================
	4310	@end group
	4311	@end example
	4312
	4313	Section titles are listed in the table of contents.
	4314
	4315	The @TeX{}, HTML, Docbook, and XML output is all analogous to the
	4316	chapter-level output, just ``one level down''; @pxref{@code{@@chapter}}.
	4317
	4318
	4319	@node @code{@@unnumberedsec @@appendixsec @@heading}
	4320	@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
	4321
	4322	@anchor{unnumberedsec appendixsec heading}@c old name
	4323	@findex unnumberedsec
	4324	@findex appendixsec
	4325	@findex heading
	4326
	4327	The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
	4328	commands are, respectively, the unnumbered, appendix-like, and
	4329	heading-like equivalents of the @code{@@section} command (see the
	4330	previous section).
	4331
	4332	@code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used
	4333	in ordinary circumstances, because @code{@@section} may also be used
	4334	within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
	4335	the previous section.
	4336
	4337	@table @code
	4338	@item @@unnumberedsec
	4339	The @code{@@unnumberedsec} command may be used within an unnumbered
	4340	chapter or within a regular chapter or appendix to produce an
	4341	unnumbered section.
	4342
	4343	@item @@appendixsec
	4344	@itemx @@appendixsection
	4345	@findex appendixsection
	4346	@findex appendixsec
	4347	@code{@@appendixsection} is a longer spelling of the
	4348	@code{@@appendixsec} command; the two are synonymous.
	4349
	4350	Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
	4351	command is used only within appendices.
	4352
	4353	@item @@heading
	4354	You may use the @code{@@heading} command (almost) anywhere for a
	4355	section-style heading that will not appear in the table of contents.
	4356	The @code{@@heading}-series commands can appear inside most
	4357	environments, for example, though pathological and useless locations
	4358	such as inside @code{@@titlepage}, as an argument to another command,
	4359	etc., are not allowed.
	4360
	4361	@end table
	4362
	4363
	4364	@node @code{@@subsection}
	4365	@section @code{@@subsection}: Subsections Below Sections
	4366
	4367	@anchor{subsection}@c old name
	4368	@findex subsection
	4369
	4370	Subsections are to sections as sections are to chapters;
	4371	@pxref{@code{@@section}}. In Info and plain text, subsection titles
	4372	are underlined with @samp{-}. For example,
	4373
	4374	@example
	4375	@@subsection This is a subsection
	4376	@end example
	4377
	4378	@noindent
	4379	might produce
	4380
	4381	@example
	4382	@group
	4383	1.2.3 This is a subsection
	4384	--------------------------
	4385	@end group
	4386	@end example
	4387
	4388	Subsection titles are listed in the table of contents.
	4389
	4390	The @TeX{}, HTML, Docbook, and XML output is all analogous to the
	4391	chapter-level output, just ``two levels down'';
	4392	@pxref{@code{@@chapter}}.
	4393
	4394
	4395	@node @code{@@unnumberedsubsec @@appendixsubsec @@subheading}
	4396	@section The @code{@@subsection}-like Commands
	4397
	4398	@anchor{unnumberedsubsec appendixsubsec subheading}@c old name
	4399	@findex unnumberedsubsec
	4400	@findex appendixsubsec
	4401	@findex subheading
	4402	@cindex Subsection-like commands
	4403
	4404	The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
	4405	@code{@@subheading} commands are, respectively, the unnumbered,
	4406	appendix-like, and heading-like equivalents of the @code{@@subsection}
	4407	command. (@xref{@code{@@subsection}}.)
	4408
	4409	@code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
	4410	be used in ordinary circumstances, because @code{@@subsection} may
	4411	also be used within sections of @code{@@unnumbered} and
	4412	@code{@@appendix} chapters (@pxref{@code{@@section}}).
	4413
	4414	An @code{@@subheading} command produces a heading like that of a
	4415	subsection except that it is not numbered and does not appear in the
	4416	table of contents. Similarly, an @code{@@unnumberedsubsec} command
	4417	produces an unnumbered heading like that of a subsection and an
	4418	@code{@@appendixsubsec} command produces a subsection-like heading
	4419	labeled with a letter and numbers; both of these commands produce
	4420	headings that appear in the table of contents. In Info and plain
	4421	text, the @code{@@subsection}-like commands generate a title
	4422	underlined with hyphens.
	4423
	4424
	4425	@node @code{@@subsubsection}
	4426	@section @code{@@subsection} and Other Subsub Commands
	4427
	4428	@anchor{subsubsection}@c old name
	4429	@findex subsubsection
	4430	@findex unnumberedsubsubsec
	4431	@findex appendixsubsubsec
	4432	@findex subsubheading
	4433	@cindex Subsub sectioning commands
	4434
	4435	The fourth and lowest level sectioning commands in Texinfo are the
	4436	`subsub' commands. They are:
	4437
	4438	@table @code
	4439	@item @@subsubsection
	4440	Subsubsections are to subsections as subsections are to sections.
	4441	(@xref{@code{@@subsection}}.) Subsubsection titles appear in the
	4442	table of contents.
	4443
	4444	@item @@unnumberedsubsubsec
	4445	Unnumbered subsubsection titles appear in the table of contents,
	4446	but lack numbers. Otherwise, unnumbered subsubsections are the same
	4447	as subsubsections.
	4448
	4449	@item @@appendixsubsubsec
	4450	Conventionally, appendix commands are used only for appendices and are
	4451	lettered and numbered appropriately. They also appear in the table
	4452	of contents.
	4453
	4454	@item @@subsubheading
	4455	The @code{@@subsubheading} command may be used anywhere that you want
	4456	a small heading that will not appear in the table of contents.
	4457	@end table
	4458
	4459	As with subsections, @code{@@unnumberedsubsubsec} and
	4460	@code{@@appendixsubsubsec} do not need to be used in ordinary
	4461	circumstances, because @code{@@subsubsection} may also be used within
	4462	subsections of @code{@@unnumbered} and @code{@@appendix} chapters
	4463	(@pxref{@code{@@section}}).
	4464
	4465	In Info, `subsub' titles are underlined with periods. For example,
	4466
	4467	@example
	4468	@@subsubsection This is a subsubsection
	4469	@end example
	4470
	4471	@noindent
	4472	might produce
	4473
	4474	@example
	4475	@group
	4476	1.2.3.4 This is a subsubsection
	4477	...............................
	4478	@end group
	4479	@end example
	4480
	4481	The @TeX{}, HTML, Docbook, and XML output is all analogous to the
	4482	chapter-level output, just ``three levels down''; @pxref{@code{@@chapter}}.
	4483
	4484
	4485	@node @code{@@part}
	4486	@section @code{@@part}: Groups of Chapters
	4487	@findex part
	4488	@cindex Part pages
	4489
	4490	The final sectioning command is @code{@@part}, to mark a @dfn{part} of
	4491	a manual, that is, a group of chapters or (rarely) appendices. This
	4492	behaves quite differently from the other sectioning commands, to fit
	4493	with the way such ``parts'' are conventionally used in books.
	4494
	4495	No @code{@@node} command is associated with @code{@@part}. Just write
	4496	the command on a line by itself, including the part title, at the
	4497	place in the document you want to mark off as starting that part. For
	4498	example:
	4499
	4500	@example
	4501	@@part Part I:@@* The beginning
	4502	@end example
	4503
	4504	As can be inferred from this example, no automatic numbering or
	4505	labeling of the @code{@@part} text is done. The text is taken as-is.
	4506
	4507	Because parts are not associated with nodes, no general text can
	4508	follow the @code{@@part} line. To produce the intended output, it
	4509	must be followed by a chapter-level command (including its node).
	4510	Thus, to continue the example:
	4511
	4512	@example
	4513	@@part Part I:@@* The beginning
	4514
	4515	@@node Introduction
	4516	@@chapter Introduction
	4517	...
	4518	@end example
	4519
	4520	In the @TeX{} output, the @code{@@part} text is included in both the
	4521	normal and short tables of contents (@pxref{Contents}), without a page
	4522	number (since that is the normal convention). In addition, a ``part
	4523	page'' is output in the body of the document, with just the
	4524	@code{@@part} text. In the example above, the @code{@@*} causes a
	4525	line break on the part page (but is replaced with a space in the
	4526	tables of contents). This part page is always forced to be on an odd
	4527	(right-hand) page, regardless of the chapter pagination
	4528	(@pxref{@code{@@setchapternewpage}}).
	4529
	4530	In the HTML output, the @code{@@part} text is similarly included in
	4531	the tables of contents, and a heading is included in the main document
	4532	text, as part of the following chapter or appendix node.
	4533
	4534	In the XML and Docbook output, the @code{<part>} element includes all
	4535	the following chapters, up to the next @code{<part>}. A @code{<part>}
	4536	containing chapters is also closed at an appendix.
	4537
	4538	In the Info and plain text output, @code{@@part} has no effect.
	4539
	4540	@code{@@part} is ignored when raising or lowering sections (see next
	4541	section). That is, it is never lowered and nothing can be raised to it.
	4542
	4543
	4544	@node Raise/lower sections
	4545	@section Raise/lower Sections: @code{@@raisesections} and @code{@@lowersections}
	4546	@findex raisesections
	4547	@findex lowersections
	4548	@cindex Raising and lowering sections
	4549	@cindex Lowering and raising sections
	4550	@cindex Sections, raising and lowering
	4551
	4552	The @code{@@raisesections} and @code{@@lowersections} commands
	4553	implicitly raise and lower the hierarchical level of following
	4554	chapters, sections and the other sectioning commands (excluding parts).
	4555
	4556	That is, the @code{@@raisesections} command changes sections to
	4557	chapters, subsections to sections, and so on. Conversely, the
	4558	@code{@@lowersections} command changes chapters to sections, sections
	4559	to subsections, and so on. Thus, a @code{@@lowersections} command
	4560	cancels a @code{@@raisesections} command, and vice versa.
	4561
	4562	@cindex Include files, and section levels
	4563	You can use @code{@@lowersections} to include text written as an outer
	4564	or standalone Texinfo file in another Texinfo file as an inner,
	4565	included file (@pxref{Include Files}). Typical usage looks like this:
	4566
	4567	@example
	4568	@@lowersections
	4569	@@include somefile.texi
	4570	@@raisesections
	4571	@end example
	4572
	4573	@noindent (Without the @code{@@raisesections}, all the subsequent
	4574	sections in the main file would also be lowered.)
	4575
	4576	If the included file being lowered has a @code{@@top} node, you'll
	4577	need to conditionalize its inclusion with a flag (@pxref{@code{@@set
	4578	@@value}}).
	4579
	4580	As a practical matter, you generally only want to raise or lower large
	4581	chunks, usually in external files as shown above. The final result has
	4582	to have menus that take the raising and lowering into account, so you
	4583	cannot just arbitrarily sprinkle @code{@@raisesections} and
	4584	@code{@@lowersections} commands throughout the document.
	4585
	4586	Repeated use of the commands continues to raise or lower the
	4587	hierarchical level a step at a time. An attempt to raise above
	4588	`chapter' reproduces chapter commands; an attempt to lower below
	4589	`subsubsection' reproduces subsubsection commands. Also, lowered
	4590	subsubsections and raised chapters will not work with
	4591	@command{makeinfo}'s feature of implicitly determining node pointers,
	4592	since the menu structure cannot be represented correctly.
	4593
	4594	Write each @code{@@raisesections} and @code{@@lowersections} command
	4595	on a line of its own.
	4596
	4597
	4598	@node Cross References
	4599	@chapter Cross-references
	4600	@cindex Making cross-references
	4601	@cindex Cross-references
	4602	@cindex References
	4603
	4604	@dfn{Cross-references} are used to refer the reader to other parts of the
	4605	same or different Texinfo files.
	4606
	4607	@menu
	4608	* References:: What cross-references are for.
	4609	* Cross Reference Commands:: A summary of the different commands.
	4610	* Cross Reference Parts:: A cross-reference has several parts.
	4611	* @code{@@xref}:: Begin a reference with `See' @dots{}
	4612	* Referring to a Manual as a Whole:: Refer to an entire manual.
	4613	* @code{@@ref}:: A reference for the last part of a sentence.
	4614	* @code{@@pxref}:: How to write a parenthetical cross-reference.
	4615	* @code{@@anchor}:: Defining arbitrary cross-reference targets
	4616	* @code{@@inforef}:: How to refer to an Info-only file.
	4617	* @code{@@url}:: How to refer to a uniform resource locator.
	4618	* @code{@@cite}:: How to refer to books not in the Info system.
	4619	@end menu
	4620
	4621
	4622	@node References
	4623	@section What References Are For
	4624
	4625	Often, but not always, a printed document should be designed so that
	4626	it can be read sequentially. People tire of flipping back and forth
	4627	to find information that should be presented to them as they need
	4628	it.
	4629
	4630	However, in any document, some information will be too detailed for
	4631	the current context, or incidental to it; use cross-references to
	4632	provide access to such information. Also, an online help system or a
	4633	reference manual is not like a novel; few read such documents in
	4634	sequence from beginning to end. Instead, people look up what they
	4635	need. For this reason, such creations should contain many cross
	4636	references to help readers find other information that they may not
	4637	have read.
	4638
	4639	In a printed manual, a cross-reference results in a page reference,
	4640	unless it is to another manual altogether, in which case the
	4641	cross-reference names that manual. In Info, a cross-reference results
	4642	in an entry that you can follow using the Info @samp{f} command.
	4643	(@xref{Help-Xref,, Following cross-references, info, Info}.) In HTML, a
	4644	cross-reference results in an hyperlink.
	4645
	4646	The various cross-reference commands use nodes (or anchors,
	4647	@pxref{@code{@@anchor}}) to define cross-reference locations.
	4648	@TeX{} needs nodes to define cross-reference locations. When @TeX{}
	4649	generates a DVI file, it records each node's page number and uses the
	4650	page numbers in making references. Thus, even if you are writing a
	4651	manual that will only be printed, and not used online, you must
	4652	nonetheless write @code{@@node} lines in order to name the places to
	4653	which you make cross-references.
	4654
	4655	@need 800
	4656	@node Cross Reference Commands
	4657	@section Different Cross-reference Commands
	4658	@cindex Different cross-reference commands
	4659
	4660	There are three different cross-reference commands:
	4661
	4662	@table @code
	4663	@item @@xref
	4664	Used to start a sentence in the printed manual and in HTML with
	4665	@w{`See @dots{}'} or an Info cross-reference saying @samp{*Note
	4666	@var{name}: @var{node}.}.
	4667
	4668	@item @@ref
	4669	Used within or, more often, at the end of a sentence; produces just
	4670	the reference in the printed manual and in HTML without the preceding
	4671	`See' (same as @code{@@xref} for Info).
	4672
	4673	@item @@pxref
	4674	Used within parentheses, at the end of a sentence, or otherwise before
	4675	punctuation, to make a reference. Its output starts with a lowercase
	4676	`see' in the printed manual and in HTML, and a lowercase @samp{*note}
	4677	in Info. (@samp{p} is for `parenthesis'.)
	4678	@end table
	4679
	4680	Additionally, there are commands to produce references to documents
	4681	outside the Texinfo system. The @code{@@cite} command is used
	4682	to make references to books and manuals. @code{@@url} produces
	4683	a @acronym{URL}, for example a reference to a page on the World
	4684	Wide Web. @code{@@inforef} is used to make a reference to an Info
	4685	file for which there is no printed manual.
	4686
	4687
	4688	@node Cross Reference Parts
	4689	@section Parts of a Cross-reference
	4690	@cindex Cross-reference parts
	4691	@cindex Parts of a cross-reference
	4692	@anchor{Reference Syntax} @c merged node
	4693
	4694	A cross-reference command requires only one argument, which is
	4695	the name of the node to which it refers. Here is a simple example:
	4696
	4697	@example
	4698	@@xref@{Node name@}.
	4699	@end example
	4700
	4701	@noindent
	4702	In Info output, this produces
	4703
	4704	@example
	4705	*Note Node name::.
	4706	@end example
	4707
	4708	@noindent
	4709	In a printed manual, the output is
	4710
	4711	@quotation
	4712	See Section @var{nnn} [Node name], page @var{ppp}.
	4713	@end quotation
	4714
	4715	A cross-reference command may contain up to four additional arguments.
	4716	By using these arguments, you can provide a cross-reference name,
	4717	a topic description or section title for the printed output, the name
	4718	of a different manual file, and the name of a different printed manual.
	4719	To refer to another manual as a whole, the manual file and/or the name
	4720	of the printed manual are the only required arguments (@pxref{Referring
	4721	to a Manual as a Whole}).
	4722
	4723	@need 700
	4724	Here is an example of a full five-part cross-reference:
	4725
	4726	@example
	4727	@group
	4728	@@xref@{Node name, Online Label, Printed Label,
	4729	info-file-name, A Printed Manual@}, for details.
	4730	@end group
	4731	@end example
	4732
	4733	@noindent
	4734	which produces
	4735
	4736	@example
	4737	*Note Online Label: (info-file-name)Node name,
	4738	for details.
	4739	@end example
	4740
	4741	@noindent
	4742	in Info and
	4743
	4744	@quotation
	4745	See section ``Printed Label'' in @i{A Printed Manual}, for details.
	4746	@end quotation
	4747
	4748	@noindent
	4749	in a printed book.
	4750
	4751	The five possible arguments for a cross-reference are:
	4752
	4753	@enumerate
	4754	@item
	4755	The node or anchor name (required, except for reference to whole
	4756	manuals). This is the location to which the cross-reference takes
	4757	you. In a printed document, the location of the node provides the
	4758	page reference only for references within the same document.
	4759	Use @code{@@node} to define the node (@pxref{Writing a Node}), or
	4760	@code{@@anchor} (@pxref{@code{@@anchor}}).
	4761
	4762	Write a node name in a cross-reference in exactly the same way as in
	4763	the @code{@@node} line, including the same capitalization; otherwise, the
	4764	formatters may not find the reference.
	4765
	4766	@item
	4767	A label for online output. It is usually omitted; then
	4768	the topic description (third argument) is used if it was specified;
	4769	if that was omitted as well, the node name is used.
	4770
	4771	@item
	4772	A label for printed output. Often, this is the title or topic of the
	4773	section. This is used as the name of the reference in the printed
	4774	manual. If omitted, the node name is used.
	4775
	4776	@item
	4777	The name of the manual file in which the reference is located, if it is
	4778	different from the current file. This name is used both for Info and
	4779	HTML.
	4780
	4781	@item
	4782	The name of a printed manual from a different Texinfo file.
	4783	@end enumerate
	4784
	4785	The template for a full five argument cross-reference looks like
	4786	this:
	4787
	4788	@example
	4789	@group
	4790	@@xref@{@var{node-name}, @var{online-label}, @var{printed-label},
	4791	@var{info-file-name}, @var{printed-manual-title}@}
	4792	@end group
	4793	@end example
	4794
	4795	Whitespace before and after the commas separating these arguments is
	4796	ignored. To include a comma in one of the arguments, use
	4797	@code{@@comma@{@}} (@pxref{Inserting a Comma}).
	4798
	4799	@cindex Comma after cross-reference
	4800	When processing with TeX, a comma is automatically inserted after the
	4801	page number for cross-references to within the same manual, unless the
	4802	closing brace of the argument is followed by non-whitespace (such as a
	4803	comma or period). This gives you the choice of whether to have a comma
	4804	there in Info or HTML output. For example,
	4805
	4806	@example
	4807	@@xref@{Another Section@} for more information
	4808	@end example
	4809
	4810	@noindent produces
	4811	@w{`See Another Section, page @var{ppp}, for more information'} in the
	4812	printed output, and
	4813	@w{@samp{*Note Another Section:: for more information}} in the Info
	4814	output.
	4815
	4816	If an unwanted comma is added, follow the argument
	4817	with a command such as @samp{@@:}. For example,
	4818	@w{@samp{@@xref@{Hurricanes@}@@: --- for the details}} produces
	4819
	4820	@quotation
	4821	See Hurricanes, page @var{ppp} --- for the details
	4822	@end quotation
	4823
	4824	@noindent instead of
	4825	@w{`See Hurricanes, page @var{ppp}, --- for the details'}.
	4826
	4827	Cross-references with one, two, three, four, and five arguments are
	4828	described separately following the description of @code{@@xref}.
	4829
	4830	@command{makeinfo} warns when the text of a cross-reference (and node
	4831	names and menu items) contains a problematic construct that will
	4832	interfere with its parsing in Info. If you don't want to see the
	4833	warnings, you can set the customization variable
	4834	@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other
	4835	Customization Variables}).
	4836
	4837
	4838	@node @code{@@xref}
	4839	@section @code{@@xref}
	4840
	4841	@anchor{xref}@c old name
	4842	@findex xref
	4843	@cindex Cross-references using @code{@@xref}
	4844	@cindex References using @code{@@xref}
	4845
	4846	The @code{@@xref} command generates a cross-reference for the
	4847	beginning of a sentence.
	4848
	4849	@menu
	4850	* One Argument:: @code{@@xref} with one argument.
	4851	* Two Arguments:: @code{@@xref} with two arguments.
	4852	* Three Arguments:: @code{@@xref} with three arguments.
	4853	* Four and Five Arguments:: @code{@@xref} with four and five arguments.
	4854	@end menu
	4855
	4856	@node One Argument
	4857	@subsection @code{@@xref} with One Argument
	4858	@cindex One-argument form of cross-references
	4859
	4860	The simplest form of @code{@@xref} takes one argument, the name of
	4861	another node in the same Texinfo file.
	4862
	4863	@need 700
	4864	@noindent
	4865	For example,
	4866
	4867	@example
	4868	@@xref@{Tropical Storms@}.
	4869	@end example
	4870
	4871	@noindent
	4872	produces
	4873
	4874	@example
	4875	*Note Tropical Storms::.
	4876	@end example
	4877
	4878	@noindent
	4879	in Info and
	4880
	4881	@quotation
	4882	See Section 3.1 [Tropical Storms], page 24.
	4883	@end quotation
	4884
	4885	@noindent
	4886	in a printed manual.
	4887
	4888
	4889	@node Two Arguments
	4890	@subsection @code{@@xref} with Two Arguments
	4891	@cindex Two-argument form of cross-references
	4892
	4893	With two arguments, the second is used as a label for the online output.
	4894
	4895	@need 750
	4896	@noindent
	4897	The template is like this:
	4898
	4899	@example
	4900	@@xref@{@var{node-name}, @var{online-label}@}.
	4901	@end example
	4902
	4903	@need 700
	4904	@noindent
	4905	For example,
	4906
	4907	@example
	4908	@@xref@{Electrical Effects, Lightning@}.
	4909	@end example
	4910
	4911	@noindent
	4912	produces:
	4913
	4914	@example
	4915	*Note Lightning: Electrical Effects.
	4916	@end example
	4917
	4918	@noindent
	4919	in Info and
	4920
	4921	@quotation
	4922	See Section 5.2 [Electrical Effects], page 57.
	4923	@end quotation
	4924
	4925	@noindent
	4926	in a printed manual, where the node name is printed.
	4927
	4928	The second argument to cross-references must observe some of the
	4929	restrictions for node names (@pxref{Node Line Requirements}). The
	4930	most common issue is that colons cannot be used, since that interferes
	4931	with the parsing of the Info file.
	4932
	4933
	4934	@node Three Arguments
	4935	@subsection @code{@@xref} with Three Arguments
	4936	@cindex Three-argument form of cross-references
	4937
	4938	A third argument replaces the node name in the @TeX{} output. The third
	4939	argument should be the name of the section in the printed output, or
	4940	else state the topic discussed by that section.
	4941
	4942	@need 750
	4943	@noindent
	4944	The template is like this:
	4945
	4946	@example
	4947	@group
	4948	@@xref@{@var{node-name}, @var{online-label}, @var{printed-label}@}.
	4949	@end group
	4950	@end example
	4951
	4952	@need 700
	4953	@noindent
	4954	For example,
	4955
	4956	@example
	4957	@group
	4958	@@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
	4959	for details.
	4960	@end group
	4961	@end example
	4962
	4963	@noindent
	4964	produces
	4965
	4966	@example
	4967	*Note Lightning: Electrical Effects, for details.
	4968	@end example
	4969
	4970	@noindent
	4971	in Info and
	4972
	4973	@quotation
	4974	See Section 5.2 [Thunder and Lightning], page 57, for details.
	4975	@end quotation
	4976
	4977	@noindent
	4978	in a printed manual.
	4979
	4980	If a third argument is given and the second one is empty, then the
	4981	third argument serves for both. (Note how two commas, side by side, mark
	4982	the empty second argument.)
	4983
	4984	@example
	4985	@group
	4986	@@xref@{Electrical Effects, , Thunder and Lightning@},
	4987	for details.
	4988	@end group
	4989	@end example
	4990
	4991	@noindent
	4992	produces
	4993
	4994	@example
	4995	*Note Thunder and Lightning: Electrical Effects, for details.
	4996	@end example
	4997
	4998	@noindent
	4999	in Info and
	5000
	5001	@quotation
	5002	See Section 5.2 [Thunder and Lightning], page 57, for details.
	5003	@end quotation
	5004
	5005	@noindent
	5006	in a printed manual.
	5007
	5008	The third argument to cross-references must observe some of the
	5009	restrictions for node names (@pxref{Node Line Requirements}). The
	5010	most common issue is that colons cannot be used, since that interferes
	5011	with the parsing of the Info file.
	5012
	5013	As a practical matter, it is often best to write cross-references with
	5014	just the first argument if the node name and the section title are the
	5015	same (or nearly so), and with the first and third arguments only if the
	5016	node name and title are different.
	5017
	5018	@findex xrefautomaticsectiontitle
	5019	Texinfo offers a setting to use the section title instead of node
	5020	names by default in cross-references (an explicitly specified third
	5021	argument still takes precedence):
	5022
	5023	@example
	5024	@@xrefautomaticsectiontitle on
	5025	@end example
	5026
	5027	Typically this line would be given near the beginning of the document
	5028	and used for the whole manual. But you can turn it off if you want
	5029	(@code{@@xrefautomaticsectiontitle off}), for example, if you're
	5030	including some other sub-document that doesn't have suitable section
	5031	names.
	5032
	5033
	5034	@node Four and Five Arguments
	5035	@subsection @code{@@xref} with Four and Five Arguments
	5036	@cindex Four- and five argument forms of cross-references
	5037
	5038	In a cross-reference, a fourth argument specifies the name of another
	5039	Info file, different from the file in which the reference appears, and
	5040	a fifth argument specifies its title as a printed manual.
	5041
	5042	@need 800
	5043	@noindent
	5044	The full template is:
	5045
	5046	@example
	5047	@group
	5048	@@xref@{@var{node-name}, @var{online-label}, @var{printed-label},
	5049	@var{info-file-name}, @var{printed-manual-title}@}.
	5050	@end group
	5051	@end example
	5052
	5053	@need 700
	5054	@noindent
	5055	For example,
	5056
	5057	@example
	5058	@@xref@{Electrical Effects, Lightning, Thunder and Lightning,
	5059	weather, An Introduction to Meteorology@}.
	5060	@end example
	5061
	5062	@noindent
	5063	produces this output in Info:
	5064
	5065	@example
	5066	*Note Lightning: (weather)Electrical Effects.
	5067	@end example
	5068
	5069	@noindent
	5070	As you can see, the name of the Info file is enclosed in parentheses
	5071	and precedes the name of the node.
	5072
	5073	@noindent
	5074	In a printed manual, the reference looks like this:
	5075
	5076	@quotation
	5077	See section ``Thunder and Lightning'' in @cite{An Introduction to
	5078	Meteorology}.
	5079	@end quotation
	5080
	5081	@noindent
	5082	The title of the printed manual is typeset like @code{@@cite}; and the
	5083	reference lacks a page number since @TeX{} cannot know to which page a
	5084	reference refers when that reference is to another manual.
	5085
	5086	Next case: often, you will leave out the second argument when you use
	5087	the long version of @code{@@xref}. In this case, the third argument,
	5088	the topic description, will be used as the cross-reference name in
	5089	Info. For example,
	5090
	5091	@example
	5092	@@xref@{Electrical Effects, , Thunder and Lightning,
	5093	weather, An Introduction to Meteorology@}.
	5094	@end example
	5095
	5096	@noindent
	5097	produces
	5098
	5099	@example
	5100	@group
	5101	*Note Thunder and Lightning: (weather)Electrical Effects.
	5102	@end group
	5103	@end example
	5104
	5105	@noindent
	5106	in Info and
	5107
	5108	@quotation
	5109	See section ``Thunder and Lightning'' in @cite{An Introduction to
	5110	Meteorology}.
	5111	@end quotation
	5112
	5113	@noindent
	5114	in a printed manual.
	5115
	5116	Next case: If the node name and the section title are the same in the
	5117	other manual, you may also leave out the section title. In this case,
	5118	the node name is used in both instances. For example,
	5119
	5120	@example
	5121	@@xref@{Electrical Effects,,,
	5122	weather, An Introduction to Meteorology@}.
	5123	@end example
	5124
	5125	@noindent
	5126	produces
	5127
	5128	@example
	5129	@group
	5130	*Note (weather)Electrical Effects::.
	5131	@end group
	5132	@end example
	5133
	5134	@noindent
	5135	in Info and
	5136
	5137	@quotation
	5138	See section ``Electrical Effects'' in @cite{An Introduction to
	5139	Meteorology}.
	5140	@end quotation
	5141
	5142	@noindent
	5143	in a printed manual.
	5144
	5145	A very unusual case: you may want to refer to another manual file that
	5146	is within a single printed manual---when multiple Texinfo files are
	5147	incorporated into the same @TeX{} run but can create separate Info or
	5148	HTML output files. In this case, you need to specify only the fourth
	5149	argument, and not the fifth.
	5150
	5151	Finally, it's also allowed to leave out all the arguments
	5152	@emph{except} the fourth and fifth, to refer to another manual as a
	5153	whole. See the next section.
	5154
	5155
	5156	@node Referring to a Manual as a Whole
	5157	@section Referring to a Manual as a Whole
	5158	@cindex Manual, referring to as a whole
	5159	@cindex Referring to an entire manual
	5160	@anchor{Top Node Naming} @c old name
	5161
	5162	Ordinarily, you must always name a node in a cross-reference.
	5163	However, it's not unusual to want to refer to another manual as a
	5164	whole, rather than a particular section within it. In this case,
	5165	giving any section name is an unnecessary distraction.
	5166
	5167	So, with cross-references to other manuals (@pxref{Four and Five
	5168	Arguments}), if the first argument is either @samp{Top} (capitalized
	5169	just that way) or omitted entirely, and the third argument is omitted,
	5170	the printed output includes no node or section name. (The Info output
	5171	includes @samp{Top} if it was given.) For example,
	5172
	5173	@example
	5174	@@xref@{Top,,, make, The GNU Make Manual@}.
	5175	@end example
	5176
	5177	@noindent produces
	5178
	5179	@example
	5180	@group
	5181	*Note (make)Top::.
	5182	@end group
	5183	@end example
	5184
	5185	@noindent and
	5186
	5187	@quotation
	5188	See @cite{The GNU Make Manual}.
	5189	@end quotation
	5190
	5191	@noindent
	5192	Info readers will go to the Top node of the manual whether
	5193	or not the `Top' node is explicitly specified.
	5194
	5195	It's also possible (and is historical practice) to refer to a whole
	5196	manual by specifying the `Top' node and an appropriate entry for the
	5197	third argument to the @code{@@xref} command. Using this idiom, to
	5198	make a cross-reference to @cite{The GNU Make Manual}, you would write:
	5199
	5200	@example
	5201	@@xref@{Top,, Overview, make, The GNU Make Manual@}.
	5202	@end example
	5203
	5204	@noindent
	5205	which produces
	5206
	5207	@example
	5208	*Note Overview: (make)Top.
	5209	@end example
	5210
	5211	@noindent
	5212	in Info and
	5213
	5214	@quotation
	5215	See section ``Overview'' in @cite{The GNU Make Manual}.
	5216	@end quotation
	5217
	5218	@noindent
	5219	in a printed manual.
	5220
	5221	In this example, @samp{Top} is the name of the first node, and
	5222	@samp{Overview} is the name of the first section of the manual. There
	5223	is no widely-used convention for naming the first section in a printed
	5224	manual, this is just what the Make manual happens to use. This
	5225	arbitrariness of the first name is a principal reason why omitting the
	5226	third argument in whole-manual cross-references is preferable.
	5227
	5228
	5229	@node @code{@@ref}
	5230	@section @code{@@ref}
	5231
	5232	@anchor{ref}@c old name
	5233	@findex ref
	5234	@cindex Cross-references using @code{@@ref}
	5235	@cindex References using @code{@@ref}
	5236
	5237	@code{@@ref} is nearly the same as @code{@@xref} except that it does
	5238	not generate a `See' in the printed output, just the reference itself.
	5239	This makes it useful as the last part of a sentence.
	5240
	5241	@noindent For example,
	5242
	5243	@cindex Hurricanes
	5244	@example
	5245	For more information, @@pxref@{This@}, and @@ref@{That@}.
	5246	@end example
	5247
	5248	@noindent
	5249	produces in Info:
	5250
	5251	@example
	5252	For more information, note This::, and note That::.
	5253	@end example
	5254
	5255	@noindent
	5256	and in printed output:
	5257
	5258	@quotation
	5259	For more information, see Section 1.1 [This], page 1,
	5260	and Section 1.2 [That], page 2.
	5261	@end quotation
	5262
	5263	The @code{@@ref} command can tempt writers to express themselves in a
	5264	manner that is suitable for a printed manual but looks awkward in the
	5265	Info format. Bear in mind that your audience could be using both the
	5266	printed and the Info format. For example:
	5267
	5268	@cindex Sea surges
	5269	@example
	5270	Sea surges are described in @@ref@{Hurricanes@}.
	5271	@end example
	5272
	5273	@noindent
	5274	looks ok in the printed output:
	5275
	5276	@quotation
	5277	Sea surges are described in Section 6.7 [Hurricanes], page 72.
	5278	@end quotation
	5279
	5280	@noindent
	5281	but is awkward to read in Info, ``note'' being a verb:
	5282
	5283	@example
	5284	Sea surges are described in *note Hurricanes::.
	5285	@end example
	5286
	5287
	5288	@node @code{@@pxref}
	5289	@section @code{@@pxref}
	5290
	5291	@anchor{pxref}@c old name
	5292	@findex pxref
	5293	@cindex Cross-references using @code{@@pxref}
	5294	@cindex References using @code{@@pxref}
	5295
	5296	The parenthetical reference command, @code{@@pxref}, is nearly the
	5297	same as @code{@@xref}, but it is best used within parentheses.
	5298	The command differs from @code{@@xref} in that @TeX{} typesets the
	5299	reference for the printed manual with a lowercase `see' rather than an
	5300	uppercase `See'.
	5301
	5302	@noindent
	5303	With one argument, a parenthetical cross-reference looks like this:
	5304
	5305	@cindex Flooding
	5306	@example
	5307	@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
	5308	@end example
	5309
	5310	@need 800
	5311	@noindent
	5312	which produces
	5313
	5314	@example
	5315	@group
	5316	@dots{} storms cause flooding (*note Hurricanes::) @dots{}
	5317	@end group
	5318	@end example
	5319
	5320	@noindent
	5321	in Info and
	5322
	5323	@quotation
	5324	@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
	5325	@end quotation
	5326
	5327	@noindent
	5328	in a printed manual.
	5329
	5330	With two arguments, a parenthetical cross-reference has this template:
	5331
	5332	@example
	5333	@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
	5334	@end example
	5335
	5336	@noindent
	5337	which produces
	5338
	5339	@example
	5340	@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
	5341	@end example
	5342
	5343	@noindent
	5344	in Info and
	5345
	5346	@quotation
	5347	@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
	5348	@end quotation
	5349
	5350	@noindent
	5351	in a printed manual.
	5352
	5353	@code{@@pxref} can be used with up to five arguments, just like
	5354	@code{@@xref} (@pxref{@code{@@xref}}).
	5355
	5356	In past versions of Texinfo, it was not allowed to write punctuation
	5357	after a @code{@@pxref}, so it could be used @emph{only} before a
	5358	right parenthesis. This is no longer the case.
	5359	The effect of @samp{@@pxref@{@var{node-name}@}} is similar to that of
	5360	@samp{see @@ref@{@var{node-name}@}}. However, in many circumstance the
	5361	latter is preferrable, as this makes it clear in the Info output that
	5362	the word ``see'' should be present.
	5363
	5364
	5365	@node @code{@@anchor}
	5366	@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
	5367
	5368	@anchor{anchor}@c old name
	5369	@findex anchor
	5370	@cindex Anchors
	5371	@cindex Cross-reference targets, arbitrary
	5372	@cindex Targets for cross-references, arbitrary
	5373
	5374	An @dfn{anchor} is a position in your document, labelled so that
	5375	cross-references can refer to it, just as they can to nodes. You
	5376	create an anchor with the @code{@@anchor} command, and give the label
	5377	as a normal brace-delimited argument. For example:
	5378
	5379	@example
	5380	This marks the @@anchor@{x-spot@}spot.
	5381	@dots{}
	5382	@@xref@{x-spot,,the spot@}.
	5383	@end example
	5384
	5385	@noindent produces:
	5386
	5387	@example
	5388	This marks the spot.
	5389	@dots{}
	5390	See [the spot], page 1.
	5391	@end example
	5392
	5393	As you can see, the @code{@@anchor} command itself produces no output.
	5394	This example defines an anchor `x-spot' just before the word `spot'.
	5395	You can refer to it later with an @code{@@xref} or other cross
	5396	reference command, as shown (@pxref{Cross References}).
	5397
	5398	It is best to put @code{@@anchor} commands just before the position you
	5399	wish to refer to; that way, the reader's eye is led on to the correct
	5400	text when they jump to the anchor. You can put the @code{@@anchor}
	5401	command on a line by itself if that helps readability of the source.
	5402	Whitespace (including newlines) is ignored after @code{@@anchor}.
	5403
	5404	Anchor names and node names may not conflict. Anchors and nodes are
	5405	given similar treatment in some ways; for example, the
	5406	@code{goto-node} command takes either an anchor name or a node name as
	5407	an argument. (@xref{Go to node,,, info, Info}.)
	5408
	5409	Also like node names, anchor names cannot include some characters
	5410	(@pxref{Node Line Requirements}).
	5411
	5412	@cindex Nodes, deleting or renaming
	5413	Because of this duality, when you delete or rename a node, it is
	5414	usually a good idea to define an @code{@@anchor} with the old name.
	5415	That way, any links to the old node, whether from other Texinfo
	5416	manuals or general web pages, keep working.
	5417
	5418
	5419	@node @code{@@inforef}
	5420	@section @code{@@inforef}: Cross-references to Info-only Material
	5421
	5422	@anchor{inforef}@c old name
	5423	@findex inforef
	5424	@cindex Cross-references using @code{@@inforef}
	5425	@cindex References using @code{@@inforef}
	5426
	5427	@code{@@inforef} is used for making cross-references to Info
	5428	documents---even from a printed manual. This might be because you
	5429	want to refer to conditional @code{@@ifinfo} text
	5430	(@pxref{Conditionals}), or because printed output is not available
	5431	(perhaps because there is no Texinfo source), among other
	5432	possibilities.
	5433
	5434	The command takes either two or three arguments, in the following
	5435	order:
	5436
	5437	@enumerate
	5438	@item
	5439	The node name.
	5440
	5441	@item
	5442	The cross-reference name (optional).
	5443
	5444	@item
	5445	The Info file name.
	5446	@end enumerate
	5447
	5448	@noindent
	5449	The template is:
	5450
	5451	@example
	5452	@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}
	5453	@end example
	5454
	5455	@need 800
	5456	@noindent
	5457	For example,
	5458
	5459	@example
	5460	@group
	5461	@@inforef@{Advanced, Advanced Info commands, info@},
	5462	for more information.
	5463	@end group
	5464	@end example
	5465
	5466	@need 800
	5467	@noindent
	5468	produces (in Info):
	5469
	5470	@example
	5471	@group
	5472	*Note Advanced Info commands: (info)Advanced,
	5473	for more information.
	5474	@end group
	5475	@end example
	5476
	5477	@need 800
	5478	@noindent
	5479	and (in the printed output):
	5480
	5481	@quotation
	5482	See Info file @file{info}, node @samp{Advanced}, for more information.
	5483	@end quotation
	5484
	5485	(This particular example is not realistic, since the Info manual is
	5486	written in Texinfo, so all formats are available. In fact, we don't
	5487	know of any extant Info-only manuals.)
	5488
	5489	The converse of @code{@@inforef} is @code{@@cite}, which is used to
	5490	refer to printed works for which no Info form exists.
	5491	@xref{@code{@@cite}}.
	5492
	5493
	5494	@node @code{@@url}
	5495	@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
	5496
	5497	@anchor{uref}@c old name
	5498	@anchor{url}
	5499	@cindex Uniform resource locator, referring to
	5500	@cindex URL, referring to
	5501
	5502	@findex url
	5503	@cindex @code{href}, producing HTML
	5504	@code{@@url} produces a reference to a uniform resource locator
	5505	(url). It takes one mandatory argument, the url, and two optional
	5506	arguments which control the text that is displayed. In HTML and PDF
	5507	output, @code{@@url} produces a link you can follow. (To merely
	5508	indicate a url without creating a link people can follow, use
	5509	@code{@@indicateurl}, @pxref{@code{@@indicateurl}}.)
	5510
	5511	@findex uref
	5512	@code{@@uref} is a synonym for @code{@@url}.
	5513	(Originally, @code{@@url} had the meaning of @code{@@indicateurl}
	5514	and @code{@@uref} was required to produce a working link, but
	5515	in practice @code{@@url} was almost always misused. So we've changed
	5516	the meaning.)
	5517
	5518	The second argument, if specified, is the text to display (the default
	5519	is the url itself); in Info, DVI, and PDF output, but not in HTML
	5520	output, the url is output in addition to this text.
	5521
	5522	@cindex Man page, reference to
	5523	The third argument, if specified, is the text to display, but in this
	5524	case the url is not output in any format. This is useful when the
	5525	text is already sufficiently referential, as in a man page. Also, if
	5526	the third argument is given, the second argument is ignored.
	5527
	5528	@menu
	5529	* @code{@@url} Examples:: Examples of using all the forms of @code{@@url}.
	5530	* URL Line Breaking:: How lines are broken within @code{@@url} text.
	5531	* @code{@@url} PDF Output Format:: A special option to hide links in PDF output.
	5532	* PDF Colors:: Colorizing urls and other links in PDF output.
	5533	@end menu
	5534
	5535
	5536	@node @code{@@url} Examples
	5537	@subsection @code{@@url} Examples
	5538
	5539	@cindex @code{@@url}, examples of using
	5540	@cindex URL, examples of displaying
	5541
	5542	First, here is an example of the simplest form of @code{@@url}, with
	5543	just one argument. The given url is both the target and the visible
	5544	text of the link:
	5545
	5546	@example
	5547	The official GNU ftp site is @@url@{http://ftp.gnu.org/gnu@}.
	5548	@end example
	5549
	5550	@noindent produces:
	5551	@display
	5552	The official GNU ftp site is @url{http://ftp.gnu.org/gnu}.
	5553	@end display
	5554
	5555	@subsubheading Two-argument form of @code{@@url}
	5556
	5557	Here is an example of the two-argument form:
	5558	@example
	5559	The official @@url@{http://ftp.gnu.org/gnu, GNU ftp site@}
	5560	holds programs and texts.
	5561	@end example
	5562
	5563	@noindent which produces:
	5564	@display
	5565	The official @url{http://ftp.gnu.org/gnu, GNU ftp site}
	5566	holds programs and texts.
	5567	@end display
	5568
	5569	@noindent that is, the Info (and @TeX{}, etc.)@: output is this:
	5570	@example
	5571	The official GNU ftp site (http://ftp.gnu.org/gnu)
	5572	holds programs and texts.
	5573	@end example
	5574
	5575	@noindent while the HTML output is this:
	5576	@example
	5577	The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a>
	5578	holds programs and texts.
	5579	@end example
	5580
	5581	@subsubheading Three-argument form of @code{@@url}
	5582
	5583	Finally, an example of the three-argument form:
	5584	@example
	5585	The @@url@{/man.cgi/1/ls,,ls@} program @dots{}
	5586	@end example
	5587
	5588	@noindent which, except for HTML, produces:
	5589	@display
	5590	The @url{/man.cgi/1/ls,,ls} program @dots{}
	5591	@end display
	5592
	5593	@noindent but with HTML:
	5594	@example
	5595	The <a href="/man.cgi/1/ls">ls</a> program @dots{}
	5596	@end example
	5597
	5598
	5599	By the way, some people prefer to display urls in the unambiguous
	5600	format:
	5601
	5602	@display
	5603	<URL:http://@var{host}/@var{path}>
	5604	@end display
	5605
	5606	@noindent
	5607	@cindex @code{<URL...>} convention, not used
	5608	You can use this form in the input file if you wish. We feel it's not
	5609	necessary to include the @samp{<URL:} and @samp{>} in the output,
	5610	since to be useful any software that tries to detect urls in text
	5611	already has to detect them without the @samp{<URL:}.
	5612
	5613
	5614	@node URL Line Breaking
	5615	@subsection URL Line Breaking
	5616
	5617	@cindex Line breaking, and urls
	5618	@cindex Breakpoints within urls
	5619	@TeX{} allows line breaking within urls at only a few characters
	5620	(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
	5621	and @samp{/} (but not between two @samp{/} characters). A tiny amount
	5622	of stretchable space is also inserted around these characters to help
	5623	with line breaking.
	5624
	5625	For HTML output, modern browsers will also do line breaking within
	5626	displayed urls. If you need to allow breaks at other characters you
	5627	can insert @code{@@/} as needed (@pxref{Line Breaks}).
	5628
	5629	@findex urefbreakstyle
	5630	By default, in @TeX{} any such breaks at special characters will occur
	5631	after the character. Some people prefer such breaks to happen before
	5632	the special character. This can be controlled with the
	5633	@code{@@urefbreakstyle} command (this command has effect only in
	5634	@TeX{}):
	5635
	5636	@example
	5637	@@urefbreakstyle @var{how}
	5638	@end example
	5639
	5640	@noindent where the argument @var{how} is one of these words:
	5641
	5642	@vindex after@r{, value for @code{@@urefbreakstyle}}
	5643	@vindex before@r{, value for @code{@@urefbreakstyle}}
	5644	@vindex none@r{, value for @code{@@urefbreakstyle}}
	5645	@table @samp
	5646	@item after
	5647	(the default) Potentially break after the special characters.
	5648	@item before
	5649	Potentially break before the special characters.
	5650	@item none
	5651	Do not consider breaking at the special characters at all; any potential
	5652	breaks must be manually inserted.
	5653	@end table
	5654
	5655
	5656	@node @code{@@url} PDF Output Format
	5657	@subsection @code{@@url} PDF Output Format
	5658
	5659	@cindex PDF output of urls
	5660	@cindex URLs, PDF output of
	5661
	5662	If the ultimate purpose of a PDF is only to be viewed online, perhaps
	5663	similar to HTML in some inchoate way, you may not want the urls to be
	5664	included in the visible text (just as urls are not visible to readers
	5665	of web pages). Texinfo provides a PDF-specific option for this, which
	5666	must be used inside @code{@@tex}:
	5667
	5668	@findex \urefurlonlylinktrue
	5669	@example
	5670	@@tex
	5671	\global\urefurlonlylinktrue
	5672	@@end tex
	5673	@end example
	5674
	5675	The result is that @code{@@url@{http://www.gnu.org, GNU@}} has the
	5676	visible output of just `GNU', with a link target of
	5677	@url{http://www.gnu.org}. Ordinarily, the visible output would
	5678	include both the label and the url: `GNU (@url{http://www.gnu.org})'.
	5679
	5680	This option only has effect when the PDF output is produced with the
	5681	pdf@TeX{} program, not with other ways of getting from Texinfo to PDF
	5682	(e.g., @TeX{} to DVI to PDF)@. Consequently, it is ok to specify this
	5683	option unconditionally within @code{@@tex}, as shown above. It is
	5684	ignored when DVI is being produced.
	5685
	5686
	5687	@node PDF Colors
	5688	@subsection PDF Colors
	5689
	5690	@cindex Colored links, in PDF output
	5691	@cindex Links, coloring in PDF output
	5692	@cindex URLs, coloring in PDF output
	5693
	5694	By default, urls and cross-reference links are printed in black in PDF
	5695	output. Very occasionally, however, you may want to highlight such
	5696	``live'' links with a different color, as is commonly done on web
	5697	pages. Texinfo provides a PDF-specific option for specifying these
	5698	colors, which must be used inside @code{@@tex}:
	5699
	5700	@findex \linkcolor
	5701	@findex \urlcolor
	5702	@example
	5703	@@tex
	5704	\global\def\linkcolor@{1 0 0@} % red
	5705	\global\def\urlcolor@{0 1 0@} % green
	5706	@@end tex
	5707	@end example
	5708
	5709	@code{\urlcolor} changes the color of @code{@@url} output (both the
	5710	actual url and any textual label), while @code{\linkcolor} changes the
	5711	color for cross-references to nodes, etc. They are independent.
	5712
	5713	@cindex RGB color specification.
	5714	The three given values must be numbers between 0 and 1, specifying the
	5715	amount of red, green, and blue respectively.
	5716
	5717	These definitions only have an effect when the PDF output is produced
	5718	with the pdf@TeX{} program, not with other ways of getting from
	5719	Texinfo to PDF (e.g., @TeX{} to DVI to PDF)@. Consequently, it is ok
	5720	to specify this option unconditionally within @code{@@tex}, as shown
	5721	above. It is ignored when DVI is being produced.
	5722
	5723	We do not recommend colorizing just for fun; unless you have a
	5724	specific reason to use colors, best to skip it.
	5725
	5726
	5727	@node @code{@@cite}
	5728	@section @code{@@cite}@{@var{reference}@}
	5729
	5730	@anchor{cite}@c old name
	5731	@findex cite
	5732
	5733	Use the @code{@@cite} command for the name of a book that lacks a
	5734	companion Info file. The command produces italics in the printed
	5735	manual, and quotation marks in the Info file.
	5736
	5737	If a book is written in Texinfo, it is better to use a cross-reference
	5738	command since a reader can easily follow such a reference in Info.
	5739	@xref{@code{@@xref}}.
	5740
	5741
	5742	@node Marking Text
	5743	@chapter Marking Text, Words and Phrases
	5744	@cindex Paragraph, marking text within
	5745	@cindex Marking words and phrases
	5746	@cindex Words and phrases, marking them
	5747	@cindex Marking text within a paragraph
	5748	@cindex Text, marking up
	5749
	5750	In Texinfo, you can mark words and phrases in a variety of ways.
	5751	The Texinfo formatters use this information to determine how to
	5752	highlight the text.
	5753	You can specify, for example, whether a word or phrase is a
	5754	defining occurrence, a metasyntactic variable, or a symbol used in a
	5755	program. Also, you can emphasize text, in several different ways.
	5756
	5757	@menu
	5758	* Indicating:: How to indicate definitions, files, etc.
	5759	* Emphasis:: How to emphasize text.
	5760	@end menu
	5761
	5762
	5763	@node Indicating
	5764	@section Indicating Definitions, Commands, etc.
	5765
	5766	@cindex Highlighting text
	5767	@cindex Indicating commands, definitions, etc.
	5768
	5769	Texinfo has commands for indicating just what kind of object a piece
	5770	of text refers to. For example, email addresses are marked by
	5771	@code{@@email}; that way, the result can be a live link to send email
	5772	when the output format supports it. If the email address was simply
	5773	marked as ``print in a typewriter font'', that would not be possible.
	5774
	5775	@menu
	5776	* Useful Highlighting:: Highlighting provides useful information.
	5777	* @code{@@code}:: Indicating program code.
	5778	* @code{@@kbd}:: Showing keyboard input.
	5779	* @code{@@key}:: Specifying keys.
	5780	* @code{@@samp}:: Indicating a literal sequence of characters.
	5781	* @code{@@verb}:: Indicating a verbatim sequence of characters.
	5782	* @code{@@var}:: Indicating metasyntactic variables.
	5783	* @code{@@env}:: Indicating environment variables.
	5784	* @code{@@file}:: Indicating file names.
	5785	* @code{@@command}:: Indicating command names.
	5786	* @code{@@option}:: Indicating option names.
	5787	* @code{@@dfn}:: Specifying definitions.
	5788	* @code{@@abbr}:: Indicating abbreviations.
	5789	* @code{@@acronym}:: Indicating acronyms.
	5790	* @code{@@indicateurl}:: Indicating an example url.
	5791	* @code{@@email}:: Indicating an electronic mail address.
	5792	@end menu
	5793
	5794
	5795	@node Useful Highlighting
	5796	@subsection Highlighting Commands are Useful
	5797
	5798	The commands serve a variety of purposes:
	5799
	5800	@table @code
	5801	@item @@code@{@var{sample-code}@}
	5802	Indicate text that is a literal example of a piece of a program.
	5803	@xref{@code{@@code}}.
	5804
	5805	@item @@kbd@{@var{keyboard-characters}@}
	5806	Indicate keyboard input. @xref{@code{@@kbd}}.
	5807
	5808	@item @@key@{@var{key-name}@}
	5809	Indicate the conventional name for a key on a keyboard.
	5810	@xref{@code{@@key}}.
	5811
	5812	@item @@samp@{@var{text}@}
	5813	Indicate text that is a literal example of a sequence of characters.
	5814	@xref{@code{@@samp}}.
	5815
	5816	@item @@verb@{@var{text}@}
	5817	Write a verbatim sequence of characters.
	5818	@xref{@code{@@verb}}.
	5819
	5820	@item @@var@{@var{metasyntactic-variable}@}
	5821	Indicate a metasyntactic variable. @xref{@code{@@var}}.
	5822
	5823	@item @@env@{@var{environment-variable}@}
	5824	Indicate an environment variable. @xref{@code{@@env}}.
	5825
	5826	@item @@file@{@var{file-name}@}
	5827	Indicate the name of a file. @xref{@code{@@file}}.
	5828
	5829	@item @@command@{@var{command-name}@}
	5830	Indicate the name of a command.
	5831	@xref{@code{@@command}}.
	5832
	5833	@item @@option@{@var{option}@}
	5834	Indicate a command-line option.
	5835	@xref{@code{@@option}}.
	5836
	5837	@item @@dfn@{@var{term}@}
	5838	Indicate the introductory or defining use of a term.
	5839	@xref{@code{@@dfn}}.
	5840
	5841	@item @@cite@{@var{reference}@}
	5842	Indicate the name of a book. @xref{@code{@@cite}}.
	5843
	5844	@item @@abbr@{@var{abbreviation}@}
	5845	Indicate an abbreviation, such as `Comput.'.
	5846
	5847	@item @@acronym@{@var{acronym}@}
	5848	Indicate an acronym. @xref{@code{@@acronym}}.
	5849
	5850	@item @@indicateurl@{@var{uniform-resource-locator}@}
	5851	Indicate an example (that is, nonfunctional) uniform resource locator.
	5852	@xref{@code{@@indicateurl}}. (Use @code{@@url} (@pxref{@code{@@url}}) for
	5853	live urls.)
	5854
	5855	@item @@email@{@var{email-address}[, @var{displayed-text}]@}
	5856	Indicate an electronic mail address. @xref{@code{@@email}}.
	5857
	5858	@end table
	5859
	5860
	5861	@node @code{@@code}
	5862	@subsection @code{@@code}@{@var{sample-code}@}
	5863
	5864	@anchor{code}@c old name
	5865	@findex code
	5866
	5867	@cindex Syntactic tokens, indicating
	5868	Use the @code{@@code} command to indicate text that is a piece of a
	5869	program and which consists of entire syntactic tokens. Enclose the
	5870	text in braces.
	5871
	5872	@cindex Expressions in a program, indicating
	5873	@cindex Keywords, indicating
	5874	@cindex Reserved words, indicating
	5875	Thus, you should use @code{@@code} for an expression in a program, for
	5876	the name of a variable or function used in a program, or for a
	5877	keyword in a programming language.
	5878
	5879	Use @code{@@code} for command names in languages that resemble
	5880	programming languages, such as Texinfo. For example, @code{@@code} and
	5881	@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
	5882	@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
	5883
	5884	@cindex Case, not altering in @code{@@code}
	5885	It is incorrect to alter the case of a word inside a @code{@@code}
	5886	command when it appears at the beginning of a sentence. Most computer
	5887	languages are case sensitive. In C, for example, @code{Printf} is
	5888	different from the identifier @code{printf}, and most likely is a
	5889	misspelling of it. Even in languages which are not case sensitive, it
	5890	is confusing to a human reader to see identifiers spelled in different
	5891	ways. Pick one spelling and always use that. If you do not want to
	5892	start a sentence with a command name written all in lowercase, you
	5893	should rearrange the sentence.
	5894
	5895	In the Info output, @code{@@code} results in single quotation marks
	5896	around the text. In other formats, @code{@@code} argument is typeset
	5897	in a typewriter (monospace) font. For example,
	5898
	5899	@example
	5900	The function returns @@code@{nil@}.
	5901	@end example
	5902
	5903	@noindent
	5904	produces this:
	5905
	5906	@quotation
	5907	The function returns @code{nil}.
	5908	@end quotation
	5909
	5910	Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
	5911
	5912	@itemize @bullet
	5913	@item
	5914	For shell command names, such as @command{ls} (use @code{@@command}).
	5915
	5916	@item
	5917	For environment variables, such as @env{TEXINPUTS} (use @code{@@env}).
	5918
	5919	@item
	5920	For shell options, such as @samp{-c}, when such options stand alone (use
	5921	@code{@@option}).
	5922
	5923	@item
	5924	An entire shell command often looks better if written using
	5925	@code{@@samp} rather than @code{@@code}. In this case, the rule is to
	5926	choose the more pleasing format.
	5927
	5928	@item
	5929	For a string of characters shorter than a syntactic token. For example,
	5930	if you are writing about @samp{goto-ch}, which is just a part of the
	5931	name for the @code{goto-char} Emacs Lisp function, you should use
	5932	@code{@@samp}.
	5933
	5934	@item
	5935	In general, when writing about the characters used in a token; for
	5936	example, do not use @code{@@code} when you are explaining what letters
	5937	or printable symbols can be used in the names of functions. (Use
	5938	@code{@@samp}.) Also, you should not use @code{@@code} to mark text
	5939	that is considered input to programs unless the input is written in a
	5940	language that is like a programming language. For example, you should
	5941	not use @code{@@code} for the keystroke commands of GNU Emacs (use
	5942	@code{@@kbd} instead) although you may use @code{@@code} for the names
	5943	of the Emacs Lisp functions that the keystroke commands invoke.
	5944
	5945	@end itemize
	5946
	5947	By default, @TeX{} will consider breaking lines at @samp{-} and
	5948	@samp{_} characters within @code{@@code} and related commands. This
	5949	can be controlled with @code{@@allowcodebreaks}
	5950	(@pxref{@code{@@allowcodebreaks}}). The HTML output attempts to
	5951	respect this for @samp{-}, but ultimately it is up to the browser's
	5952	behavior. For Info, it seems better never to make such breaks.
	5953
	5954	For Info, the quotes are omitted in the output of the @code{@@code}
	5955	command and related commands (e.g., @code{@@kbd}, @code{@@command}),
	5956	in typewriter-like contexts such as the @code{@@example} environment
	5957	(@pxref{@code{@@example}}) and @code{@@code} itself, etc.
	5958
	5959	To control which quoting characters are implicitly inserted by Texinfo
	5960	processors in the output of @samp{@@code}, etc., see the
	5961	@code{OPEN_QUOTE_SYMBOL} and @code{CLOSE_QUOTE_SYMBOL} customization
	5962	variables (@pxref{Other Customization Variables}). This is separate
	5963	from how actual quotation characters in the input document are handled
	5964	(@pxref{Inserting Quote Characters}).
	5965
	5966
	5967	@node @code{@@kbd}
	5968	@subsection @code{@@kbd}@{@var{keyboard-characters}@}
	5969
	5970	@anchor{kbd}@c old name
	5971	@findex kbd
	5972	@cindex Keyboard input
	5973
	5974	Use the @code{@@kbd} command for characters of input to be typed by
	5975	users. For example, to refer to the characters @kbd{M-a}, write:
	5976
	5977	@example
	5978	@@kbd@{M-a@}
	5979	@end example
	5980
	5981	@noindent
	5982	and to refer to the characters @kbd{M-x shell}, write:
	5983
	5984	@example
	5985	@@kbd@{M-x shell@}
	5986	@end example
	5987
	5988	@cindex User input
	5989	@cindex Slanted typewriter font, for @code{@@kbd}
	5990	By default, the @code{@@kbd} command produces a different font
	5991	(slanted typewriter instead of normal typewriter),
	5992	so users can distinguish the characters that they are supposed
	5993	to type from those that the computer outputs.
	5994
	5995	@findex kbdinputstyle
	5996	Since the usage of @code{@@kbd} varies from manual to manual, you can
	5997	control the font switching with the @code{@@kbdinputstyle} command.
	5998	This command has no effect on Info output. Write this command at the
	5999	beginning of a line with a single word as an argument, one of the
	6000	following:
	6001
	6002	@vindex distinct@r{, value for @code{@@kbdinputstyle}}
	6003	@vindex example@r{, value for @code{@@kbdinputstyle}}
	6004	@vindex code@r{, value for @code{@@kbdinputstyle}}
	6005	@table @samp
	6006	@item code
	6007	Always use the same font for @code{@@kbd} as @code{@@code}.
	6008	@item example
	6009	Use the distinguishing font for @code{@@kbd} only in @code{@@example}
	6010	and similar environments.
	6011	@item distinct
	6012	(the default) Always use the distinguishing font for @code{@@kbd}.
	6013	@end table
	6014
	6015	You can embed another @@-command inside the braces of a @code{@@kbd}
	6016	command. Here, for example, is the way to describe a command that
	6017	would be described more verbosely as ``press the @samp{r} key and then
	6018	press the @key{RETURN} key'':
	6019
	6020	@example
	6021	@@kbd@{r @@key@{RET@}@}
	6022	@end example
	6023
	6024	@noindent
	6025	This produces: @kbd{r @key{RET}}. (The present manual uses the
	6026	default for @code{@@kbdinputstyle}.)
	6027
	6028	You also use the @code{@@kbd} command if you are spelling out the letters
	6029	you type; for example:
	6030
	6031	@example
	6032	To give the @@code@{logout@} command,
	6033	type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
	6034	@end example
	6035
	6036	@noindent
	6037	This produces:
	6038
	6039	@quotation
	6040	To give the @code{logout} command,
	6041	type the characters @kbd{l o g o u t @key{RET}}.
	6042	@end quotation
	6043
	6044	(Also, this example shows that you can add spaces for clarity. If you
	6045	explicitly want to mention a space character as one of the characters of
	6046	input, write @kbd{@@key@{SPC@}} for it.)
	6047
	6048
	6049	@node @code{@@key}
	6050	@subsection @code{@@key}@{@var{key-name}@}
	6051
	6052	@anchor{key}@c old name
	6053	@findex key
	6054
	6055	Use the @code{@@key} command for the conventional name for a key on a
	6056	keyboard, as in:
	6057
	6058	@example
	6059	@@key@{RET@}
	6060	@end example
	6061
	6062	You can use the @code{@@key} command within the argument of an
	6063	@code{@@kbd} command when the sequence of characters to be typed
	6064	includes one or more keys that are described by name.
	6065
	6066	For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you
	6067	would type:
	6068
	6069	@example
	6070	@@kbd@{C-x @@key@{ESC@}@}
	6071	@@kbd@{M-@@key@{TAB@}@}
	6072	@end example
	6073
	6074	Here is a list of the recommended names for keys:
	6075	@cindex Recommended names for keys
	6076	@cindex Keys, recommended names
	6077	@cindex Names recommended for keys
	6078	@cindex Abbreviations for keys
	6079	@cindex Control keys, specifying
	6080	@cindex Meta keys, specifying
	6081
	6082	@quotation
	6083	@table @t
	6084	@item SPC
	6085	Space
	6086	@item RET
	6087	Return
	6088	@item LFD
	6089	Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
	6090	it might be better to call this character @kbd{C-j})
	6091	@item TAB
	6092	Tab
	6093	@item BS
	6094	Backspace
	6095	@item ESC
	6096	Escape
	6097	@item DELETE
	6098	Delete
	6099	@item SHIFT
	6100	Shift
	6101	@item CTRL
	6102	Control
	6103	@item META
	6104	Meta
	6105	@end table
	6106	@end quotation
	6107
	6108	@cindex META key
	6109	There are subtleties to handling words like `meta' or `ctrl' that are
	6110	names of modifier keys. When mentioning a character in which the
	6111	modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
	6112	alone; do not use the @code{@@key} command; but when you are referring
	6113	to the modifier key in isolation, use the @code{@@key} command. For
	6114	example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
	6115	@samp{@@key@{META@}} to produce @key{META}.
	6116
	6117	@c per rms.
	6118	As a convention in GNU manuals, @code{@@key} should not be used in
	6119	index entries.
	6120
	6121
	6122	@node @code{@@samp}
	6123	@subsection @code{@@samp}@{@var{text}@}
	6124
	6125	@anchor{samp}@c old name
	6126	@findex samp
	6127
	6128	Use the @code{@@samp} command to indicate text that is a literal example
	6129	or `sample' of a sequence of characters in a file, string, pattern, etc.
	6130	Enclose the text in braces. The argument appears within single
	6131	quotation marks in both the Info file and the printed manual; in
	6132	addition, it is printed in a fixed-width font.
	6133
	6134	@example
	6135	To match @@samp@{foo@} at the end of the line,
	6136	use the regexp @@samp@{foo$@}.
	6137	@end example
	6138
	6139	@noindent
	6140	produces
	6141
	6142	@quotation
	6143	To match @samp{foo} at the end of the line, use the regexp
	6144	@samp{foo$}.
	6145	@end quotation
	6146
	6147	Any time you are referring to single characters, you should use
	6148	@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
	6149	Also, you may use @code{@@samp} for entire statements in C and for entire
	6150	shell commands---in this case, @code{@@samp} often looks better than
	6151	@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
	6152	not covered by @code{@@code}, @code{@@kbd}, @code{@@key},
	6153	@code{@@command}, etc.
	6154
	6155	Only include punctuation marks within braces if they are part of the
	6156	string you are specifying. Write punctuation marks outside the braces
	6157	if those punctuation marks are part of the English text that surrounds
	6158	the string. In the following sentence, for example, the commas and
	6159	period are outside of the braces:
	6160
	6161	@example
	6162	@group
	6163	In English, the vowels are @@samp@{a@}, @@samp@{e@},
	6164	@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
	6165	@@samp@{y@}.
	6166	@end group
	6167	@end example
	6168
	6169	@noindent
	6170	This produces:
	6171
	6172	@quotation
	6173	In English, the vowels are @samp{a}, @samp{e},
	6174	@samp{i}, @samp{o}, @samp{u}, and sometimes
	6175	@samp{y}.
	6176	@end quotation
	6177
	6178
	6179	@node @code{@@verb}
	6180	@subsection @code{@@verb}@{@var{char}@var{text}@var{char}@}
	6181
	6182	@anchor{verb}@c old name
	6183	@findex verb
	6184	@cindex Verbatim in-line text
	6185
	6186	@cindex Delimiter character, for verbatim
	6187	Use the @code{@@verb} command to print a verbatim sequence of
	6188	characters.
	6189
	6190	Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using
	6191	any unique delimiter character. Enclose the verbatim text, including the
	6192	delimiters, in braces. Text is printed in a fixed-width font:
	6193
	6194	@example
	6195	How many @@verb@{\|@@\|@}-escapes does one need to print this
	6196	@@verb@{.@@a @@b.@@c.@} string or @@verb@{+@@'e?`@{@}!`\+@} this?
	6197	@end example
	6198
	6199	@noindent
	6200	produces
	6201
	6202	@example
	6203	How many @verb{\|@\|}-escapes does one need to print this
	6204	@verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this?
	6205	@end example
	6206
	6207	This is in contrast to @code{@@samp} (see the previous section),
	6208	@code{@@code}, and similar commands; in those cases, the argument is
	6209	normal Texinfo text, where the three characters @code{@@@{@}} are
	6210	special, as usual. With @code{@@verb}, nothing is special except the
	6211	delimiter character you choose.
	6212
	6213	The delimiter character itself may appear inside the verbatim text, as
	6214	shown above. As another example, @samp{@@verb@{...@}} prints a single
	6215	(fixed-width) period.
	6216
	6217	It is not reliable to use @code{@@verb} inside other Texinfo
	6218	constructs. In particular, it does not work to use @code{@@verb} in
	6219	anything related to cross-referencing, such as section titles or
	6220	figure captions.
	6221
	6222
	6223	@node @code{@@var}
	6224	@subsection @code{@@var}@{@var{metasyntactic-variable}@}
	6225
	6226	@anchor{var}@c old name
	6227	@findex var
	6228
	6229	Use the @code{@@var} command to indicate metasyntactic variables. A
	6230	@dfn{metasyntactic variable} is something that stands for another
	6231	piece of text. For example, you should use a metasyntactic variable
	6232	in the documentation of a function to describe the arguments that are
	6233	passed to that function.
	6234
	6235	Do not use @code{@@var} for the names of normal variables in computer
	6236	programs. These are specific names, so @code{@@code} is correct for
	6237	them (@code{@@code}). For example, the Emacs Lisp variable
	6238	@code{texinfo-tex-command} is not a metasyntactic variable; it is
	6239	properly formatted using @code{@@code}.
	6240
	6241	Do not use @code{@@var} for environment variables either; @code{@@env}
	6242	is correct for them (see the next section).
	6243
	6244	The effect of @code{@@var} in the Info file is to change the case of
	6245	the argument to all uppercase. In the printed manual and HTML
	6246	output, the argument is output in slanted type.
	6247
	6248	@need 700
	6249	For example,
	6250
	6251	@example
	6252	To delete file @@var@{filename@},
	6253	type @@samp@{rm @@var@{filename@}@}.
	6254	@end example
	6255
	6256	@noindent
	6257	produces
	6258
	6259	@quotation
	6260	To delete file @var{filename}, type @samp{rm @var{filename}}.
	6261	@end quotation
	6262
	6263	@noindent
	6264	(Note that @code{@@var} may appear inside @code{@@code},
	6265	@code{@@samp}, @code{@@file}, etc.)
	6266
	6267	Write a metasyntactic variable all in lowercase without spaces, and
	6268	use hyphens to make it more readable. Thus, the Texinfo source for
	6269	the illustration of how to begin a Texinfo manual looks like
	6270	this:
	6271
	6272	@example
	6273	@group
	6274	\input texinfo
	6275	@@@@settitle @@var@{name-of-manual@}
	6276	@end group
	6277	@end example
	6278
	6279	@noindent
	6280	This produces:
	6281
	6282	@example
	6283	@group
	6284	\input texinfo
	6285	@@settitle @var{name-of-manual}
	6286	@end group
	6287	@end example
	6288
	6289	In some documentation styles, metasyntactic variables are shown with
	6290	angle brackets, for example:
	6291
	6292	@example
	6293	@dots{}, type rm <filename>
	6294	@end example
	6295
	6296	@noindent
	6297	However, that is not the style that Texinfo uses.
	6298
	6299	@c FIXME add a customization variable? Add an example on how to do that
	6300	@c for HTML?
	6301	@c (You can, of course, modify the sources to @file{texinfo.tex}
	6302	@c and the Info formatting commands
	6303	@c to output the @code{<@dots{}>} format if you wish.)
	6304
	6305
	6306	@node @code{@@env}
	6307	@subsection @code{@@env}@{@var{environment-variable}@}
	6308
	6309	@anchor{env}@c old name
	6310	@findex env
	6311
	6312	Use the @code{@@env} command to indicate environment variables, as
	6313	used by many operating systems, including GNU@. Do not use it for
	6314	@emph{meta}syntactic variables; use @code{@@var} for those (see the
	6315	previous section).
	6316
	6317	@code{@@env} is equivalent to @code{@@code} in its effects.
	6318	For example:
	6319
	6320	@example
	6321	The @@env@{PATH@} environment variable @dots{}
	6322	@end example
	6323	@noindent produces
	6324	@quotation
	6325	The @env{PATH} environment variable @dots{}
	6326	@end quotation
	6327
	6328
	6329	@node @code{@@file}
	6330	@subsection @code{@@file}@{@var{file-name}@}
	6331
	6332	@anchor{file}@c old name
	6333	@findex file
	6334
	6335	Use the @code{@@file} command to indicate text that is the name of a
	6336	file, buffer, or directory, or is the name of a node in Info. You can
	6337	also use the command for file name suffixes. Do not use @code{@@file}
	6338	for symbols in a programming language; use @code{@@code}.
	6339
	6340	@code{@@file} is equivalent to @code{code} in its effects. For
	6341	example,
	6342
	6343	@example
	6344	The @@file@{.el@} files are in
	6345	the @@file@{/usr/local/emacs/lisp@} directory.
	6346	@end example
	6347
	6348	@noindent
	6349	produces
	6350
	6351	@quotation
	6352	The @file{.el} files are in
	6353	the @file{/usr/local/emacs/lisp} directory.
	6354	@end quotation
	6355
	6356
	6357	@node @code{@@command}
	6358	@subsection @code{@@command}@{@var{command-name}@}
	6359
	6360	@anchor{command}@c old name
	6361	@findex command
	6362	@cindex Command names, indicating
	6363	@cindex Program names, indicating
	6364
	6365	Use the @code{@@command} command to indicate command names, such as
	6366	@command{ls} or @command{cc}.
	6367
	6368	@code{@@command} is equivalent to @code{@@code} in its effects.
	6369	For example:
	6370
	6371	@example
	6372	The command @@command@{ls@} lists directory contents.
	6373	@end example
	6374	@noindent produces
	6375	@quotation
	6376	The command @command{ls} lists directory contents.
	6377	@end quotation
	6378
	6379	You should write the name of a program in the ordinary text font, rather
	6380	than using @code{@@command}, if you regard it as a new English word,
	6381	such as `Emacs' or `Bison'.
	6382
	6383	When writing an entire shell command invocation, as in @samp{ls -l},
	6384	you should use either @code{@@samp} or @code{@@code} at your discretion.
	6385
	6386
	6387	@node @code{@@option}
	6388	@subsection @code{@@option}@{@var{option-name}@}
	6389
	6390	@anchor{option}@c old name
	6391	@findex option
	6392
	6393	Use the @code{@@option} command to indicate a command-line option; for
	6394	example, @option{-l} or @option{--version} or
	6395	@option{--output=@var{filename}}.
	6396
	6397	@code{@@option} is equivalent to @code{@@code} in its effects.
	6398	For example:
	6399
	6400	@example
	6401	The option @@option@{-l@} produces a long listing.
	6402	@end example
	6403	@noindent produces
	6404	@quotation
	6405	The option @option{-l} produces a long listing.
	6406	@end quotation
	6407
	6408
	6409	@node @code{@@dfn}
	6410	@subsection @code{@@dfn}@{@var{term}@}
	6411
	6412	@anchor{dfn}@c old name
	6413	@findex dfn
	6414
	6415	Use the @code{@@dfn} command to identify the introductory or defining
	6416	use of a technical term. Use the command only in passages whose
	6417	purpose is to introduce a term which will be used again or which the
	6418	reader ought to know. Mere passing mention of a term for the first
	6419	time does not deserve @code{@@dfn}. The command generates italics in
	6420	the printed manual, and double quotation marks in the Info file. For
	6421	example:
	6422
	6423	@example
	6424	Getting rid of a file is called @@dfn@{deleting@} it.
	6425	@end example
	6426
	6427	@noindent
	6428	produces
	6429
	6430	@quotation
	6431	Getting rid of a file is called @dfn{deleting} it.
	6432	@end quotation
	6433
	6434	As a general rule, a sentence containing the defining occurrence of a
	6435	term should be a definition of the term. The sentence does not need
	6436	to say explicitly that it is a definition, but it should contain the
	6437	information of a definition---it should make the meaning clear.
	6438
	6439
	6440	@node @code{@@abbr}
	6441	@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@}
	6442
	6443	@anchor{abbr}@c old name
	6444	@findex abbr
	6445
	6446	@cindex Abbreviations, tagging
	6447	You can use the @code{@@abbr} command for general abbreviations. The
	6448	abbreviation is given as the single argument in braces, as in
	6449	@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular
	6450	abbreviations, you may prefer to omit periods, as in
	6451	@samp{@@abbr@{Mr@} Stallman}.
	6452
	6453	@code{@@abbr} accepts an optional second argument, intended to be used
	6454	for the meaning of the abbreviation.
	6455
	6456	If the abbreviation ends with a lowercase letter and a period, and is
	6457	not at the end of a sentence, and has no second argument, remember to
	6458	use the @code{@@.} command (@pxref{Ending a Sentence}) to get the
	6459	correct spacing. However, you do not have to use @code{@@.} within
	6460	the abbreviation itself; Texinfo automatically assumes periods within
	6461	the abbreviation do not end a sentence.
	6462
	6463	@cindex @code{<abbr>} and @code{<abbrev>} tags
	6464	In @TeX{} and in the Info output, the first argument is printed as-is;
	6465	if the second argument is present, it is printed in parentheses after
	6466	the abbreviation. In HTML the @code{<abbr>} tag is used; in Docbook,
	6467	the @code{<abbrev>} tag is used. For instance:
	6468
	6469	@example
	6470	@@abbr@{Comput. J., Computer Journal@}
	6471	@end example
	6472
	6473	@noindent produces:
	6474
	6475	@display
	6476	@abbr{Comput. J., Computer Journal}
	6477	@end display
	6478
	6479	For abbreviations consisting of all capital letters, you may prefer to
	6480	use the @code{@@acronym} command instead. See the next section for
	6481	more on the usage of these two commands.
	6482
	6483
	6484	@node @code{@@acronym}
	6485	@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@}
	6486
	6487	@anchor{acronym}@c old name
	6488	@findex acronym
	6489
	6490	@cindex NASA, as acronym
	6491	@cindex Acronyms, tagging
	6492	You can use the @code{@@acronym} command for abbreviations written in
	6493	all capital letters, such as `@acronym{NASA}'. The abbreviation is
	6494	given as the single argument in braces, as in
	6495	@samp{@@acronym@{NASA@}}. As a matter of style, or for particular
	6496	acronyms, you may prefer to use periods, as in
	6497	@samp{@@acronym@{N.A.S.A.@}}.
	6498
	6499	@code{@@acronym} accepts an optional second argument, intended to be
	6500	used for the meaning of the acronym.
	6501
	6502	If the acronym is at the end of a sentence, and if there is no second
	6503	argument, remember to use the @code{@@.} or similar command
	6504	(@pxref{Ending a Sentence}) to get the correct spacing.
	6505
	6506	@cindex @code{<acronym>} tag
	6507	In @TeX{}, the acronym is printed in slightly smaller font. In the
	6508	Info output, the argument is printed as-is. In either format, if the
	6509	second argument is present, it is printed in parentheses after the
	6510	acronym. In HTML and Docbook the @code{<acronym>} tag is used.
	6511
	6512	For instance (since GNU is a recursive acronym, we use
	6513	@code{@@acronym} recursively):
	6514
	6515	@example
	6516	@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@}
	6517	@end example
	6518
	6519	@noindent produces:
	6520
	6521	@display
	6522	@acronym{GNU, @acronym{GNU}'s Not Unix}
	6523	@end display
	6524
	6525	@cindex Family names, in all capitals
	6526	In some circumstances, it is conventional to print family names in all
	6527	capitals. Don't use @code{@@acronym} for this, since a name is not an
	6528	acronym. Use @code{@@sc} instead (@pxref{Smallcaps}).
	6529
	6530	@code{@@abbr} and @code{@@acronym} are closely related commands: they
	6531	both signal to the reader that a shortened form is being used, and
	6532	possibly give a meaning. When choosing whether to use these two
	6533	commands, please bear the following in mind.
	6534
	6535	@itemize @minus
	6536	@item
	6537	In common English usage, acronyms are a subset of abbreviations: they
	6538	include pronounceable words like `@acronym{NATO}', `radar', and
	6539	`snafu'; some sources also include syllable acronyms like
	6540	`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable
	6541	initialisms like `@acronym{FBI}'.
	6542
	6543	@item
	6544	In Texinfo, an acronym (but not an abbreviation) should consist only
	6545	of capital letters and periods, no lowercase.
	6546
	6547	@item
	6548	In @TeX{}, an acronym (but not an abbreviation) is printed in a
	6549	slightly smaller font.
	6550
	6551	@item
	6552	Some browsers place a dotted bottom border under abbreviations but not
	6553	acronyms.
	6554
	6555	@item
	6556	It usually turns out to be quite difficult and/or time-consuming to
	6557	consistently use @code{@@acronym} for all sequences of uppercase
	6558	letters. Furthermore, it looks strange for some acronyms to be in the
	6559	normal font size and others to be smaller. Thus, a simpler approach
	6560	you may wish to consider is to avoid @code{@@acronym} and just typeset
	6561	everything as normal text in all capitals: @samp{GNU}, producing the
	6562	output `GNU'.
	6563
	6564	@item
	6565	In general, it's not essential to use either of these commands for all
	6566	abbreviations; use your judgment. Text is perfectly readable without
	6567	them.
	6568	@end itemize
	6569
	6570
	6571	@node @code{@@indicateurl}
	6572	@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@}
	6573
	6574	@anchor{indicateurl}@c old name
	6575	@findex indicateurl
	6576	@cindex Uniform resource locator, indicating
	6577	@cindex URL, indicating
	6578
	6579	Use the @code{@@indicateurl} command to indicate a uniform resource
	6580	locator on the World Wide Web. This is purely for markup purposes and
	6581	does not produce a link you can follow (use the @code{@@url} or
	6582	@code{@@uref} command for that, @pxref{@code{@@url}}).
	6583	@code{@@indicateurl} is useful for urls which do not actually exist.
	6584	For example:
	6585
	6586	@example
	6587	For example, the url might be @@indicateurl@{http://example.org/path@}.
	6588	@end example
	6589
	6590	@noindent which produces:
	6591
	6592	@display
	6593	For example, the url might be @indicateurl{http://example.org/path}.
	6594	@end display
	6595
	6596	The output from @code{@@indicateurl} is more or less like that of
	6597	@code{@@samp} (@pxref{@code{@@samp}}).
	6598
	6599
	6600	@node @code{@@email}
	6601	@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
	6602
	6603	@anchor{email}@c old name
	6604	@findex email
	6605
	6606	Use the @code{@@email} command to indicate an electronic mail address.
	6607	It takes one mandatory argument, the address, and one optional argument, the
	6608	text to display (the default is the address itself).
	6609
	6610	@cindex Mailto link
	6611	In Info, the address is shown in angle brackets, preceded by the text
	6612	to display if any. In @TeX{}, the angle brackets are omitted. In
	6613	HTML output, @code{@@email} produces a @samp{mailto} link that usually
	6614	brings up a mail composition window. For example:
	6615
	6616	@example
	6617	Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
	6618	suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
	6619	@end example
	6620
	6621	@noindent produces
	6622
	6623	@display
	6624	Send bug reports to @email{bug-texinfo@@gnu.org},
	6625	suggestions to the @email{bug-texinfo@@gnu.org, same place}.
	6626	@end display
	6627
	6628
	6629	@node Emphasis
	6630	@section Emphasizing Text
	6631	@cindex Emphasizing text
	6632
	6633	Usually, Texinfo changes the font to mark words in the text according
	6634	to the category the words belong to; an example is the @code{@@code}
	6635	command. Most often, this is the best way to mark words. However,
	6636	sometimes you will want to emphasize text without indicating a
	6637	category. Texinfo has two commands to do this. Also, Texinfo has
	6638	several commands that specify the font in which text will be output.
	6639	These commands have no effect in Info and only one of them, the
	6640	@code{@@r} command, has any regular use.
	6641
	6642	@menu
	6643	* @code{@@emph @@strong}:: How to emphasize text in Texinfo.
	6644	* Smallcaps:: How to use the small caps font.
	6645	* Fonts:: Various font commands for printed output.
	6646	@end menu
	6647
	6648
	6649	@node @code{@@emph @@strong}
	6650	@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
	6651
	6652	@anchor{emph & strong}@c oldname
	6653	@findex emph
	6654	@findex strong
	6655	@cindex Emphasizing text, font for
	6656
	6657	The @code{@@emph} and @code{@@strong} commands are for emphasis;
	6658	@code{@@strong} is stronger. In printed output, @code{@@emph} produces
	6659	@emph{italics} and @code{@@strong} produces @strong{bold}.
	6660	In the Info output, @code{@@emph} surrounds the text with underscores
	6661	(@samp{_}), and @code{@@strong} puts asterisks around the text.
	6662
	6663	For example,
	6664
	6665	@example
	6666	@group
	6667	@@strong@{Caution:@} @@samp@{rm * .[^.]*@}
	6668	removes @@emph@{all@} files in the directory.
	6669	@end group
	6670	@end example
	6671
	6672	@noindent
	6673	produces the following:
	6674
	6675	@quotation
	6676	@strong{Caution}: @samp{rm * .[^.]*}
	6677	removes @emph{all} files in the directory.
	6678	@end quotation
	6679
	6680	The @code{@@strong} command is seldom used except to mark what is, in
	6681	effect, a typographical element, such as the word `Caution' in the
	6682	preceding example.
	6683
	6684	@quotation Caution
	6685	Do not use @code{@@strong} with the word @samp{Note} followed by a
	6686	space; Info will mistake the combination for a cross-reference. Use a
	6687	phrase such as @strong{Please notice} or @strong{Caution} instead, or
	6688	the optional argument to @code{@@quotation}---@samp{Note} is allowable
	6689	there.
	6690	@end quotation
	6691
	6692
	6693	@node Smallcaps
	6694	@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
	6695	@cindex Small caps font
	6696	@findex sc @r{(small caps font)}
	6697
	6698	Use the @samp{@@sc} command to set text in @sc{a small caps font}
	6699	(where possible). Write the text you want to be in small caps between
	6700	braces in lowercase, like this:
	6701
	6702	@example
	6703	Richard @@sc@{Stallman@} commenc@'{e} GNU.
	6704	@end example
	6705
	6706	@noindent
	6707	This produces:
	6708
	6709	@display
	6710	Richard @sc{Stallman} commenc@'{e} GNU.
	6711	@end display
	6712
	6713	As shown here, we recommend reserving @code{@@sc} for special cases
	6714	where you want typographic small caps; family names are one such,
	6715	especially in languages other than English, though there are no
	6716	hard-and-fast rules about such things.
	6717
	6718	@cindex @code{<small>} tag
	6719	@TeX{} typesets any uppercase letters between the braces of an
	6720	@code{@@sc} command in full-size capitals; only lowercase letters are
	6721	printed in the small caps font. In the Info output, the argument to
	6722	@code{@@sc} is printed in all uppercase. In HTML, the argument is
	6723	uppercased and the output marked with the @code{<small>} tag to reduce
	6724	the font size, since HTML cannot easily represent true small caps.
	6725
	6726	Overall, we recommend using standard upper- and lowercase letters
	6727	wherever possible.
	6728
	6729
	6730	@node Fonts
	6731	@subsection Fonts for Printing
	6732	@cindex Fonts for printing
	6733
	6734	@findex fonttextsize
	6735	@cindex Font size, reducing
	6736	@cindex Reducing font size
	6737	@cindex Smaller fonts
	6738	Texinfo provides one command to change the size of the main body font
	6739	in the @TeX{} output for a document: @code{@@fonttextsize}. It has no
	6740	effect in other output. It takes a single argument on the remainder
	6741	of the line, which must be either @samp{10} or @samp{11}. For
	6742	example:
	6743
	6744	@example
	6745	@@fonttextsize 10
	6746	@end example
	6747
	6748	@cindex Printing cost, reducing
	6749	The effect is to reduce the body font to a 10@dmn{pt} size (the
	6750	default is 11@dmn{pt}). Fonts for other elements, such as sections
	6751	and chapters, are reduced accordingly. This should only be used in
	6752	conjunction with @code{@@smallbook} (@pxref{@code{@@smallbook}}) or
	6753	similar, since 10@dmn{pt} fonts on standard paper (8.5x11 or A4) are
	6754	too small. One reason to use this command is to save pages, and hence
	6755	printing cost, for physical books.
	6756
	6757	Texinfo does not at present have commands to switch the font family
	6758	to use, or more general size-changing commands.
	6759
	6760	Texinfo also provides a number of font commands that specify font
	6761	changes in the printed manual and (where possible) in the HTML output.
	6762	They have no effect in Info. All the commands apply to a following
	6763	argument surrounded by braces.
	6764
	6765	@table @code
	6766	@item @@b
	6767	@findex b @r{(bold font)}
	6768	@cindex Bold font
	6769	selects @b{bold} face;
	6770
	6771	@item @@i
	6772	@findex i @r{(italic font)}
	6773	@cindex Italic font
	6774	selects an @i{italic} font;
	6775
	6776	@item @@r
	6777	@findex r @r{(roman font)}
	6778	@cindex Roman font
	6779	@cindex Default font
	6780	selects a @r{roman} font, which is the usual font in which text is
	6781	printed. It may or may not be seriffed.
	6782
	6783	@item @@sansserif
	6784	@findex sansserif @r{(sans serif font)}
	6785	@cindex Sans serif font
	6786	selects a @sansserif{sans serif} font;
	6787
	6788	@item @@slanted
	6789	@findex slanted @r{(slanted font)}
	6790	@cindex Slanted font
	6791	@cindex Oblique font
	6792	selects a @slanted{slanted} font;
	6793
	6794	@item @@t
	6795	@findex t @r{(typewriter font)}
	6796	@cindex Monospace font
	6797	@cindex Fixed-width font
	6798	@cindex Typewriter font
	6799	selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
	6800
	6801	@end table
	6802
	6803	(The commands with longer names were invented much later than the
	6804	others, at which time it did not seem desirable to use very short
	6805	names for such infrequently needed features.)
	6806
	6807	@cindex @code{<lineannotation>} Docbook tag
	6808	The @code{@@r} command can be useful in example-like environments, to
	6809	write comments in the standard roman font instead of the fixed-width
	6810	font. This looks better in printed output, and produces a
	6811	@code{<lineannotation>} tag in Docbook output.
	6812
	6813	For example,
	6814
	6815	@example
	6816	@group
	6817	@@lisp
	6818	(+ 2 2) ; @@r@{Add two plus two.@}
	6819	@@end lisp
	6820	@end group
	6821	@end example
	6822
	6823	@noindent
	6824	produces
	6825
	6826	@lisp
	6827	(+ 2 2) ; @r{Add two plus two.}
	6828	@end lisp
	6829
	6830	The @code{@@t} command can occasionally be useful to produce output in
	6831	a typewriter font where that is supported (e.g., HTML and PDF), but no
	6832	distinction is needed in Info or plain text: @code{@@t@{foo@}}
	6833	produces @t{foo}, cf. @code{@@code@{foo@}} producing @code{foo}.
	6834
	6835	In general, the other font commands are unlikely to be useful; they
	6836	exist primarily to make it possible to document the functionality of
	6837	specific font effects, such as in @TeX{} and related packages.
	6838
	6839
	6840	@node Quotations and Examples
	6841	@chapter Quotations and Examples
	6842
	6843	Quotations and examples are blocks of text consisting of one or more
	6844	whole paragraphs that are set off from the bulk of the text and
	6845	treated differently. They are usually indented in the output.
	6846
	6847	@findex end
	6848	In Texinfo, you always begin a quotation or example by writing an
	6849	@@-command at the beginning of a line by itself, and end it by writing
	6850	an @code{@@end} command that is also at the beginning of a line by
	6851	itself. For instance, you begin an example by writing
	6852	@code{@@example} by itself at the beginning of a line and end the
	6853	example by writing @code{@@end example} on a line by itself, at the
	6854	beginning of that line, and with only one space between the
	6855	@code{@@end} and the @code{example}.
	6856
	6857	@menu
	6858	* Block Enclosing Commands:: Different constructs for different purposes.
	6859	* @code{@@quotation}:: Writing a quotation.
	6860	* @code{@@indentedblock}:: Block of text indented on left.
	6861	* @code{@@example}:: Writing an example in a fixed-width font.
	6862	* @code{@@verbatim}:: Writing a verbatim example.
	6863	* @code{@@lisp}:: Illustrating Lisp code.
	6864	* @code{@@display}:: Writing an example in the current font.
	6865	* @code{@@format}:: Writing an example without narrowed margins.
	6866	* @code{@@exdent}:: Undo indentation on a line.
	6867	* @code{@@flushleft @@flushright}:: Pushing text flush left or flush right.
	6868	* @code{@@raggedright}:: Avoiding justification on the right.
	6869	* @code{@@noindent}:: Preventing paragraph indentation.
	6870	* @code{@@indent}:: Forcing paragraph indentation.
	6871	* @code{@@cartouche}:: Drawing rounded rectangles around text.
	6872	* @code{@@small@dots{}}:: Examples in a smaller font.
	6873	@end menu
	6874
	6875
	6876	@node Block Enclosing Commands
	6877	@section Block Enclosing Commands
	6878
	6879	Here is a summary of commands that enclose blocks of text, also known
	6880	as @dfn{environments}. They're explained further in the following
	6881	sections.
	6882
	6883	@table @code
	6884	@item @@quotation
	6885	Indicate text that is quoted. The text is filled, indented (from both
	6886	margins), and printed in a roman font by default.
	6887
	6888	@item @@indentedblock
	6889	Like @code{@@quotation}, but the text is indented only on the left.
	6890
	6891	@item @@example
	6892	Illustrate code, commands, and the like. The text is printed
	6893	in a fixed-width font, and indented but not filled.
	6894
	6895	@item @@lisp
	6896	Like @code{@@example}, but specifically for illustrating Lisp code. The
	6897	text is printed in a fixed-width font, and indented but not filled.
	6898
	6899	@item @@verbatim
	6900	Mark a piece of text that is to be printed verbatim; no character
	6901	substitutions are made and all commands are ignored, until the next
	6902	@code{@@end verbatim}. The text is printed in a fixed-width font,
	6903	and not indented or filled. Extra spaces and blank lines are
	6904	significant, and tabs are expanded.
	6905
	6906	@item @@display
	6907	Display illustrative text. The text is indented but not filled, and
	6908	no font is selected (so, by default, the font is roman).
	6909
	6910	@item @@format
	6911	Like @code{@@display} (the text is not filled and no font is
	6912	selected), but the text is not indented.
	6913
	6914	@item @@smallquotation
	6915	@itemx @@smallindentedblock
	6916	@itemx @@smallexample
	6917	@itemx @@smalllisp
	6918	@itemx @@smalldisplay
	6919	@itemx @@smallformat
	6920	These @code{@@small...} commands are just like their non-small
	6921	counterparts, except that they output text in a smaller font size,
	6922	where possible.
	6923
	6924	@item @@flushleft
	6925	@itemx @@flushright
	6926	Text is not filled, but is set flush with the left or right margin,
	6927	respectively.
	6928
	6929	@item @@raggedright
	6930	Text is filled, but only justified on the left, leaving the right
	6931	margin ragged.
	6932
	6933	@item @@cartouche
	6934	Highlight text, often an example or quotation, by drawing a box with
	6935	rounded corners around it.
	6936	@end table
	6937
	6938	The @code{@@exdent} command is used within the above constructs to
	6939	undo the indentation of a line.
	6940
	6941	The @code{@@noindent} command may be used after one of the above
	6942	constructs (or at the beginning of any paragraph) to prevent the
	6943	following text from being indented as a new paragraph.
	6944
	6945
	6946	@node @code{@@quotation}
	6947	@section @code{@@quotation}: Block Quotations
	6948	@anchor{quotation}@c old name
	6949
	6950	@cindex Quotations
	6951	@findex quotation
	6952
	6953	The text of a quotation is processed like normal text (regular font,
	6954	text is filled) except that:
	6955
	6956	@itemize @bullet
	6957	@item
	6958	both the left and right margins are closer to the center of the page,
	6959	so the whole of the quotation is indented;
	6960
	6961	@item
	6962	the first lines of paragraphs are indented no more than other lines; and
	6963
	6964	@item
	6965	an @code{@@author} command may be given to specify the author of the
	6966	quotation.
	6967	@end itemize
	6968
	6969	@quotation
	6970	This is an example of text written between a @code{@@quotation}
	6971	command and an @code{@@end quotation} command. A @code{@@quotation}
	6972	command is most often used to indicate text that is excerpted from
	6973	another (real or hypothetical) printed work.
	6974	@end quotation
	6975
	6976	Write a @code{@@quotation} command as text on a line by itself. This
	6977	line will disappear from the output. Mark the end of the quotation
	6978	with a line beginning with and containing only @code{@@end quotation}.
	6979	The @code{@@end quotation} line will likewise disappear from the
	6980	output.
	6981
	6982	@code{@@quotation} takes one optional argument, given on the remainder
	6983	of the line. This text, if present, is included at the beginning of
	6984	the quotation in bold or otherwise emphasized, and followed with a
	6985	@samp{:}. For example:
	6986
	6987	@example
	6988	@@quotation Note
	6989	This is
	6990	a foo.
	6991	@@end quotation
	6992	@end example
	6993
	6994	@noindent
	6995	produces
	6996
	6997	@quotation Note
	6998	This is
	6999	a foo.
	7000	@end quotation
	7001
	7002	If the @code{@@quotation} argument is one of these English words
	7003	(case-insensitive):
	7004
	7005	@example
	7006	Caution Important Note Tip Warning
	7007	@end example
	7008
	7009	@cindex @code{<caution>} Docbook tag
	7010	@cindex @code{<important>} Docbook tag
	7011	@cindex @code{<note>} Docbook tag
	7012	@cindex @code{<tip>} Docbook tag
	7013	@cindex @code{<warning>} Docbook tag
	7014	@cindex @code{<blockquote>} HTML tag
	7015	@noindent then the Docbook output uses corresponding special tags
	7016	(@code{<note>}, etc.)@: instead of the default @code{<blockquote>}.
	7017	HTML output always uses @code{<blockquote>}.
	7018
	7019	If the author of the quotation is specified in the @code{@@quotation}
	7020	block with the @code{@@author} command, a line with the author name is
	7021	displayed after the quotation:
	7022
	7023	@example
	7024	@@quotation
	7025	People sometimes ask me if it is a sin in the Church of Emacs to use
	7026	vi. Using a free version of vi is not a sin; it is a penance. So happy
	7027	hacking.
	7028
	7029	@@author Richard Stallman
	7030	@@end quotation
	7031	@end example
	7032
	7033	@noindent
	7034	produces
	7035
	7036	@quotation
	7037	People sometimes ask me if it is a sin in the Church of Emacs to use
	7038	vi. Using a free version of vi is not a sin; it is a penance. So happy
	7039	hacking.
	7040
	7041	@author Richard Stallman
	7042	@end quotation
	7043
	7044	@findex smallquotation
	7045	Texinfo also provides a command @code{@@smallquotation}, which is just
	7046	like @code{@@quotation} but uses a smaller font size where possible.
	7047	@xref{@code{@@small@dots{}}}.
	7048
	7049
	7050	@node @code{@@indentedblock}
	7051	@section @code{@@indentedblock}: Indented text blocks
	7052	@cindex Indented text block
	7053	@findex indentedblock
	7054
	7055	The @code{@@indentedblock} environment is similar to
	7056	@code{@@quotation}, except that text is only indented on the left (and
	7057	there is no optional argument for an author). Thus, the text font
	7058	remains unchanged, and text is gathered and filled as usual, but the
	7059	left margin is increased. For example:
	7060
	7061	@indentedblock
	7062	This is an example of text written between an @code{@@indentedblock}
	7063	command and an @code{@@end indentedblock} command. The
	7064	@code{@@indentedblock} environment can contain any text or other
	7065	commands desired.
	7066	@end indentedblock
	7067
	7068	This is written in the Texinfo source as:
	7069
	7070	@example
	7071	@@indentedblock
	7072	This is an example ...
	7073	@@end indentedblock
	7074	@end example
	7075
	7076	@findex smallindentedblock
	7077	Texinfo also provides a command @code{@@smallindentedblock}, which is
	7078	just like @code{@@indentedblock} but uses a smaller font size where
	7079	possible. @xref{@code{@@small@dots{}}}.
	7080
	7081
	7082	@node @code{@@example}
	7083	@section @code{@@example}: Example Text
	7084
	7085	@anchor{example}@c old name
	7086	@findex example
	7087	@cindex Examples, formatting them
	7088	@cindex Formatting examples
	7089
	7090	The @code{@@example} environment is used to indicate an example that
	7091	is not part of the running text, such as computer input or output.
	7092	Write an @code{@@example} command at the beginning of a line by
	7093	itself. Mark the end of the example with an @code{@@end example}
	7094	command, also written at the beginning of a line by itself.
	7095
	7096	An @code{@@example} environment has the following characteristics:
	7097
	7098	@itemize
	7099	@item Each line in the input file is a line in the output; that is,
	7100	the source text is not filled as it normally is.
	7101	@item Extra spaces and blank lines are significant.
	7102	@item The output is indented.
	7103	@item The output uses a fixed-width font.
	7104	@item Texinfo commands @emph{are} expanded; if you want the output to
	7105	be the input verbatim, use the @code{@@verbatim} environment instead
	7106	(@pxref{@code{@@verbatim}}).
	7107	@end itemize
	7108
	7109	For example,
	7110
	7111	@example
	7112	@@example
	7113	cp foo @@var@{dest1@}; \
	7114	cp foo @@var@{dest2@}
	7115	@@end example
	7116	@end example
	7117
	7118	@noindent
	7119	produces
	7120
	7121	@example
	7122	cp foo @var{dest1}; \
	7123	cp foo @var{dest2}
	7124	@end example
	7125
	7126	The lines containing @code{@@example} and @code{@@end example} will
	7127	disappear from the output. To make the output look good, you should
	7128	put a blank line before the @code{@@example} and another blank line
	7129	after the @code{@@end example}. Blank lines inside the beginning
	7130	@code{@@example} and the ending @code{@@end example}, on the other
	7131	hand, do appear in the output.
	7132
	7133	@quotation Caution
	7134	Do not use tabs in the lines of an example! (Or anywhere else in
	7135	Texinfo, except in verbatim environments.) @TeX{} treats tabs as
	7136	single spaces, and that is not what they look like. In Emacs, you can
	7137	use @kbd{M-x untabify} to convert tabs in a region to multiple spaces.
	7138	@end quotation
	7139
	7140	Examples are often, logically speaking, ``in the middle'' of a
	7141	paragraph, and the text that continues afterwards should not be
	7142	indented, as in the example above. The @code{@@noindent} command
	7143	prevents a piece of text from being indented as if it were a new
	7144	paragraph (@pxref{@code{@@noindent}}).
	7145
	7146	If you want to embed code fragments within sentences, instead of
	7147	displaying them, use the @code{@@code} command or its relatives
	7148	(@pxref{@code{@@code}}).
	7149
	7150	If you wish to write a ``comment'' on a line of an example in the
	7151	normal roman font, you can use the @code{@@r} command (@pxref{Fonts}).
	7152
	7153
	7154	@node @code{@@verbatim}
	7155	@section @code{@@verbatim}: Literal Text
	7156
	7157	@anchor{verbatim}@c old name
	7158	@findex verbatim
	7159	@cindex Verbatim environment
	7160
	7161	Use the @code{@@verbatim} environment for printing of text that may
	7162	contain special characters or commands that should not be interpreted,
	7163	such as computer input or output (@code{@@example} interprets its text
	7164	as regular Texinfo commands). This is especially useful for including automatically
	7165	generated files in a Texinfo manual.
	7166
	7167	In general, the output will be just the same as the input. No
	7168	character substitutions are made, e.g., all spaces and blank lines are
	7169	significant, including tabs. In the printed manual, the text is
	7170	typeset in a fixed-width font, and not indented or filled.
	7171
	7172	Write a @code{@@verbatim} command at the beginning of a line by
	7173	itself. This line will disappear from the output. Mark the end of
	7174	the verbatim block with an @code{@@end verbatim} command, also written
	7175	at the beginning of a line by itself. The @code{@@end verbatim} will
	7176	also disappear from the output.
	7177
	7178	For example:
	7179	@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
	7180
	7181	@example
	7182	@exdent @t{@@verbatim}
	7183	@exdent @t{@{}
	7184	@exdent @key{TAB}@t{@@command with strange characters: @@'e}
	7185	@exdent @t{expand@key{TAB}me}
	7186	@exdent @t{@}}
	7187	@exdent @t{@@end verbatim}
	7188	@end example
	7189
	7190	@noindent
	7191	This produces:
	7192
	7193	@verbatim
	7194	{
	7195	@command with strange characters: @'e
	7196	expand me
	7197	}
	7198	@end verbatim
	7199
	7200	Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
	7201	produce no output, typically you should put a blank line before the
	7202	@code{@@verbatim} and another blank line after the @code{@@end
	7203	verbatim}. Blank lines between the beginning @code{@@verbatim} and
	7204	the ending @code{@@end verbatim} will appear in the output.
	7205
	7206	@cindex Verbatim, small
	7207	@cindex Small verbatim
	7208	You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
	7209	an @code{@@smallformat} environment, as shown here:
	7210
	7211	@c more cheating ...
	7212	@smallexample
	7213	@exdent @t{@@smallformat}
	7214	@exdent @t{@@verbatim}
	7215	@exdent @t{... still verbatim, but in a smaller font ...}
	7216	@exdent @t{@@end verbatim}
	7217	@exdent @t{@@end smallformat}
	7218	@end smallexample
	7219
	7220	Finally, a word of warning: it is not reliable to use
	7221	@code{@@verbatim} inside other Texinfo constructs.
	7222
	7223	See also @ref{@code{@@verbatiminclude}}.
	7224
	7225
	7226	@node @code{@@lisp}
	7227	@section @code{@@lisp}: Marking a Lisp Example
	7228
	7229	@anchor{lisp}@c old name
	7230	@findex lisp
	7231	@cindex Lisp example
	7232
	7233	The @code{@@lisp} command is used for Lisp code. It is synonymous
	7234	with the @code{@@example} command.
	7235
	7236	@lisp
	7237	This is an example of text written between an
	7238	@code{@@lisp} command and an @code{@@end lisp} command.
	7239	@end lisp
	7240
	7241	Use @code{@@lisp} instead of @code{@@example} to preserve information
	7242	regarding the nature of the example. This is useful, for example, if
	7243	you write a function that evaluates only and all the Lisp code in a
	7244	Texinfo file. Then you can use the Texinfo file as a Lisp
	7245	library. Mark the end of @code{@@lisp} with @code{@@end lisp} on a line
	7246	by itself.
	7247
	7248
	7249	@node @code{@@display}
	7250	@section @code{@@display}: Examples Using the Text Font
	7251
	7252	@anchor{display}@c old name
	7253	@findex display
	7254	@cindex Display formatting
	7255
	7256	The @code{@@display} command begins another kind of environment, where
	7257	the font is left unchanged, not switched to typewriter as with
	7258	@code{@@example}. Each line of input still produces a line of output,
	7259	and the output is still indented.
	7260
	7261	@display
	7262	This is an example of text written between a @code{@@display} command
	7263	and an @code{@@end display} command. The @code{@@display} command
	7264	indents the text, but does not fill it.
	7265	@end display
	7266
	7267	@findex smalldisplay
	7268	Texinfo also provides the environment @code{@@smalldisplay}, which is
	7269	like @code{@@display} but uses a smaller font size.
	7270	@xref{@code{@@small@dots{}}}.
	7271
	7272
	7273	@node @code{@@format}
	7274	@section @code{@@format}: Examples Using the Full Line Width
	7275
	7276	@anchor{format}@c old name
	7277	@findex format
	7278
	7279	The @code{@@format} command is similar to @code{@@display}, except it
	7280	leaves the text unindented. Like @code{@@display}, it does not select
	7281	the fixed-width font.
	7282
	7283	@format
	7284	This is an example of text written between a @code{@@format} command
	7285	and an @code{@@end format} command. As you can see
	7286	from this example,
	7287	the @code{@@format} command does not fill the text.
	7288	@end format
	7289
	7290	@findex smallformat
	7291	Texinfo also provides the environment @code{@@smallformat}, which is
	7292	like @code{@@format} but uses a smaller font size.
	7293	@xref{@code{@@small@dots{}}}.
	7294
	7295
	7296	@node @code{@@exdent}
	7297	@section @code{@@exdent}: Undoing a Line's Indentation
	7298
	7299	@anchor{exdent}@c old name
	7300	@findex exdent
	7301	@cindex Indentation undoing
	7302
	7303	The @code{@@exdent} command removes any indentation a line might have.
	7304	The command is written at the beginning of a line and applies only to
	7305	the text that follows the command that is on the same line. Do not use
	7306	braces around the text. In a printed manual, the text on an
	7307	@code{@@exdent} line is printed in the roman font.
	7308
	7309	@code{@@exdent} is usually used within examples. Thus,
	7310
	7311	@example
	7312	@group
	7313	@@example
	7314	This line follows an @@@@example command.
	7315	@@exdent This line is exdented.
	7316	This line follows the exdented line.
	7317	The @@@@end example comes on the next line.
	7318	@@end example
	7319	@end group
	7320	@end example
	7321
	7322	@noindent
	7323	produces
	7324
	7325	@example
	7326	@group
	7327	This line follows an @@example command.
	7328	@exdent This line is exdented.
	7329	This line follows the exdented line.
	7330	The @@end example comes on the next line.
	7331	@end group
	7332	@end example
	7333
	7334	In practice, the @code{@@exdent} command is rarely used. Usually, you
	7335	un-indent text by ending the example and returning the page to its
	7336	normal width.
	7337
	7338	@code{@@exdent} has no effect in HTML output.
	7339
	7340
	7341	@node @code{@@flushleft @@flushright}
	7342	@section @code{@@flushleft} and @code{@@flushright}
	7343
	7344	@anchor{flushleft & flushright}@c old name
	7345	@findex flushleft
	7346	@findex flushright
	7347	@cindex Ragged right, without filling
	7348	@cindex Ragged left, without filling
	7349
	7350	The @code{@@flushleft} and @code{@@flushright} commands line up the
	7351	ends of lines on the left and right margins of a page,
	7352	but do not fill the text. The commands are written on lines of their
	7353	own, without braces. The @code{@@flushleft} and @code{@@flushright}
	7354	commands are ended by @code{@@end flushleft} and @code{@@end
	7355	flushright} commands on lines of their own.
	7356
	7357	@need 1500
	7358	For example,
	7359
	7360	@example
	7361	@group
	7362	@@flushleft
	7363	This text is
	7364	written flushleft.
	7365	@@end flushleft
	7366	@end group
	7367	@end example
	7368
	7369	@noindent
	7370	produces
	7371
	7372	@quotation
	7373	@flushleft
	7374	This text is
	7375	written flushleft.
	7376	@end flushleft
	7377	@end quotation
	7378
	7379
	7380	@code{@@flushright} produces the type of indentation often used in the
	7381	return address of letters. For example,
	7382
	7383	@example
	7384	@group
	7385	@@flushright
	7386	Here is an example of text written
	7387	flushright. The @@code@{@@flushright@} command
	7388	right justifies every line but leaves the
	7389	left end ragged.
	7390	@@end flushright
	7391	@end group
	7392	@end example
	7393
	7394	@noindent
	7395	produces
	7396
	7397	@flushright
	7398	Here is an example of text written
	7399	flushright. The @code{@@flushright} command
	7400	right justifies every line but leaves the
	7401	left end ragged.
	7402	@end flushright
	7403
	7404
	7405	@node @code{@@raggedright}
	7406	@section @code{@@raggedright}: Ragged Right Text
	7407
	7408	@anchor{raggedright}@c old name
	7409	@findex raggedright
	7410	@cindex Ragged right, with filling
	7411
	7412	The @code{@@raggedright} fills text as usual, but the text is only
	7413	justified on the left; the right margin is ragged. The command is
	7414	written on a line of its own, without braces. The
	7415	@code{@@raggedright} command is ended by @code{@@end raggedright} on a
	7416	line of its own. This command has no effect in Info and HTML output,
	7417	where text is always set ragged right.
	7418
	7419	The @code{@@raggedright} command can be useful with paragraphs
	7420	containing lists of commands with long names, when it is known in
	7421	advance that justifying the text on both margins will make the
	7422	paragraph look bad.
	7423
	7424	An example (from elsewhere in this manual):
	7425
	7426	@example
	7427	@group
	7428	@@raggedright
	7429	Commands for double and single angle quotation marks:
	7430	@@code@{@@@@guillemetleft@@@{@@@}@}, @@code@{@@@@guillemetright@@@{@@@}@},
	7431	@@code@{@@@@guillemotleft@@@{@@@}@}, @@code@{@@@@guillemotright@@@{@@@}@},
	7432	@@code@{@@@@guilsinglleft@@@{@@@}@}, @@code@{@@@@guilsinglright@@@{@@@}@}.
	7433	@@end raggedright
	7434	@end group
	7435	@end example
	7436
	7437	@noindent
	7438	produces
	7439
	7440	@raggedright
	7441	Commands for double and single angle quotation marks:
	7442	@code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}},
	7443	@code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}},
	7444	@code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}.
	7445	@end raggedright
	7446
	7447
	7448	@node @code{@@noindent}
	7449	@section @code{@@noindent}: Omitting Indentation
	7450
	7451	@anchor{noindent}@c old name
	7452	@findex noindent
	7453	@cindex Omitting indentation
	7454	@cindex Suppressing indentation
	7455	@cindex Indentation, omitting
	7456
	7457	An example or other inclusion can break a paragraph into segments.
	7458	Ordinarily, the formatters indent text that follows an example as a new
	7459	paragraph. You can prevent this on a case-by-case basis by writing
	7460	@code{@@noindent} at the beginning of a line, preceding the continuation
	7461	text. You can also disable indentation for all paragraphs globally with
	7462	@code{@@paragraphindent} (@pxref{@code{@@paragraphindent}}).
	7463
	7464	Here is an example showing how to eliminate the normal indentation of
	7465	the text after an @code{@@example}, a common situation:
	7466
	7467	@example
	7468	@group
	7469	@@example
	7470	This is an example
	7471	@@end example
	7472
	7473	@@noindent
	7474	This line is not indented. As you can see, the
	7475	beginning of the line is fully flush left with the
	7476	line that follows after it.
	7477	@end group
	7478	@end example
	7479
	7480	@noindent produces:
	7481
	7482	@display
	7483	@example
	7484	This is an example
	7485	@end example
	7486
	7487	@noindent
	7488	This line is not indented. As you can see, the
	7489	beginning of the line is fully flush left with the
	7490	line that follows after it.
	7491	@end display
	7492
	7493	The standard usage of @code{@@noindent} is just as above: at the
	7494	beginning of what would otherwise be a paragraph, to eliminate the
	7495	indentation that normally happens there. It can either be followed by
	7496	text or be on a line by itself. There is no reason to use it
	7497	in other contexts, such as in the middle of a paragraph or inside an
	7498	environment (@pxref{Quotations and Examples}).
	7499
	7500	You can control the number of blank lines in the Info file output by
	7501	adjusting the input as desired: a line containing just
	7502	@code{@@noindent} does not generate a blank line, and neither does an
	7503	@code{@@end} line for an environment.
	7504
	7505	Do not put braces after a @code{@@noindent} command; they are not
	7506	used, since @code{@@noindent} is a command used outside of paragraphs
	7507	(@pxref{Command Syntax}).
	7508
	7509
	7510	@node @code{@@indent}
	7511	@section @code{@@indent}: Forcing Indentation
	7512
	7513	@anchor{indent}@c old name
	7514	@findex indent
	7515	@cindex Forcing indentation
	7516	@cindex Inserting indentation
	7517	@cindex Indentation, forcing
	7518
	7519	@indent
	7520	To complement the @code{@@noindent} command (see the previous
	7521	section), Texinfo provides the @code{@@indent} command to force a
	7522	paragraph to be indented. For instance, this paragraph (the first in
	7523	this section) is indented using an @code{@@indent} command.
	7524
	7525	And indeed, the first paragraph of a section is the most likely place
	7526	to use @code{@@indent}, to override the normal behavior of no
	7527	indentation there (@pxref{@code{@@paragraphindent}}). It can either be
	7528	followed by text or be on a line by itself.
	7529
	7530	As a special case, when @code{@@indent} is used in an environment
	7531	where text is not filled, it produces a paragraph indentation space in
	7532	the @TeX{} output. (These environments are where a line of input
	7533	produces a line of output, such as @code{@@example} and
	7534	@code{@@display}; for a summary of all environments, @pxref{Block
	7535	Enclosing Commands}.)
	7536
	7537	Do not put braces after an @code{@@indent} command; they are not used,
	7538	since @code{@@indent} is a command used outside of paragraphs
	7539	(@pxref{Command Syntax}).
	7540
	7541
	7542	@node @code{@@cartouche}
	7543	@section @code{@@cartouche}: Rounded Rectangles
	7544
	7545	@anchor{cartouche}@c old name
	7546	@findex cartouche
	7547	@cindex Box with rounded corners
	7548	@cindex Rounded rectangles, around text
	7549
	7550	In a printed manual, the @code{@@cartouche} command draws a box with
	7551	rounded corners around its contents. In HTML, a normal rectangle is
	7552	drawn. @code{@@cartouche} has no effect in Info output.
	7553
	7554	You can use this command to further highlight an example or quotation.
	7555	For instance, you could write a manual in which one type of example is
	7556	surrounded by a cartouche for emphasis.
	7557
	7558	For example,
	7559
	7560	@example
	7561	@@cartouche
	7562	@@example
	7563	% pwd
	7564	/usr/local/share/emacs
	7565	@@end example
	7566	@@end cartouche
	7567	@end example
	7568
	7569	@noindent
	7570	surrounds the two-line example with a box with rounded corners, in the
	7571	printed manual.
	7572
	7573	The output from the example looks like this (if you're reading this in
	7574	Info, you'll see the @code{@@cartouche} had no effect):
	7575
	7576	@cartouche
	7577	@example
	7578	% pwd
	7579	/usr/local/share/emacs
	7580	@end example
	7581	@end cartouche
	7582
	7583	@code{@@cartouche} also implies @code{@@group} (@pxref{@code{@@group}}).
	7584
	7585	@node @code{@@small@dots{}}
	7586	@section @code{@@small@dots{}} Block Commands
	7587
	7588	@anchor{small}@c old name
	7589	@findex smallexample
	7590	@findex smallformat
	7591	@findex smalllisp
	7592	@findex smallquotation
	7593	@cindex Small examples
	7594	@cindex Examples in smaller fonts
	7595	@cindex Quotations in smaller fonts
	7596	@cindex Lisp examples in smaller fonts
	7597
	7598	In addition to the regular @code{@@example} and similar commands,
	7599	Texinfo has ``small'' example-style commands. These are
	7600	@code{@@smallquotation}, @code{@@smallindentedblock},
	7601	@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat},
	7602	and @code{@@smalllisp}.
	7603
	7604	In Info and HTML output, the @code{@@small@dots{}} commands are
	7605	equivalent to their non-small companion commands.
	7606
	7607	In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in
	7608	a smaller font than the non-small example commands. Thus, for
	7609	instance, code examples can contain longer lines and still fit on a
	7610	page without needing to be rewritten.
	7611
	7612	A smaller font size is also retained in the Texinfo@tie{}XML transliteration.
	7613
	7614	Mark the end of a @code{@@small@dots{}} block with a corresponding
	7615	@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
	7616	@code{@@end smallexample}.
	7617
	7618	Here is an example of the font used by the @code{@@smallexample}
	7619	command (in Info, the output will be the same as usual):
	7620
	7621	@smallexample
	7622	@dots{} to make sure that you have the freedom to
	7623	distribute copies of free software (and charge for
	7624	this service if you wish), that you receive source
	7625	code or can get it if you want it, that you can
	7626	change the software or use pieces of it in new free
	7627	programs; and that you know you can do these things.
	7628	@end smallexample
	7629
	7630	The @code{@@small@dots{}} commands use the same font style as their
	7631	normal counterparts: @code{@@smallexample} and @code{@@smalllisp} use
	7632	a fixed-width font, and everything else uses the regular font.
	7633	They also have the same behavior in other respects---whether filling
	7634	is done and whether margins are narrowed.
	7635
	7636	As a general rule, a printed document looks better if you use only one
	7637	of (for instance) @code{@@example} or @code{@@smallexample}
	7638	consistently within a chapter.
	7639
	7640
	7641
	7642
	7643	@node Lists and Tables
	7644	@chapter Lists and Tables
	7645	@cindex Making lists and tables
	7646	@cindex Lists and tables, making
	7647	@cindex Tables and lists, making
	7648
	7649	Texinfo has several ways of making lists and tables. Lists can be
	7650	bulleted or numbered; two-column tables can highlight the items in
	7651	the first column; multi-column tables are also supported.
	7652
	7653	@menu
	7654	* Introducing Lists:: Texinfo formats lists for you.
	7655	* @code{@@itemize}:: How to construct a simple list.
	7656	* @code{@@enumerate}:: How to construct a numbered list.
	7657	* Two-column Tables:: How to construct a two-column table.
	7658	* Multi-column Tables:: How to construct generalized tables.
	7659	@end menu
	7660
	7661	@node Introducing Lists
	7662	@section Introducing Lists
	7663
	7664	Texinfo automatically indents the text in lists or tables, and numbers
	7665	an enumerated list. This last feature is useful if you modify the
	7666	list, since you do not need to renumber it yourself.
	7667
	7668	Numbered lists and tables begin with the appropriate @@-command at the
	7669	beginning of a line, and end with the corresponding @code{@@end}
	7670	command on a line by itself. The table and itemized-list commands
	7671	also require that you write formatting information on the same line as
	7672	the beginning @@-command.
	7673
	7674	Begin an enumerated list, for example, with an @code{@@enumerate}
	7675	command and end the list with an @code{@@end enumerate} command.
	7676	Begin an itemized list with an @code{@@itemize} command, followed on
	7677	the same line by a formatting command such as @code{@@bullet}, and end
	7678	the list with an @code{@@end itemize} command.
	7679	@findex end
	7680
	7681	Precede each element of a list with an @code{@@item} or @code{@@itemx}
	7682	command.
	7683
	7684	@sp 1
	7685	@noindent
	7686	Here is an itemized list of the different kinds of table and lists:
	7687
	7688	@itemize @bullet
	7689	@item
	7690	Itemized lists with and without bullets.
	7691
	7692	@item
	7693	Enumerated lists, using numbers or letters.
	7694
	7695	@item
	7696	Two-column tables with highlighting.
	7697	@end itemize
	7698
	7699	@sp 1
	7700	@noindent
	7701	Here is an enumerated list with the same items:
	7702
	7703	@enumerate
	7704	@item
	7705	Itemized lists with and without bullets.
	7706
	7707	@item
	7708	Enumerated lists, using numbers or letters.
	7709
	7710	@item
	7711	Two-column tables with highlighting.
	7712	@end enumerate
	7713
	7714	@sp 1
	7715	@noindent
	7716	And here is a two-column table with the same items and their
	7717	@w{@@-commands}:
	7718
	7719	@table @code
	7720	@item @@itemize
	7721	Itemized lists with and without bullets.
	7722
	7723	@item @@enumerate
	7724	Enumerated lists, using numbers or letters.
	7725
	7726	@item @@table
	7727	@itemx @@ftable
	7728	@itemx @@vtable
	7729	Two-column tables, optionally with indexing.
	7730	@end table
	7731
	7732
	7733	@node @code{@@itemize}
	7734	@section @code{@@itemize}: Making an Itemized List
	7735
	7736	@anchor{itemize}@c old name
	7737	@findex itemize
	7738	@cindex Itemization
	7739
	7740	The @code{@@itemize} command produces a sequence of ``items'', each
	7741	starting with a bullet or other mark inside the left margin, and
	7742	generally indented.
	7743
	7744	@cindex @code{@@w}, for blank items
	7745	Begin an itemized list by writing @code{@@itemize} at the beginning of
	7746	a line. Follow the command, on the same line, with a character or a
	7747	Texinfo command that generates a mark. Usually, you will use
	7748	@code{@@bullet} after @code{@@itemize}, but you can use
	7749	@code{@@minus}, or any command or character that results in a single
	7750	character in the Info file. (When you write the mark command such as
	7751	@code{@@bullet} after an @code{@@itemize} command, you may omit the
	7752	@samp{@{@}}.) If you don't specify a mark command, the default is
	7753	@code{@@bullet}. If you don't want any mark at all, but still want
	7754	logical items, use @code{@@w@{@}} (in this case the braces are
	7755	required).
	7756
	7757	@findex item
	7758	After the @code{@@itemize}, write your items, each starting with
	7759	@code{@@item}. Text can follow on the same line as the @code{@@item}.
	7760	The text of an item can continue for more than one paragraph.
	7761
	7762	There should be at least one @code{@@item} inside the @code{@@itemize}
	7763	environment. If none are present, @code{makeinfo} gives a warning.
	7764	If you just want indented text and not a list of items, use
	7765	@code{@@indentedblock}; @pxref{@code{@@indentedblock}}.
	7766
	7767	Index entries and comments that are given before an @code{@@item}
	7768	including the first, are automatically moved (internally) to after the
	7769	@code{@@item}, so the output is as expected. Historically this has
	7770	been a common practice.
	7771
	7772	Usually, you should put a blank line between items. This puts a blank
	7773	line in the Info file. (@TeX{} inserts the proper vertical space in
	7774	any case.) Except when the entries are very brief, these blank lines
	7775	make the list look better.
	7776
	7777	Here is an example of the use of @code{@@itemize}, followed by the
	7778	output it produces. @code{@@bullet} produces an @samp{*} in Info and
	7779	a round dot in other output formats.
	7780
	7781	@example
	7782	@group
	7783	@@itemize @@bullet
	7784	@@item
	7785	Some text for foo.
	7786
	7787	@@item
	7788	Some text
	7789	for bar.
	7790	@@end itemize
	7791	@end group
	7792	@end example
	7793
	7794	@noindent
	7795	This produces:
	7796
	7797	@quotation
	7798	@itemize @bullet
	7799	@item
	7800	Some text for foo.
	7801
	7802	@item
	7803	Some text
	7804	for bar.
	7805	@end itemize
	7806	@end quotation
	7807
	7808	Itemized lists may be embedded within other itemized lists. Here is a
	7809	list marked with dashes embedded in a list marked with bullets:
	7810
	7811	@example
	7812	@group
	7813	@@itemize @@bullet
	7814	@@item
	7815	First item.
	7816
	7817	@@itemize @@minus
	7818	@@item
	7819	Inner item.
	7820
	7821	@@item
	7822	Second inner item.
	7823	@@end itemize
	7824
	7825	@@item
	7826	Second outer item.
	7827	@@end itemize
	7828	@end group
	7829	@end example
	7830
	7831	@noindent
	7832	This produces:
	7833
	7834	@quotation
	7835	@itemize @bullet
	7836	@item
	7837	First item.
	7838
	7839	@itemize @minus
	7840	@item
	7841	Inner item.
	7842
	7843	@item
	7844	Second inner item.
	7845	@end itemize
	7846
	7847	@item
	7848	Second outer item.
	7849	@end itemize
	7850	@end quotation
	7851
	7852
	7853	@node @code{@@enumerate}
	7854	@section @code{@@enumerate}: Making a Numbered or Lettered List
	7855
	7856	@anchor{enumerate}@c old name
	7857	@findex enumerate
	7858	@cindex Enumeration
	7859
	7860	@code{@@enumerate} is like @code{@@itemize} (@pxref{@code{@@itemize}}),
	7861	except that the labels on the items are successive integers or letters
	7862	instead of bullets.
	7863
	7864	Write the @code{@@enumerate} command at the beginning of a line. The
	7865	command does not require an argument, but accepts either a number or a
	7866	letter as an option. Without an argument, @code{@@enumerate} starts the
	7867	list with the number @samp{1}. With a numeric argument, such as
	7868	@samp{3}, the command starts the list with that number. With an upper-
	7869	or lowercase letter, such as @samp{a} or @samp{A}, the command starts
	7870	the list with that letter.
	7871
	7872	Write the text of the enumerated list in the same way as an itemized
	7873	list: write a line starting with @code{@@item} at the beginning of
	7874	each item in the enumeration. It is ok to have text following the
	7875	@code{@@item}, and the text for an item can continue for several
	7876	paragraphs.
	7877
	7878	You should put a blank line between entries in the list.
	7879	This generally makes it easier to read the Info file.
	7880
	7881	@need 1500
	7882	Here is an example of @code{@@enumerate} without an argument:
	7883
	7884	@example
	7885	@group
	7886	@@enumerate
	7887	@@item
	7888	Underlying causes.
	7889
	7890	@@item
	7891	Proximate causes.
	7892	@@end enumerate
	7893	@end group
	7894	@end example
	7895
	7896	@noindent
	7897	This produces:
	7898
	7899	@enumerate
	7900	@item
	7901	Underlying causes.
	7902
	7903	@item
	7904	Proximate causes.
	7905	@end enumerate
	7906	@sp 1
	7907	Here is an example with an argument of @kbd{3}:
	7908	@sp 1
	7909	@example
	7910	@group
	7911	@@enumerate 3
	7912	@@item
	7913	Predisposing causes.
	7914
	7915	@@item
	7916	Precipitating causes.
	7917
	7918	@@item
	7919	Perpetuating causes.
	7920	@@end enumerate
	7921	@end group
	7922	@end example
	7923
	7924	@noindent
	7925	This produces:
	7926
	7927	@enumerate 3
	7928	@item
	7929	Predisposing causes.
	7930
	7931	@item
	7932	Precipitating causes.
	7933
	7934	@item
	7935	Perpetuating causes.
	7936	@end enumerate
	7937	@sp 1
	7938	Here is a brief summary of the alternatives. The summary is constructed
	7939	using @code{@@enumerate} with an argument of @kbd{a}.
	7940	@sp 1
	7941	@enumerate a
	7942	@item
	7943	@code{@@enumerate}
	7944
	7945	Without an argument, produce a numbered list, with the first item
	7946	numbered@tie{}1.
	7947
	7948	@item
	7949	@code{@@enumerate @var{unsigned-integer}}
	7950
	7951	With an (unsigned) numeric argument, start a numbered list with that
	7952	number. You can use this to continue a list that you interrupted with
	7953	other text.
	7954
	7955	@item
	7956	@code{@@enumerate @var{upper-case-letter}}
	7957
	7958	With an uppercase letter as argument, start a list
	7959	in which each item is marked
	7960	by a letter, beginning with that uppercase letter.
	7961
	7962	@item
	7963	@code{@@enumerate @var{lower-case-letter}}
	7964
	7965	With a lowercase letter as argument, start a list
	7966	in which each item is marked by
	7967	a letter, beginning with that lowercase letter.
	7968	@end enumerate
	7969
	7970	You can also nest enumerated lists, as in an outline.
	7971
	7972
	7973	@node Two-column Tables
	7974	@section Making a Two-column Table
	7975
	7976	@cindex Tables, making two-column
	7977	@findex table
	7978
	7979	@code{@@table} is similar to @code{@@itemize}
	7980	(@pxref{@code{@@itemize}}), but allows you to specify a name or
	7981	heading line for each item. The @code{@@table} command is used to
	7982	produce two-column tables, and is especially useful for glossaries,
	7983	explanatory exhibits, and command-line option summaries.
	7984
	7985	@menu
	7986	* @code{@@table}:: How to construct a two-column table.
	7987	* @code{@@ftable @@vtable}:: Automatic indexing for two-column tables.
	7988	* @code{@@itemx}:: How to put more entries in the first column.
	7989	@end menu
	7990
	7991	@node @code{@@table}
	7992	@subsection Using the @code{@@table} Command
	7993
	7994	@anchor{table}@c old name
	7995
	7996	@cindex Definition lists, typesetting
	7997	Use the @code{@@table} command to produce a two-column table. This
	7998	command is typically used when you have a list of items and a brief text
	7999	with each one, such as a list of definitions.
	8000
	8001	Write the @code{@@table} command at the beginning of a line, after a
	8002	blank line, and follow it on the same line with an argument that is an
	8003	`indicating' command, such as @code{@@code}, @code{@@samp},
	8004	@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
	8005	This command will be applied to the text in the first column. For
	8006	example, @code{@@table @@code} will cause the text in the first column
	8007	to be output as if it had been the argument to a @code{@@code} command.
	8008
	8009	@anchor{@code{@@asis}}@c command name with @, for consistency
	8010	@findex asis
	8011	You may use the @code{@@asis} command as an argument to
	8012	@code{@@table}. @code{@@asis} is a command that does nothing: if you
	8013	use this command after @code{@@table}, the first column entries are
	8014	output without added highlighting (``as is'').
	8015
	8016	The @code{@@table} command works with other commands besides those
	8017	explicitly mentioned here. However, you can only use predefined
	8018	Texinfo commands that take an argument in braces. You cannot
	8019	reliably use a new command defined with @code{@@macro}, although an
	8020	@code{@@alias} (for a suitable predefined command) is acceptable.
	8021	@xref{Defining New Texinfo Commands}.
	8022
	8023	@findex item
	8024	Begin each table entry with an @code{@@item} command at the beginning
	8025	of a line. Write the text for the first column on the same line as the
	8026	@code{@@item} command. Write the text for the second column on the line
	8027	following the @code{@@item} line and on subsequent lines. You may
	8028	write as many lines of supporting text as you wish, even several
	8029	paragraphs. But only the text on the same line as the @code{@@item}
	8030	will be placed in the first column (including any footnotes).
	8031	You do not need to type anything for an empty second column.
	8032
	8033	Normally, you should put a blank line before an @code{@@item} line
	8034	(except the first one). This puts a blank line in the Info file.
	8035	Except when the entries are very brief, a blank line looks better.
	8036	End the table with a line consisting of @code{@@end table}, followed
	8037	by a blank line. @TeX{} will always start a new paragraph after the
	8038	table, so the blank line is needed for the Info output to be analogous.
	8039
	8040	@need 1500
	8041	For example, the following table highlights the text in the first
	8042	column with the @code{@@samp} command:
	8043
	8044	@example
	8045	@group
	8046	@@table @@samp
	8047	@@item foo
	8048	This is the text for
	8049	@@samp@{foo@}.
	8050
	8051	@@item bar
	8052	Text for @@samp@{bar@}.
	8053	@@end table
	8054	@end group
	8055	@end example
	8056
	8057	@noindent
	8058	This produces:
	8059
	8060	@table @samp
	8061	@item foo
	8062	This is the text for
	8063	@samp{foo}.
	8064	@item bar
	8065	Text for @samp{bar}.
	8066	@end table
	8067
	8068	If you want to list two or more named items with a single block of
	8069	text, use the @code{@@itemx} command. (@xref{@code{@@itemx}}.)
	8070
	8071	The @code{@@table} command (@pxref{@code{@@table}}) is not supported
	8072	inside @code{@@display}. Since @code{@@display} is line-oriented, it
	8073	doesn't make sense to use them together. If you want to indent a
	8074	table, try @code{@@quotation} (@pxref{@code{@@quotation}}) or
	8075	@code{@@indentedblock} (@pxref{@code{@@indentedblock}}).
	8076
	8077	@node @code{@@ftable @@vtable}
	8078	@subsection @code{@@ftable} and @code{@@vtable}
	8079
	8080	@anchor{ftable vtable}@c old name
	8081	@findex ftable
	8082	@findex vtable
	8083	@cindex Tables with indexing
	8084	@cindex Indexing table entries automatically
	8085
	8086	The @code{@@ftable} and @code{@@vtable} commands are the same as the
	8087	@code{@@table} command except that @code{@@ftable} automatically enters
	8088	each of the items in the first column of the table into the index of
	8089	functions and @code{@@vtable} automatically enters each of the items in
	8090	the first column of the table into the index of variables. This
	8091	simplifies the task of creating indices. Only the items on the same
	8092	line as the @code{@@item} or @code{@@itemx} commands are indexed, and
	8093	they are indexed in exactly the form that they appear on that line.
	8094	@xref{Indices}, for more information about indices.
	8095
	8096	Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
	8097	writing the @@-command at the beginning of a line, followed on the same
	8098	line by an argument that is a Texinfo command such as @code{@@code},
	8099	exactly as you would for a @code{@@table} command; and end the table
	8100	with an @code{@@end ftable} or @code{@@end vtable} command on a line by
	8101	itself.
	8102
	8103	See the example for @code{@@table} in the previous section.
	8104
	8105
	8106	@node @code{@@itemx}
	8107	@subsection @code{@@itemx}: Second and Subsequent Items
	8108
	8109	@anchor{itemx}@c old name
	8110	@cindex Two named items for @code{@@table}
	8111	@findex itemx
	8112
	8113	Use the @code{@@itemx} command inside a table when you have two or more
	8114	first column entries for the same item, each of which should appear on a
	8115	line of its own.
	8116
	8117	Use @code{@@item} for the first entry, and @code{@@itemx} for all
	8118	subsequent entries; @code{@@itemx} must always follow an @code{@@item}
	8119	command, with no blank line intervening.
	8120
	8121	The @code{@@itemx} command works exactly like @code{@@item} except
	8122	that it does not generate extra vertical space above the first column
	8123	text. If you have multiple consecutive @code{@@itemx} commands, do
	8124	not insert any blank lines between them.
	8125
	8126	For example,
	8127
	8128	@example
	8129	@group
	8130	@@table @@code
	8131	@@item upcase
	8132	@@itemx downcase
	8133	These two functions accept a character or a string as
	8134	argument, and return the corresponding uppercase (lowercase)
	8135	character or string.
	8136	@@end table
	8137	@end group
	8138	@end example
	8139
	8140	@noindent
	8141	This produces:
	8142
	8143	@table @code
	8144	@item upcase
	8145	@itemx downcase
	8146	These two functions accept a character or a string as
	8147	argument, and return the corresponding uppercase (lowercase)
	8148	character or string.
	8149	@end table
	8150
	8151	@noindent
	8152	(Note also that this example illustrates multi-line supporting text in
	8153	a two-column table.)
	8154
	8155
	8156	@node Multi-column Tables
	8157	@section @code{@@multitable}: Multi-column Tables
	8158
	8159	@findex multitable
	8160	@cindex Tables, making multi-column
	8161
	8162	@code{@@multitable} allows you to construct tables with any number of
	8163	columns, with each column having any width you like.
	8164
	8165	You define the column widths on the @code{@@multitable} line itself, and
	8166	write each row of the actual table following an @code{@@item} command,
	8167	with columns separated by a @code{@@tab} command. Finally, @code{@@end
	8168	multitable} completes the table. Details in the sections below.
	8169
	8170	@menu
	8171	* Multitable Column Widths:: Defining multitable column widths.
	8172	* Multitable Rows:: Defining multitable rows, with examples.
	8173	@end menu
	8174
	8175	@node Multitable Column Widths
	8176	@subsection Multitable Column Widths
	8177	@cindex Multitable column widths
	8178	@cindex Column widths, defining for multitables
	8179	@cindex Widths, defining multitable column
	8180
	8181	You can define the column widths for a multitable in two ways: as
	8182	fractions of the line length; or with a prototype row. Mixing the two
	8183	methods is not supported. In either case, the widths are defined
	8184	entirely on the same line as the @code{@@multitable} command.
	8185
	8186	@enumerate
	8187	@item
	8188	@findex columnfractions
	8189	@cindex Line length, column widths as fraction of
	8190	To specify column widths as fractions of the line length, write
	8191	@code{@@columnfractions} and the decimal numbers (presumably less than
	8192	1; a leading zero is allowed and ignored) after the
	8193	@code{@@multitable} command, as in:
	8194
	8195	@example
	8196	@@multitable @@columnfractions .33 .33 .33
	8197	@end example
	8198
	8199	The fractions need not add up exactly to 1.0, as these do not. This
	8200	allows you to produce tables that do not need the full line length.
	8201
	8202	@item
	8203	@cindex Prototype row, column widths defined by
	8204	To specify a prototype row, write the longest entry for each column
	8205	enclosed in braces after the @code{@@multitable} command. For example:
	8206
	8207	@example
	8208	@@multitable @{some text for column one@} @{for column two@}
	8209	@end example
	8210
	8211	@noindent
	8212	The first column will then have the width of the typeset `some text for
	8213	column one', and the second column the width of `for column two'.
	8214
	8215	The prototype entries need not appear in the table itself.
	8216
	8217	Although we used simple text in this example, the prototype entries can
	8218	contain Texinfo commands; markup commands such as @code{@@code} are
	8219	particularly likely to be useful.
	8220
	8221	@end enumerate
	8222
	8223
	8224	@node Multitable Rows
	8225	@subsection Multitable Rows
	8226
	8227	@cindex Multitable rows
	8228	@cindex Rows, of a multitable
	8229
	8230	@findex item
	8231	@findex tab
	8232	After the @code{@@multitable} command defining the column widths (see
	8233	the previous section), you begin each row in the body of a multitable
	8234	with @code{@@item}, and separate the column entries with @code{@@tab}.
	8235	Line breaks are not special within the table body, and you may break
	8236	input lines in your source file as necessary.
	8237
	8238	@findex headitem
	8239	@cindex Heading row, in table
	8240	@cindex @code{<thead>} HTML/XML tag
	8241	You can also use @code{@@headitem} instead of @code{@@item} to produce
	8242	a @dfn{heading row}. The @TeX{} output for such a row is in bold, and
	8243	the HTML and Docbook output uses the @code{<thead>} tag. In Info, the
	8244	heading row is followed by a separator line made of dashes (@samp{-}
	8245	characters).
	8246
	8247	@findex headitemfont
	8248	@cindex Font for multitable heading rows
	8249	The command @code{@@headitemfont} can be used in templates when the
	8250	entries in a @code{@@headitem} row need to be used in a template. It
	8251	is a synonym for @code{@@b}, but using @code{@@headitemfont} avoids
	8252	any dependency on that particular font style, in case we provide a way
	8253	to change it in the future.
	8254
	8255	Here is a complete example of a multi-column table (the text is from
	8256	@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
	8257	emacs, The GNU Emacs Manual}):
	8258
	8259	@example
	8260	@@multitable @@columnfractions .15 .45 .4
	8261	@@headitem Key @@tab Command @@tab Description
	8262	@@item C-x 2
	8263	@@tab @@code@{split-window-vertically@}
	8264	@@tab Split the selected window into two windows,
	8265	with one above the other.
	8266	@@item C-x 3
	8267	@@tab @@code@{split-window-horizontally@}
	8268	@@tab Split the selected window into two windows
	8269	positioned side by side.
	8270	@@item C-Mouse-2
	8271	@@tab
	8272	@@tab In the mode line or scroll bar of a window,
	8273	split that window.
	8274	@@end multitable
	8275	@end example
	8276
	8277	@noindent produces:
	8278
	8279	@multitable @columnfractions .15 .45 .4
	8280	@headitem Key @tab Command @tab Description
	8281	@item C-x 2
	8282	@tab @code{split-window-vertically}
	8283	@tab Split the selected window into two windows,
	8284	with one above the other.
	8285	@item C-x 3
	8286	@tab @code{split-window-horizontally}
	8287	@tab Split the selected window into two windows
	8288	positioned side by side.
	8289	@item C-Mouse-2
	8290	@tab
	8291	@tab In the mode line or scroll bar of a window,
	8292	split that window.
	8293	@end multitable
	8294
	8295
	8296	@node Special Displays
	8297	@chapter Special Displays
	8298	@cindex Special displays
	8299
	8300	The commands in this chapter allow you to write text that is specially
	8301	displayed (output format permitting), outside of the normal document
	8302	flow.
	8303
	8304	One set of such commands is for creating ``floats'', that is, figures,
	8305	tables, and the like, set off from the main text, possibly numbered,
	8306	captioned, and/or referred to from elsewhere in the document. Images
	8307	are often included in these displays.
	8308
	8309	Another group of commands is for creating footnotes in Texinfo.
	8310
	8311	@menu
	8312	* Floats:: Figures, tables, and the like.
	8313	* Images:: Including graphics and images.
	8314	* Footnotes:: Writing footnotes.
	8315	@end menu
	8316
	8317
	8318	@node Floats
	8319	@section Floats
	8320	@cindex Floats, in general
	8321
	8322	A @dfn{float} is a display which is set off from the main text. It is
	8323	typically labeled as being a ``Figure'', ``Table'', ``Example'', or
	8324	some similar type.
	8325
	8326	@cindex Floating, not yet implemented
	8327	A float is so-named because, in principle, it can be moved to the
	8328	bottom or top of the current page, or to a following page, in the
	8329	printed output. (Floating does not make sense in other output
	8330	formats.) In the present version of Texinfo, however, this floating
	8331	is unfortunately not yet implemented. Instead, the floating material
	8332	is simply output at the current location, more or less as if it were
	8333	an @code{@@group} (@pxref{@code{@@group}}).
	8334
	8335	@menu
	8336	* @code{@@float}:: Producing floating material.
	8337	* @code{@@caption @@shortcaption}:: Specifying descriptions for floats.
	8338	* @code{@@listoffloats}:: A table of contents for floats.
	8339	@end menu
	8340
	8341
	8342	@node @code{@@float}
	8343	@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material
	8344
	8345	@anchor{float}@c old name
	8346	@findex float
	8347	@cindex Float environment
	8348
	8349	To produce floating material, enclose the material you want to be
	8350	displayed separate between @code{@@float} and @code{@@end float}
	8351	commands, on lines by themselves.
	8352
	8353	Floating material often uses @code{@@image} to display an
	8354	already-existing graphic (@pxref{Images}), or @code{@@multitable} to
	8355	display a table (@pxref{Multi-column Tables}). However, the contents
	8356	of the float can be anything. Here's an example with simple text:
	8357
	8358	@example
	8359	@@float Figure,fig:ex1
	8360	This is an example float.
	8361	@@end float
	8362	@end example
	8363
	8364	@noindent And the output:
	8365
	8366	@float Figure,fig:ex1
	8367	This is an example float.
	8368	@end float
	8369
	8370	As shown in the example, @code{@@float} takes two arguments (separated
	8371	by a comma), @var{type} and @var{label}. Both are optional.
	8372
	8373	@table @var
	8374	@item type
	8375	Specifies the sort of float this is; typically a word such as
	8376	``Figure'', ``Table'', etc. If this is not given, and @var{label} is,
	8377	any cross-referencing will simply use a bare number.
	8378
	8379	@item label
	8380	Specifies a cross-reference label for this float. If given, this
	8381	float is automatically given a number, and will appear in any
	8382	@code{@@listoffloats} output (@pxref{@code{@@listoffloats}}). Cross
	8383	references to @var{label} are allowed.
	8384
	8385	@cindex Floats, making unnumbered
	8386	@cindex Unnumbered float, creating
	8387	On the other hand, if @var{label} is not given, then the float will
	8388	not be numbered and consequently will not appear in the
	8389	@code{@@listoffloats} output or be cross-referenceable.
	8390	@end table
	8391
	8392	@noindent Ordinarily, you specify both @var{type} and @var{label}, to get a
	8393	labeled and numbered float.
	8394
	8395	@cindex Floats, numbering of
	8396	@cindex Numbering of floats
	8397	In Texinfo, all floats are numbered in the same way: with the chapter
	8398	number (or appendix letter), a period, and the float number, which
	8399	simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each
	8400	float type is counted independently.
	8401
	8402	Floats within an @code{@@unnumbered}, or outside of any chapter, are
	8403	simply numbered consecutively from 1.
	8404
	8405	These numbering conventions are not, at present, changeable.
	8406
	8407
	8408	@node @code{@@caption @@shortcaption}
	8409	@subsection @code{@@caption} & @code{@@shortcaption}
	8410
	8411	@anchor{caption shortcaption}@c old name
	8412	@findex caption
	8413	@findex shortcaption
	8414	@cindex Captions, for floats
	8415	@cindex Short captions, for lists of floats
	8416
	8417	You may write a @code{@@caption} anywhere within a @code{@@float}
	8418	environment, to define a caption for the float. It is not allowed in
	8419	any other context. @code{@@caption} takes a single argument, enclosed
	8420	in braces. Here's an example:
	8421
	8422	@example
	8423	@@float
	8424	An example float, with caption.
	8425	@@caption@{Caption for example float.@}
	8426	@@end float
	8427	@end example
	8428
	8429	@noindent The output is:
	8430
	8431	@float
	8432	An example float, with caption.
	8433	@caption{Caption for example float.}
	8434	@end float
	8435
	8436	@code{@@caption} can appear anywhere within the float; it is not
	8437	processed until the @code{@@end float}. The caption text is usually a
	8438	sentence or two, but may consist of several paragraphs if necessary.
	8439
	8440	In the output, the caption always appears below the float; this is not
	8441	currently changeable. It is preceded by the float type and/or number,
	8442	as specified to the @code{@@float} command (see the previous section).
	8443
	8444	The @code{@@shortcaption} command likewise may be used only within
	8445	@code{@@float}, and takes a single argument in braces. The short
	8446	caption text is used instead of the caption text in a list of floats
	8447	(see the next section). Thus, you can write a long caption for the
	8448	main document, and a short title to appear in the list of floats. For
	8449	example:
	8450
	8451	@example
	8452	@@float
	8453	... as above ...
	8454	@@shortcaption@{Text for list of floats.@}
	8455	@@end float
	8456	@end example
	8457
	8458	The text for @code{@@shortcaption} may not contain comments
	8459	(@code{@@c}), verbatim text (@code{@@verb}), environments such as
	8460	@code{@@example}, footnotes (@code{@@footnote}) or other complex
	8461	constructs. The same constraints apply to @code{@@caption} unless
	8462	there is a @code{@@shortcaption}.
	8463
	8464
	8465	@node @code{@@listoffloats}
	8466	@subsection @code{@@listoffloats}: Tables of Contents for Floats
	8467
	8468	@anchor{listoffloats}@c old name
	8469	@findex listoffloats
	8470	@cindex List of floats
	8471	@cindex Floats, list of
	8472	@cindex Table of contents, for floats
	8473
	8474	You can write a @code{@@listoffloats} command to generate a list of
	8475	floats for a given float type (@pxref{@code{@@float}}), analogous to
	8476	the document's overall table of contents. Typically, it is written in
	8477	its own @code{@@unnumbered} node to provide a heading and structure,
	8478	rather like @code{@@printindex} (@pxref{Printing Indices & Menus}).
	8479
	8480	@code{@@listoffloats} takes one optional argument, the float type.
	8481	Here's an example:
	8482
	8483	@example
	8484	@@node List of Figures
	8485	@@unnumbered List of Figures
	8486	@@listoffloats Figure
	8487	@end example
	8488
	8489	@noindent And here's what the output from @code{@@listoffloats}
	8490	looks like, given the example figure earlier in this chapter (the Info
	8491	output is formatted as a menu):
	8492
	8493	@display
	8494	@ifinfo
	8495	* Figure 12.1: fig:ex1.
	8496	@end ifinfo
	8497	@ifnotinfo
	8498	@listoffloats Figure
	8499	@end ifnotinfo
	8500	@end display
	8501
	8502	Without any argument, @code{@@listoffloats} generates a list of floats
	8503	for which no float type was specified, i.e., no first argument to the
	8504	@code{@@float} command (@pxref{@code{@@float}}).
	8505
	8506	Each line in the list of floats contains the float type (if any),
	8507	the float number, and the caption, if any---the @code{@@shortcaption}
	8508	argument, if it was specified, else the @code{@@caption} argument.
	8509	In Info, the result is a menu where each float can be selected. In
	8510	HTML, each line is a link to the float. In printed output, the page
	8511	number is included.
	8512
	8513	Unnumbered floats (those without cross-reference labels) are omitted
	8514	from the list of floats.
	8515
	8516
	8517	@node Images
	8518	@section Inserting Images
	8519
	8520	@cindex Images, inserting
	8521	@cindex Pictures, inserting
	8522	@findex image
	8523
	8524	You can insert an image given in an external file with the
	8525	@code{@@image} command. Although images can be used anywhere,
	8526	including the middle of a paragraph, we describe them in this chapter
	8527	since they are most often part of a displayed figure or example.
	8528
	8529	@menu
	8530	* Image Syntax::
	8531	* Image Scaling::
	8532	@end menu
	8533
	8534
	8535	@node Image Syntax
	8536	@subsection Image Syntax
	8537
	8538	Here is the synopsis of the @code{@@image} command:
	8539
	8540	@example
	8541	@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@}
	8542	@end example
	8543
	8544	@cindex Formats for images
	8545	@cindex Image formats
	8546	The @var{filename} argument is mandatory, and must not have an
	8547	extension, because the different processors support different formats:
	8548
	8549	@itemize @bullet
	8550	@item
	8551	@pindex eps image format
	8552	@TeX{} (DVI output) reads the file @file{@var{filename}.eps}
	8553	(Encapsulated PostScript format).
	8554
	8555	@item
	8556	@pindex pdftex@r{, and images}
	8557	@pindex png image format
	8558	@pindex jpeg image format
	8559	@pindex pdf image inclusions
	8560	pdf@TeX{} reads @file{@var{filename}.pdf}, @file{@var{filename}.png},
	8561	@file{@var{filename}.jpg}, or @file{@var{filename}.jpeg} (in that
	8562	order). It also tries uppercase versions of the extensions. The PDF
	8563	format does not support EPS images, so such must be converted first.
	8564
	8565	@item
	8566	For Info, @code{makeinfo} includes @file{@var{filename}.txt} verbatim
	8567	(more or less as if it were in @code{@@verbatim}). The Info output
	8568	may also include a reference to @file{@var{filename}.png} or
	8569	@file{@var{filename}.jpg}. (See below.)
	8570
	8571	@item
	8572	For HTML, @code{makeinfo} outputs a reference to
	8573	@file{@var{filename}.png}, @file{@var{filename}.jpg},
	8574	@file{@var{filename}.jpeg} or @file{@var{filename}.gif} (in that
	8575	order). If none of those exist, it gives an error, and outputs a
	8576	reference to @file{@var{filename}.jpg} anyway.
	8577
	8578	@item
	8579	@cindex SVG images, used in Docbook
	8580	For Docbook, @code{makeinfo} outputs references to
	8581	@file{@var{filename}.eps}, @file{@var{filename}.gif}
	8582	@file{@var{filename}.jpeg}, @file{@var{filename}.jpg},
	8583	@file{@var{filename}.pdf}, @file{@var{filename}.png} and
	8584	@file{@var{filename}.svg}, for every file found. Also,
	8585	@file{@var{filename}.txt} is included verbatim, if present. (The
	8586	subsequent Docbook processor is supposed to choose the appropriate one.)
	8587
	8588	@item
	8589	For Info and HTML output, @code{makeinfo} uses the optional fifth
	8590	argument @var{extension} to @code{@@image} for the filename extension,
	8591	if it is specified and the file is found. Any leading period should
	8592	be included in @var{extension}. For example:
	8593
	8594	@pindex XPM image format
	8595	@example
	8596	@@image@{foo,,,,.xpm@}
	8597	@end example
	8598
	8599	@end itemize
	8600
	8601	If you want to install image files for use by Info readers too, we
	8602	recommend putting them in a subdirectory like @samp{@var{foo}-figures}
	8603	for a package @var{foo}. Copying the files into
	8604	@code{$(infodir)/@var{foo}-figures/} should be done in your
	8605	@code{Makefile}.
	8606
	8607	The @var{width} and @var{height} arguments are described in the next
	8608	section.
	8609
	8610	For @TeX{} output, if an image is the only thing in a paragraph it
	8611	will ordinarily be displayed on a line by itself, respecting the
	8612	current environment indentation, but without the normal paragraph
	8613	indentation. If you want it centered, use @code{@@center}
	8614	(@pxref{@code{@@titlefont @@center @@sp}}).
	8615
	8616	@cindex Alt attribute for images
	8617	@cindex Images, alternate text for
	8618	@findex @sortas{-} -@r{ (in image alt string)}
	8619	For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
	8620	inline images to the optional @var{alttext} (fourth) argument to
	8621	@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses
	8622	the full file name of the image being displayed. The @var{alttext} is
	8623	processed as Texinfo text, so special characters such as @samp{"} and
	8624	@samp{<} and @samp{&} are escaped in the HTML output; also, you can
	8625	get an empty @code{alt} string with @code{@@-} (a command that
	8626	produces no output; @pxref{@code{@@- @@hyphenation}}).
	8627
	8628	For Info output, the @code{alt} string is also processed as Texinfo
	8629	text and output. In this case, @samp{\} is escaped as @samp{\\} and
	8630	@samp{"} as @samp{\"}; no other escapes are done.
	8631
	8632	In Info output, @code{makeinfo} writes a reference to the binary image
	8633	file (trying @var{filename} suffixed with @file{@var{extension}},
	8634	@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
	8635	if one exists. It also literally includes the @file{.txt} file if one
	8636	exists. This way, Info readers which can display images (such as the
	8637	Emacs Info browser, running under X) can do so, whereas Info readers
	8638	which can only use text (such as the standalone Info reader) can
	8639	display the textual version.
	8640
	8641	@cindex @samp{^@@^H} for images in Info
	8642	The implementation of this is to put the following construct into the
	8643	Info output:
	8644
	8645	@example
	8646	^@@^H[image src="@var{binaryfile}" text="@var{txtfile}"
	8647	alt="@var{alttext} ... ^@@^H]
	8648	@end example
	8649
	8650	@noindent where @samp{^@@} and @samp{^H} stand for the actual null and
	8651	backspace control characters. If one of the files is not present, the
	8652	corresponding argument is omitted.
	8653
	8654	The reason for mentioning this here is that older Info browsers (this
	8655	feature was introduced in Texinfo version 4.6) will display the above
	8656	literally, which, although not pretty, should not be harmful.
	8657
	8658
	8659	@node Image Scaling
	8660	@subsection Image Scaling
	8661
	8662	@cindex Images, scaling
	8663	@cindex Scaling images
	8664	@cindex Width of images
	8665	@cindex Height of images
	8666	@cindex Aspect ratio of images
	8667	@cindex Distorting images
	8668	The optional @var{width} and @var{height} arguments to the
	8669	@code{@@image} command (see the previous section) specify the size to
	8670	which to scale the image. They are only taken into account in @TeX{}.
	8671	If neither is specified, the image is presented in its natural size
	8672	(given in the file); if only one is specified, the other is scaled
	8673	proportionately; and if both are specified, both are respected, thus
	8674	likely distorting the original image by changing its aspect ratio.
	8675
	8676	@cindex Dimensions and image sizes
	8677	The @var{width} and @var{height} may be specified using any valid @TeX{}
	8678	dimension, namely:
	8679
	8680	@table @asis
	8681	@item pt
	8682	@cindex Points (dimension)
	8683	point (72.27pt = 1in)
	8684	@item pc
	8685	@cindex Picas
	8686	pica (1pc = 12pt)
	8687	@item bp
	8688	@cindex Big points
	8689	big point (72bp = 1in)
	8690	@item in
	8691	@cindex Inches
	8692	inch
	8693	@item cm
	8694	@cindex Centimeters
	8695	centimeter (2.54cm = 1in)
	8696	@item mm
	8697	@cindex Millimeters
	8698	millimeter (10mm = 1cm)
	8699	@item dd
	8700	@cindex Did@^ot points
	8701	did@^ot point (1157dd = 1238pt)
	8702	@item cc
	8703	@cindex Ciceros
	8704	cicero (1cc = 12dd)
	8705	@item sp
	8706	@cindex Scaled points
	8707	scaled point (65536sp = 1pt)
	8708	@end table
	8709
	8710	@pindex ridt.eps
	8711	For example, the following will scale a file @file{ridt.eps} to one
	8712	inch vertically, with the width scaled proportionately:
	8713
	8714	@example
	8715	@@image@{ridt,,1in@}
	8716	@end example
	8717
	8718	@pindex epsf.tex
	8719	For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
	8720	installed somewhere that @TeX{} can find it. (The standard location is
	8721	@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
	8722	root of your @TeX{} directory tree.) This file is included in the
	8723	Texinfo distribution and is also available from
	8724	@uref{ftp://tug.org/tex/epsf.tex}, among other places.
	8725
	8726	@code{@@image} can be used within a line as well as for displayed
	8727	figures. Therefore, if you intend it to be displayed, be sure to leave
	8728	a blank line before the command, or the output will run into the
	8729	preceding text.
	8730
	8731	Image scaling is presently implemented only in @TeX{}, not in HTML or
	8732	any other sort of output.
	8733
	8734
	8735	@node Footnotes
	8736	@section Footnotes
	8737	@cindex Footnotes
	8738	@findex footnote
	8739
	8740	A @dfn{footnote} is for a reference that documents or elucidates the
	8741	primary text.@footnote{A footnote should complement or expand upon the
	8742	primary text, but a reader should not need to read a footnote to
	8743	understand the primary text. For a thorough discussion of footnotes,
	8744	see @cite{The Chicago Manual of Style}, which is published by the
	8745	University of Chicago Press.}
	8746
	8747	Footnotes are distracting; use them sparingly at most, and it is best
	8748	to avoid them completely. Standard bibliographical references are
	8749	usually better placed in a bibliography at the end of a document
	8750	instead of in footnotes throughout.
	8751
	8752	@menu
	8753	* Footnote Commands:: How to write a footnote in Texinfo.
	8754	* Footnote Styles:: Controlling how footnotes appear in Info.
	8755	@end menu
	8756
	8757
	8758	@node Footnote Commands
	8759	@subsection Footnote Commands
	8760
	8761	In Texinfo, footnotes are created with the @code{@@footnote} command.
	8762	This command is followed immediately by a left brace, then by the text
	8763	of the footnote, and then by a terminating right brace. Footnotes may
	8764	be of any length (they will be broken across pages if necessary), but
	8765	are usually short. The template is:
	8766
	8767	@example
	8768	ordinary text@@footnote@{@var{text of footnote}@}
	8769	@end example
	8770
	8771	As shown here, the @code{@@footnote} command should come right after the
	8772	text being footnoted, with no intervening space; otherwise, the footnote
	8773	marker might end up starting a line.
	8774
	8775	For example, this clause is followed by a sample footnote@footnote{Here
	8776	is the sample footnote.}; in the Texinfo source, it looks like
	8777	this:
	8778
	8779	@example
	8780	@dots{}a sample footnote@@footnote@{Here is the sample
	8781	footnote.@}; in the Texinfo source@dots{}
	8782	@end example
	8783
	8784	As you can see, this source includes two punctuation marks next to
	8785	each other; in this case, @samp{.@};} is the sequence. This is normal
	8786	(the first ends the footnote and the second belongs to the sentence
	8787	being footnoted), so don't worry that it looks odd. (Another style,
	8788	perfectly acceptable, is to put the footnote after punctuation
	8789	belonging to the sentence, as in @samp{;@@footnote@{...}.)
	8790
	8791	In a printed manual or book, the reference mark for a footnote is a
	8792	small, superscripted number; the text of the footnote appears at the
	8793	bottom of the page, below a horizontal line.
	8794
	8795	In Info, the reference mark for a footnote is a pair of parentheses
	8796	with the footnote number between them, like this: @samp{(1)}. The
	8797	reference mark is followed by a cross-reference link to the footnote
	8798	text if footnotes are put in separate nodes (@pxref{Footnote Styles}).
	8799
	8800	In the HTML output, footnote references are generally marked with a
	8801	small, superscripted number which is rendered as a hypertext link to
	8802	the footnote text.
	8803
	8804	@cindex Critical editions
	8805	@cindex Nested footnotes
	8806	Footnotes cannot be nested, and cannot appear in section headings of
	8807	any kind or other ``unusual'' places.
	8808
	8809	A final tip: footnotes in the argument of an @code{@@item} command for
	8810	an @code{@@table} must be entirely on the same line as the
	8811	@code{@@item} (as usual). @xref{Two-column Tables}.
	8812
	8813
	8814	@node Footnote Styles
	8815	@subsection Footnote Styles
	8816
	8817	Info has two footnote styles, which determine where the text of the
	8818	footnote is located:
	8819
	8820	@itemize @bullet
	8821	@cindex @samp{@r{End}} node footnote style
	8822	@item
	8823	In the `End' node style, all the footnotes for a single node are
	8824	placed at the end of that node. The footnotes are separated from the
	8825	rest of the node by a line of dashes with the word @samp{Footnotes}
	8826	within it. Each footnote begins with an @samp{(@var{n})} reference
	8827	mark.
	8828
	8829	@need 700
	8830	@noindent
	8831	Here is an example of the Info output for a single footnote in the
	8832	end-of-node style:
	8833
	8834	@example
	8835	@group
	8836	--------- Footnotes ---------
	8837
	8838	(1) Here is a sample footnote.
	8839	@end group
	8840	@end example
	8841
	8842	@cindex @samp{@r{Separate}} footnote style
	8843	@item
	8844	In the `Separate' node style, all the footnotes for a single
	8845	node are placed in an automatically constructed node of
	8846	their own. In this style, a ``footnote reference'' follows
	8847	each @samp{(@var{n})} reference mark in the body of the
	8848	node. The footnote reference is actually a cross-reference
	8849	which you use to reach the footnote node.
	8850
	8851	The name of the node with the footnotes is constructed
	8852	by appending @w{@samp{-Footnotes}} to the name of the node
	8853	that contains the footnotes. (Consequently, the footnotes'
	8854	node for the @file{Footnotes} node is
	8855	@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
	8856	`Up' node pointer that leads back to its parent node.
	8857
	8858	@noindent
	8859	Here is how the first footnote in this manual looks after being
	8860	formatted for Info in the separate node style:
	8861
	8862	@smallexample
	8863	@group
	8864	File: texinfo.info Node: Overview-Footnotes, Up: Overview
	8865
	8866	(1) The first syllable of "Texinfo" is pronounced like "speck", not
	8867	"hex". @dots{}
	8868	@end group
	8869	@end smallexample
	8870	@end itemize
	8871
	8872	Unless your document has long and important footnotes (as in, say,
	8873	Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end}
	8874	style, as it is simpler for readers to follow.
	8875
	8876	@findex footnotestyle
	8877	Use the @code{@@footnotestyle} command to specify an Info file's
	8878	footnote style. Write this command at the beginning of a line followed
	8879	by an argument, either @samp{end} for the end node style or
	8880	@samp{separate} for the separate node style.
	8881
	8882	@need 700
	8883	For example,
	8884
	8885	@example
	8886	@@footnotestyle end
	8887	@end example
	8888	@noindent
	8889	or
	8890	@example
	8891	@@footnotestyle separate
	8892	@end example
	8893
	8894	Write a @code{@@footnotestyle} command before or shortly after the
	8895	end-of-header line at the beginning of a Texinfo file. (You should
	8896	include any @code{@@footnotestyle} command between the start-of-header
	8897	and end-of-header lines, so the region formatting commands will format
	8898	footnotes as specified.)
	8899
	8900	In HTML, when the footnote style is @samp{end}, or if the output is
	8901	not split, footnotes are put at the end of the output. If set to
	8902	@samp{separate}, and the output is split, they are placed in a
	8903	separate file.
	8904
	8905
	8906	@node Indices
	8907	@chapter Indices
	8908	@cindex Indices
	8909
	8910	Using Texinfo, you can generate indices without having to sort and
	8911	collate entries manually. In an index, the entries are listed in
	8912	alphabetical order, together with information on how to find the
	8913	discussion of each entry. In a printed manual, this information
	8914	consists of page numbers. In an Info file, this information is a menu
	8915	entry leading to the first node referenced.
	8916
	8917	Texinfo provides several predefined kinds of indices: an index for
	8918	functions, an index for variables, an index for concepts, and so on.
	8919	You can combine indices or use them for other than their canonical
	8920	purpose. Lastly, you can define your own new indices.
	8921
	8922	@menu
	8923	* Predefined Indices:: Use different indices for different kinds
	8924	of entries.
	8925	* Indexing Commands:: How to make an index entry.
	8926	* Advanced Indexing:: Advanced indexing commands.
	8927	* Index Entries:: Choose different words for index entries.
	8928	* Printing Indices & Menus:: How to print an index in hardcopy and
	8929	generate index menus in Info.
	8930	* Combining Indices:: How to combine indices.
	8931	* New Indices:: How to define your own indices.
	8932	@end menu
	8933
	8934
	8935	@node Predefined Indices
	8936	@section Predefined Indices
	8937
	8938	Texinfo provides six predefined indices. Here are their nominal
	8939	meanings, abbreviations, and the corresponding index entry commands:
	8940
	8941	@table @samp
	8942	@item cp
	8943	@cindex @code{cp} (concept) index
	8944	@findex cindex
	8945	(@code{@@cindex}) Concept index, for general concepts.
	8946	@item fn
	8947	@cindex @code{fn} (function) index
	8948	@findex findex
	8949	(@code{@@findex}) Function index, for function and function-like
	8950	names (such as entry points of libraries).
	8951	@item ky
	8952	@cindex @code{ky} (keystroke) index
	8953	@findex kindex
	8954	(@code{@@kindex}) Keystroke index, for keyboard commands.
	8955	@item pg
	8956	@cindex @code{pg} (program) index
	8957	@findex pindex
	8958	(@code{@@pindex}) Program index, for names of programs.
	8959	@item tp
	8960	@cindex @code{tp} (data type) index
	8961	@findex tindex
	8962	(@code{@@tindex}) Data type index, for type names (such as structures
	8963	defined in header files).
	8964	@item vr
	8965	@cindex @code{vr} (variable) index
	8966	@findex vindex
	8967	(@code{@@vindex}) Variable index, for variable names (such as library global
	8968	variables).
	8969	@end table
	8970
	8971	@noindent
	8972	Not every manual needs all of these, and most manuals use only two or
	8973	three at most. The present manual, for example, has two indices: a
	8974	concept index and an @@-command index. (The latter is actually the function
	8975	index but is called a command index in the chapter heading.)
	8976
	8977	You are not required to use the predefined indices strictly for their
	8978	canonical purposes. For example, suppose you wish to index some C
	8979	preprocessor macros. You could put them in the function index along
	8980	with actual functions, just by writing @code{@@findex} commands for
	8981	them; then, when you print the ``Function Index'' as an unnumbered
	8982	chapter, you could give it the title `Function and Macro Index' and
	8983	all will be consistent for the reader.
	8984
	8985	On the other hand, it is best not to stray too far from the meaning of
	8986	the predefined indices. Otherwise, in the event that your text is
	8987	combined with other text from other manuals, the index entries will
	8988	not match up. Instead, define your own new index (@pxref{New
	8989	Indices}).
	8990
	8991	We recommend having a single index in the final document whenever
	8992	possible, however many source indices you use, since then readers have
	8993	only one place to look. Two or more source indices can be combined
	8994	into one output index by using the @code{@@synindex} or
	8995	@code{@@syncodeindex} commands (@pxref{Combining Indices}).
	8996
	8997
	8998	@node Indexing Commands
	8999	@section Defining the Entries of an Index
	9000
	9001	@cindex Defining indexing entries
	9002	@cindex Index entries
	9003	@cindex Entries for an index
	9004	@cindex Specifying index entries
	9005	@cindex Creating index entries
	9006
	9007	The data to make an index come from many individual indexing commands
	9008	scattered throughout the Texinfo source file. Each command says to add
	9009	one entry to a particular index; after formatting, the index will give
	9010	the current page number or node name as the reference.
	9011
	9012	An index entry consists of an indexing command at the beginning of a
	9013	line followed, on the rest of the line, by the entry.
	9014
	9015	For example, this section begins with the following five entries for
	9016	the concept index:
	9017
	9018	@example
	9019	@@cindex Defining indexing entries
	9020	@@cindex Index entries, defining
	9021	@@cindex Entries for an index
	9022	@@cindex Specifying index entries
	9023	@@cindex Creating index entries
	9024	@end example
	9025
	9026	Each predefined index has its own indexing command---@code{@@cindex}
	9027	for the concept index, @code{@@findex} for the function index, and so
	9028	on, as listed in the previous section.
	9029
	9030	Index entries should precede the visible material that is being
	9031	indexed. For instance:
	9032
	9033	@example
	9034	@@cindex hello
	9035	Hello, there!
	9036	@end example
	9037
	9038	@noindent Among other reasons, that way following indexing links (in
	9039	whatever context) ends up before the material, where readers want to
	9040	be, instead of after.
	9041
	9042	Try to avoid using a colon in index entries, as this may confuse some
	9043	Info readers. @xref{Menu Parts} for more information about the
	9044	structure of a menu entry.
	9045	@c At the time of writing, it always works in standalone info, and a
	9046	@c single colon not followed by a space works in Emacs.
	9047
	9048	@cindex Index font types
	9049	By default, entries for a concept index are printed in a small roman
	9050	font and entries for the other indices are printed in a small
	9051	@code{@@code} font. You may change the way part of an entry is
	9052	printed with the usual Texinfo commands, such as @code{@@file} for
	9053	file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
	9054	font (@pxref{Fonts}).
	9055
	9056	@findex sortas
	9057	@cindex sort keys for index entries
	9058	@cindex index sorting
	9059	For the printed output, you may specify an explicit sort key for an
	9060	index entry using @code{@@sortas} following either the index command
	9061	or the text of the entry. For example: @samp{@@findex @@sortas@{\@}
	9062	\ @@r@{(literal \ in @@code@{@@@@math@})} sorts the index entry this
	9063	produces under backslash.
	9064
	9065	@vindex txiindexbackslashignore
	9066	@vindex txiindexhyphenignore
	9067	@vindex txiindexlessthanignore
	9068	@vindex txiindexatsignignore
	9069	To reduce the quantity of sort keys you need to provide explicitly,
	9070	you may choose to ignore certain characters in index entries
	9071	for the purposes of sorting. The characters that you can
	9072	currently choose to ignore are @samp{\}, @samp{-}, @samp{<}
	9073	and @samp{@@}, which are ignored by giving as an argument to the
	9074	@code{@@set} command, respectively, @code{txiindexbackslashignore},
	9075	@code{txiindexhyphenignore}, @code{txiindexlessthanignore} and
	9076	@code{txiindexatsignignore}. For example, specifying @samp{@@set
	9077	txiindexbackslashignore} causes the @samp{\mathopsup} entry in the
	9078	index for this manual to be sorted as if it were @samp{mathopsup},
	9079	so that it appears among the other entries beginning with `M'.
	9080
	9081	@node Advanced Indexing
	9082	@section Advanced Indexing Commands
	9083	@cindex Indexing, advanced
	9084	@cindex Advanced indexing
	9085
	9086	Texinfo provides several commands for doing advanced indexing,
	9087	similar to the indices you may see in professionally published books.
	9088
	9089	@findex @@subentry
	9090	First, you can create @dfn{multilevel} index entries, allowing you
	9091	to group many related subtopics under the same higher level topic.
	9092	You do this by separating the parts of such an entry with the
	9093	@code{@@subentry} command. Such commands might look like this:
	9094
	9095	@example
	9096	@@cindex Superhumans @@subentry villians
	9097	@@cindex Superhumans @@subentry heros
	9098	@end example
	9099
	9100	You may have up to three levels in an entry:
	9101
	9102	@example
	9103	@@cindex coffee makers @@subentry electric @@subentry pink
	9104	@@cindex coffee makers @@subentry electric @@subentry blue
	9105	@end example
	9106
	9107	You can use the @code{@@sortas} command mentioned earlier with any or
	9108	all of the three parts of an entry to cause them to sort differently
	9109	than they would by default.
	9110
	9111	@findex @@seeentry
	9112	Second, you may provide an index entry that points to another,
	9113	using the @code{@@seeentry} (``see entry'') command. For example:
	9114
	9115	@example
	9116	@@cindex Indexes @@seeentry@{Indices@}
	9117	@end example
	9118
	9119	Such an entry should be unique in your document; the idea is to
	9120	redirect the reader to the other entry where they will find all
	9121	the information they are looking for.
	9122
	9123	@findex @@seealso
	9124	Finally, you may provide a ``see also'' entry using the @code{@@seealso}
	9125	command. These entries go along with regular entries, and are grouped
	9126	together with them in the final printed index. For example:
	9127
	9128	@example
	9129	@@cindex Coffee
	9130	@@cindex Coffee @@subentry With milk and sugar
	9131	@@cindex Coffee @@subentry With doughnuts
	9132	@@cindex Coffee @@subentry Decaffeinated
	9133	@@cindex Coffee @@seealso@{Tea@}
	9134	@end example
	9135
	9136	When using all three of these advanced commands, @emph{do not}
	9137	place a comma betwen the different parts of the index text. The
	9138	@command{texindex} program, which sorts the index entries and
	9139	generates the indexing formatting commands, takes care of placing
	9140	commas in the correct places for you.
	9141
	9142	These features are most useful with printed documents created
	9143	with @TeX{}, and when translating Texinfo to Docbook.
	9144
	9145	@node Index Entries
	9146	@section Making Index Entries
	9147	@cindex Index entries, making
	9148	@cindex Entries, making index
	9149
	9150	@cindex Writing index entries
	9151	@cindex Index entries, advice on writing
	9152	@cindex Advice on writing entries
	9153	@cindex Capitalization of index entries
	9154	Concept index entries consist of text. The best way to write an index
	9155	is to devise entries which are terse yet clear. If you can do this,
	9156	the index usually looks better if the entries are written just as they
	9157	would appear in the middle of a sentence, that is, capitalizing only
	9158	proper names and acronyms that always call for uppercase letters.
	9159	This is the case convention we use in most GNU manuals' indices.
	9160
	9161	If you don't see how to make an entry terse yet clear, make it longer
	9162	and clear---not terse and confusing. If many of the entries are
	9163	several words long, the index may look better if you use a different
	9164	convention: capitalize the first word of each entry. Whichever
	9165	case convention you use, use it consistently.
	9166
	9167	In any event, do not ever capitalize a case-sensitive name such as a C
	9168	or Lisp function name or a shell command; that would be a spelling
	9169	error. Entries in indices other than the concept index are symbol
	9170	names in programming languages, or program names; these names are
	9171	usually case-sensitive, so likewise use upper- and lowercase as
	9172	required.
	9173
	9174	@cindex Unique index entries
	9175	It is a good idea to make index entries unique wherever feasible.
	9176	That way, people using the printed output or online completion of
	9177	index entries don't see undifferentiated lists. Consider this an
	9178	opportunity to make otherwise-identical index entries be more
	9179	specific, so readers can more easily find the exact place they are
	9180	looking for.
	9181	The advanced indexing features described in @ref{Advanced Indexing}
	9182	can help with this, as well.
	9183
	9184
	9185	When you are making index entries, it is good practice to think of the
	9186	different ways people may look for something. Different people
	9187	@emph{do not} think of the same words when they look something up. A
	9188	helpful index will have items indexed under all the different words
	9189	that people may use. For example, one reader may think it obvious
	9190	that the two-letter names for indices should be listed under
	9191	``Indices, two-letter names'', since ``Indices'' are the general
	9192	concept. But another reader may remember the specific concept of
	9193	two-letter names and search for the entry listed as ``Two letter names
	9194	for indices''. A good index will have both entries and will help both
	9195	readers.
	9196
	9197	Like typesetting, the construction of an index is a skilled art, the
	9198	subtleties of which may not be appreciated until you need to do it
	9199	yourself.
	9200
	9201
	9202	@node Printing Indices & Menus
	9203	@section Printing Indices and Menus
	9204	@cindex Printing an index
	9205	@cindex Indices, printing and menus
	9206	@cindex Generating menus with indices
	9207	@cindex Menus generated with indices
	9208
	9209	To print an index means to include it as part of a manual or Info file.
	9210	This does not happen automatically just because you use @code{@@cindex}
	9211	or other index-entry generating commands in the Texinfo file; those just
	9212	cause the raw data for the index to be accumulated. To generate an
	9213	index, you must include the @code{@@printindex} command at the place in
	9214	the document where you want the index to appear. Also, as part of the
	9215	process of creating a printed manual, you must run a program called
	9216	@code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
	9217	sorted index file. The sorted index file is what is actually used to
	9218	print the index.
	9219
	9220	Texinfo offers six separate types of predefined index, which suffice in
	9221	most cases. See the other parts of this chapter for information on this,
	9222	as well as advanced indexing commands, defining your own new indices,
	9223	combining indices, and, most importantly, advice on writing the actual
	9224	index entries. This section focuses on printing indices, which is done
	9225	with the @code{@@printindex} command.
	9226
	9227	@findex printindex
	9228	@code{@@printindex} takes one argument, a two-letter index
	9229	abbreviation. It reads the corresponding sorted index file (for
	9230	printed output), and formats it appropriately into an index.
	9231
	9232	The @code{@@printindex} command does not generate a chapter heading
	9233	for the index, since different manuals have different needs.
	9234	Consequently, you should precede the @code{@@printindex} command with
	9235	a suitable section or chapter command (usually @code{@@appendix} or
	9236	@code{@@unnumbered}) to supply the chapter heading and put the index
	9237	into the table of contents. Precede the chapter heading with an
	9238	@code{@@node} line as usual.
	9239
	9240	For example:
	9241
	9242	@smallexample
	9243	@group
	9244	@@node Variable Index
	9245	@@unnumbered Variable Index
	9246
	9247	@@printindex vr
	9248	@end group
	9249
	9250	@group
	9251	@@node Concept Index
	9252	@@unnumbered Concept Index
	9253
	9254	@@printindex cp
	9255	@end group
	9256	@end smallexample
	9257
	9258	If you have more than one index, we recommend placing the concept index last.
	9259
	9260	@itemize
	9261	@item
	9262	In printed output, @code{@@printindex} produces a traditional
	9263	two-column index, with dot leaders between the index terms and page
	9264	numbers.
	9265
	9266	@item
	9267	In Info output, @code{@@printindex} produces a special menu containing
	9268	the line number of the entry, relative to the start of the node. Info
	9269	readers can use this to go to the exact line of an entry, not just the
	9270	containing node. (Older Info readers will just go to the node.)
	9271	Here's an example:
	9272
	9273	@smallexample
	9274	* First index entry: Top. (line 7)
	9275	@end smallexample
	9276
	9277	@noindent The actual number of spaces is variable, to right-justify
	9278	the line number; it's been reduced here to make the line fit in the
	9279	printed manual.
	9280
	9281	@item
	9282	In plain text output, @code{@@printindex} produces the same menu, but
	9283	the line numbers are relative to the start of the file, since that's
	9284	more convenient for that format.
	9285
	9286	@item
	9287	In HTML output, @code{@@printindex} produces links to the index
	9288	entries.
	9289
	9290	@item
	9291	In XML and Docbook output, it simply records the index to be printed.
	9292	@end itemize
	9293
	9294
	9295	@node Combining Indices
	9296	@section Combining Indices
	9297	@cindex Combining indices
	9298	@cindex Indices, combining them
	9299
	9300	Sometimes you will want to combine two disparate indices such as
	9301	functions and concepts, perhaps because you have few enough entries
	9302	that a separate index would look silly.
	9303
	9304	You could put functions into the concept index by writing
	9305	@code{@@cindex} commands for them instead of @code{@@findex} commands,
	9306	and produce a consistent manual by printing the concept index with the
	9307	title `Function and Concept Index' and not printing the `Function
	9308	Index' at all; but this is not a robust procedure. It works only if
	9309	your document is never included as part of another document that is
	9310	designed to have a separate function index; if your document were to
	9311	be included with such a document, the functions from your document and
	9312	those from the other would not end up together. Also, to make your
	9313	function names appear in the right font in the concept index, you
	9314	would need to enclose every one of them between the braces of
	9315	@code{@@code}.
	9316
	9317	@menu
	9318	* @code{@@syncodeindex}:: How to merge two indices, using @code{@@code}
	9319	font for the merged-from index.
	9320	* @code{@@synindex}:: How to merge two indices, using the
	9321	roman font for the merged-from index.
	9322	@end menu
	9323
	9324
	9325	@node @code{@@syncodeindex}
	9326	@subsection @code{@@syncodeindex}: Combining Indices Using @code{@@code}
	9327
	9328	@anchor{syncodeindex}@c old name
	9329	@findex syncodeindex
	9330
	9331	When you want to combine functions and concepts into one index, you
	9332	should index the functions with @code{@@findex} and index the concepts
	9333	with @code{@@cindex}, and use the @code{@@syncodeindex} command to
	9334	redirect the function index entries into the concept index.
	9335
	9336	The @code{@@syncodeindex} command takes two arguments; they are the name
	9337	of the index to redirect, and the name of the index to redirect it to.
	9338	The template looks like this:
	9339
	9340	@example
	9341	@@syncodeindex @var{from} @var{to}
	9342	@end example
	9343
	9344	@cindex Predefined names for indices
	9345	@cindex Two letter names for indices
	9346	@cindex Indices, two letter names
	9347	@cindex Names for indices
	9348	For this purpose, the indices are given two-letter names:
	9349
	9350	@table @samp
	9351	@item cp
	9352	Concept index
	9353	@item fn
	9354	Function index
	9355	@item ky
	9356	Key index
	9357	@item pg
	9358	Program index
	9359	@item tp
	9360	Data type index
	9361	@item vr
	9362	Variable index
	9363	@end table
	9364
	9365	Write a @code{@@syncodeindex} command before or shortly after the
	9366	end-of-header line at the beginning of a Texinfo file. For example,
	9367	to merge a function index with a concept index, write the
	9368	following:
	9369
	9370	@example
	9371	@@syncodeindex fn cp
	9372	@end example
	9373
	9374	@noindent
	9375	This causes all entries designated for the function index to merge
	9376	in with the concept index instead.
	9377
	9378	To merge both a variables index and a function index into a concept
	9379	index, write the following:
	9380
	9381	@example
	9382	@group
	9383	@@syncodeindex vr cp
	9384	@@syncodeindex fn cp
	9385	@end group
	9386	@end example
	9387
	9388	@cindex Fonts for indices
	9389	The @code{@@syncodeindex} command puts all the entries from the `from'
	9390	index (the redirected index) into the @code{@@code} font, overriding
	9391	whatever default font is used by the index to which the entries are
	9392	now directed. This way, if you direct function names from a function
	9393	index into a concept index, all the function names are printed in the
	9394	@code{@@code} font as you would expect.
	9395
	9396
	9397	@node @code{@@synindex}
	9398	@subsection @code{@@synindex}: Combining Indices
	9399
	9400	@anchor{synindex}@c old name
	9401	@findex synindex
	9402
	9403	The @code{@@synindex} command is nearly the same as the
	9404	@code{@@syncodeindex} command, except that it does not put the `from'
	9405	index entries into the @code{@@code} font; rather it puts them in the
	9406	roman font. Thus, you use @code{@@synindex} when you merge a concept
	9407	index into a function index.
	9408
	9409	@xref{Printing Indices & Menus}, for information about printing an index
	9410	at the end of a book or creating an index menu in an Info file.
	9411
	9412
	9413	@node New Indices
	9414	@section Defining New Indices
	9415
	9416	@cindex Defining new indices
	9417	@cindex Indices, defining new
	9418	@cindex New index defining
	9419	@findex defindex
	9420	@findex defcodeindex
	9421
	9422	In addition to the predefined indices (@pxref{Predefined Indices}),
	9423	you may use the @code{@@defindex} and @code{@@defcodeindex} commands
	9424	to define new indices. These commands create new indexing @@-commands
	9425	with which you mark index entries. The @code{@@defindex} command is
	9426	used like this:
	9427
	9428	@example
	9429	@@defindex @var{name}
	9430	@end example
	9431
	9432	New index names are usually two-letter words, such as @samp{au}.
	9433	For example:
	9434
	9435	@example
	9436	@@defindex au
	9437	@end example
	9438
	9439	This defines a new index, called the @samp{au} index. At the same
	9440	time, it creates a new indexing command, @code{@@auindex}, that you
	9441	can use to make index entries. Use this new indexing command just as
	9442	you would use a predefined indexing command.
	9443
	9444	For example, here is a section heading followed by a concept index
	9445	entry and two @samp{au} index entries.
	9446
	9447	@example
	9448	@@section Cognitive Semantics
	9449	@@cindex kinesthetic image schemas
	9450	@@auindex Johnson, Mark
	9451	@@auindex Lakoff, George
	9452	@end example
	9453
	9454	@noindent
	9455	(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
	9456
	9457	Texinfo constructs the new indexing command by concatenating the name
	9458	of the index with @samp{index}; thus, defining an @samp{xy} index
	9459	leads to the automatic creation of an @code{@@xyindex} command.
	9460
	9461	Use the @code{@@printindex} command to print the index, as you do with
	9462	the predefined indices. For example:
	9463
	9464	@example
	9465	@group
	9466	@@node Author Index
	9467	@@unnumbered Author Index
	9468
	9469	@@printindex au
	9470	@end group
	9471	@end example
	9472
	9473	The @code{@@defcodeindex} command is like the @code{@@defindex} command,
	9474	except that, in the printed output, it prints entries in an
	9475	@code{@@code} font by default instead of in a roman font.
	9476
	9477	You should define new indices before the end-of-header line of a
	9478	Texinfo file, and (of course) before any @code{@@synindex} or
	9479	@code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
	9480
	9481	As mentioned earlier (@pxref{Predefined Indices}), we recommend having
	9482	a single index in the final document whenever possible (no matter however many
	9483	source indices you use), since then readers have only one place to
	9484	look.
	9485
	9486	When creating an index, @TeX{} creates a file whose extension is the
	9487	name of the index (@pxref{Names of index files}). Therefore you
	9488	should avoid using index names that collide with extensions used for
	9489	other purposes, such as @samp{.aux} or @samp{.xml}.
	9490	@command{makeinfo} already reports an error if a new index conflicts
	9491	well-known extension name.
	9492
	9493
	9494	@node Insertions
	9495	@chapter Special Insertions
	9496	@cindex Inserting special characters and symbols
	9497	@cindex Special insertions
	9498
	9499	Texinfo provides several commands for inserting characters that have
	9500	special meaning in Texinfo, such as braces, and for other graphic
	9501	elements that do not correspond to simple characters you can type.
	9502
	9503	@iftex
	9504	These are:
	9505
	9506	@itemize @bullet
	9507	@item The Texinfo special characters: @samp{@@ @{@} , \ # &}.
	9508	@item Whitespace within and around a sentence.
	9509	@item Accents.
	9510	@item Dots and bullets.
	9511	@item The @TeX{} logo and the copyright symbol.
	9512	@item The euro and pounds currency symbols.
	9513	@item The degrees symbol.
	9514	@item The minus sign.
	9515	@item Mathematical expressions.
	9516	@item Glyphs for examples of programming: evaluation, macros, errors, etc.
	9517	@item Footnotes.
	9518	@end itemize
	9519	@end iftex
	9520
	9521	@menu
	9522	* Special Characters:: Inserting @@ @{@} , \ # &
	9523	* Inserting Quote Characters:: Inserting left and right quotes, in code.
	9524	* Inserting Space:: Inserting the right amount of whitespace.
	9525	* Inserting Accents:: Inserting accents and special characters.
	9526	* Inserting Quotation Marks:: Inserting quotation marks.
	9527	* Inserting Subscripts and Superscripts:: Inserting sub/superscripts.
	9528	* Inserting Math:: Formatting mathematical expressions.
	9529	* Glyphs for Text:: Inserting dots, bullets, currencies, etc.
	9530	* Glyphs for Programming:: Indicating results of evaluation,
	9531	expansion of macros, errors, etc.
	9532	* Inserting Unicode:: Inserting a Unicode character by code point.
	9533	@end menu
	9534
	9535
	9536	@node Special Characters
	9537	@section Special Characters: Inserting @@ @{@} , \ # &
	9538	@anchor{Braces Atsign}@c previous names for this node
	9539	@anchor{Atsign Braces Comma}
	9540	@cindex Special characters, inserting
	9541	@cindex Commands to insert special characters
	9542
	9543	@samp{@@} and curly braces are the basic special characters in
	9544	Texinfo. To insert these characters so they appear in text, you must
	9545	put an @samp{@@} in front of these characters to prevent Texinfo from
	9546	misinterpreting them. Alphabetic commands are also provided.
	9547
	9548	The other characters (comma, backslash, hash, ampersand) are special
	9549	only in restricted contexts, as explained in the respective sections.
	9550
	9551	@menu
	9552	* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}.
	9553	* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}.
	9554	* Inserting a Comma:: , and @code{@@comma@{@}}.
	9555	* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}.
	9556	* Inserting a Hashsign:: # and @code{@@hashchar@{@}}.
	9557	* Inserting an Ampersand:: & and @code{@@ampchar@{@}}.
	9558	@end menu
	9559
	9560
	9561	@node Inserting an Atsign
	9562	@subsection Inserting `@@' with @code{@@@@} and @code{@@atchar@{@}}
	9563	@cindex At sign, inserting
	9564	@cindex Inserting @@ @r{(literal @samp{@@})}
	9565	@findex @sortas{@@} @@ @r{(literal @samp{@@})}
	9566	@findex atchar@{@} @r{(literal @samp{@@})}
	9567
	9568	@code{@@@@} produces a single @samp{@@} character in the output. Do
	9569	not put braces after an @code{@@@@} command.
	9570
	9571	@code{@@atchar@{@}} also produces a single @samp{@@} character in the
	9572	output. It does need following braces, as usual for alphabetic
	9573	commands. In inline conditionals (@pxref{Inline Conditionals}), it
	9574	can be necessary to avoid using the literal @samp{@@} character in the
	9575	source (and may be clearer in other contexts).
	9576
	9577
	9578	@node Inserting Braces
	9579	@subsection Inserting `@{ `@}' with @code{@@@{ @@@}} and @code{@@l rbracechar@{@}}
	9580
	9581	@findex @{ @r{(literal @samp{@{})}
	9582	@findex @} @r{(literal @samp{@}})}
	9583	@findex lbracechar@{@} @r{(literal @samp{@{})}
	9584	@findex rbracechar@{@} @r{(literal @samp{@}})}
	9585	@cindex Braces, inserting
	9586
	9587	@code{@@@{} produces a single @samp{@{} in the output, and @code{@@@}}
	9588	produces a single @samp{@}}. Do not put braces after either an
	9589	@code{@@@{} or an @code{@@@}} command.
	9590
	9591	@code{@@lbracechar@{@}} and @code{@@rbracechar@{@}} also produce
	9592	single @samp{@{} and @samp{@}} characters in the output. They do need
	9593	following braces, as usual for alphabetic commands. In inline
	9594	conditionals (@pxref{Inline Conditionals}), it can be
	9595	necessary to avoid using literal brace characters in the source (and
	9596	may be clearer in other contexts).
	9597
	9598
	9599	@node Inserting a Comma
	9600	@subsection Inserting `,' with @code{@@comma@{@}}
	9601
	9602	@findex comma
	9603	@cindex Comma, inserting
	9604
	9605	Ordinarily, a comma `,' is a normal character that can be simply typed
	9606	in your input where you need it.
	9607
	9608	However, Texinfo uses the comma as a special character only in one
	9609	context: to separate arguments to those Texinfo commands, such as
	9610	@code{@@acronym} (@pxref{@code{@@acronym}}) and @code{@@xref}
	9611	(@pxref{Cross References}), as well as user-defined macros
	9612	(@pxref{Defining Macros}), which take more than one argument.
	9613
	9614	Since a comma character would confuse Texinfo's parsing for these
	9615	commands, you must use the command @samp{@@comma@{@}} instead if you want
	9616	to pass an actual comma. Here are some examples:
	9617
	9618	@example
	9619	@@acronym@{ABC, A Bizarre @@comma@{@}@}
	9620	@@xref@{Comma,, The @@comma@{@} symbol@}
	9621	@@mymac@{One argument@@comma@{@} containing a comma@}
	9622	@end example
	9623
	9624	Although @samp{@@comma@{@}} can be used nearly anywhere, there is no
	9625	need for it anywhere except in this unusual case.
	9626
	9627	(Incidentally, the name @samp{@@comma} lacks the @samp{char} suffix used
	9628	in its companion commands only for historical reasons. It didn't seem
	9629	important enough to define a synonym.)
	9630
	9631
	9632	@node Inserting a Backslash
	9633	@subsection Inserting `\' with @code{@@backslashchar@{@}}
	9634
	9635	@findex backslashchar
	9636	@cindex Backslash, inserting
	9637
	9638	Ordinarily, a backslash `\' is a normal character in Texinfo that can
	9639	be simply typed in your input where you need it. The result is to
	9640	typeset the backslash from the typewriter font.
	9641
	9642	However, Texinfo uses the backslash as a special character in one
	9643	restricted context: to delimit formal arguments in the bodies of
	9644	user-defined macros (@pxref{Defining Macros}).
	9645
	9646	Due to the vagaries of macro argument parsing, it is more reliable to
	9647	pass an alphabetic command that produces a backslash instead of using
	9648	a literal \. Hence @code{@@backslashchar@{@}}. Here is an example
	9649	macro call:
	9650
	9651	@example
	9652	@@mymac@{One argument@@backslashchar@{@} with a backslash@}
	9653	@end example
	9654
	9655	@findex \backslash
	9656	Texinfo documents may also use \ as a command character inside
	9657	@code{@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or
	9658	@code{\backslash} produces a ``math'' backslash (from the math symbol
	9659	font), while @code{@@backslashchar@{@}} produces a typewriter
	9660	backslash as usual.
	9661
	9662	Although @samp{@@backslashchar@{@}} can be used nearly anywhere, there
	9663	is no need for it except in these unusual cases.
	9664
	9665
	9666	@node Inserting a Hashsign
	9667	@subsection Inserting `#' with @code{@@hashchar@{@}}
	9668
	9669	@findex hashchar@{@} @r{(literal @samp{#})}
	9670	@cindex Inserting #
	9671	@cindex Hash sign, inserting
	9672
	9673	Ordinarily, a hash `#' is a normal character in Texinfo that can be
	9674	simply typed in your input where you need it. The result is to
	9675	typeset the hash character from the current font.
	9676
	9677	@cindex Number sign, inserting
	9678	@cindex Octotherp, inserting
	9679	@cindex Sharp sign (not), inserting
	9680	This character has many other names, varying by locale, such as
	9681	``number sign'', ``pound'', and ``octothorp''. It is also sometimes
	9682	called ``sharp'' or ``sharp sign'' since it vaguely resembles the
	9683	musical symbol by that name. In situations where Texinfo is used,
	9684	``hash'' is the most common in our experience.
	9685
	9686	However, Texinfo uses the hash character as a special character in one
	9687	restricted context: to introduce the so-called @code{#line} directive
	9688	and variants (@pxref{External Macro Processors}).
	9689
	9690	So, in order to typeset an actual hash character in such a place (for
	9691	example, in a program that needs documentation about @code{#line}),
	9692	it's necessary to use @code{@@hashchar@{@}} or some other construct.
	9693	Here's an example:
	9694
	9695	@example
	9696	@@hashchar@{@} 10 "example.c"
	9697	@end example
	9698
	9699	Although @samp{@@hashchar@{@}} can be used nearly anywhere, there
	9700	is no need for it anywhere except this unusual case.
	9701
	9702
	9703	@node Inserting an Ampersand
	9704	@subsection Inserting `&' with @code{@@&} and @code{@@ampchar@{@}}
	9705
	9706	@findex ampchar@{@} @r{(literal @samp{&})}
	9707	@cindex Inserting &
	9708	@cindex Ampersand, inserting
	9709
	9710	Ordinarily, an ampersand `&' is a normal character in Texinfo that can be
	9711	simply typed in your input where you need it. The result is to
	9712	typeset the ampersand character.
	9713
	9714	However, the ampersand character has a special meaning in Texinfo in
	9715	just one restricted context. In the argument to a definition command
	9716	(@pxref{Definition Commands}), Emacs Lisp keywords beginning with
	9717	ampersands are recognized and typeset specially. @xref{A Sample
	9718	Function Description,,, elisp, GNU Emacs Lisp Reference Manual}.
	9719	For example:
	9720
	9721	@example
	9722	@@defun foo integer1 &optional integer2 &rest integers
	9723	@@code@{foo@} described here.
	9724	@@end defun
	9725	@end example
	9726
	9727	@noindent leads to the output
	9728
	9729	@defun foo integer1 &optional integer2 &rest integers
	9730	@code{foo} described here.
	9731	@end defun
	9732
	9733	So, in order to typeset an ampersand in such a context (for example, in
	9734	documentation of a C++ function taking a reference as a parameter),
	9735	it's necessary to use @code{@@&} or some other construct.
	9736	Here's an example:
	9737
	9738	@example
	9739	@@deftypefn Function int foo (@@code@{const std::vector<int>@@&@} bar)
	9740	Documentation of @@code@{foo@}.
	9741	@@end deftypefn
	9742	@end example
	9743
	9744	@noindent This gives the output
	9745
	9746	@deftypefn Function int foo (@code{const std::vector<int>@&} bar)
	9747	Documentation of @code{foo}.
	9748	@end deftypefn
	9749
	9750	Although @samp{@@&} and @samp{@@ampchar@{@}} can be used nearly
	9751	anywhere, there is no need for them anywhere except this unusual case.
	9752
	9753
	9754	@node Inserting Quote Characters
	9755	@section Inserting Quote Characters
	9756
	9757	@cindex Inserting quote characters
	9758	@cindex Quote characters, inserting
	9759
	9760	As explained in the early section on general Texinfo input conventions
	9761	(@pxref{Conventions}), Texinfo source files use the ASCII character
	9762	@code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'}
	9763	(39 decimal) to produce a right quote ('). Doubling these input
	9764	characters (@code{``} and @code{''}) produces double quotes (`` and
	9765	''). These are the conventions used by @TeX{}.
	9766
	9767	This works all right for text. However, in examples of computer code,
	9768	readers are especially likely to cut and paste the text
	9769	verbatim---and, unfortunately, some document viewers will mangle these
	9770	characters. (The free PDF reader @command{xpdf} works fine, but other
	9771	PDF readers, both free and nonfree, have problems.)
	9772
	9773	If this is a concern for you, Texinfo provides these two commands:
	9774
	9775	@table @code
	9776	@item @@codequoteundirected @var{on-off}
	9777	@findex codequoteundirected
	9778	@cindex undirected single quote
	9779	causes the output for the @code{'} character in code environments to
	9780	be the undirected single quote, like this:
	9781	@set txicodequoteundirected on
	9782	@code{'}.
	9783	@set txicodequoteundirected off
	9784
	9785	@item @@codequotebacktick @var{on-off}
	9786	@findex codequotebacktick
	9787	@cindex backtick
	9788	@cindex grave accent, standalone
	9789	causes the output for the @code{`} character in code environments to
	9790	be the backtick character (standalone grave accent), like this:
	9791	@set txicodequotebacktick on
	9792	@code{`}.
	9793	@set txicodequotebacktick off
	9794	@end table
	9795
	9796	If you want these settings for only part of the document,
	9797	@code{@@codequote... off} will restore the normal behavior, as in
	9798	@code{@@codequoteundirected off}.
	9799
	9800	These settings affect @code{@@code}, @code{@@example}, @code{@@kbd},
	9801	@code{@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful
	9802	Highlighting}.
	9803
	9804	@vindex txicodequoteundirected@r{, obsolete variable}
	9805	@vindex txicodequotebacktick@r{, obsolete variable}
	9806	This feature used to be controlled by using @code{@@set} to change the
	9807	values of the corresponding variables @code{txicodequoteundirected}
	9808	and @code{txicodequotebacktick}; they are still supported, but the
	9809	command interface is preferred.
	9810
	9811
	9812	@node Inserting Space
	9813	@section Inserting Space
	9814
	9815	@cindex Inserting space
	9816	@cindex Spacing, inserting
	9817	The following sections describe commands that control spacing of various
	9818	kinds within and after sentences.
	9819
	9820	@menu
	9821	* Multiple Spaces:: Inserting multiple spaces.
	9822	* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
	9823	* Ending a Sentence:: Sometimes it does.
	9824	* @code{@@frenchspacing}:: Specifying end-of-sentence spacing.
	9825	* @code{@@dmn}:: Formatting a dimension.
	9826	@end menu
	9827
	9828
	9829	@node Multiple Spaces
	9830	@subsection Multiple Spaces
	9831
	9832	@cindex Multiple spaces
	9833	@cindex Whitespace, inserting
	9834	@cindex Space, inserting horizontal
	9835	@findex <space>
	9836	@findex <tab>
	9837	@findex <newline>
	9838
	9839	Ordinarily, multiple whitespace characters (space, tab, and newline)
	9840	are collapsed into a single space.
	9841
	9842	Occasionally, you may want to produce several consecutive spaces,
	9843	either for purposes of example (e.g., what your program does with
	9844	multiple spaces as input), or merely for purposes of appearance in
	9845	headings or lists. Texinfo supports three commands:
	9846	@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all
	9847	of which insert a single space into the output. (Here,
	9848	@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
	9849	space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character,
	9850	and @code{@@@kbd{NL}} represents an @samp{@@} character and end-of-line,
	9851	i.e., when @samp{@@} is the last character on a line.)
	9852
	9853	For example,
	9854	@example
	9855	Spacey@@ @@ @@ @@
	9856	example.
	9857	@end example
	9858
	9859	@noindent produces
	9860
	9861	@example
	9862	Spacey@ @ @ @
	9863	example.
	9864	@end example
	9865
	9866	Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
	9867	@code{@@multitable} (@pxref{Multi-column Tables}).
	9868
	9869	Do not follow any of these commands with braces.
	9870
	9871	To produce a non-breakable space, see @ref{@code{@@tie}}.
	9872
	9873
	9874	@node Not Ending a Sentence
	9875	@subsection Not Ending a Sentence
	9876
	9877	@cindex Not ending a sentence
	9878	@cindex Sentence non-ending punctuation
	9879	@cindex Periods, inserting
	9880	@cindex Spacing, in the middle of sentences
	9881	When a period, exclamation point or question mark is
	9882	at the end of a sentence, slightly more space is
	9883	inserted after it in a typeset manual.
	9884
	9885	@findex <colon> @r{(suppress end-of-sentence space)}
	9886	@findex :
	9887	Usually, Texinfo can determine automatically when a period ends a
	9888	sentence. However, special commands are needed in some circumstances.
	9889	Use the @code{@@:} command after a period, question mark, exclamation
	9890	mark or colon that should not be followed by extra space. This is
	9891	necessary in the following situations:
	9892
	9893	@enumerate
	9894	@item After a period that ends a lowercase abbreviation which is not at
	9895	the end of a sentences.
	9896
	9897	@item When a parenthetical remark in the middle of a sentence (like
	9898	this one!)@: ends with a period, exclamation point or question mark,
	9899	@code{@@:} should be used after the right parenthesis. Similarly for
	9900	right brackets and right quotes (both single and double).
	9901	@end enumerate
	9902
	9903	For example:
	9904
	9905	@example
	9906	@samp{foo vs.@@: bar (or?)@@: baz},
	9907	@end example
	9908
	9909	@noindent
	9910	The first line below shows the output, and for comparison, the second
	9911	line shows the spacing when the @samp{@@:} commands were not used.
	9912
	9913	@quotation
	9914	foo vs.@: bar (or?)@: baz@*
	9915	foo vs. bar (or?) baz
	9916	@end quotation
	9917
	9918	@iftex
	9919	If you look carefully, you will see a bit of extraneous space after the
	9920	@samp{vs.}@: and @samp{(or?)}@:.
	9921	@end iftex
	9922
	9923	It may help you to remember what @code{@@:} does by imagining that it
	9924	stands for an invisible lower-case character that stops a word ending in
	9925	a period.
	9926
	9927	A few Texinfo commands force normal interword spacing, so that you
	9928	don't have to insert @code{@@:} where you otherwise would. These are
	9929	the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and
	9930	@code{@@acronym} (@pxref{Useful Highlighting}). For example, in
	9931	@samp{@@code@{foo. bar@}} the period is not considered to be the end of a
	9932	sentence, and no extra space is inserted.
	9933
	9934	@code{@@:} has no effect on the HTML or Docbook output.
	9935
	9936
	9937	@node Ending a Sentence
	9938	@subsection Ending a Sentence
	9939
	9940	@cindex Ending a Sentence
	9941	@cindex Sentence ending punctuation
	9942
	9943	@findex . @r{(end of sentence)}
	9944	@findex ! @r{(end of sentence)}
	9945	@findex ? @r{(end of sentence)}
	9946	@cindex Spacing, at ends of sentences
	9947	As mentioned above, Texinfo normally inserts additional space after
	9948	the end of a sentence. It uses the same heuristic for this as @TeX{}:
	9949	a sentence ends with a period, exclamation point, or question mark,
	9950	either preceded or followed by optional closing punctuation, and then
	9951	whitespace, and @emph{not} preceded by a capital letter.
	9952
	9953	Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
	9954	exclamation point, and @code{@@?}@: instead of a question mark at the
	9955	end of a sentence that does end with a capital letter. Do not put
	9956	braces after any of these commands. For example:
	9957
	9958	@example
	9959	Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
	9960	Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
	9961	@end example
	9962
	9963	@noindent
	9964	The output follows. In printed output and Info, you can see the
	9965	desired extra whitespace after the @samp{W} in the first line.
	9966
	9967	@quotation
	9968	Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
	9969	Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
	9970	@end quotation
	9971
	9972	In the HTML output, @code{@@.}@: is equivalent to a simple @samp{.};
	9973	likewise for @code{@@!}@: and @code{@@?}@:.
	9974
	9975	@cindex Closing punctuation, and sentence ending
	9976	The ``closing punctuation'' mentioned above is defined as a right
	9977	parenthesis (@samp{)}, right bracket (@samp{]}), or right quote,
	9978	either single or double (@samp{'} and @samp{''}; the many possible
	9979	additional Unicode right quotes are not included). These characters
	9980	can be thought of as invisible with respect to whether a given period
	9981	ends a sentence. (This is the same rule as @TeX{}.) For instance,
	9982	the periods in @samp{foo.) Bar} and @samp{foo.'' Bar} do end
	9983	sentences.
	9984
	9985	The meanings of @code{@@:} and @code{@@.}, etc.@: in Texinfo are
	9986	designed to work well with the Emacs sentence motion commands
	9987	(@pxref{Sentences,,, emacs, The GNU Emacs Manual}). It may help to
	9988	imagine that the @samp{@@} in @samp{@@.}, etc., is an invisible
	9989	lower-case letter `a' which makes an upper-case letter before it
	9990	immaterial for the purposes of deciding whether the period ends the
	9991	sentence.
	9992
	9993	A few Texinfo commands are not considered as being an abbreviation,
	9994	even though they may end with a capital letter when expanded, so that
	9995	you don't have to insert @code{@@.} and companions. Notably, this is
	9996	the case for code-like highlighting commands, @code{@@var} arguments
	9997	ending with a capital letter, @code{@@LaTeX}, and @code{@@TeX}. For
	9998	example, that sentence ended with @samp{... @@code@{@@@@TeX@}.};
	9999	@code{@@.} was not needed. Similarly, in
	10000	@code{... @@var@{VARNAME@}. Text} the period after @var{VARNAME} ends
	10001	the sentence; there is no need to use @code{@@.}.
	10002
	10003
	10004	@node @code{@@frenchspacing}
	10005	@subsection @code{@@frenchspacing} @var{val}: Control Sentence Spacing
	10006
	10007	@anchor{frenchspacing}@c old name
	10008	@findex frenchspacing
	10009	@cindex French spacing
	10010	@cindex Sentences, spacing after
	10011	@cindex Space, after sentences
	10012
	10013	In American typography, it is traditional and correct to put extra
	10014	space at the end of a sentence. This is the default in Texinfo
	10015	(implemented in Info and printed output; for HTML, we don't try to
	10016	override the browser). In French typography (and others), this extra
	10017	space is wrong; all spaces are uniform.
	10018
	10019	Therefore Texinfo provides the @code{@@frenchspacing} command to
	10020	control the spacing after punctuation. It reads the rest of the line
	10021	as its argument, which must be the single word @samp{on} or @samp{off}
	10022	(always these words, regardless of the language of the document).
	10023	Here is an example:
	10024
	10025	@example
	10026	@@frenchspacing on
	10027	This is text. Two sentences. Three sentences. French spacing.
	10028
	10029	@@frenchspacing off
	10030	This is text. Two sentences. Three sentences. Non-French spacing.
	10031	@end example
	10032
	10033	@noindent produces:
	10034
	10035	@frenchspacing on
	10036	This is text. Two sentences. Three sentences. French spacing.
	10037
	10038	@frenchspacing off
	10039	This is text. Two sentences. Three sentences. Non-French spacing.
	10040
	10041	@code{@@frenchspacing} also affects the output after @code{@@.},
	10042	@code{@@!}, and @code{@@?} (@pxref{Ending a Sentence}).
	10043
	10044	@code{@@frenchspacing} has no effect on the HTML or Docbook output;
	10045	for XML, it outputs a transliteration of itself (@pxref{Output
	10046	Formats}).
	10047
	10048
	10049	@node @code{@@dmn}
	10050	@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
	10051
	10052	@anchor{dmn}@c old name
	10053	@cindex Thin space between number, dimension
	10054	@cindex Dimension formatting
	10055	@cindex Format a dimension
	10056	@findex dmn
	10057
	10058	You can use the @code{@@dmn} command to format a dimension with a
	10059	little extra space in the printed output. That is, on seeing
	10060	@code{@@dmn}, @TeX{} inserts just enough space for proper typesetting;
	10061	in other output formats, the formatting commands insert no space at
	10062	all.
	10063
	10064	To use the @code{@@dmn} command, write the number and then follow it
	10065	immediately, with no intervening space, by @code{@@dmn}, and then by
	10066	the dimension within braces. For example,
	10067
	10068	@example
	10069	A4 paper is 8.27@@dmn@{in@} wide.
	10070	@end example
	10071
	10072	@noindent
	10073	produces
	10074
	10075	@quotation
	10076	A4 paper is 8.27@dmn{in} wide.
	10077	@end quotation
	10078
	10079	Not everyone uses this style. Some people prefer `8.27@tie{}in.'@: or
	10080	`8.27@tie{}inches'. In these cases, however, you need to use
	10081	@code{@@tie} (@pxref{@code{@@tie}}) or @code{@@w} (@pxref{@code{@@w}})
	10082	so that no line break can occur between the number and the dimension.
	10083	Also, if you write a period after an abbreviation within a sentence
	10084	(as with the `in.'@: above), you should write @samp{@@:} after the
	10085	period to prevent @TeX{} from inserting extra whitespace, as shown
	10086	here. @xref{Not Ending a Sentence}.
	10087
	10088
	10089	@node Inserting Accents
	10090	@section Inserting Accents
	10091
	10092	@cindex Inserting accents
	10093	@cindex Accents, inserting
	10094	@cindex Floating accents, inserting
	10095
	10096	Here is a table with the commands Texinfo provides for inserting
	10097	floating accents. They all need an argument, the character to accent,
	10098	which can either be given in braces as usual (@code{@@'@{e@}}), or, as
	10099	a special case, the braces can be omitted, in which case the argument
	10100	is the next character (@code{@@'e}). This is to make the source as
	10101	convenient as possible to type and read, since accented characters are
	10102	very common in some languages.
	10103
	10104	If the command is alphabetic, such as @code{@@dotaccent}, then there
	10105	must be a space between the command name and argument if braces are
	10106	not used. If the command is non-alphabetic, such as @code{@@'}, then
	10107	there must @emph{not} be a space; the argument is the very next
	10108	character.
	10109
	10110	Exception: the argument to @code{@@tieaccent} must be enclosed in
	10111	braces (since it is two characters instead of one).
	10112
	10113	To get the true accented characters output in Info, not just the ASCII
	10114	transliterations, it is necessary to specify @code{@@documentencoding}
	10115	with an encoding which supports the required characters
	10116	(@pxref{@code{@@documentencoding}}). In this case, you can also use
	10117	non-ASCII (e.g., pre-accented) characters in the source file.
	10118
	10119	@findex " @r{(umlaut accent)}
	10120	@cindex Umlaut accent
	10121	@findex ' @r{(acute accent)}
	10122	@cindex Acute accent
	10123	@findex = @r{(macron accent)}
	10124	@cindex Macron accent
	10125	@findex ^ @r{(circumflex accent)}
	10126	@cindex Circumflex accent
	10127	@findex ` @r{(grave accent)}
	10128	@cindex Grave accent
	10129	@findex ~ @r{(tilde accent)}
	10130	@cindex Tilde accent
	10131	@findex , @r{(cedilla accent)}
	10132	@cindex Cedilla accent
	10133	@findex dotaccent
	10134	@cindex Dot accent
	10135	@findex H @r{(Hungarian umlaut accent)}
	10136	@cindex Hungarian umlaut accent
	10137	@findex ogonek
	10138	@cindex Ogonek diacritic
	10139	@findex ringaccent
	10140	@cindex Ring accent
	10141	@findex tieaccent
	10142	@cindex Tie-after accent
	10143	@findex u @r{(breve accent)}
	10144	@cindex Breve accent
	10145	@findex ubaraccent
	10146	@cindex Underbar accent
	10147	@findex udotaccent
	10148	@cindex Underdot accent
	10149	@findex v @r{(caron)}
	10150	@cindex Hacek accent
	10151	@cindex Check accent
	10152	@cindex Caron
	10153	@multitable {@t{@@questiondown@{@}}} {Output} {caron/hacek/check accent}
	10154	@headitem Command @tab Output @tab What
	10155	@item @t{@@"o} @tab @"o @tab umlaut accent
	10156	@item @t{@@'o} @tab @'o @tab acute accent
	10157	@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
	10158	@item @t{@@=o} @tab @=o @tab macron/overbar accent
	10159	@item @t{@@^o} @tab @^o @tab circumflex accent
	10160	@item @t{@@`o} @tab @`o @tab grave accent
	10161	@item @t{@@~o} @tab @~o @tab tilde accent
	10162	@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
	10163	@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
	10164	@item @t{@@ogonek@{a@}} @tab @ogonek{a} @tab ogonek
	10165	@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
	10166	@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
	10167	@item @t{@@u@{o@}} @tab @u{o} @tab breve accent
	10168	@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
	10169	@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
	10170	@item @t{@@v@{o@}} @tab @v{o} @tab caron/hacek/check accent
	10171	@end multitable
	10172
	10173	This table lists the Texinfo commands for inserting other characters
	10174	commonly used in languages other than English.
	10175
	10176	@findex questiondown
	10177	@cindex @questiondown{}
	10178	@findex exclamdown
	10179	@cindex @exclamdown{}
	10180	@findex aa
	10181	@cindex @aa{}
	10182	@findex AA
	10183	@cindex @AA{}
	10184	@findex ae
	10185	@cindex @ae{}
	10186	@findex AE
	10187	@cindex @AE{}
	10188	@cindex Icelandic
	10189	@cindex Eth
	10190	@findex dh
	10191	@cindex @dh{}
	10192	@findex DH
	10193	@cindex @DH{}
	10194	@findex dotless
	10195	@cindex @dotless{i} (dotless i)
	10196	@cindex @dotless{j} (dotless j)
	10197	@cindex Dotless i, j
	10198	@findex l
	10199	@cindex @l{}
	10200	@findex L
	10201	@cindex @L{}
	10202	@findex o
	10203	@cindex @o{}
	10204	@findex O
	10205	@cindex @O{}
	10206	@findex oe
	10207	@cindex @oe{}
	10208	@findex OE
	10209	@cindex @OE{}
	10210	@cindex Romance ordinals
	10211	@cindex Ordinals, Romance
	10212	@cindex Feminine ordinal
	10213	@findex ordf
	10214	@cindex @ordf{}
	10215	@cindex Masculine ordinal
	10216	@findex ordm
	10217	@cindex @ordm{}
	10218	@findex ss
	10219	@cindex @ss{}
	10220	@cindex Es-zet
	10221	@cindex Sharp S
	10222	@cindex German S
	10223	@cindex Thorn
	10224	@findex th
	10225	@cindex @th{}
	10226	@findex TH
	10227	@cindex @TH{}
	10228	@multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S}
	10229	@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
	10230	@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
	10231	@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle
	10232	@item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures
	10233	@item @t{@@dh@{@} @@DH@{@}} @tab @dh{} @DH{} @tab Icelandic eth
	10234	@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
	10235	@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
	10236	@item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l
	10237	@item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash
	10238	@item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures
	10239	@item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals
	10240	@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
	10241	@item @t{@@th@{@} @@TH@{@}} @tab @th{} @TH{} @tab Icelandic thorn
	10242	@end multitable
	10243
	10244
	10245	@node Inserting Quotation Marks
	10246	@section Inserting Quotation Marks
	10247	@cindex Inserting quotation marks
	10248	@cindex Quotation marks, inserting
	10249
	10250	@cindex Quotation characters (`'), in source
	10251	Use doubled single-quote characters to begin and end quotations:
	10252	@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to
	10253	left- and right-hand doubled quotation marks,
	10254	@c this comes out as "like this" in Info, which is just confusing.
	10255	@iftex
	10256	``like this'',
	10257	@end iftex
	10258	and Info converts doubled single-quote characters to ASCII
	10259	double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
	10260
	10261	You may occasionally need to produce two consecutive single quotes;
	10262	for example, in documenting a computer language such as Maxima where
	10263	@t{'@w{}'} is a valid command. You can do this with the input
	10264	@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into
	10265	the double-quote characters.
	10266
	10267	@cindex Unicode quotation characters
	10268	@cindex Grave accent, vs. left quote
	10269	The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
	10270	grave accent in ANSI and ISO character set standards. We use it as a
	10271	quote character because that is how @TeX{} is set up, by default.
	10272
	10273	Texinfo supports several other quotation marks used in languages other
	10274	than English. Below is a table with the commands Texinfo provides for
	10275	inserting quotation marks.
	10276
	10277	@cindex UTF-8
	10278	@cindex ISO 8859-15
	10279	@cindex Latin 9
	10280	@cindex ISO 8859-1
	10281	@cindex Latin 1
	10282	In order to get the symbols for the quotation marks in encoded Info
	10283	output, it is necessary to specify @code{@@documentencoding UTF-8}.
	10284	(@xref{@code{@@documentencoding}}.) Double guillemets are also
	10285	present in ISO 8859-1 (aka Latin@tie{}1) and ISO 8859-15 (aka
	10286	Latin@tie{}9).
	10287
	10288	@cindex European Computer Modern fonts
	10289	@cindex EC fonts
	10290	The standard @TeX{} fonts support the usual quotation marks used in
	10291	English (the ones produced with single and doubled ASCII
	10292	single-quotes). For the other quotation marks, @TeX{} uses European
	10293	Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
	10294	These fonts are freely available, of course; you can download them
	10295	from @url{http://ctan.org/pkg/ec}, among other places.
	10296
	10297	@cindex CM-Super fonts
	10298	The free EC fonts are bitmap fonts created with Metafont. Especially
	10299	for on-line viewing, Type@tie{}1 (vector) versions of the fonts are
	10300	preferable; these are available in the CM-Super font package
	10301	(@url{http://ctan.org/pkg/cm-super}).
	10302
	10303	Both distributions include installation instructions.
	10304
	10305	@cindex Single quotation marks
	10306	@cindex Double quotation marks
	10307	@cindex Left quotation marks
	10308	@cindex Right quotation marks
	10309	@findex quotedblleft
	10310	@cindex `@w{}`
	10311	@findex quoteleft
	10312	@cindex `
	10313	@cindex " (undirected double quote character)
	10314	@findex quotedblright
	10315	@cindex '@w{}'
	10316	@findex quoteright
	10317	@cindex '
	10318	@cindex Double low-9 quotation mark
	10319	@cindex Single low-9 quotation mark
	10320	@findex quotedblbase
	10321	@cindex @quotedblbase{} (double low-9 quotation mark)
	10322	@findex quotesinglbase
	10323	@cindex @quotesinglbase{} (single low-9 quotation mark)
	10324	@cindex Angle quotation marks
	10325	@cindex Guillemets
	10326	@cindex Guillemots
	10327	@cindex French quotation marks
	10328	@cindex Quotation marks, French
	10329	@cindex German quotation marks
	10330	@cindex Quotation marks, German
	10331	@cindex Double guillemets
	10332	@cindex Single guillemets
	10333	@cindex Double angle quotation marks
	10334	@cindex Single angle quotation marks
	10335	@cindex Left-pointing angle quotation marks
	10336	@cindex Right-pointing angle quotation marks
	10337	@cindex Double left-pointing angle quotation mark
	10338	@cindex Double right-pointing angle quotation mark
	10339	@cindex Single left-pointing angle quotation mark
	10340	@cindex Single right-pointing angle quotation mark
	10341	@findex guillemetleft
	10342	@findex guillemotleft
	10343	@cindex @sortas{<<} @guillemetleft{}
	10344	@findex guillemetright
	10345	@findex guillemotright
	10346	@cindex @guillemetright{}
	10347	@findex guilsinglleft
	10348	@cindex @sortas{<} @guilsinglleft{}
	10349	@findex guilsinglright
	10350	@cindex @guilsinglright{}
	10351	@c The third column doesn't have the full text in the prototype so that
	10352	@c the Info output fits within 72 columns.
	10353	@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation}
	10354	@headitem Command @tab Glyph @tab Unicode name (point)
	10355	@item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C)
	10356	@item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D)
	10357	@item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018)
	10358	@item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019)
	10359	@item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E)
	10360	@item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A)
	10361	@item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB)
	10362	@item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB)
	10363	@item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039)
	10364	@item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A)
	10365	@end multitable
	10366
	10367	@cindex Auk, bird species
	10368	For the double angle quotation marks, Adobe and @LaTeX{} glyph names
	10369	are also supported: @code{@@guillemotleft} and
	10370	@code{@@guillemotright}. These names are incorrect; a
	10371	``guillemot'' is a bird species (a type of auk).
	10372
	10373	Traditions for quotation mark usage vary to a great extent between
	10374	languages (@url{http://en.wikipedia.org/wiki/Quotation_mark}).
	10375	Texinfo does not provide commands or configurations for typesetting
	10376	quotation marks according to the numerous traditions. Therefore, you
	10377	have to choose the commands appropriate for the language of your
	10378	manual. Sometimes aliases (@pxref{@code{@@alias}}) can simplify the
	10379	usage and make the source code more readable. For example, in German,
	10380	@code{@@quotedblbase} is used for the left double quote, and the right
	10381	double quote is the glyph produced by @code{@@quotedblleft}, which is
	10382	counter-intuitive. Thus, in this case the following aliases would be
	10383	convenient:
	10384
	10385	@example
	10386	@@alias lgqq = quotedblbase
	10387	@@alias rgqq = quotedblleft
	10388	@end example
	10389
	10390
	10391	@node Inserting Subscripts and Superscripts
	10392	@section @code{@@sub} and @code{@@sup}: Inserting Subscripts and Superscripts
	10393
	10394	@findex sub
	10395	@findex sup
	10396	@cindex Subscripts and superscripts, text
	10397
	10398	You can insert subscripts and superscripts, in either text or math,
	10399	with the @code{@@sub} and @code{@@sup} commands. (For other
	10400	mathematical expressions, see the next section.) For example, here is
	10401	a purely textual subscript and superscript:
	10402
	10403	@example
	10404	here@@sub@{below@}@@sup@{above@}
	10405	@end example
	10406
	10407	@noindent produces:
	10408
	10409	@display
	10410	here@sub{below}@sup{above}
	10411	@end display
	10412
	10413	@cindex Math italic font
	10414	Inside @code{@@math}, @code{@@sub} and @code{@@sup} produce
	10415	mathematical subscripts and superscripts. This uses a different font
	10416	in the @TeX{} output (math italic instead of text italic); it makes no
	10417	difference in the other output formats. Here's an example:
	10418
	10419	@example
	10420	@@math@{e@@sup@{x@}@}
	10421	@end example
	10422
	10423	@noindent produces:
	10424
	10425	@display
	10426	@math{e@sup{x}}
	10427	@end display
	10428
	10429	In Info and plain text, regardless of being used inside @code{@@math},
	10430	@code{@@sub@{@var{text}@}} is output as @samp{_@{@var{text}@}} and
	10431	@code{@@sup@{@var{text}@}} as @samp{^@{@var{text}@}}, including the
	10432	literal braces (to mark the beginning and end of the ``script'' text
	10433	to the reader).
	10434
	10435	When the output format (and display program) permit (@TeX{} math,
	10436	HTML), the superscript is set above the subscript when both commands
	10437	are given consecutively.
	10438
	10439
	10440	@node Inserting Math
	10441	@section @code{@@math}: Inserting Mathematical Expressions
	10442
	10443	@anchor{math}@c old name
	10444	@findex math
	10445	@cindex Mathematical expressions, inserting
	10446	@cindex Formulas, mathematical
	10447
	10448	You can write a short mathematical expression with the @code{@@math}
	10449	command. Write the mathematical expression between braces, like this:
	10450
	10451	@example
	10452	@@math@{(a + b) = (b + a)@}
	10453	@end example
	10454
	10455	@iftex
	10456	@noindent This produces the following in @TeX{}:
	10457
	10458	@display
	10459	@math{(a + b) = (b + a)}
	10460	@end display
	10461
	10462	@noindent and the following in other formats:
	10463	@end iftex
	10464	@ifnottex
	10465	@noindent This produces the following in Info and HTML:
	10466	@end ifnottex
	10467
	10468	@example
	10469	(a + b) = (b + a)
	10470	@end example
	10471
	10472	@cindex MathML, not used
	10473	The @code{@@math} command has no special effect on the Info and HTML
	10474	output. @command{makeinfo} expands any @@-commands as usual, but it
	10475	does not try to use produce good mathematical formatting in any way
	10476	(no use of MathML, etc.). The HTML output is enclosed by
	10477	@code{<em>...</em>}, but nothing more.
	10478
	10479	@findex \mathopsup
	10480	However, as far as the @TeX{} output is concerned, plain @TeX{}
	10481	mathematical commands are allowed in @code{@@math}, starting with
	10482	@samp{\}. In essence, @code{@@math} switches into plain @TeX{} math
	10483	mode. (Exception: the plain @TeX{} command @code{\sup}, which
	10484	typesets the mathematical operator name `sup', must be accessed as
	10485	@code{\mathopsup}, due to the conflict with Texinfo's @code{@@sup}
	10486	command.)
	10487
	10488	This allows you to use all the plain @TeX{} math control sequences for
	10489	symbols, functions, and so on, and thus get proper formatting in the
	10490	@TeX{} output, at least.
	10491
	10492	The @code{@@sub} and @code{@@sup} commands described in the previous
	10493	section produce subscripts and superscripts in HTML output as well as
	10494	@TeX{}; the plain @TeX{} characters @code{_} and @code{^} for
	10495	subscripts and superscripts are recognized by @TeX{} inside
	10496	@code{@@math}, but do nothing special in HTML or other output formats.
	10497
	10498	It's best to use @samp{\} instead of @samp{@@} for any such
	10499	mathematical commands; otherwise, @command{makeinfo} will complain.
	10500	On the other hand, @command{makeinfo} does allow input with matching
	10501	(but unescaped) braces, such as @samp{k_@{75@}}; it complains about
	10502	such bare braces in regular input.
	10503
	10504	Here's an example:
	10505
	10506	@example
	10507	@@math@{\sin 2\pi \equiv \cos 3\pi@}
	10508	@end example
	10509
	10510	@iftex
	10511	@noindent which looks like this in @TeX{}:
	10512	@display
	10513	@math{\sin 2\pi \equiv \cos 3\pi}
	10514	@end display
	10515
	10516	@noindent but
	10517	@end iftex
	10518	@noindent which looks like the input in Info and HTML:
	10519	@example
	10520	\sin 2\pi \equiv \cos 3\pi
	10521	@end example
	10522
	10523	@findex @sortas{\} \ @r{(literal \ in @code{@@math})}
	10524	Since @samp{\} is an escape character inside @code{@@math}, you can
	10525	use @code{@@\} to get a literal backslash (@code{\\} will work in
	10526	@TeX{}, but you'd get the literal two characters @samp{\\} in Info).
	10527	@code{@@\} is not defined outside of @code{@@math}, since a @samp{\}
	10528	ordinarily produces a literal (typewriter) @samp{\}. You can also use
	10529	@code{@@backslashchar@{@}} in any mode to get a typewriter backslash.
	10530	@xref{Inserting a Backslash}.
	10531
	10532	@cindex Displayed equations
	10533	@cindex Equations, displayed
	10534	For displayed equations, you must at present use @TeX{} directly
	10535	(@pxref{Raw Formatter Commands}).
	10536
	10537
	10538	@node Glyphs for Text
	10539	@section Glyphs for Text
	10540
	10541	@anchor{Glyphs}@c old name
	10542	@anchor{TeX and copyright}@c another old node, now split into two
	10543	@cindex Glyphs for text
	10544	@cindex Textual glyphs
	10545
	10546	Texinfo has support for a few additional glyphs that are commonly used
	10547	in printed text but not available in ASCII@. Of course, there are
	10548	many thousands more. It is possible to use Unicode characters as-is
	10549	as far as @code{makeinfo} is concerned, but @TeX{} is not so lucky.
	10550
	10551	@menu
	10552	* @code{@@TeX @@LaTeX}:: The @TeX{} logos.
	10553	* @code{@@copyright}:: The copyright symbol (c in a circle).
	10554	* @code{@@registeredsymbol}:: The registered symbol (R in a circle).
	10555	* @code{@@dots}:: How to insert ellipses: @dots{} and @enddots{}
	10556	* @code{@@bullet}:: How to insert a bullet: @bullet{}
	10557	* @code{@@euro}:: How to insert the euro currency symbol.
	10558	* @code{@@pounds}:: How to insert the pounds currency symbol.
	10559	* @code{@@textdegree}:: How to insert the degrees symbol.
	10560	* @code{@@minus}:: How to insert a minus sign.
	10561	* @code{@@geq @@leq}:: How to insert greater/less-than-or-equal signs.
	10562	@end menu
	10563
	10564
	10565	@node @code{@@TeX @@LaTeX}
	10566	@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{})
	10567
	10568	@anchor{tex}@c old name
	10569	@findex TeX
	10570	@findex LaTeX
	10571	@cindex Logos, @TeX{}
	10572	@cindex @TeX{} logo
	10573	@cindex @LaTeX{} logo
	10574
	10575	Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
	10576	manual, this is a special logo that is different from three ordinary
	10577	letters. In Info, it just looks like @samp{TeX}.
	10578
	10579	Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}',
	10580	which is even more special in printed manuals (and different from the
	10581	incorrect @code{La@@TeX@{@}}. In Info, the result is just
	10582	@samp{LaTeX}. (@LaTeX{} is another macro package built on top of
	10583	@TeX{}, very loosely analogous to Texinfo in that it emphasizes
	10584	logical structure, but much (much) larger.)
	10585
	10586	The spelling of these commands are unusual for Texinfo, in that they
	10587	use both uppercase and lowercase letters.
	10588
	10589
	10590	@node @code{@@copyright}
	10591	@subsection @code{@@copyright@{@}} (@copyright{})
	10592
	10593	@anchor{copyright symbol}@c old name
	10594	@findex copyright
	10595	@cindex Copyright symbol
	10596
	10597	Use the @code{@@copyright@{@}} command to generate the copyright
	10598	symbol, `@copyright{}'. Where possible, this is a @samp{c} inside a
	10599	circle; in Info, this is @samp{(C)}.
	10600
	10601	Legally, it's not necessary to use the copyright symbol; the English
	10602	word `Copyright' suffices, according to international treaty.
	10603
	10604
	10605	@node @code{@@registeredsymbol}
	10606	@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{})
	10607
	10608	@anchor{registered symbol}@c old name
	10609	@findex registeredsymbol
	10610	@cindex Registered symbol
	10611
	10612	Use the @code{@@registeredsymbol@{@}} command to generate the
	10613	registered symbol, `@registeredsymbol{}'. Where possible, this is an
	10614	@samp{R} inside a circle; in Info, this is @samp{(R)}.
	10615
	10616
	10617	@node @code{@@dots}
	10618	@subsection @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{})
	10619
	10620	@anchor{dots}@c old name
	10621	@findex dots
	10622	@findex enddots
	10623	@cindex Inserting dots
	10624	@cindex Inserting ellipsis
	10625	@cindex Dots, inserting
	10626	@cindex Ellipsis, inserting
	10627
	10628	@anchor{Dots Bullets}@c old name
	10629
	10630	An @dfn{ellipsis} (a sequence of dots) would be spaced wrong when
	10631	typeset as a string of periods, so a special command is used in
	10632	Texinfo: use the @code{@@dots@{@}} command to generate a normal
	10633	ellipsis, which is three dots in a row, appropriately spaced @dots{}
	10634	like so. To emphasize: do not simply write three periods in the input
	10635	file; that would work for the Info file output, but would produce the
	10636	wrong amount of space between the periods in the printed manual.
	10637
	10638	The @code{@@enddots@{@}} command generates an end-of-sentence
	10639	ellipsis, which also has three dots, but with different spacing
	10640	afterwards, @enddots{} Look closely to see the difference.
	10641
	10642	Here is an ellipsis: @dots{}
	10643	Here are three periods in a row: ...
	10644
	10645	In printed (and usually HTML) output, the three periods in a row are
	10646	much closer together than the dots in the ellipsis.
	10647
	10648
	10649	@node @code{@@bullet}
	10650	@subsection @code{@@bullet} (@bullet{})
	10651
	10652	@anchor{bullet}@c old name
	10653	@findex bullet
	10654
	10655	Use the @code{@@bullet@{@}} command to generate a large round dot, or
	10656	the closest possible thing to one. In Info, an asterisk is used.
	10657	Here is a bullet: @bullet{}
	10658
	10659	When you use @code{@@bullet} in @code{@@itemize}, you do not need to
	10660	type the braces, because @code{@@itemize} supplies them.
	10661	(@pxref{@code{@@itemize}}).
	10662
	10663
	10664	@node @code{@@euro}
	10665	@subsection @code{@@euro} (@euro{}): Euro Currency Symbol
	10666
	10667	@anchor{euro}@c old name
	10668	@findex euro
	10669	@cindex Euro symbol, producing
	10670
	10671	Use the @code{@@euro@{@}} command to generate `@euro{}'. Where
	10672	possible, this is the symbol for the Euro currency. Otherwise, the
	10673	word @samp{Euro} is used.
	10674
	10675	Texinfo cannot magically synthesize support for the Euro symbol where
	10676	the underlying system (fonts, software, whatever) does not support it.
	10677	Therefore, you may find it preferable to use the word ``Euro''. (In
	10678	banking contexts, the abbreviation for the Euro is EUR@.)
	10679
	10680	@cindex ISO 8859-15, and Euro
	10681	@cindex Latin 9, and Euro
	10682	In order to get the Euro symbol in encoded Info output, for example,
	10683	it is necessary to specify @code{@@documentencoding ISO-8859-15} or
	10684	@code{@@documentencoding UTF-8} (@xref{@code{@@documentencoding}}.)
	10685	The Euro symbol is in ISO 8859-15 (aka Latin@tie{}9), and is
	10686	@emph{not} in the more widely-used ISO 8859-1 (Latin@tie{}1).
	10687
	10688	@pindex feymr10
	10689	@cindex Euro font
	10690	The Euro symbol does not exist in the standard @TeX{} fonts (which
	10691	were designed before the Euro was legislated into existence).
	10692	Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
	10693	with other variables). It is freely available, of course; you can
	10694	download it from @url{http://ctan.org/pkg/eurosym}, among other
	10695	places. The distribution includes installation instructions.
	10696
	10697
	10698	@node @code{@@pounds}
	10699	@subsection @code{@@pounds} (@pounds{}): Pounds Sterling
	10700
	10701	@anchor{pounds}@c old name
	10702	@findex pounds
	10703	@cindex Pounds symbol
	10704
	10705	Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where
	10706	possible, this is the symbol for the pounds sterling British currency.
	10707	Otherwise, it is @samp{#}.
	10708
	10709
	10710	@node @code{@@textdegree}
	10711	@subsection @code{@@textdegree} (@textdegree{}): Degrees Symbol
	10712
	10713	@anchor{textdegree}@c old name
	10714	@findex textdegree
	10715	@cindex Degree symbol
	10716
	10717	Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'.
	10718	Where possible, this is the normal symbol for degrees. Otherwise,
	10719	it is an @samp{o}.
	10720
	10721
	10722	@node @code{@@minus}
	10723	@subsection @code{@@minus} (@minus{}): Inserting a Minus Sign
	10724
	10725	@anchor{minus}@c old name
	10726	@findex minus
	10727	@cindex Minus sign
	10728
	10729	@cindex Em dash, compared to minus sign
	10730	@cindex Hyphen, compared to minus
	10731	Use the @code{@@minus@{@}} command to generate a minus sign. In a
	10732	fixed-width font, this is a single hyphen, but in a proportional font,
	10733	the symbol is the customary length for a minus sign---a little longer
	10734	than a hyphen, shorter than an em-dash:
	10735
	10736	@display
	10737	@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
	10738
	10739	`-' is a hyphen generated with the character @samp{-},
	10740
	10741	`---' is an em-dash for text.
	10742	@end display
	10743
	10744	@noindent
	10745	In the fixed-width font used by Info, @code{@@minus@{@}} is the same
	10746	as a hyphen.
	10747
	10748	You should not use @code{@@minus@{@}} inside @code{@@code} or
	10749	@code{@@example} because the width distinction is not made in the
	10750	fixed-width font they use.
	10751
	10752	When you use @code{@@minus} to specify the mark beginning each entry
	10753	in an itemized list, you do not need to type the braces
	10754	(@pxref{@code{@@itemize}}).
	10755
	10756	If you actually want to typeset some math that does a subtraction, it
	10757	is better to use @code{@@math}. Then the regular @samp{-} character
	10758	produces a minus sign, as in @code{@@math@{a-b@}} (@pxref{Inserting
	10759	Math}).
	10760
	10761
	10762	@node @code{@@geq @@leq}
	10763	@subsection @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting Relations
	10764
	10765	@anchor{geq leq}@c old name
	10766	@findex geq
	10767	@findex leq
	10768
	10769	Use the @code{@@geq@{@}} and @code{@@leq@{@}} commands to generate
	10770	greater-than-or-equal and less-than-equal-signs, `@geq{}' and
	10771	`@leq{}'. When those symbols are not available, the ASCII sequences
	10772	@samp{>=} and @samp{<=} are output.
	10773
	10774
	10775	@node Glyphs for Programming
	10776	@section Glyphs for Programming
	10777
	10778	@cindex Glyphs for programming
	10779	@cindex Examples, glyphs for
	10780	@cindex Programming, glyphs for
	10781
	10782	In Texinfo, code is often illustrated in examples that are delimited
	10783	by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
	10784	@code{@@end lisp}. In such examples, you can indicate the results of
	10785	evaluation or an expansion using @samp{@result{}} or
	10786	@samp{@expansion{}}. Likewise, there are commands to insert glyphs to
	10787	indicate printed output, error messages, equivalence of expressions,
	10788	the location of point in an editor, and GUI operation sequences.
	10789
	10790	The glyph-insertion commands do not need to be used within an example,
	10791	but most often they are. All glyph-insertion commands are followed by
	10792	empty braces.
	10793
	10794	@menu
	10795	* Glyphs Summary::
	10796	* @code{@@result}:: How to show the result of expression.
	10797	* @code{@@expansion}:: How to indicate an expansion.
	10798	* @code{@@print}:: How to indicate generated output.
	10799	* @code{@@error}:: How to indicate an error message.
	10800	* @code{@@equiv}:: How to indicate equivalence.
	10801	* @code{@@point}:: How to indicate the location of point.
	10802	* Click Sequences:: Inserting GUI usage sequences.
	10803	@end menu
	10804
	10805
	10806	@node Glyphs Summary
	10807	@subsection Glyphs Summary
	10808
	10809	Here is a summary of the glyph commands:
	10810
	10811	@table @asis
	10812	@item @result{}
	10813	@code{@@result@{@}} indicates the result of an expression.
	10814
	10815	@item @expansion{}
	10816	@code{@@expansion@{@}} indicates the results of a macro expansion.
	10817
	10818	@item @print{}
	10819	@code{@@print@{@}} indicates printed output.
	10820
	10821	@item @error{}
	10822	@code{@@error@{@}} indicates the following text is an error message.
	10823
	10824	@item @equiv{}
	10825	@code{@@equiv@{@}} indicates the exact equivalence of two forms.
	10826
	10827	@item @point{}
	10828	@code{@@point@{@}} shows the location of point.
	10829
	10830	@item @clicksequence{A @click{} B}
	10831	@code{@@clicksequence@{A @@click@{@} B} indicates a GUI operation
	10832	sequence: first A, then clicking B, or choosing B from a menu, or
	10833	otherwise selecting it.
	10834	@end table
	10835
	10836
	10837	@node @code{@@result}
	10838	@subsection @code{@@result@{@}} (@result{}): Result of an Expression
	10839
	10840	@anchor{result}@c old name
	10841	@findex result
	10842	@cindex Result of an expression
	10843	@cindex Indicating evaluation
	10844	@cindex Evaluation glyph
	10845	@cindex Value of an expression, indicating
	10846
	10847	Use the @code{@@result@{@}} command to indicate the result of
	10848	evaluating an expression.
	10849
	10850	The @code{@@result@{@}} command is displayed as @samp{@result{}},
	10851	either a double stemmed arrow or (when that is not available) the
	10852	ASCII sequence @samp{=>}.
	10853
	10854	Thus, the following,
	10855
	10856	@lisp
	10857	(cdr '(1 2 3))
	10858	@result{} (2 3)
	10859	@end lisp
	10860
	10861	@noindent
	10862	may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
	10863
	10864
	10865	@node @code{@@expansion}
	10866	@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
	10867
	10868	@anchor{expansion}@c old name
	10869	@cindex Expansion, indicating
	10870	@cindex Macro expansion, indicating
	10871	@findex expansion
	10872
	10873	When an expression is a macro call, it expands into a new expression.
	10874	You can indicate the result of the expansion with the
	10875	@code{@@expansion@{@}} command.
	10876
	10877	The @code{@@expansion@{@}} command is displayed as
	10878	@samp{@expansion{}}, either a long arrow with a flat base or (when
	10879	that is not available) the ASCII sequence @samp{==>}.
	10880
	10881	@need 700
	10882	For example, the following
	10883
	10884	@example
	10885	@group
	10886	@@lisp
	10887	(third '(a b c))
	10888	@@expansion@{@} (car (cdr (cdr '(a b c))))
	10889	@@result@{@} c
	10890	@@end lisp
	10891	@end group
	10892	@end example
	10893
	10894	@noindent
	10895	produces
	10896
	10897	@lisp
	10898	@group
	10899	(third '(a b c))
	10900	@expansion{} (car (cdr (cdr '(a b c))))
	10901	@result{} c
	10902	@end group
	10903	@end lisp
	10904
	10905	@noindent
	10906	which may be read as:
	10907
	10908	@quotation
	10909	@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
	10910	the result of evaluating the expression is @code{c}.
	10911	@end quotation
	10912
	10913	@noindent
	10914	Often, as in this case, an example looks better if the
	10915	@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented.
	10916
	10917
	10918	@node @code{@@print}
	10919	@subsection @code{@@print@{@}} (@print{}): Indicating Generated Output
	10920
	10921	@anchor{Print Glyph}@c old name
	10922	@findex print
	10923	@cindex Printed output, indicating
	10924
	10925	Sometimes an expression will generate output during its execution.
	10926	You can indicate such displayed output with the @code{@@print@{@}}
	10927	command.
	10928
	10929	The @code{@@print@{@}} command is displayed as @samp{@print{}}, either
	10930	a horizontal dash butting against a vertical bar or (when that is not
	10931	available) the ASCII sequence @samp{-\|}.
	10932
	10933	In the following example, the printed text is indicated with
	10934	@samp{@print{}}, and the value of the expression follows on the
	10935	last line.
	10936
	10937	@lisp
	10938	@group
	10939	(progn (print 'foo) (print 'bar))
	10940	@print{} foo
	10941	@print{} bar
	10942	@result{} bar
	10943	@end group
	10944	@end lisp
	10945
	10946	@noindent
	10947	In a Texinfo source file, this example is written as follows:
	10948
	10949	@lisp
	10950	@group
	10951	@@lisp
	10952	(progn (print 'foo) (print 'bar))
	10953	@@print@{@} foo
	10954	@@print@{@} bar
	10955	@@result@{@} bar
	10956	@@end lisp
	10957	@end group
	10958	@end lisp
	10959
	10960
	10961	@node @code{@@error}
	10962	@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
	10963
	10964	@anchor{Error Glyph}@c old name
	10965	@cindex Error message, indicating
	10966	@findex error
	10967
	10968	A piece of code may cause an error when you evaluate it. You can
	10969	designate the error message with the @code{@@error@{@}} command.
	10970
	10971	The @code{@@error@{@}} command is displayed as @samp{@error{}}, either
	10972	the word `error' in a box in the printed output, the word error
	10973	followed by an arrow in other formats or (when no arrow is available)
	10974	@samp{error-->}.
	10975
	10976	@need 700
	10977	Thus,
	10978
	10979	@example
	10980	@@lisp
	10981	(+ 23 'x)
	10982	@@error@{@} Wrong type argument: integer-or-marker-p, x
	10983	@@end lisp
	10984	@end example
	10985
	10986	@noindent
	10987	produces
	10988
	10989	@lisp
	10990	(+ 23 'x)
	10991	@error{} Wrong type argument: integer-or-marker-p, x
	10992	@end lisp
	10993
	10994	@noindent
	10995	This indicates that the following error message is printed
	10996	when you evaluate the expression:
	10997
	10998	@lisp
	10999	Wrong type argument: integer-or-marker-p, x
	11000	@end lisp
	11001
	11002	The word @samp{@error{}} itself is not part of the error message.
	11003
	11004
	11005	@node @code{@@equiv}
	11006	@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
	11007
	11008	@anchor{Equivalence}@c oldname
	11009	@cindex Equivalence, indicating
	11010	@findex equiv
	11011
	11012	Sometimes two expressions produce identical results. You can indicate
	11013	the exact equivalence of two forms with the @code{@@equiv@{@}}
	11014	command. The @code{@@equiv@{@}} command is displayed as
	11015	@samp{@equiv{}}, either a standard mathematical equivalence sign
	11016	(three parallel horizontal lines) or (when that is not available) as
	11017	the ASCII sequence @samp{==}.
	11018
	11019	Thus,
	11020
	11021	@example
	11022	@@lisp
	11023	(make-sparse-keymap) @@equiv@{@} (list 'keymap)
	11024	@@end lisp
	11025	@end example
	11026
	11027	@noindent
	11028	produces
	11029
	11030	@lisp
	11031	(make-sparse-keymap) @equiv{} (list 'keymap)
	11032	@end lisp
	11033
	11034	@noindent
	11035	This indicates that evaluating @code{(make-sparse-keymap)} produces
	11036	identical results to evaluating @code{(list 'keymap)}.
	11037
	11038
	11039	@node @code{@@point}
	11040	@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
	11041
	11042	@anchor{Point Glyph}@c old name
	11043	@cindex Point, indicating in a buffer
	11044	@findex point
	11045
	11046	Sometimes you need to show an example of text in an Emacs buffer. In
	11047	such examples, the convention is to include the entire contents of the
	11048	buffer in question between two lines of dashes containing the buffer
	11049	name.
	11050
	11051	You can use the @samp{@@point@{@}} command to show the location of
	11052	point in the text in the buffer. (The symbol for point, of course, is
	11053	not part of the text in the buffer; it indicates the place
	11054	@emph{between} two characters where point is located.)
	11055
	11056	The @code{@@point@{@}} command is displayed as @samp{@point{}}, either
	11057	a pointed star or (when that is not available) the ASCII sequence
	11058	@samp{-!-}.
	11059
	11060	The following example shows the contents of buffer @file{foo} before
	11061	and after evaluating a Lisp command to insert the word @code{changed}.
	11062
	11063	@example
	11064	@group
	11065	---------- Buffer: foo ----------
	11066	This is the @point{}contents of foo.
	11067	---------- Buffer: foo ----------
	11068
	11069	@end group
	11070	@end example
	11071
	11072	@example
	11073	@group
	11074	(insert "changed ")
	11075	@result{} nil
	11076	---------- Buffer: foo ----------
	11077	This is the changed @point{}contents of foo.
	11078	---------- Buffer: foo ----------
	11079
	11080	@end group
	11081	@end example
	11082
	11083	In a Texinfo source file, the example is written like this:
	11084
	11085	@example
	11086	@@example
	11087	---------- Buffer: foo ----------
	11088	This is the @@point@{@}contents of foo.
	11089	---------- Buffer: foo ----------
	11090
	11091	(insert "changed ")
	11092	@@result@{@} nil
	11093	---------- Buffer: foo ----------
	11094	This is the changed @@point@{@}contents of foo.
	11095	---------- Buffer: foo ----------
	11096	@@end example
	11097	@end example
	11098
	11099
	11100	@node Click Sequences
	11101	@subsection Click Sequences
	11102
	11103	@cindex Click sequences
	11104	@cindex Sequence of clicks
	11105	@cindex GUI click sequence
	11106
	11107	@findex clicksequence
	11108	When documenting graphical interfaces, it is necessary to describe
	11109	sequences such as `Click on @samp{File}, then choose @samp{Open}, then
	11110	@dots{}'. Texinfo offers commands @code{@@clicksequence} and
	11111	@code{click} to represent this, typically used like this:
	11112
	11113	@example
	11114	@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
	11115	@end example
	11116
	11117	@noindent
	11118	which produces:
	11119
	11120	@display
	11121	@dots{} @clicksequence{File @click{} Open} @dots{}
	11122	@end display
	11123
	11124	@findex click
	11125	@findex arrow
	11126	The @code{@@click} command produces a right arrow by default; this
	11127	glyph is also available independently via the command
	11128	@code{@@arrow@{@}}.
	11129
	11130	@findex clickstyle
	11131	You can change the glyph produced by @code{@@click} with the command
	11132	@code{@@clickstyle}, which takes a command name as its single argument
	11133	on the rest of the line, much like @code{@@itemize} and friends
	11134	(@pxref{@code{@@itemize}}). The command should produce a glyph, and
	11135	the usual empty braces @samp{@{@}} are omitted. Here's an example:
	11136
	11137	@example
	11138	@@clickstyle @@result
	11139	@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
	11140	@end example
	11141
	11142	@noindent
	11143	now produces:
	11144
	11145	@display
	11146	@clickstyle @result
	11147	@dots{} @clicksequence{File @click{} Open} @dots{}
	11148	@end display
	11149
	11150
	11151	@node Inserting Unicode
	11152	@section Inserting Unicode: @code{@@U}
	11153
	11154	@cindex Unicode character, inserting
	11155	@cindex Code point of Unicode character, inserting by
	11156	@findex U
	11157
	11158	The command @code{@@U@{@var{hex}@}} inserts a representation of the
	11159	Unicode character U+@var{hex}. For example, @code{@@U@{0132@}}
	11160	inserts the Dutch `IJ' ligature (`@U{0132}').
	11161
	11162	The @var{hex} value should be at least four hex digits; leading zeros
	11163	are @emph{not} added. In general, @var{hex} must specify a valid
	11164	normal Unicode character; e.g., U+10FFFF (the very last code point) is
	11165	invalid by definition, and thus cannot be inserted this way.
	11166
	11167	@cindex ASCII, source document portability using
	11168	@code{@@U} is useful for inserting occasional glyphs for which Texinfo
	11169	has no dedicated command, while allowing the Texinfo source to remain
	11170	purely 7-bit ASCII for maximum portability.
	11171
	11172	@cindex Unicode and @TeX{}
	11173	This command has many limitations---the same limitations as inserting
	11174	Unicode characters in UTF-8 or another binary form. First and most
	11175	importantly, @TeX{} knows nothing about most of Unicode. Supporting
	11176	specific additional glyphs upon request is possible, but it's not
	11177	viable for @file{texinfo.tex} to support whole additional scripts
	11178	(Japanese, Urdu, @dots{}). The @code{@@U} command does nothing to
	11179	change this. If the specified character is not supported in @TeX{},
	11180	an error is given. (@xref{@code{@@documentencoding}}.)
	11181
	11182	@cindex Entity reference in HTML et al.
	11183	@cindex @samp{&#x@var{hex};}, output from @code{@@U}
	11184	In HTML, XML, and Docbook, the output from @code{@@U} is always an
	11185	entity reference of the form @samp{&#x@var{hex};}, as in
	11186	@samp{Ĳ} for the example above. This should work even when an
	11187	HTML document uses some other encoding (say, Latin@tie{}1) and the
	11188	given character is not supported in that encoding.
	11189
	11190	In Info and plain text, if the output encoding is not UTF-8, the output
	11191	is the ASCII sequence @samp{U+@var{hex}}, as in the six ASCII characters
	11192	@samp{U+0132} for the example above.
	11193
	11194
	11195	@node Breaks
	11196	@chapter Forcing and Preventing Breaks
	11197
	11198	@cindex Forcing line and page breaks
	11199	@cindex Making line and page breaks
	11200	@cindex Preventing line and page breaks
	11201	@cindex Line breaks, awkward
	11202	@cindex Page breaks, awkward
	11203
	11204	Line and page breaks can sometimes occur in the `wrong' place in one
	11205	or another form of output. It's up to you to ensure that text looks
	11206	right in all the output formats.
	11207
	11208	For example, in a printed manual, page breaks may occur awkwardly in
	11209	the middle of an example; to prevent this, you can hold text together
	11210	using a grouping command that keeps the text from being split across
	11211	two pages. Conversely, you may want to force a page break where none
	11212	would occur normally.
	11213
	11214	You can use the break, break prevention, or pagination commands to fix
	11215	problematic line and page breaks.
	11216
	11217	@menu
	11218	* Break Commands:: Summary of break-related commands.
	11219	* Line Breaks:: Forcing line breaks.
	11220	* @code{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
	11221	* @code{@@allowcodebreaks}:: Controlling line breaks within @@code text.
	11222	* @code{@@w}:: Preventing unwanted line breaks in text.
	11223	* @code{@@tie}:: Inserting an unbreakable but varying space.
	11224	* @code{@@sp}:: Inserting blank lines.
	11225	* @code{@@page}:: Forcing the start of a new page.
	11226	* @code{@@group}:: Preventing unwanted page breaks.
	11227	* @code{@@need}:: Another way to prevent unwanted page breaks.
	11228	@end menu
	11229
	11230
	11231	@node Break Commands
	11232	@section Break Commands
	11233
	11234	The break commands create or allow line and paragraph breaks:
	11235
	11236	@table @code
	11237	@item @@*
	11238	Force a line break.
	11239
	11240	@item @@sp @var{n}
	11241	Skip @var{n} blank lines.
	11242
	11243	@item @@-
	11244	Insert a discretionary hyphen.
	11245
	11246	@item @@hyphenation@{@var{hy-phen-a-ted words}@}
	11247	Define hyphen points in @var{hy-phen-a-ted words}.
	11248	@end table
	11249
	11250	These commands hold text together on a single line:
	11251
	11252	@table @code
	11253	@item @@w@{@var{text}@}
	11254	Prevent @var{text} from being split and hyphenated across two lines.
	11255
	11256	@item @@tie@{@}
	11257	Insert a normal interword space at which a line break may not occur.
	11258	@end table
	11259
	11260	The pagination commands apply only to printed output, since other
	11261	output formats do not have pages.
	11262
	11263	@table @code
	11264	@item @@page
	11265	Start a new page.
	11266
	11267	@item @@group
	11268	Hold text together that must appear on one page.
	11269
	11270	@item @@need @var{mils}
	11271	Start a new page if not enough space on this one.
	11272	@end table
	11273
	11274
	11275	@node Line Breaks
	11276	@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks
	11277
	11278	@findex * @r{(force line break)}
	11279	@findex / @r{(allow line break)}
	11280	@cindex Line breaks, controlling
	11281	@cindex Controlling line breaks
	11282	@cindex Breaks in a line
	11283	@cindex Force line break
	11284	@cindex Allow line break
	11285
	11286	The @code{@@*} command forces a line break in all output formats.
	11287	The @code{@@/} command allows a line break (printed manual only).
	11288
	11289	Here is an example with @code{@@*}:
	11290
	11291	@example
	11292	This sentence is broken @@*into two lines.
	11293	@end example
	11294
	11295	@noindent produces
	11296
	11297	@example
	11298	@group
	11299	This sentence is broken
	11300	into two lines.
	11301	@end group
	11302	@end example
	11303
	11304	The @code{@@/} command can be useful within long urls or other
	11305	identifiers where @TeX{} can't find a good place to break. @TeX{}
	11306	will automatically break urls at the natural places (@pxref{URL Line
	11307	Breaking}), so only use @code{@@/} if you need it. @code{@@/} has no
	11308	effect in the other output format.
	11309
	11310
	11311	@node @code{@@- @@hyphenation}
	11312	@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
	11313
	11314	@anchor{- and hyphenation}@c old name
	11315	@findex @sortas{-} - @r{(discretionary hyphen)}
	11316	@findex hyphenation
	11317	@cindex Hyphenation, helping @TeX{} do
	11318	@cindex Fine-tuning, and hyphenation
	11319
	11320	Although @TeX{}'s hyphenation algorithm is generally pretty good, it
	11321	does miss useful hyphenation points from time to time. (Or, far more
	11322	rarely, insert an incorrect hyphenation.) So, for documents with an
	11323	unusual vocabulary or when fine-tuning for a printed edition, you may
	11324	wish to help @TeX{} out. Texinfo supports two commands for this:
	11325
	11326	@table @code
	11327	@item @@-
	11328	Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
	11329	not have to) hyphenate. This is especially useful when you notice an
	11330	overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
	11331	hboxes}). @TeX{} will not insert any hyphenation points itself into a
	11332	word containing @code{@@-}.
	11333
	11334	@item @@hyphenation@{@var{hy-phen-a-ted words}@}
	11335	Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
	11336	put a @samp{-} at each hyphenation point. For example:
	11337	@example
	11338	@@hyphenation@{man-u-script man-u-scripts@}
	11339	@end example
	11340	@noindent @TeX{} only uses the specified hyphenation points when the
	11341	words match exactly, so give all necessary variants, such as plurals.
	11342	@end table
	11343
	11344	Info, HTML, and other non-@TeX{} output is not hyphenated, so none of
	11345	these commands have any effect there.
	11346
	11347
	11348	@node @code{@@allowcodebreaks}
	11349	@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
	11350
	11351	@anchor{allowcodebreaks}@c old name
	11352	@findex allowcodebreaks
	11353	@cindex Breaks, within @code{@@code}
	11354	@cindex @sortas{-} -, breakpoint within @code{@@code}
	11355	@cindex Hyphen, breakpoint within @code{@@code}
	11356	@cindex Dash, breakpoint within @code{@@code}
	11357	@cindex _, breakpoint within @code{@@code}
	11358	@cindex Underscore, breakpoint within @code{@@code}
	11359
	11360	Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_}
	11361	characters within @code{@@code} and related commands
	11362	(@pxref{@code{@@code}}), more or less as if they were ``empty''
	11363	hyphenation points.
	11364
	11365	This is necessary since many manuals, especially for Lisp-family
	11366	languages, must document very long identifiers. On the other hand,
	11367	some manuals don't have this problems, and you may not wish to allow a
	11368	line break at the underscore in, for example, @code{SIZE_MAX}, or even
	11369	worse, after any of the four underscores in @code{__typeof__}.
	11370
	11371	So Texinfo provides this command:
	11372
	11373	@example
	11374	@@allowcodebreaks false
	11375	@end example
	11376
	11377	@noindent to prevent from breaking at @samp{-} or @samp{_} within
	11378	@code{@@code}. You can go back to allowing such breaks with
	11379	@code{@@allowcodebreaks true}. Write these commands on lines by
	11380	themselves.
	11381
	11382	These commands can be given anywhere in the document. For example,
	11383	you may have just one problematic paragraph where you need to turn off
	11384	the breaks, but want them in general, or vice versa.
	11385
	11386	This command has no effect except in HTML and @TeX{} output.
	11387
	11388
	11389	@node @code{@@w}
	11390	@section @code{@@w}@{@var{text}@}: Prevent Line Breaks
	11391
	11392	@anchor{w}@c old name
	11393	@findex w
	11394	@cindex Line breaks, preventing
	11395
	11396	@code{@@w@{@var{text}@}} outputs @var{text}, while prohibiting line
	11397	breaks within @var{text}.
	11398
	11399	@cindex Non-breakable space, fixed
	11400	@cindex Unbreakable space, fixed
	11401	Thus, you can use @code{@@w} to produce a non-breakable space, fixed at
	11402	the width of a normal interword space:
	11403
	11404	@example
	11405	@@w@{ @} @@w@{ @} @@w@{ @} indentation.
	11406	@end example
	11407
	11408	@noindent produces:
	11409
	11410	@display
	11411	@w{ } @w{ } @w{ } indentation.
	11412	@end display
	11413
	11414	The space from @code{@@w@{@w{ }@}}, as well as being non-breakable,
	11415	also will not stretch or shrink. Sometimes that is what you want, for
	11416	instance if you're doing manual indenting. However, usually you want
	11417	a normal interword space that does stretch and shrink (in the printed
	11418	output); for that, see the @code{@@tie} command in the next section.
	11419
	11420	@cindex Hyphenation, preventing
	11421	You can also use the @code{@@w} command to prevent @TeX{} from
	11422	automatically hyphenating a long name or phrase that happens to fall
	11423	near the end of a line. @command{makeinfo} does not ever hyphenate
	11424	words.
	11425
	11426	@cindex Keyword expansion, preventing
	11427	@cindex Version control keywords, preventing expansion of
	11428	@cindex $Id expansion, preventing
	11429	You can also use @code{@@w} to avoid unwanted keyword expansion in
	11430	source control systems. For example, to literally write @t{@w{$}Id$}
	11431	in your document, use @code{@@w@{$@}Id$}. This trick isn't effective
	11432	in Info or plain text output, though.
	11433
	11434
	11435	@node @code{@@tie}
	11436	@section @code{@@tie@{@}}: Inserting an Unbreakable Space
	11437
	11438	@anchor{tie}@c old name
	11439	@findex tie @r{(unbreakable interword space)}
	11440	@cindex Tied space
	11441	@cindex Non-breakable space, variable
	11442	@cindex Unbreakable space, variable
	11443
	11444	The @code{@@tie@{@}} command produces a normal interword space at which
	11445	a line break may not occur. Always write it with following (empty)
	11446	braces, as usual for commands used within a paragraph. Here's an
	11447	example:
	11448
	11449	@example
	11450	@@TeX@{@} was written by Donald E.@@tie@{@}Knuth.
	11451	@end example
	11452
	11453	@noindent produces:
	11454
	11455	@display
	11456	@TeX{} was written by Donald E.@tie{}Knuth.
	11457	@end display
	11458
	11459	There are two important differences between @code{@@tie@{@}} and
	11460	@code{@@w@{@w{ }@}}:
	11461
	11462	@itemize
	11463	@item
	11464	The space produced by @code{@@tie@{@}} will stretch and shrink slightly
	11465	along with the normal interword spaces in the paragraph; the space
	11466	produced by @code{@@w@{@w{ }@}} will not vary.
	11467
	11468	@item
	11469	@code{@@tie@{@}} allows hyphenation of the surrounding words, while
	11470	@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical
	11471	reasons, namely that it produces an @samp{\hbox}).
	11472
	11473	@end itemize
	11474
	11475
	11476	@node @code{@@sp}
	11477	@section @code{@@sp} @var{n}: Insert Blank Lines
	11478
	11479	@anchor{sp}@c old name
	11480	@findex sp @r{(line spacing)}
	11481	@cindex Space, inserting vertical
	11482	@cindex Blank lines
	11483	@cindex Line spacing
	11484
	11485	A line beginning with and containing only @code{@@sp @var{n}}
	11486	generates @var{n} blank lines of space in both the printed manual and
	11487	the Info file. @code{@@sp} also forces a paragraph break. For
	11488	example,
	11489
	11490	@example
	11491	@@sp 2
	11492	@end example
	11493
	11494	@noindent
	11495	generates two blank lines.
	11496
	11497	The @code{@@sp} command is most often used in the title page.
	11498
	11499
	11500	@node @code{@@page}
	11501	@section @code{@@page}: Start a New Page
	11502
	11503	@anchor{page}@c old name
	11504	@findex page
	11505	@cindex Page breaks, forcing
	11506
	11507	A line containing only @code{@@page} starts a new page in a printed
	11508	manual. In other formats, without the concept of pages, it starts a
	11509	new paragraph. A @code{@@page} command is often used in the
	11510	@code{@@titlepage} section of a Texinfo file to start the copyright
	11511	page.
	11512
	11513
	11514	@node @code{@@group}
	11515	@section @code{@@group}: Prevent Page Breaks
	11516
	11517	@anchor{group}@c old name
	11518	@findex group
	11519	@cindex Group (hold text together vertically)
	11520	@cindex Holding text together vertically
	11521	@cindex Vertically holding text together
	11522
	11523	The @code{@@group} command (on a line by itself) is used inside an
	11524	@code{@@example} or similar construct to begin an unsplittable vertical
	11525	group, which will appear entirely on one page in the printed output.
	11526	The group is terminated by a line containing only @code{@@end group}.
	11527	These two lines produce no output of their own, and in the Info file
	11528	output they have no effect at all.
	11529
	11530	@c Once said that these environments
	11531	@c turn off vertical spacing between ``paragraphs''.
	11532	@c Also, quotation used to work, but doesn't in texinfo-2.72
	11533	Although @code{@@group} would make sense conceptually in a wide
	11534	variety of contexts, its current implementation works reliably only
	11535	within @code{@@example} and variants, and within @code{@@display},
	11536	@code{@@format}, @code{@@flushleft} and @code{@@flushright}.
	11537	@xref{Quotations and Examples}. (What all these commands have in
	11538	common is that each line of input produces a line of output.) In
	11539	other contexts, @code{@@group} can cause anomalous vertical
	11540	spacing.
	11541
	11542	@need 750
	11543	This formatting requirement means that you should write:
	11544
	11545	@example
	11546	@group
	11547	@@example
	11548	@@group
	11549	@dots{}
	11550	@@end group
	11551	@@end example
	11552	@end group
	11553	@end example
	11554
	11555	@noindent
	11556	with the @code{@@group} and @code{@@end group} commands inside the
	11557	@code{@@example} and @code{@@end example} commands.
	11558
	11559	The @code{@@group} command is most often used to hold an example
	11560	together on one page. In this Texinfo manual, more than 100 examples
	11561	contain text that is enclosed between @code{@@group} and @code{@@end
	11562	group}.
	11563
	11564	If you forget to end a group, you may get strange and unfathomable
	11565	error messages when you run @TeX{}. This is because @TeX{} keeps
	11566	trying to put the rest of the Texinfo file onto the one page and does
	11567	not start to generate error messages until it has processed
	11568	considerable text. It is a good rule of thumb to look for a missing
	11569	@code{@@end group} if you get incomprehensible error messages in
	11570	@TeX{}.
	11571
	11572
	11573	@node @code{@@need}
	11574	@section @code{@@need @var{mils}}: Prevent Page Breaks
	11575
	11576	@anchor{need}@c old name
	11577	@findex need
	11578	@cindex Need space at page bottom
	11579	@cindex Mils, argument to @code{@@need}
	11580
	11581	A line containing only @code{@@need @var{n}} starts a new page in a
	11582	printed manual if fewer than @var{n} mils (thousandths of an inch)
	11583	remain on the current page. Do not use braces around the argument
	11584	@var{n}. The @code{@@need} command has no effect on other output
	11585	formats since they are not paginated.
	11586
	11587	@need 800
	11588	This paragraph is preceded by a @code{@@need} command that tells
	11589	@TeX{} to start a new page if fewer than 800 mils (eight-tenths
	11590	inch) remain on the page. It looks like this:
	11591
	11592	@example
	11593	@group
	11594	@@need 800
	11595	This paragraph is preceded by @dots{}
	11596	@end group
	11597	@end example
	11598
	11599	@cindex Orphans, preventing
	11600	The @code{@@need} command is useful for preventing orphans: single
	11601	lines at the bottoms of printed pages.
	11602
	11603
	11604	@node Definition Commands
	11605	@chapter Definition Commands
	11606	@cindex Definition commands
	11607
	11608	The @code{@@deffn} command and the other @dfn{definition commands}
	11609	enable you to describe functions, variables, macros, commands, user
	11610	options, special forms and other such artifacts in a uniform
	11611	format.
	11612
	11613	In the Info file, a definition causes the entity
	11614	category---`Function', `Variable', or whatever---to appear at the
	11615	beginning of the first line of the definition, followed by the
	11616	entity's name and arguments. In the printed manual, the command
	11617	causes @TeX{} to print the entity's name and its arguments on the left
	11618	margin and print the category next to the right margin. In both
	11619	output formats, the body of the definition is indented. Also, the
	11620	name of the entity is entered into the appropriate index:
	11621	@code{@@deffn} enters the name into the index of functions,
	11622	@code{@@defvr} enters it into the index of variables, and so
	11623	on (@pxref{Predefined Indices}).
	11624
	11625	A manual need not and should not contain more than one definition for
	11626	a given name. An appendix containing a summary should use
	11627	@code{@@table} rather than the definition commands.
	11628
	11629	@menu
	11630	* Def Cmd Template:: Writing descriptions using definition commands.
	11631	* Def Cmd Continuation Lines:: Continuing the heading over source lines.
	11632	* Optional Arguments:: Handling optional and repeated arguments.
	11633	* @code{@@deffnx}:: Group two or more `first' lines.
	11634	* Def Cmds in Detail:: Reference for all the definition commands.
	11635	* Def Cmd Conventions:: Conventions for writing definitions.
	11636	* Sample Function Definition:: An example.
	11637	@end menu
	11638
	11639
	11640	@node Def Cmd Template
	11641	@section The Template for a Definition
	11642	@cindex Definition template
	11643	@cindex Template for a definition
	11644
	11645	The @code{@@deffn} command is used for definitions of entities that
	11646	resemble functions. To write a definition using the @code{@@deffn}
	11647	command, write the @code{@@deffn} command at the beginning of a line
	11648	and follow it on the same line by the category of the entity, the name
	11649	of the entity itself, and its arguments (if any). Then write the body
	11650	of the definition on succeeding lines. (You may embed examples in the
	11651	body.) Finally, end the definition with an @code{@@end deffn} command
	11652	written on a line of its own.
	11653
	11654	The other definition commands follow the same format: a line with the
	11655	@code{@@def@dots{}} command and whatever arguments are appropriate for
	11656	that command; the body of the definition; and a corresponding
	11657	@code{@@end} line.
	11658
	11659	The template for a definition looks like this:
	11660
	11661	@example
	11662	@group
	11663	@@deffn @var{category} @var{name} @var{arguments}@dots{}
	11664	@var{body-of-definition}
	11665	@@end deffn
	11666	@end group
	11667	@end example
	11668
	11669	@need 700
	11670	@noindent
	11671	For example,
	11672
	11673	@example
	11674	@group
	11675	@@deffn Command forward-word count
	11676	This command moves point forward @@var@{count@} words
	11677	(or backward if @@var@{count@} is negative). @dots{}
	11678	@@end deffn
	11679	@end group
	11680	@end example
	11681
	11682	@noindent
	11683	produces
	11684
	11685	@quotation
	11686	@deffn Command forward-word count
	11687	This command moves point forward @var{count} words
	11688	(or backward if @var{count} is negative). @dots{}
	11689	@end deffn
	11690	@end quotation
	11691
	11692	Capitalize the category name like a title. If the name of the
	11693	category contains spaces, as in the phrase `Interactive Command',
	11694	enclose it in braces. For example:
	11695
	11696	@example
	11697	@group
	11698	@@deffn @{Interactive Command@} isearch-forward
	11699	@dots{}
	11700	@@end deffn
	11701	@end group
	11702	@end example
	11703
	11704	@noindent
	11705	Otherwise, the second word will be mistaken for the name of the
	11706	entity. As a general rule, when any of the arguments in the heading
	11707	line @emph{except} the last one are more than one word, you need to
	11708	enclose them in braces. This may also be necessary if the text
	11709	contains commands, for example, @samp{@{declaraci@@'on@}} if you are
	11710	writing in Spanish.
	11711
	11712	Some of the definition commands are more general than others. The
	11713	@code{@@deffn} command, for example, is the general definition command
	11714	for functions and the like---for entities that may take arguments.
	11715	When you use this command, you specify the category to which the
	11716	entity belongs. Three predefined, specialized variations
	11717	(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the
	11718	category for you: ``Function'', ``Macro'', and ``Special Form''
	11719	respectively. (In Lisp, a special form is an entity much like a
	11720	function.) Similarly, the general @code{@@defvr} command is
	11721	accompanied by several specialized variations for describing
	11722	particular kinds of variables.
	11723
	11724	@xref{Sample Function Definition}, for a detailed example of a
	11725	function definition, including the use of @code{@@example} inside the
	11726	definition.
	11727
	11728
	11729	@node Def Cmd Continuation Lines
	11730	@section Definition Command Continuation Lines
	11731	@cindex Continuation lines in definition commands
	11732	@cindex Definition command headings, continuing
	11733	@cindex @sortas{@@} @samp{@@} as continuation in definition commands
	11734
	11735	The heading line of a definition command can get very long.
	11736	Therefore, Texinfo has a special syntax allowing them to be continued
	11737	over multiple lines of the source file: a lone @samp{@@} at the end of
	11738	each line to be continued. Here's an example:
	11739
	11740	@example
	11741	@@defun fn-name @@
	11742	arg1 arg2 arg3
	11743	This is the basic continued defun.
	11744	@@end defun
	11745	@end example
	11746
	11747	@noindent produces:
	11748
	11749	@defun fn-name arg1 arg2 arg3
	11750	This is the basic continued defun.
	11751	@end defun
	11752
	11753	@noindent
	11754	As you can see, the continued lines are combined, as if they had been
	11755	typed on one source line.
	11756
	11757	Although this example only shows a one-line continuation,
	11758	continuations may extend over any number of lines, in the same way;
	11759	put an @code{@@} at the end of each line to be continued.
	11760
	11761	@cindex Whitespace, collapsed around continuations
	11762	@cindex Collapsing whitespace around continuations
	11763	In general, any number of spaces or tabs before the @code{@@}
	11764	continuation character are collapsed into a single space. There is one
	11765	exception: the Texinfo processors will not fully collapse whitespace
	11766	around a continuation inside braces. For example:
	11767
	11768	@example
	11769	@@deffn @{Category @@
	11770	Name@} @dots{}
	11771	@end example
	11772
	11773	@noindent The output (not shown) has excess space between `Category'
	11774	and `Name'. To avoid this, elide the unwanted whitespace in your
	11775	input, or put the continuation @code{@@} outside braces.
	11776
	11777	@code{@@} does not function as a continuation character in @emph{any}
	11778	other context. Ordinarily, @samp{@@} followed by a whitespace
	11779	character (space, tab, newline) produces a normal interword space
	11780	(@pxref{Multiple Spaces}).
	11781
	11782
	11783	@node Optional Arguments
	11784	@section Optional and Repeated Arguments
	11785	@cindex Optional and repeated arguments
	11786	@cindex Repeated and optional arguments
	11787	@cindex Arguments, repeated and optional
	11788	@cindex Syntax, optional & repeated arguments
	11789	@cindex Meta-syntactic chars for arguments
	11790
	11791	@c This is consistent with the Emacs Lisp Reference Manual.
	11792	Some entities take optional or repeated arguments, conventionally
	11793	specified by using square brackets and ellipses: an argument enclosed
	11794	within square brackets is optional, and an argument followed by an
	11795	ellipsis is optional and may be repeated more than once.
	11796
	11797	Thus, [@var{optional-arg}] means that @var{optional-arg} is optional
	11798	and @var{repeated-args}@code{@dots{}} stands for zero or more
	11799	arguments. Parentheses are used when several arguments are grouped
	11800	into additional levels of list structure in Lisp.
	11801
	11802	Here is the @code{@@defspec} line of an example of an imaginary
	11803	(complicated) special form:
	11804
	11805	@quotation
	11806	@defspec foobar (var [from to [inc]]) body@dots{}
	11807	@end defspec
	11808	@end quotation
	11809
	11810	@noindent
	11811	In this example, the arguments @var{from} and @var{to} are optional,
	11812	but must both be present or both absent. If they are present,
	11813	@var{inc} may optionally be specified as well. These arguments are
	11814	grouped with the argument @var{var} into a list, to distinguish them
	11815	from @var{body}, which includes all remaining elements of the
	11816	form.
	11817
	11818	In a Texinfo source file, this @code{@@defspec} line is written like
	11819	this:
	11820
	11821	@example
	11822	@@defspec foobar (var [from to [inc]]) body@@dots@{@}
	11823	@end example
	11824
	11825	@noindent
	11826	The function is listed in the Command and Variable Index under
	11827	@samp{foobar}.
	11828
	11829
	11830	@node @code{@@deffnx}
	11831	@section @code{@@deffnx}, et al.: Two or More `First' Lines
	11832
	11833	@anchor{deffnx}@c old node
	11834	@findex deffnx
	11835	@cindex Two `First' Lines for @code{@@deffn}
	11836	@cindex Grouping two definitions together
	11837	@cindex Definitions grouped together
	11838
	11839	To create two or more `first' or header lines for a definition, follow
	11840	the first @code{@@deffn} line by a line beginning with
	11841	@code{@@deffnx}. The @code{@@deffnx} command works exactly like
	11842	@code{@@deffn} except that it does not generate extra vertical white
	11843	space between it and the preceding line.
	11844
	11845	@need 1000
	11846	For example,
	11847
	11848	@example
	11849	@group
	11850	@@deffn @{Interactive Command@} isearch-forward
	11851	@@deffnx @{Interactive Command@} isearch-backward
	11852	These two search commands are similar except @dots{}
	11853	@@end deffn
	11854	@end group
	11855	@end example
	11856
	11857	@noindent
	11858	produces
	11859
	11860	@deffn {Interactive Command} isearch-forward
	11861	@deffnx {Interactive Command} isearch-backward
	11862	These two search commands are similar except @dots{}
	11863	@end deffn
	11864
	11865	@findex defcvx
	11866	@findex defivarx
	11867	@findex defmacx
	11868	@findex defmethodx
	11869	@findex defoptx
	11870	@findex defopx
	11871	@findex defspecx
	11872	@findex deftpx
	11873	@findex deftypecvx
	11874	@findex deftypefnx
	11875	@findex deftypefunx
	11876	@findex deftypeivarx
	11877	@findex deftypemethodx
	11878	@findex deftypeopx
	11879	@findex deftypevarx
	11880	@findex deftypevrx
	11881	@findex defunx
	11882	@findex defvarx
	11883	@findex defvrx
	11884	Each definition command has an `x' form: @code{@@defunx},
	11885	@code{@@defvrx}, @code{@@deftypefunx}, etc.
	11886
	11887	The `x' forms work similarly to @code{@@itemx}
	11888	(@pxref{@code{@@itemx}}).
	11889
	11890
	11891	@node Def Cmds in Detail
	11892	@section The Definition Commands
	11893
	11894	Texinfo provides more than a dozen definition commands, all of which
	11895	are described in this section.
	11896
	11897	The definition commands automatically enter the name of the entity in
	11898	the appropriate index: for example, @code{@@deffn}, @code{@@defun},
	11899	and @code{@@defmac} enter function names in the index of functions;
	11900	@code{@@defvr} and @code{@@defvar} enter variable names in the index
	11901	of variables.
	11902
	11903	Although the examples that follow mostly illustrate Lisp, the commands
	11904	can be used for other programming languages.
	11905
	11906	@menu
	11907	* Functions Commands:: Commands for functions and similar entities.
	11908	* Variables Commands:: Commands for variables and similar entities.
	11909	* Typed Functions:: Commands for functions in typed languages.
	11910	* Typed Variables:: Commands for variables in typed languages.
	11911	* Data Types:: The definition command for data types.
	11912	* Abstract Objects:: Commands for object-oriented programming.
	11913	@end menu
	11914
	11915	@node Functions Commands
	11916	@subsection Functions and Similar Entities
	11917
	11918	This section describes the commands for describing functions and similar
	11919	entities:
	11920
	11921	@table @code
	11922	@findex deffn
	11923	@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
	11924	The @code{@@deffn} command is the general definition command for
	11925	functions, interactive commands, and similar entities that may take
	11926	arguments. You must choose a term to describe the category of entity
	11927	being defined; for example, ``Function'' could be used if the entity is
	11928	a function. The @code{@@deffn} command is written at the beginning of a
	11929	line and is followed on the same line by the category of entity being
	11930	described, the name of this particular entity, and its arguments, if
	11931	any. Terminate the definition with @code{@@end deffn} on a line of its
	11932	own.
	11933
	11934	@need 750
	11935	For example, here is a definition:
	11936
	11937	@example
	11938	@group
	11939	@@deffn Command forward-char nchars
	11940	Move point forward @@var@{nchars@} characters.
	11941	@@end deffn
	11942	@end group
	11943	@end example
	11944
	11945	@noindent
	11946	This shows a rather terse definition for a ``command'' named
	11947	@code{forward-char} with one argument, @var{nchars}.
	11948
	11949	@code{@@deffn} prints argument names such as @var{nchars} in slanted
	11950	type in the printed output, because we think of these names as
	11951	metasyntactic variables---they stand for the actual argument values.
	11952	Within the text of the description, however, write an argument name
	11953	explicitly with @code{@@var} to refer to the value of the argument.
	11954	In the example above, we used @samp{@@var@{nchars@}} in this way.
	11955
	11956	In the extremely unusual case when an argument name contains
	11957	@samp{--}, or another character sequence which is treated specially
	11958	(@pxref{Conventions}), use @code{@@code} around the special
	11959	characters. This avoids the conversion to typographic en-dashes and
	11960	em-dashes.
	11961	@c @var also works; that's what we used to recommend.
	11962
	11963	The template for @code{@@deffn} is:
	11964
	11965	@example
	11966	@group
	11967	@@deffn @var{category} @var{name} @var{arguments}@dots{}
	11968	@var{body-of-definition}
	11969	@@end deffn
	11970	@end group
	11971	@end example
	11972
	11973	@findex defun
	11974	@item @@defun @var{name} @var{arguments}@dots{}
	11975	The @code{@@defun} command is the definition command for functions.
	11976	@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
	11977	Terminate the definition with @code{@@end defun} on a line of its own.
	11978	Thus, the template is:
	11979
	11980	@example
	11981	@group
	11982	@@defun @var{function-name} @var{arguments}@dots{}
	11983	@var{body-of-definition}
	11984	@@end defun
	11985	@end group
	11986	@end example
	11987
	11988	@findex defmac
	11989	@item @@defmac @var{name} @var{arguments}@dots{}
	11990	The @code{@@defmac} command is the definition command for macros.
	11991	@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
	11992	works like @code{@@defun}.
	11993
	11994	@findex defspec
	11995	@item @@defspec @var{name} @var{arguments}@dots{}
	11996	The @code{@@defspec} command is the definition command for special
	11997	forms. (In Lisp, a special form is an entity much like a function;
	11998	@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
	11999	@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
	12000	@dots{}} and works like @code{@@defun}.
	12001	@end table
	12002
	12003	All these commands create entries in the index of functions.
	12004
	12005
	12006	@node Variables Commands
	12007	@subsection Variables and Similar Entities
	12008
	12009	Here are the commands for defining variables and similar
	12010	entities:
	12011
	12012	@table @code
	12013	@findex defvr
	12014	@item @@defvr @var{category} @var{name}
	12015	The @code{@@defvr} command is a general definition command for
	12016	something like a variable---an entity that records a value. You must
	12017	choose a term to describe the category of entity being defined; for
	12018	example, ``Variable'' could be used if the entity is a variable.
	12019	Write the @code{@@defvr} command at the beginning of a line and
	12020	follow it on the same line by the category of the entity and the
	12021	name of the entity.
	12022
	12023	We recommend capitalizing the category name like a title. If the name
	12024	of the category contains spaces, as in the name ``User Option'',
	12025	enclose it in braces. Otherwise, the second word will be mistaken for
	12026	the name of the entity. For example,
	12027
	12028	@example
	12029	@group
	12030	@@defvr @{User Option@} fill-column
	12031	This buffer-local variable specifies
	12032	the maximum width of filled lines.
	12033	@dots{}
	12034	@@end defvr
	12035	@end group
	12036	@end example
	12037
	12038	Terminate the definition with @code{@@end defvr} on a line of its
	12039	own.
	12040
	12041	The template is:
	12042
	12043	@example
	12044	@group
	12045	@@defvr @var{category} @var{name}
	12046	@var{body-of-definition}
	12047	@@end defvr
	12048	@end group
	12049	@end example
	12050
	12051	@code{@@defvr} creates an entry in the index of variables for @var{name}.
	12052
	12053	@findex defvar
	12054	@item @@defvar @var{name}
	12055	The @code{@@defvar} command is the definition command for variables.
	12056	@code{@@defvar} is equivalent to @samp{@@defvr Variable
	12057	@dots{}}.
	12058
	12059	@need 750
	12060	For example:
	12061
	12062	@example
	12063	@group
	12064	@@defvar kill-ring
	12065	@dots{}
	12066	@@end defvar
	12067	@end group
	12068	@end example
	12069
	12070	The template is:
	12071
	12072	@example
	12073	@group
	12074	@@defvar @var{name}
	12075	@var{body-of-definition}
	12076	@@end defvar
	12077	@end group
	12078	@end example
	12079
	12080	@code{@@defvar} creates an entry in the index of variables for
	12081	@var{name}.
	12082
	12083	@findex defopt
	12084	@item @@defopt @var{name}
	12085	@cindex User options, marking
	12086	The @code{@@defopt} command is the definition command for @dfn{user
	12087	options}, i.e., variables intended for users to change according to
	12088	taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
	12089	Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
	12090	Option@} @dots{}} and works like @code{@@defvar}. It creates an entry
	12091	in the index of variables.
	12092	@end table
	12093
	12094
	12095	@node Typed Functions
	12096	@subsection Functions in Typed Languages
	12097
	12098	@cindex Typed functions
	12099	@cindex Functions, in typed languages
	12100
	12101	The @code{@@deftypefn} command and its variations are for describing
	12102	functions in languages in which you must declare types of variables
	12103	and functions, such as C and C++.
	12104
	12105	@table @code
	12106	@findex deftypefn
	12107	@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
	12108	The @code{@@deftypefn} command is the general definition command for
	12109	functions and similar entities that may take arguments and that are
	12110	typed. The @code{@@deftypefn} command is written at the beginning of
	12111	a line and is followed on the same line by the category of entity
	12112	being described, the type of the returned value, the name of this
	12113	particular entity, and its arguments, if any.
	12114
	12115	@need 800
	12116	@noindent
	12117	For example,
	12118
	12119	@example
	12120	@group
	12121	@@deftypefn @{Library Function@} int foobar @@
	12122	(int @@var@{foo@}, float @@var@{bar@})
	12123	@dots{}
	12124	@@end deftypefn
	12125	@end group
	12126	@end example
	12127
	12128	produces:
	12129
	12130	@quotation
	12131	@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
	12132	@dots{}
	12133	@end deftypefn
	12134	@end quotation
	12135
	12136	This means that @code{foobar} is a ``library function'' that returns an
	12137	@code{int}, and its arguments are @var{foo} (an @code{int}) and
	12138	@var{bar} (a @code{float}).
	12139
	12140	Since in typed languages, the actual names of the arguments are
	12141	typically scattered among data type names and keywords, Texinfo cannot
	12142	find them without help. You can either (a)@tie{}write everything as
	12143	straight text, and it will be printed in slanted type; (b)@tie{}use
	12144	@code{@@var} for the variable names, which will uppercase the variable
	12145	names in Info and use the slanted typewriter font in printed output;
	12146	(c)@tie{}use @code{@@var} for the variable names and @code{@@code} for
	12147	the type names and keywords, which will be dutifully obeyed.
	12148
	12149	The template for @code{@@deftypefn} is:
	12150
	12151	@example
	12152	@group
	12153	@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
	12154	@var{body-of-description}
	12155	@@end deftypefn
	12156	@end group
	12157	@end example
	12158
	12159	@noindent
	12160	Note that if the @var{category} or @var{data type} is more than one
	12161	word then it must be enclosed in braces to make it a single argument.
	12162
	12163	If you are describing a procedure in a language that has packages,
	12164	such as Ada, you might consider using @code{@@deftypefn} in a manner
	12165	somewhat contrary to the convention described in the preceding
	12166	paragraphs. For example:
	12167
	12168	@example
	12169	@group
	12170	@@deftypefn stacks private push @@
	12171	(@@var@{s@}:in out stack; @@
	12172	@@var@{n@}:in integer)
	12173	@dots{}
	12174	@@end deftypefn
	12175	@end group
	12176	@end example
	12177
	12178	@noindent
	12179	(In these examples the @code{@@deftypefn} arguments are shown using
	12180	continuations (@pxref{Def Cmd Continuation Lines}), but could be on a
	12181	single line.)
	12182
	12183	In this instance, the procedure is classified as belonging to the
	12184	package @code{stacks} rather than classified as a `procedure' and its
	12185	data type is described as @code{private}. (The name of the procedure
	12186	is @code{push}, and its arguments are @var{s} and @var{n}.)
	12187
	12188	@code{@@deftypefn} creates an entry in the index of functions for
	12189	@var{name}.
	12190
	12191	@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
	12192	@findex deftypefun
	12193	The @code{@@deftypefun} command is the specialized definition command
	12194	for functions in typed languages. The command is equivalent to
	12195	@samp{@@deftypefn Function @dots{}}. The template is:
	12196
	12197	@example
	12198	@group
	12199	@@deftypefun @var{type} @var{name} @var{arguments}@dots{}
	12200	@var{body-of-description}
	12201	@@end deftypefun
	12202	@end group
	12203	@end example
	12204
	12205	@code{@@deftypefun} creates an entry in the index of functions for
	12206	@var{name}.
	12207
	12208	@end table
	12209
	12210	@cindex Return type, own line for
	12211	@findex deftypefnnewline
	12212	Ordinarily, the return type is printed on the same line as the
	12213	function name and arguments, as shown above. In source code, GNU
	12214	style is to put the return type on a line by itself. So Texinfo
	12215	provides an option to do that: @code{@@deftypefnnewline on}.
	12216
	12217	This affects typed functions only---not untyped functions, not typed
	12218	variables, etc.. Specifically, it affects the commands in this
	12219	section, and the analogous commands for object-oriented languages,
	12220	namely @code{@@deftypeop} and @code{@@deftypemethod}
	12221	(@pxref{Object-Oriented Methods}).
	12222
	12223	Specifying @code{@@deftypefnnewline off} reverts to the default.
	12224
	12225
	12226	@node Typed Variables
	12227	@subsection Variables in Typed Languages
	12228
	12229	@cindex Typed variables
	12230	@cindex Variables, in typed languages
	12231
	12232	Variables in typed languages are handled in a manner similar to
	12233	functions in typed languages. @xref{Typed Functions}. The general
	12234	definition command @code{@@deftypevr} corresponds to
	12235	@code{@@deftypefn} and the specialized definition command
	12236	@code{@@deftypevar} corresponds to @code{@@deftypefun}.
	12237
	12238	@table @code
	12239	@findex deftypevr
	12240	@item @@deftypevr @var{category} @var{data-type} @var{name}
	12241	The @code{@@deftypevr} command is the general definition command for
	12242	something like a variable in a typed language---an entity that records
	12243	a value. You must choose a term to describe the category of the
	12244	entity being defined; for example, ``Variable'' could be used if the
	12245	entity is a variable.
	12246
	12247	The @code{@@deftypevr} command is written at the beginning of a line
	12248	and is followed on the same line by the category of the entity
	12249	being described, the data type, and the name of this particular
	12250	entity.
	12251
	12252	@need 800
	12253	@noindent
	12254	For example:
	12255
	12256	@example
	12257	@group
	12258	@@deftypevr @{Global Flag@} int enable
	12259	@dots{}
	12260	@@end deftypevr
	12261	@end group
	12262	@end example
	12263
	12264	@noindent
	12265	produces the following:
	12266
	12267	@quotation
	12268	@deftypevr {Global Flag} int enable
	12269	@dots{}
	12270	@end deftypevr
	12271	@end quotation
	12272
	12273	@need 800
	12274	The template is:
	12275
	12276	@example
	12277	@@deftypevr @var{category} @var{data-type} @var{name}
	12278	@var{body-of-description}
	12279	@@end deftypevr
	12280	@end example
	12281
	12282	@findex deftypevar
	12283	@item @@deftypevar @var{data-type} @var{name}
	12284	The @code{@@deftypevar} command is the specialized definition command
	12285	for variables in typed languages. @code{@@deftypevar} is equivalent
	12286	to @samp{@@deftypevr Variable @dots{}}. The template is:
	12287
	12288	@example
	12289	@group
	12290	@@deftypevar @var{data-type} @var{name}
	12291	@var{body-of-description}
	12292	@@end deftypevar
	12293	@end group
	12294	@end example
	12295	@end table
	12296
	12297	These commands create entries in the index of variables.
	12298
	12299
	12300	@node Data Types
	12301	@subsection Data Types
	12302
	12303	Here is the command for data types:
	12304
	12305	@table @code
	12306	@findex deftp
	12307	@item @@deftp @var{category} @var{name} @var{attributes}@dots{}
	12308	The @code{@@deftp} command is the generic definition command for data
	12309	types. The command is written at the beginning of a line and is
	12310	followed on the same line by the category, by the name of the type
	12311	(which is a word like @code{int} or @code{float}), and then by names of
	12312	attributes of objects of that type. Thus, you could use this command
	12313	for describing @code{int} or @code{float}, in which case you could use
	12314	@code{data type} as the category. (A data type is a category of
	12315	certain objects for purposes of deciding which operations can be
	12316	performed on them.)
	12317
	12318	In Lisp, for example, @dfn{pair} names a particular data
	12319	type, and an object of that type has two slots called the
	12320	@sc{car} and the @sc{cdr}. Here is how you would write the first line
	12321	of a definition of @code{pair}.
	12322
	12323	@example
	12324	@group
	12325	@@deftp @{Data type@} pair car cdr
	12326	@dots{}
	12327	@@end deftp
	12328	@end group
	12329	@end example
	12330
	12331	@need 950
	12332	The template is:
	12333
	12334	@example
	12335	@group
	12336	@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
	12337	@var{body-of-definition}
	12338	@@end deftp
	12339	@end group
	12340	@end example
	12341
	12342	@code{@@deftp} creates an entry in the index of data types.
	12343	@end table
	12344
	12345
	12346	@node Abstract Objects
	12347	@subsection Object-Oriented Programming
	12348
	12349	@cindex Object-oriented programming
	12350
	12351	Here are the commands for formatting descriptions about abstract
	12352	objects, such as are used in object-oriented programming. A class is
	12353	a defined type of abstract object. An instance of a class is a
	12354	particular object that has the type of the class. An instance
	12355	variable is a variable that belongs to the class but for which each
	12356	instance has its own value.
	12357
	12358	@menu
	12359	* Variables: Object-Oriented Variables.
	12360	* Methods: Object-Oriented Methods.
	12361	@end menu
	12362
	12363
	12364	@node Object-Oriented Variables
	12365	@subsubsection Object-Oriented Variables
	12366
	12367	@cindex Variables, object-oriented
	12368
	12369	These commands allow you to define different sorts of variables in
	12370	object-oriented programming languages.
	12371
	12372	@table @code
	12373	@item @@defcv @var{category} @var{class} @var{name}
	12374	@findex defcv
	12375	The @code{@@defcv} command is the general definition command for
	12376	variables associated with classes in object-oriented programming. The
	12377	@code{@@defcv} command is followed by three arguments: the category of
	12378	thing being defined, the class to which it belongs, and its
	12379	name. For instance:
	12380
	12381	@example
	12382	@group
	12383	@@defcv @{Class Option@} Window border-pattern
	12384	@dots{}
	12385	@@end defcv
	12386	@end group
	12387	@end example
	12388
	12389	@noindent produces:
	12390	@defcv {Class Option} Window border-pattern
	12391	@dots{}
	12392	@end defcv
	12393
	12394	@code{@@defcv} creates an entry in the index of variables.
	12395
	12396	@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
	12397	@findex deftypecv
	12398	The @code{@@deftypecv} command is the definition command for typed
	12399	class variables in object-oriented programming. It is analogous to
	12400	@code{@@defcv} with the addition of the @var{data-type} parameter to
	12401	specify the type of the instance variable. Ordinarily, the data type
	12402	is a programming language construct that should be marked with
	12403	@code{@@code}. For instance:
	12404
	12405	@example
	12406	@group
	12407	@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern
	12408	@dots{}
	12409	@@end deftypecv
	12410	@end group
	12411	@end example
	12412
	12413	@noindent produces:
	12414
	12415	@deftypecv {Class Option} Window @code{int} border-pattern
	12416	@dots{}
	12417	@end deftypecv
	12418
	12419	@code{@@deftypecv} creates an entry in the index of variables.
	12420
	12421	@item @@defivar @var{class} @var{name}
	12422	@findex defivar
	12423	The @code{@@defivar} command is the definition command for instance
	12424	variables in object-oriented programming. @code{@@defivar} is
	12425	equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For
	12426	instance:
	12427
	12428	@example
	12429	@group
	12430	@@defivar Window border-pattern
	12431	@dots{}
	12432	@@end defivar
	12433	@end group
	12434	@end example
	12435
	12436	@noindent produces:
	12437
	12438	@defivar Window border-pattern
	12439	@dots{}
	12440	@end defivar
	12441
	12442	@code{@@defivar} creates an entry in the index of variables.
	12443
	12444	@item @@deftypeivar @var{class} @var{data-type} @var{name}
	12445	@findex deftypeivar
	12446	The @code{@@deftypeivar} command is the definition command for typed
	12447	instance variables in object-oriented programming. It is analogous to
	12448	@code{@@defivar} with the addition of the @var{data-type} parameter to
	12449	specify the type of the instance variable. Ordinarily, the data type
	12450	is a programming language construct that should be marked with
	12451	@code{@@code}. For instance:
	12452
	12453	@example
	12454	@group
	12455	@@deftypeivar Window @@code@{int@} border-pattern
	12456	@dots{}
	12457	@@end deftypeivar
	12458	@end group
	12459	@end example
	12460
	12461	@noindent produces:
	12462
	12463	@deftypeivar Window @code{int} border-pattern
	12464	@dots{}
	12465	@end deftypeivar
	12466
	12467	@code{@@deftypeivar} creates an entry in the index of variables.
	12468
	12469	@end table
	12470
	12471
	12472	@node Object-Oriented Methods
	12473	@subsubsection Object-Oriented Methods
	12474
	12475	@cindex Methods, object-oriented
	12476
	12477	These commands allow you to define different sorts of function-like
	12478	entities resembling methods in object-oriented programming languages.
	12479	These entities take arguments, as functions do, but are associated with
	12480	particular classes of objects.
	12481
	12482	@table @code
	12483
	12484	@findex defop
	12485	@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
	12486	The @code{@@defop} command is the general definition command for these
	12487	method-like entities.
	12488
	12489	For example, some systems have constructs called @dfn{wrappers} that
	12490	are associated with classes as methods are, but that act more like
	12491	macros than like functions. You could use @code{@@defop Wrapper} to
	12492	describe one of these.
	12493
	12494	Sometimes it is useful to distinguish methods and @dfn{operations}.
	12495	You can think of an operation as the specification for a method.
	12496	Thus, a window system might specify that all window classes have a
	12497	method named @code{expose}; we would say that this window system
	12498	defines an @code{expose} operation on windows in general. Typically,
	12499	the operation has a name and also specifies the pattern of arguments;
	12500	all methods that implement the operation must accept the same
	12501	arguments, since applications that use the operation do so without
	12502	knowing which method will implement it.
	12503
	12504	Often it makes more sense to document operations than methods. For
	12505	example, window application developers need to know about the
	12506	@code{expose} operation, but need not be concerned with whether a
	12507	given class of windows has its own method to implement this operation.
	12508	To describe this operation, you would write:
	12509
	12510	@example
	12511	@@defop Operation windows expose
	12512	@end example
	12513
	12514	The @code{@@defop} command is written at the beginning of a line and
	12515	is followed on the same line by the overall name of the category of
	12516	operation, the name of the class of the operation, the name of the
	12517	operation, and its arguments, if any.
	12518
	12519	The template is:
	12520	@example
	12521	@group
	12522	@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
	12523	@var{body-of-definition}
	12524	@@end defop
	12525	@end group
	12526	@end example
	12527
	12528	@code{@@defop} creates an entry, such as `@code{expose} on
	12529	@code{windows}', in the index of functions.
	12530
	12531	@findex deftypeop
	12532	@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
	12533	The @code{@@deftypeop} command is the definition command for typed
	12534	operations in object-oriented programming. It is similar to
	12535	@code{@@defop} with the addition of the @var{data-type} parameter to
	12536	specify the return type of the method. @code{@@deftypeop} creates an
	12537	entry in the index of functions.
	12538
	12539	@item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
	12540	@findex defmethod
	12541	The @code{@@defmethod} command is the definition command for methods
	12542	in object-oriented programming. A method is a kind of function that
	12543	implements an operation for a particular class of objects and its
	12544	subclasses.
	12545	@ignore
	12546	@c ADR: Who cares?!?
	12547	@c KB: Oh, I don't know, I think this info is crucial!
	12548	In the Lisp Machine, methods actually were functions, but
	12549	they were usually defined with @code{defmethod}.
	12550	@end ignore
	12551
	12552	@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
	12553	The command is written at the beginning of a line and is followed by
	12554	the name of the class of the method, the name of the method, and its
	12555	arguments, if any.
	12556
	12557	@noindent
	12558	For example:
	12559	@example
	12560	@group
	12561	@@defmethod @code{bar-class} bar-method argument
	12562	@dots{}
	12563	@@end defmethod
	12564	@end group
	12565	@end example
	12566
	12567	@noindent
	12568	illustrates the definition for a method called @code{bar-method} of
	12569	the class @code{bar-class}. The method takes an argument.
	12570
	12571	@code{@@defmethod} creates an entry in the index of functions.
	12572
	12573	@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
	12574	@findex deftypemethod
	12575	The @code{@@deftypemethod} command is the definition command for methods
	12576	in object-oriented typed languages, such as C++ and Java. It is similar
	12577	to the @code{@@defmethod} command with the addition of the
	12578	@var{data-type} parameter to specify the return type of the method.
	12579	@code{@@deftypemethod} creates an entry in the index of functions.
	12580
	12581	@end table
	12582
	12583	The typed commands are affected by the @code{@@deftypefnnewline}
	12584	option (@pxref{Typed Functions,, Functions in Typed Languages}).
	12585
	12586
	12587	@node Def Cmd Conventions
	12588	@section Conventions for Writing Definitions
	12589	@cindex Definition conventions
	12590	@cindex Conventions for writing definitions
	12591
	12592	When you write a definition using @code{@@deffn}, @code{@@defun}, or
	12593	one of the other definition commands, please take care to use
	12594	arguments that indicate the meaning, as with the @var{count} argument
	12595	to the @code{forward-word} function. Also, if the name of an argument
	12596	contains the name of a type, such as @var{integer}, take care that the
	12597	argument actually is of that type.
	12598
	12599
	12600	@node Sample Function Definition
	12601	@section A Sample Function Definition
	12602	@cindex Function definitions
	12603	@cindex Command definitions
	12604	@cindex Macro definitions, programming-language
	12605	@cindex Sample function definition
	12606
	12607	A function definition uses the @code{@@defun} and @code{@@end defun}
	12608	commands. The name of the function follows immediately after the
	12609	@code{@@defun} command and it is followed, on the same line, by the
	12610	parameter list.
	12611
	12612	Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
	12613	Lisp Reference Manual}.
	12614
	12615	@quotation
	12616	@defun apply function &rest arguments
	12617	@code{apply} calls @var{function} with @var{arguments}, just
	12618	like @code{funcall} but with one difference: the last of
	12619	@var{arguments} is a list of arguments to give to
	12620	@var{function}, rather than a single argument. We also say
	12621	that this list is @dfn{appended} to the other arguments.
	12622
	12623	@code{apply} returns the result of calling @var{function}.
	12624	As with @code{funcall}, @var{function} must either be a Lisp
	12625	function or a primitive function; special forms and macros
	12626	do not make sense in @code{apply}.
	12627
	12628	@example
	12629	(setq f 'list)
	12630	@result{} list
	12631	(apply f 'x 'y 'z)
	12632	@error{} Wrong type argument: listp, z
	12633	(apply '+ 1 2 '(3 4))
	12634	@result{} 10
	12635	(apply '+ '(1 2 3 4))
	12636	@result{} 10
	12637
	12638	(apply 'append '((a b c) nil (x y z) nil))
	12639	@result{} (a b c x y z)
	12640	@end example
	12641
	12642	An interesting example of using @code{apply} is found in the description
	12643	of @code{mapcar}.
	12644	@end defun
	12645	@end quotation
	12646
	12647	In the Texinfo source file, this example looks like this:
	12648
	12649	@example
	12650	@group
	12651	@@defun apply function &rest arguments
	12652	@@code@{apply@} calls @@var@{function@} with
	12653	@@var@{arguments@}, just like @@code@{funcall@} but with one
	12654	difference: the last of @@var@{arguments@} is a list of
	12655	arguments to give to @@var@{function@}, rather than a single
	12656	argument. We also say that this list is @@dfn@{appended@}
	12657	to the other arguments.
	12658	@end group
	12659
	12660	@group
	12661	@@code@{apply@} returns the result of calling
	12662	@@var@{function@}. As with @@code@{funcall@},
	12663	@@var@{function@} must either be a Lisp function or a
	12664	primitive function; special forms and macros do not make
	12665	sense in @@code@{apply@}.
	12666	@end group
	12667
	12668	@group
	12669	@@example
	12670	(setq f 'list)
	12671	@@result@{@} list
	12672	(apply f 'x 'y 'z)
	12673	@@error@{@} Wrong type argument: listp, z
	12674	(apply '+ 1 2 '(3 4))
	12675	@@result@{@} 10
	12676	(apply '+ '(1 2 3 4))
	12677	@@result@{@} 10
	12678
	12679	(apply 'append '((a b c) nil (x y z) nil))
	12680	@@result@{@} (a b c x y z)
	12681	@@end example
	12682	@end group
	12683
	12684	@group
	12685	An interesting example of using @@code@{apply@} is found
	12686	in the description of @@code@{mapcar@}.
	12687	@@end defun
	12688	@end group
	12689	@end example
	12690
	12691	@noindent
	12692	In this manual, this function is listed in the Command and Variable
	12693	Index under @code{apply}.
	12694
	12695	Ordinary variables and user options are described using a format like
	12696	that for functions except that variables do not take arguments.
	12697
	12698
	12699	@node Internationalization
	12700	@chapter Internationalization
	12701
	12702	@cindex Internationalization
	12703	Texinfo has some support for writing in languages other than English,
	12704	although this area still needs considerable work. (If you are
	12705	the one helping to translate the fixed strings written to documents,
	12706	@pxref{Internationalization of Document Strings}.)
	12707
	12708	For a list of the various accented and special characters Texinfo
	12709	supports, see @ref{Inserting Accents}.
	12710
	12711	@menu
	12712	* @code{@@documentlanguage}:: Declaring the current language.
	12713	* @code{@@documentencoding}:: Declaring the input encoding.
	12714	@end menu
	12715
	12716
	12717	@node @code{@@documentlanguage}
	12718	@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language
	12719	@anchor{documentlanguage}
	12720
	12721	@findex documentlanguage
	12722	@cindex Language, declaring
	12723	@cindex Locale, declaring
	12724	@cindex Document language, declaring
	12725
	12726	The @code{@@documentlanguage} command declares the current document
	12727	locale. Write it on a line by itself, near the beginning of the file.
	12728
	12729	@example
	12730	@@documentlanguage @var{ll}[_@var{cc}]
	12731	@end example
	12732
	12733	Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following
	12734	the command name, optionally followed by an underscore and two-letter
	12735	ISO@tie{}3166 two-letter country code (@var{cc}). If you have a
	12736	multilingual document, the intent is to be able to use this command
	12737	multiple times, to declare each language change. If the command is
	12738	not used at all, the default is @code{en_US} for US English.
	12739
	12740	As with GNU Gettext (@pxref{Top,,, gettext, Gettext}), if the country
	12741	code is omitted, the main dialect is assumed where possible. For
	12742	example, @code{de} is equivalent to @code{de_DE} (German as spoken in
	12743	Germany).
	12744
	12745	@cindex Document strings, translation of
	12746	For Info and other online output, this command changes the translation
	12747	of various @dfn{document strings} such as ``see'' in cross-references
	12748	(@pxref{Cross References}), ``Function'' in defuns (@pxref{Definition
	12749	Commands}), and so on. Some strings, such as ``Node:'', ``Next:'',
	12750	``Menu:'', etc., are keywords in Info output, so are not translated
	12751	there; they are translated in other output formats.
	12752
	12753	@cindex @file{txi-@var{cc}.tex}
	12754	For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to
	12755	be read (if it exists). If @code{@@documentlanguage} argument
	12756	contains the optional @samp{_@var{cc}} suffix, this is tried first.
	12757	For example, with @code{@@documentlanguage de_DE}, @TeX{} first looks
	12758	for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
	12759
	12760	Such a @file{txi-*} file is intended to redefine the various English
	12761	words used in @TeX{} output, such as `Chapter', `See', and so on. We
	12762	are aware that individual words like these cannot always be translated
	12763	in isolation, and that a very different strategy would be required for
	12764	ideographic (among other) scripts. Help in improving Texinfo's
	12765	language support is welcome.
	12766
	12767	@cindex Hyphenation patterns, language-dependent
	12768	@code{@@documentlanguage} also changes @TeX{}'s current hyphenation
	12769	patterns, if the @TeX{} program being run has the necessary support
	12770	included. This will generally not be the case for @command{tex}
	12771	itself, but will usually be the case for up-to-date distributions of
	12772	the extended @TeX{} programs @command{etex} (DVI output) and
	12773	@command{pdftex} (PDF output). @command{texi2dvi} will use the
	12774	extended @TeX{}s if they are available (@pxref{Format with
	12775	@command{texi2dvi}}).
	12776
	12777	In September 2006, the W3C Internationalization Activity released a
	12778	new recommendation for specifying languages:
	12779	@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext
	12780	supports this new scheme, Texinfo will too.
	12781
	12782	@cindex ISO 639-2 language codes
	12783	@cindex ISO 3166 country codes
	12784	@cindex Language codes
	12785	@cindex Country codes
	12786	Since the lists of language codes and country codes are updated
	12787	relatively frequently, we don't attempt to list them here. The valid
	12788	language codes are on the official home page for ISO@tie{}639,
	12789	@url{http://www.loc.gov/standards/iso639-2/}. The country codes and
	12790	the official web site for ISO@tie{}3166 can be found via
	12791	@url{http://en.wikipedia.org/wiki/ISO_3166}.
	12792
	12793
	12794	@node @code{@@documentencoding}
	12795	@section @code{@@documentencoding @var{enc}}: Set Input Encoding
	12796
	12797	@anchor{documentencoding}@c old name
	12798	@findex documentencoding
	12799	@cindex Encoding, declaring
	12800	@cindex Input encoding, declaring
	12801	@cindex Character set, declaring
	12802	@cindex Document input encoding
	12803
	12804	The @code{@@documentencoding} command declares the input document
	12805	encoding, and can also affect the encoding of the output. Write it on
	12806	a line by itself, with a valid encoding specification following, near
	12807	the beginning of the file.
	12808
	12809	@example
	12810	@@documentencoding @var{enc}
	12811	@end example
	12812
	12813	Texinfo supports these encodings:
	12814
	12815	@table @code
	12816	@item US-ASCII
	12817	This has no particular effect, but it's included for completeness.
	12818
	12819	@item UTF-8
	12820	The vast global character encoding, expressed in 8-bit bytes.
	12821
	12822	@item ISO-8859-1
	12823	@itemx ISO-8859-15
	12824	@itemx ISO-8859-2
	12825	@cindex Euro symbol, and encodings
	12826	These specify the standard encodings for Western European (the first
	12827	two) and Eastern European languages (the third), respectively. ISO
	12828	8859-15 replaces some little-used characters from 8859-1 (e.g.,
	12829	precomposed fractions) with more commonly needed ones, such as the
	12830	Euro symbol (@euro{}).
	12831
	12832	A full description of the encodings is beyond our scope here;
	12833	one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
	12834
	12835	@item koi8-r
	12836	This is the commonly used encoding for the Russian language.
	12837
	12838	@item koi8-u
	12839	This is the commonly used encoding for the Ukrainian language.
	12840
	12841	@end table
	12842
	12843	Specifying an encoding @var{enc} has the following effects:
	12844
	12845	@cindex Local Variables section, for encoding
	12846	@cindex Info output, and encoding
	12847	In Info output, a so-called `Local Variables' section (@pxref{File
	12848	Variables,,, emacs, The GNU Emacs Manual}) is output including
	12849	@var{enc}. This allows Info readers to set the encoding
	12850	appropriately. It looks like this:
	12851
	12852	@example
	12853	Local Variables:
	12854	coding: @var{enc}
	12855	End:
	12856	@end example
	12857
	12858	Also, in Info and plain text output, unless the option
	12859	@option{--disable-encoding} is given to @command{makeinfo}, accent
	12860	constructs and special characters, such as @code{@@'e}, are output as
	12861	the actual 8-bit or UTF-8 character in the given encoding where
	12862	possible.
	12863
	12864	@cindex HTML output, and encodings
	12865	@cindex @code{http-equiv}, and charset specification
	12866	@cindex @code{<meta>} HTML tag, and charset specification
	12867	In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
	12868	section of the HTML, that specifies @var{enc}. Web servers and
	12869	browsers cooperate to use this information so the correct encoding is
	12870	used to display the page, if supported by the system. That looks like
	12871	this:
	12872
	12873	@example
	12874	<meta http-equiv="Content-Type" content="text/html;
	12875	charset=@var{enc}">
	12876	@end example
	12877
	12878	In XML and Docbook output, UTF-8 is always used for the output,
	12879	according to the conventions of those formats.
	12880
	12881	@cindex Computer Modern fonts
	12882	In @TeX{} output, the characters which are supported in the standard
	12883	Computer Modern fonts are output accordingly. For example, this
	12884	means using constructed accents rather than precomposed glyphs.
	12885	Using a missing character generates a warning message, as does
	12886	specifying an unimplemented encoding.
	12887
	12888	Although modern @TeX{} systems support nearly every script in use in
	12889	the world, this wide-ranging support is not available in
	12890	@file{texinfo.tex}, and it's not feasible to duplicate or incorporate
	12891	all that effort. (Our plan to support other scripts is to create a
	12892	@LaTeX{} back-end to @command{texi2any}, where the support is already
	12893	present.)
	12894
	12895	For maximum portability of Texinfo documents across the many different
	12896	user environments in the world, we recommend sticking to 7-bit ASCII
	12897	in the input unless your particular manual needs a substantial amount
	12898	of non-ASCII, e.g., it's written in German. You can use the
	12899	@code{@@U} command to insert an occasional needed character
	12900	(@pxref{Inserting Unicode}).
	12901
	12902
	12903	@node Conditionals
	12904	@chapter Conditionally Visible Text
	12905	@cindex Conditionally visible text
	12906	@cindex Text, conditionally visible
	12907	@cindex Visibility of conditional text
	12908	@cindex If text conditionally visible
	12909
	12910	The @dfn{conditional commands} allow you to use different text for
	12911	different output formats, or for general conditions that you define.
	12912	For example, you can use them to specify different text for the
	12913	printed manual and the Info output.
	12914
	12915	The conditional commands comprise the following categories.
	12916
	12917	@itemize @bullet
	12918	@item
	12919	Commands specific to an output format (Info, @TeX{}, HTML, @dots{}).
	12920
	12921	@item
	12922	Commands specific to any output format @emph{excluding} a given
	12923	one (e.g., not Info, not @TeX{}, @dots{}).
	12924
	12925	@item
	12926	`Raw' formatter text for any output format, passed straight
	12927	through with minimal (but not zero) interpretation of @@-commands.
	12928
	12929	@item
	12930	Format-independent variable substitutions, and testing if a variable
	12931	is set or clear.
	12932
	12933	@end itemize
	12934
	12935	@menu
	12936	* Conditional Commands:: Text for a given format.
	12937	* Conditional Not Commands:: Text for any format other than a given one.
	12938	* Raw Formatter Commands:: Using raw formatter commands.
	12939	* Inline Conditionals:: Brace-delimited conditional text.
	12940	* @code{@@set @@clear @@value}:: Variable tests and substitutions.
	12941	* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
	12942	* Conditional Nesting:: Using conditionals inside conditionals.
	12943	@end menu
	12944
	12945
	12946	@node Conditional Commands
	12947	@section Conditional Commands
	12948
	12949	Texinfo has an @code{@@if@var{format}} environment for each output
	12950	format, to allow conditional inclusion of text for a particular output
	12951	format.
	12952
	12953	@findex ifinfo
	12954	@code{@@ifinfo} begins segments of text that should be ignored by
	12955	@TeX{} when it typesets the printed manual, and by @command{makeinfo}
	12956	when not producing Info output. The segment of text appears only in
	12957	the Info file and, for historical compatibility, the plain text
	12958	output.
	12959
	12960	@findex ifdocbook
	12961	@findex ifhtml
	12962	@findex ifplaintext
	12963	@findex iftex
	12964	@findex ifxml
	12965	The environments for the other formats are analogous:
	12966
	12967	@table @code
	12968	@item @@ifdocbook @dots{} @@end ifdocbook
	12969	Text to appear only in the Docbook output.
	12970
	12971	@item @@ifhtml @dots{} @@end ifhtml
	12972	Text to appear only in the HTML output.
	12973
	12974	@item @@ifplaintext @dots{} @@end ifplaintext
	12975	Text to appear only in the plain text output.
	12976
	12977	@item @@iftex @dots{} @@end iftex
	12978	Text to appear only in the printed manual.
	12979
	12980	@item @@ifxml @dots{} @@end ifxml
	12981	Text to appear only in the XML output.
	12982	@end table
	12983
	12984	The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear
	12985	on lines by themselves in your source file. The newlines following
	12986	the commands are (more or less) treated as whitespace, so that the
	12987	conditional text is flowed normally into a surrounding paragraph.
	12988
	12989	The @code{@@if@dots{}} constructs are intended to conditionalize
	12990	normal Texinfo source; @pxref{Raw Formatter Commands}, for using
	12991	underlying format commands directly.
	12992
	12993	Here is an example showing all these conditionals:
	12994
	12995	@example
	12996	@@iftex
	12997	This text will appear only in the printed manual.
	12998	@@end iftex
	12999	@@ifinfo
	13000	However, this text will appear only in Info and plain text.
	13001	@@end ifinfo
	13002	@@ifhtml
	13003	And this text will only appear in HTML.
	13004	@@end ifhtml
	13005	@@ifplaintext
	13006	Whereas this text will only appear in plain text.
	13007	@@end ifplaintext
	13008	@@ifxml
	13009	Notwithstanding that this will only appear in XML@.
	13010	@@end ifxml
	13011	@@ifdocbook
	13012	Nevertheless, this will only appear in Docbook.
	13013	@@end ifdocbook
	13014	@end example
	13015
	13016	@noindent
	13017	The preceding example produces the following line:
	13018
	13019	@iftex
	13020	This text will appear only in the printed manual.
	13021	@end iftex
	13022	@ifinfo
	13023	However, this text will appear only in Info and plain text.
	13024	@end ifinfo
	13025	@ifhtml
	13026	And this text will only appear in HTML.
	13027	@end ifhtml
	13028	@ifplaintext
	13029	Whereas this text will only appear in plain text.
	13030	@end ifplaintext
	13031	@ifxml
	13032	Notwithstanding that this will only appear in XML@.
	13033	@end ifxml
	13034	@ifdocbook
	13035	Nevertheless, this will only appear in Docbook.
	13036	@end ifdocbook
	13037
	13038	@noindent
	13039	Notice that you only see one of the input lines, depending on which
	13040	version of the manual you are reading.
	13041
	13042	@findex errormsg
	13043	In complex documents, you may want Texinfo to issue an error message
	13044	in some conditionals that should not ever be processed. The
	13045	@code{@@errormsg@{@var{text}@}} command will do this; it takes one
	13046	argument, the text of the error message.
	13047
	13048	We mention @code{@@errormsg@{@}} here even though it is not strictly
	13049	related to conditionals, since in practice it is most likely to be
	13050	useful in that context. Technically, it can be used anywhere.
	13051	@xref{External Macro Processors}, for a caveat regarding the line
	13052	numbers which @code{@@errormsg} emits in @TeX{}.
	13053
	13054
	13055	@node Conditional Not Commands
	13056	@section Conditional Not Commands
	13057	@findex ifnotdocbook
	13058	@findex ifnothtml
	13059	@findex ifnotinfo
	13060	@findex ifnotplaintext
	13061	@findex ifnottex
	13062	@findex ifnotxml
	13063
	13064	You can specify text to be included in any output format @emph{other}
	13065	than a given one with the @code{@@ifnot@dots{}} environments:
	13066
	13067	@example
	13068	@@ifnotdocbook @dots{} @@end ifnotdocbook
	13069	@@ifnothtml @dots{} @@end ifnothtml
	13070	@@ifnotinfo @dots{} @@end ifnotinfo
	13071	@@ifnotplaintext @dots{} @@end ifnotplaintext
	13072	@@ifnottex @dots{} @@end ifnottex
	13073	@@ifnotxml @dots{} @@end ifnotxml
	13074	@end example
	13075
	13076	@noindent
	13077	The @code{@@ifnot@dots{}} command and the @code{@@end} command must
	13078	appear on lines by themselves in your actual source file.
	13079
	13080	If the output file is being made in the given format, the
	13081	region is @emph{ignored}. Otherwise, it is included.
	13082
	13083	There is one exception (for historical compatibility):
	13084	@code{@@ifnotinfo} text is omitted for both Info and plain text
	13085	output, not just Info. To specify text which appears only in Info and
	13086	not in plain text, use @code{@@ifnotplaintext}, like this:
	13087
	13088	@example
	13089	@@ifinfo
	13090	@@ifnotplaintext
	13091	This will be in Info, but not plain text.
	13092	@@end ifnotplaintext
	13093	@@end ifinfo
	13094	@end example
	13095
	13096	The regions delimited by these commands are ordinary Texinfo source as
	13097	with @code{@@iftex}, not raw formatter source as with @code{@@tex}
	13098	(@pxref{Raw Formatter Commands}).
	13099
	13100
	13101	@node Raw Formatter Commands
	13102	@section Raw Formatter Commands
	13103	@cindex Raw formatter commands
	13104
	13105	@cindex @TeX{} commands, using ordinary
	13106	@cindex Ordinary @TeX{} commands, using
	13107	@cindex Commands using raw @TeX{}
	13108	@cindex Plain @TeX{}
	13109
	13110	The @code{@@if@dots{}} conditionals just described must be used only
	13111	with normal Texinfo source. For instance, most features of plain
	13112	@TeX{} will not work within @code{@@iftex}. The purpose of
	13113	@code{@@if@dots{}} is to provide conditional processing for Texinfo
	13114	source, not provide access to underlying formatting features. For
	13115	that, Texinfo provides so-called @dfn{raw formatter commands}. They
	13116	should only be used when truly required (most documents do not need
	13117	them).
	13118
	13119	@findex tex
	13120	@cindex Category codes, of plain @TeX{}
	13121	The first raw formatter command is @code{@@tex}. You can enter plain
	13122	@TeX{} completely, and use @samp{\} in the @TeX{} commands, by
	13123	delineating a region with the @code{@@tex} and @code{@@end tex}
	13124	commands. All plain @TeX{} commands and category codes are restored
	13125	within a @code{@@tex} region. The sole exception is that the
	13126	@code{@@} character still introduces a command, so that @code{@@end
	13127	tex} can be recognized. Texinfo processors will not output material
	13128	in such a region, unless @TeX{} output is being produced.
	13129
	13130	@findex \gdef @r{within @code{@@tex}}
	13131	@findex \globaldefs @r{within @code{@@tex}}
	13132	In complex cases, you may wish to define new @TeX{} macros within
	13133	@code{@@tex}. You must use @code{\gdef} to do this, not @code{\def},
	13134	because @code{@@tex} regions are processed in a @TeX{} group. If you
	13135	need to make several definitions, you may wish to set
	13136	@code{\globaldefs=1} (its value will be restored to zero as usual when
	13137	the group ends at @code{@@end tex}, so it won't cause problems with
	13138	the rest of the document).
	13139
	13140	@cindex Equation, displayed, in plain @TeX{}
	13141	@cindex Displayed equation, in plain @TeX{}
	13142	As an example, here is a displayed equation written in plain @TeX{}:
	13143
	13144	@example
	13145	@@tex
	13146	$$ \chi^2 = \sum_@{i=1@}^N
	13147	\left (y_i - (a + b x_i)
	13148	\over \sigma_i\right)^2 $$
	13149	@@end tex
	13150	@end example
	13151
	13152	@noindent
	13153	The output of this example will appear only in a printed manual. If
	13154	you are reading this in a format not generated by @TeX{}, you will not
	13155	see the equation that appears in the printed manual.
	13156
	13157	@tex
	13158	$$ \chi^2 = \sum_{i=1}^N
	13159	\left(y_i - (a + b x_i)
	13160	\over \sigma_i\right)^2 $$
	13161	@end tex
	13162
	13163	@cindex HTML, including raw
	13164	@findex ifhtml
	13165	@findex html
	13166	Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to
	13167	delimit Texinfo source to be included in HTML output only, and
	13168	@code{@@html @dots{} @@end html} for a region of raw HTML.
	13169
	13170	@cindex XML, including raw
	13171	@findex ifxml
	13172	@findex xml
	13173	Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
	13174	Texinfo source to be included in XML output only, and @code{@@xml
	13175	@dots{} @@end xml} for a region of raw XML@. Regions of raw text in
	13176	other formats will also be present in the XML output, but with
	13177	protection of XML characters and within corresponding elements. For
	13178	example, the raw HTML text:
	13179
	13180	@example
	13181	@group
	13182	@@html
	13183	<br />
	13184	@@end html
	13185	@end group
	13186	@end example
	13187
	13188	@noindent
	13189	will be included in the XML output as:
	13190
	13191	@example
	13192	@group
	13193	<html>
	13194	<br />
	13195	</html>
	13196	@end group
	13197	@end example
	13198
	13199	@cindex Docbook, including raw
	13200	@findex ifdocbook
	13201	@findex docbook
	13202	Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
	13203	to delimit Texinfo source to be included in Docbook output only, and
	13204	@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook.
	13205
	13206	The behavior of newlines in raw regions is unspecified.
	13207
	13208	In all cases, in raw processing, @code{@@} retains the same meaning as
	13209	in the remainder of the document. Thus, the Texinfo processors must
	13210	recognize and even execute, to some extent, the contents of the raw
	13211	regions, regardless of the final output format. Therefore, specifying
	13212	changes that globally affect the document inside a raw region leads to
	13213	unpredictable and generally undesirable behavior. For example, using
	13214	the @code{@@kbdinputstyle} command inside a raw region is undefined.
	13215
	13216	The remedy is simple: don't do that. Use the raw formatter commands
	13217	for their intended purpose, of providing material directly in the
	13218	underlying format. When you simply want to give different Texinfo
	13219	specifications for different output formats, use the
	13220	@code{@@if@dots{}} conditionals and stay in Texinfo syntax.
	13221
	13222
	13223
	13224	@node Inline Conditionals
	13225	@section Inline Conditionals: @code{@@inline}, @code{@@inlineifelse}, @code{@@inlineraw}
	13226	@findex inlinefmt
	13227	@findex inlinefmtifelse
	13228	@findex inlineraw
	13229	@cindex Inline conditionals
	13230	@cindex Conditional commands, inline
	13231	@cindex Brace-delimited conditional text
	13232	@cindex Newlines, avoiding in conditionals
	13233	@cindex Whitespace, controlling in conditionals
	13234
	13235	Texinfo provides a set of conditional commands with arguments given
	13236	within braces:
	13237
	13238	@table @code
	13239	@item @@inlinefmt@{@var{format}, @var{text}@}
	13240	Process the Texinfo @var{text} if @var{format} output is being
	13241	generated.
	13242
	13243	@item @@inlinefmtifelse@{@var{format}, @var{then-text}, @var{else-text}@}
	13244	Process the Texinfo @var{then-text} if @var{format} output is being
	13245	generated; otherwise, process @var{else-text}.
	13246
	13247	@item @@inlineraw@{@var{format}, @var{text}@}
	13248	Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}).
	13249	@end table
	13250
	13251	The supported @var{format} names are:
	13252
	13253	@example
	13254	docbook html info plaintext tex xml
	13255	@end example
	13256
	13257	For example,
	13258
	13259	@example
	13260	@@inlinefmt@{html, @@emph@{HTML-only text@}@}
	13261	@end example
	13262
	13263	@noindent is nearly equivalent to
	13264
	13265	@example
	13266	@@ifhtml
	13267	@@emph@{HTML-only text@}
	13268	@@end ifhtml
	13269	@end example
	13270
	13271	@noindent except that no whitespace is added, as happens in the latter
	13272	(environment) case.
	13273
	13274	In these commands, whitespace is ignored after the comma separating
	13275	the arguments, as usual, but is @emph{not} ignored at the end of
	13276	@var{text}.
	13277
	13278	To insert a literal at sign, left brace, or right brace in one of the
	13279	arguments, you must use the alphabetic commands @code{@@atchar@{@}}
	13280	(@pxref{Inserting an Atsign}), and @code{@@lbracechar@{@}} or
	13281	@code{@@rbracechar@{@}} (@pxref{Inserting Braces}), or the parsing
	13282	will become confused.
	13283
	13284	With @code{@@inlinefmtifelse}, it is also necessary to use
	13285	@code{@@comma@{@}} to avoid mistaking a @samp{,} in the text for the
	13286	delimiter. With @code{@@inlinefmt} and @code{@@inlineraw},
	13287	@code{@@comma@{@}} is not required (though it's fine to use it), since
	13288	these commands always have exactly two arguments.
	13289
	13290	For @TeX{}, the processed @var{text} cannot contain newline-delimited
	13291	commands. Text to be ignored (i.e., for non-@TeX{}) can, though.
	13292
	13293	Two other @code{@@inline...} conditionals complement the
	13294	@code{@@ifset} and @code{@@ifclear} commands; see the next section.
	13295
	13296
	13297	@node @code{@@set @@clear @@value}
	13298	@section Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value}
	13299
	13300	@anchor{set clear value}@c old name
	13301	You can direct the Texinfo formatting commands to format or ignore parts
	13302	of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
	13303	and @code{@@ifclear} commands.
	13304
	13305	Here are brief descriptions of these commands, see the following
	13306	sections for more details:
	13307
	13308	@table @code
	13309	@item @@set @var{flag} [@var{value}]
	13310	Set the variable @var{flag}, to the optional @var{value} if specified.
	13311
	13312	@item @@clear @var{flag}
	13313	Undefine the variable @var{flag}, whether or not it was previously defined.
	13314
	13315	@item @@ifset @var{flag}
	13316	If @var{flag} is set, text through the next @code{@@end ifset} command
	13317	is formatted. If @var{flag} is clear, text through the following
	13318	@code{@@end ifset} command is ignored.
	13319
	13320	@item @@inlineifset@{@var{flag}, @var{text}@}
	13321	Brace-delimited version of @code{@@ifset}.
	13322
	13323	@item @@ifclear @var{flag}
	13324	If @var{flag} is set, text through the next @code{@@end ifclear} command
	13325	is ignored. If @var{flag} is clear, text through the following
	13326	@code{@@end ifclear} command is formatted.
	13327
	13328	@item @@inlineifclear@{@var{flag}, @var{text}@}
	13329	Brace-delimited version of @code{@@ifclear}.
	13330
	13331	@end table
	13332
	13333	@menu
	13334	* @code{@@set @@value}:: Expand a flag variable to a string.
	13335	* @code{@@ifset @@ifclear}:: Format a region if a flag is set.
	13336	* @code{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals.
	13337	* @code{@@value} Example:: An easy way to update edition information.
	13338	@end menu
	13339
	13340
	13341	@node @code{@@set @@value}
	13342	@subsection @code{@@set} and @code{@@value}
	13343
	13344	@anchor{set value}@c old name
	13345	@findex set
	13346	@findex value
	13347	@findex clear
	13348
	13349	You use the @code{@@set} command to specify a value for a flag, which
	13350	is later expanded by the @code{@@value} command.
	13351
	13352	A @dfn{flag} (aka @dfn{variable}) name is an identifier starting with
	13353	an alphanumeric, @samp{-}, or @samp{_}. Subsequent characters, if
	13354	any, may not be whitespace, @samp{@@}, braces, angle brackets, or any
	13355	of @samp{~`^+\|}; other characters, such as @samp{%}, may work.
	13356	However, it is best to use only letters and numerals in a flag name,
	13357	not @samp{-} or @samp{_} or others---they will work in some contexts,
	13358	but not all, due to limitations in @TeX{}.
	13359
	13360	The value is the remainder of the input line, and can contain anything.
	13361	However, unlike most other commands which take the rest of the line as
	13362	a value, @code{@@set} need not appear at the beginning of a line.
	13363
	13364	Write the @code{@@set} command like this:
	13365
	13366	@example
	13367	@@set foo This is a string.
	13368	@end example
	13369
	13370	@noindent
	13371	This sets the value of the flag @code{foo} to ``This is a string.''.
	13372
	13373	The Texinfo formatters then replace a @code{@@value@{@var{flag}@}}
	13374	command with the string to which @var{flag} is set. Thus, when
	13375	@code{foo} is set as shown above, the Texinfo formatters convert this:
	13376
	13377	@example
	13378	@group
	13379	@@value@{foo@}
	13380	@exdent @r{to this:}
	13381	This is a string.
	13382	@end group
	13383	@end example
	13384
	13385	You can write a @code{@@value} command within a paragraph; but you
	13386	must write a @code{@@set} command on a line of its own.
	13387
	13388	If you write the @code{@@set} command like this:
	13389
	13390	@example
	13391	@@set foo
	13392	@end example
	13393
	13394	@noindent
	13395	without specifying a string, the value of @code{foo} is the empty string.
	13396
	13397	If you clear a previously set flag with @code{@@clear @var{flag}}, a
	13398	subsequent @code{@@value@{flag@}} command will report an error.
	13399
	13400	For example, if you set @code{foo} as follows:
	13401
	13402	@example
	13403	@@set howmuch very, very, very
	13404	@end example
	13405
	13406	@noindent
	13407	then the formatters transform
	13408
	13409	@example
	13410	@group
	13411	It is a @@value@{howmuch@} wet day.
	13412	@exdent @r{into}
	13413	It is a very, very, very wet day.
	13414	@end group
	13415	@end example
	13416
	13417	If you write
	13418
	13419	@example
	13420	@@clear howmuch
	13421	@end example
	13422
	13423	@noindent
	13424	then the formatters transform
	13425
	13426	@example
	13427	@group
	13428	It is a @@value@{howmuch@} wet day.
	13429	@exdent @r{into}
	13430	It is a @{No value for "howmuch"@} wet day.
	13431	@end group
	13432	@end example
	13433
	13434	@code{@@value} cannot be reliably used as the argument to an accent
	13435	command (@pxref{Inserting Accents}). For example, this fails:
	13436
	13437	@example
	13438	@@set myletter a
	13439	@@'@@value@{myletter@} @c fails!
	13440	@end example
	13441
	13442
	13443	@node @code{@@ifset @@ifclear}
	13444	@subsection @code{@@ifset} and @code{@@ifclear}
	13445
	13446	@anchor{ifset ifclear}@c old name
	13447	@findex ifset
	13448
	13449	When a @var{flag} is set, the Texinfo formatting commands format text
	13450	between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
	13451	ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
	13452	commands do @emph{not} format the text. @code{@@ifclear} operates
	13453	analogously.
	13454
	13455	Write the conditionally formatted text between @code{@@ifset @var{flag}}
	13456	and @code{@@end ifset} commands, like this:
	13457
	13458	@example
	13459	@group
	13460	@@ifset @var{flag}
	13461	@var{conditional-text}
	13462	@@end ifset
	13463	@end group
	13464	@end example
	13465
	13466	For example, you can create one document that has two variants, such as
	13467	a manual for a `large' and `small' model:
	13468
	13469	@cindex Shrubbery
	13470	@example
	13471	You can use this machine to dig up shrubs
	13472	without hurting them.
	13473
	13474	@@set large
	13475
	13476	@@ifset large
	13477	It can also dig up fully grown trees.
	13478	@@end ifset
	13479
	13480	Remember to replant promptly @dots{}
	13481	@end example
	13482
	13483	@noindent
	13484	In the example, the formatting commands will format the text between
	13485	@code{@@ifset large} and @code{@@end ifset} because the @code{large}
	13486	flag is set.
	13487
	13488	When @var{flag} is cleared, the Texinfo formatting commands do
	13489	@emph{not} format the text between @code{@@ifset @var{flag}} and
	13490	@code{@@end ifset}; that text is ignored and does not appear in either
	13491	printed or Info output.
	13492
	13493	For example, if you clear the flag of the preceding example by writing
	13494	an @code{@@clear large} command after the @code{@@set large} command
	13495	(but before the conditional text), then the Texinfo formatting commands
	13496	ignore the text between the @code{@@ifset large} and @code{@@end ifset}
	13497	commands. In the formatted output, that text does not appear; in both
	13498	printed and Info output, you see only the lines that say, ``You can use
	13499	this machine to dig up shrubs without hurting them. Remember to replant
	13500	promptly @dots{}''.
	13501
	13502	@findex ifclear
	13503	If a flag is cleared with a @code{@@clear @var{flag}} command, then
	13504	the formatting commands format text between subsequent pairs of
	13505	@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
	13506	is set with @code{@@set @var{flag}}, then the formatting commands do
	13507	@emph{not} format text between an @code{@@ifclear} and an @code{@@end
	13508	ifclear} command; rather, they ignore that text. An @code{@@ifclear}
	13509	command looks like this:
	13510
	13511	@example
	13512	@@ifclear @var{flag}
	13513	@end example
	13514
	13515
	13516	@node @code{@@inlineifset @@inlineifclear}
	13517	@subsection @code{@@inlineifset} and @code{@@inlineifclear}
	13518
	13519	@findex inlineifset
	13520	@findex inlineifclear
	13521	@cindex Flag conditionals, brace-delimited
	13522	@cindex Brace-delimited flag conditionals
	13523
	13524	@code{@@inlineifset} and @code{@@inlineifclear} provide
	13525	brace-delimited alternatives to the @code{@@ifset} and
	13526	@code{@@ifclear} forms, similar to the other @code{@@inline...}
	13527	Commands (@pxref{Inline Conditionals}). The same caveats about
	13528	argument parsing given there apply here too.
	13529
	13530	@table @code
	13531	@item @@inlineifset@{@var{var}, @var{text}@}
	13532	Process the Texinfo @var{text} if the flag @var{var} is defined.
	13533
	13534	@item @@inlineifclear@{@var{var}, @var{text}@}
	13535	Process the Texinfo @var{text} if the flag @var{var} is not defined.
	13536	@end table
	13537
	13538	Except for the syntax, their general behavior and purposes is the same
	13539	as with @code{@@ifset} and @code{@@ifclear}, described in the previous
	13540	section.
	13541
	13542
	13543	@node @code{@@value} Example
	13544	@subsection @code{@@value} Example
	13545
	13546	@anchor{value Example}@c old name
	13547
	13548	You can use the @code{@@value} command to minimize the number of
	13549	places you need to change when you record an update to a manual.
	13550	@xref{GNU Sample Texts}, for the full text of an example of using this
	13551	to work with Automake distributions.
	13552
	13553	This example is adapted from @ref{Top,,, make, The GNU Make Manual}.
	13554
	13555	@enumerate
	13556	@item
	13557	Set the flags:
	13558
	13559	@example
	13560	@group
	13561	@@set EDITION 0.35 Beta
	13562	@@set VERSION 3.63 Beta
	13563	@@set UPDATED 14 August 1992
	13564	@@set UPDATE-MONTH August 1992
	13565	@end group
	13566	@end example
	13567
	13568	@item
	13569	Write text for the @code{@@copying} section (@pxref{@code{@@copying}}):
	13570
	13571	@example
	13572	@group
	13573	@@copying
	13574	This is Edition @@value@{EDITION@},
	13575	last updated @@value@{UPDATED@},
	13576	of @@cite@{The GNU Make Manual@},
	13577	for @@code@{make@}, version @@value@{VERSION@}.
	13578
	13579	Copyright @dots{}
	13580
	13581	Permission is granted @dots{}
	13582	@@end copying
	13583	@end group
	13584	@end example
	13585
	13586	@item
	13587	Write text for the title page, for people reading the printed manual:
	13588
	13589	@example
	13590	@group
	13591	@@titlepage
	13592	@@title GNU Make
	13593	@@subtitle A Program for Directing Recompilation
	13594	@@subtitle Edition @@value@{EDITION@}, @dots{}
	13595	@@subtitle @@value@{UPDATE-MONTH@}
	13596	@@page
	13597	@@insertcopying
	13598	@dots{}
	13599	@@end titlepage
	13600	@end group
	13601	@end example
	13602
	13603	@noindent
	13604	(On a printed cover, a date listing the month and the year looks less
	13605	fussy than a date listing the day as well as the month and year.)
	13606
	13607	@item
	13608	Write text for the Top node, for people reading the Info file:
	13609
	13610	@example
	13611	@group
	13612	@@ifnottex
	13613	@@node Top
	13614	@@top Make
	13615
	13616	This is Edition @@value@{EDITION@},
	13617	last updated @@value@{UPDATED@},
	13618	of @@cite@{The GNU Make Manual@},
	13619	for @@code@{make@}, version @@value@{VERSION@}.
	13620	@@end ifnottex
	13621	@end group
	13622	@end example
	13623
	13624	After you format the manual, the @code{@@value} constructs have been
	13625	expanded, so the output contains text like this:
	13626
	13627	@example
	13628	@group
	13629	This is Edition 0.35 Beta, last updated 14 August 1992,
	13630	of `The GNU Make Manual', for `make', Version 3.63 Beta.
	13631	@end group
	13632	@end example
	13633	@end enumerate
	13634
	13635	When you update the manual, you change only the values of the flags; you
	13636	do not need to edit the three sections.
	13637
	13638
	13639	@node Testing for Texinfo Commands
	13640	@section Testing for Texinfo Commands: @code{@@ifcommanddefined}, @code{@@ifcommandnotdefined}
	13641
	13642	@cindex Testing for Texinfo commands
	13643	@cindex Checking for Texinfo commands
	13644	@cindex Texinfo commands, testing for
	13645	@cindex Commands, testing for Texinfo
	13646	@cindex Versions of Texinfo, adapting to
	13647	@cindex Features of Texinfo, adapting to
	13648	@findex ifcommanddefined
	13649	@findex ifcommandnotdefined
	13650
	13651	Occasionally, you may want to arrange for your manual to test if a
	13652	given Texinfo command is available and (presumably) do some sort of
	13653	fallback formatting if not. There are conditionals
	13654	@code{@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this.
	13655	For example:
	13656
	13657	@example
	13658	@@ifcommanddefined node
	13659	Good, @@samp@{@@@@node@} is defined.
	13660	@@end ifcommanddefined
	13661	@end example
	13662
	13663	@noindent will output the expected `Good, @samp{@@node} is defined.'.
	13664
	13665	This conditional will also consider any new commands defined by
	13666	the document via @code{@@macro}, @code{@@alias},
	13667	@code{@@definfoenclose}, and @code{@@def@r{(}code@r{)}index}
	13668	(@pxref{Defining New Texinfo Commands}) to be true. Caveat: the @TeX{}
	13669	implementation reports internal @TeX{} commands, in addition to all
	13670	the Texinfo commands, as being ``defined''; the @code{makeinfo}
	13671	implementation is reliable in this regard, however.
	13672
	13673	@pindex @file{NEWS} file for Texinfo
	13674	You can check the @file{NEWS} file in the Texinfo source distribution
	13675	and linked from the Texinfo home page
	13676	(@url{http://www.gnu.org/software/texinfo}) to see when a particular
	13677	command was added.
	13678
	13679	@vindex txicommandconditionals
	13680	These command-checking conditionals themselves were added in
	13681	Texinfo@tie{}5.0, released in 2013---decades after Texinfo's
	13682	inception. In order to test if they themselves are available,
	13683	the predefined flag @code{txicommandconditionals} can be tested, like
	13684	this:
	13685
	13686	@example
	13687	@@ifset txicommandconditionals
	13688	@@ifcommandnotdefined foobarnode
	13689	(Good, @@samp@{@@@@foobarnode@} is not defined.)
	13690	@@end ifcommandnotdefined
	13691	@@end ifset
	13692	@end example
	13693
	13694	Since flags (see the previous section) were added early in the
	13695	existence of Texinfo, there is no problem with assuming they are
	13696	available.
	13697
	13698	We recommend avoiding these tests whenever possible---which is usually
	13699	the case. For many software packages, it is reasonable for all
	13700	developers to have a given version of Texinfo (or newer) installed,
	13701	and thus no reason to worry about older versions. (It is
	13702	straightforward for anyone to download and install the Texinfo source;
	13703	it does not have any problematic dependencies.)
	13704
	13705	The issue of Texinfo versions does not generally arise for end-users.
	13706	With properly distributed packages, users need not process the Texinfo
	13707	manual simply to build and install the package; they can use
	13708	preformatted Info (or other) output files. This is desirable in
	13709	general, to avoid unnecessary dependencies between packages
	13710	(@pxref{Releases,,, standards, GNU Coding Standards}).
	13711
	13712
	13713	@node Conditional Nesting
	13714	@section Conditional Nesting
	13715	@cindex Conditionals, nested
	13716	@cindex Nesting conditionals
	13717
	13718	Conditionals can be nested; however, the details are a little tricky.
	13719	The difficulty comes with failing conditionals, such as
	13720	@code{@@ifhtml} when HTML is not being produced, where the included
	13721	text is to be ignored. However, it is not to be @emph{completely}
	13722	ignored, since it is useful to have one @code{@@ifset} inside another,
	13723	for example---that is a way to include text only if two conditions are
	13724	met. Here's an example:
	13725
	13726	@example
	13727	@@ifset somevar
	13728	@@ifset anothervar
	13729	Both somevar and anothervar are set.
	13730	@@end ifset
	13731	@@ifclear anothervar
	13732	Somevar is set, anothervar is not.
	13733	@@end ifclear
	13734	@@end ifset
	13735	@end example
	13736
	13737	Technically, Texinfo requires that for a failing conditional, the
	13738	ignored text must be properly nested with respect to that failing
	13739	conditional. Unfortunately, it's not always feasible to check that
	13740	@emph{all} conditionals are properly nested, because then the
	13741	processors could have to fully interpret the ignored text, which
	13742	defeats the purpose of the command. Here's an example illustrating
	13743	these rules:
	13744
	13745	@example
	13746	@@ifset a
	13747	@@ifset b
	13748	@@ifclear ok - ok, ignored
	13749	@@end junky - ok, ignored
	13750	@@end ifset
	13751	@@c WRONG - missing @@end ifset.
	13752	@end example
	13753
	13754	Finally, as mentioned above, all conditional commands must be on lines
	13755	by themselves, with no text (even spaces) before or after. Otherwise,
	13756	the processors cannot reliably determine which commands to consider
	13757	for nesting purposes.
	13758
	13759
	13760	@node Defining New Texinfo Commands
	13761	@chapter Defining New Texinfo Commands
	13762
	13763	@cindex Macros
	13764	@cindex Defining new Texinfo commands
	13765	@cindex New Texinfo commands, defining
	13766	@cindex Texinfo commands, defining new
	13767	@cindex User-defined Texinfo commands
	13768
	13769	Texinfo provides several ways to define new commands (in all cases,
	13770	it's not recommended to try redefining existing commands):
	13771
	13772	@itemize @bullet
	13773	@item
	13774	A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
	13775	sequence of text and/or existing commands (including other macros). The
	13776	macro can have any number of @dfn{parameters}---text you supply each
	13777	time you use the macro.
	13778
	13779	Incidentally, these macros have nothing to do with the @code{@@defmac}
	13780	command, which is for documenting macros in the subject area of the
	13781	manual (@pxref{Def Cmd Template}).
	13782
	13783	@item
	13784	@samp{@@alias} is a convenient way to define a new name for an existing
	13785	command.
	13786
	13787	@item
	13788	@samp{@@definfoenclose} allows you to define new commands with
	13789	customized output for all non-@TeX{} output formats.
	13790
	13791	@end itemize
	13792
	13793	Most generally of all (not just for defining new commands), it is
	13794	possible to invoke any external macro processor and have Texinfo
	13795	recognize so-called @code{#line} directives for error reporting.
	13796
	13797	If you want to do simple text substitution, @code{@@set} and
	13798	@code{@@value} is the simplest approach (@pxref{@code{@@set @@clear
	13799	@@value}}).
	13800
	13801	@menu
	13802	* Defining Macros:: Defining and undefining new commands.
	13803	* Invoking Macros:: Using a macro, once you've defined it.
	13804	* Macro Details:: Limitations of Texinfo macros.
	13805	* @code{@@alias}:: Command aliases.
	13806	* @code{@@definfoenclose}:: Customized highlighting.
	13807	* External Macro Processors:: @code{#line} directives.
	13808	@end menu
	13809
	13810
	13811	@node Defining Macros
	13812	@section Defining Macros
	13813	@cindex Defining macros
	13814	@cindex Macro definitions, Texinfo
	13815
	13816	@findex macro
	13817	You use the Texinfo @code{@@macro} command to define a macro, like this:
	13818
	13819	@example
	13820	@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
	13821	@var{text} @dots{} \@var{param1}\ @dots{}
	13822	@@end macro
	13823	@end example
	13824
	13825	The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
	13826	arguments supplied when the macro is subsequently used in the document
	13827	(described in the next section).
	13828
	13829	@cindex Macro names, valid characters in
	13830	@cindex Names of macros, valid characters of
	13831	For a macro to work consistently with @TeX{}, @var{macroname} must
	13832	consist entirely of letters: no digits, hyphens, underscores, or other
	13833	special characters. So, we recommend using only letters. However,
	13834	@command{makeinfo} will accept anything consisting of alphanumerics,
	13835	and (except as the first character) @samp{-}. The @samp{_} character
	13836	is excluded so that macros can be called inside @code{@@math} without
	13837	a following space (@pxref{Inserting Math}).
	13838
	13839	If a macro needs no parameters, you can define it either with an empty
	13840	list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
	13841	foo}).
	13842
	13843	@cindex Body of a macro
	13844	The definition or @dfn{body} of the macro can contain most Texinfo
	13845	commands, including macro invocations. However, a macro definition
	13846	that defines another macro does not work in @TeX{} due to limitations
	13847	in the design of @code{@@macro}.
	13848
	13849	@cindex Parameters to macros
	13850	In the macro body, instances of a parameter name surrounded by
	13851	backslashes, as in @samp{\@var{param1}\} in the example above, are
	13852	replaced by the corresponding argument from the macro invocation. You
	13853	can use parameter names any number of times in the body, including zero.
	13854
	13855	@cindex Backslash in macros
	13856	To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
	13857	other use of @samp{\} in the body yields a warning.
	13858
	13859	@cindex Spaces in macros
	13860	@cindex Whitespace in macros
	13861	The newline characters after the @code{@@macro} line and before the
	13862	@code{@@end macro} line are ignored, that is, not included in the
	13863	macro body. All other whitespace is treated according to the usual
	13864	Texinfo rules.
	13865
	13866	@cindex Recursive macro invocations
	13867	@findex rmacro
	13868	To allow a macro to be used recursively, that is, in an argument to a
	13869	call to itself, you must define it with @samp{@@rmacro}, like this:
	13870
	13871	@example
	13872	@@rmacro rmac @{arg@}
	13873	a\arg\b
	13874	@@end rmacro
	13875	@dots{}
	13876	@@rmac@{1@@rmac@{text@}2@}
	13877	@end example
	13878
	13879	This produces the output `a1atextb2b'. With @samp{@@macro} instead of
	13880	@samp{@@rmacro}, an error message is given.
	13881
	13882	@findex unmacro
	13883	@cindex Macros, undefining
	13884	@cindex Undefining macros
	13885	You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
	13886	It is not an error to undefine a macro that is already undefined.
	13887	For example:
	13888
	13889	@example
	13890	@@unmacro foo
	13891	@end example
	13892
	13893
	13894	@node Invoking Macros
	13895	@section Invoking Macros
	13896
	13897	@cindex Invoking macros
	13898	@cindex Expanding macros
	13899	@cindex Running macros
	13900	@cindex Macro invocation
	13901
	13902	After a macro is defined (see the previous section), you can
	13903	@dfn{invoke} (use) it in your document like this:
	13904
	13905	@example
	13906	@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
	13907	@end example
	13908
	13909	@noindent and the result will be more or less as if you typed the body of
	13910	@var{macroname} at that spot. For example:
	13911
	13912	@example
	13913	@@macro foo @{p, q@}
	13914	Together: \p\ & \q\.
	13915	@@end macro
	13916	@@foo@{a, b@}
	13917	@end example
	13918
	13919	@noindent produces:
	13920
	13921	@display
	13922	Together: a & b.
	13923	@end display
	13924
	13925	@cindex Backslash, and macros
	13926	Thus, the arguments and parameters are separated by commas and
	13927	delimited by braces; any whitespace after (but not before) a comma is
	13928	ignored. The braces are required in the invocation even when the
	13929	macro takes no arguments, consistent with other Texinfo commands. For
	13930	example:
	13931
	13932	@example
	13933	@@macro argless @{@}
	13934	No arguments here.
	13935	@@end macro
	13936	@@argless@{@}
	13937	@end example
	13938
	13939	@noindent produces:
	13940
	13941	@display
	13942	No arguments here.
	13943	@end display
	13944
	13945	@cindex Comma, in macro arguments
	13946	Passing macro arguments containing commas requires care, since
	13947	commas also separate the arguments. To include a comma character in
	13948	an argument, the most reliable method is to use the @code{@@comma@{@}}
	13949	command. For @code{makeinfo}, you can also prepend a backslash
	13950	character, as in @samp{\,}, but this does not work with @TeX{}.
	13951
	13952	@cindex Automatic quoting of commas for some macros
	13953	@cindex Quoting, automatic for some macros
	13954	It's not always necessary to worry about commas. To facilitate use of
	13955	macros, @command{makeinfo} implements two rules for @dfn{automatic
	13956	quoting} in some circumstances:
	13957
	13958	@enumerate 1
	13959	@item If a macro takes only one argument, all commas in its invocation
	13960	are quoted by default. For example:
	13961
	13962	@example
	13963	@group
	13964	@@macro TRYME@{text@}
	13965	@@strong@{TRYME: \text\@}
	13966	@@end macro
	13967
	13968	@@TRYME@{A nice feature, though it can be dangerous.@}
	13969	@end group
	13970	@end example
	13971
	13972	@noindent
	13973	will produce the following output
	13974
	13975	@example
	13976	@strong{TRYME: A nice feature, though it can be dangerous.}
	13977	@end example
	13978
	13979	And indeed, it can. Namely, @command{makeinfo} does not control the
	13980	number of arguments passed to one-argument macros, so be careful when
	13981	you invoke them.
	13982
	13983	@item If a macro invocation includes another command (including a
	13984	recursive invocation of itself), any commas in the nested command
	13985	invocation(s) are quoted by default. For example, in
	13986
	13987	@example
	13988	@@say@{@@strong@{Yes, I do@}, person one@}
	13989	@end example
	13990
	13991	the comma after @samp{Yes} is implicitly quoted. Here's another
	13992	example, with a recursive macro:
	13993
	13994	@example
	13995	@group
	13996	@@rmacro cat@{a,b@}
	13997	\a\\b\
	13998	@@end rmacro
	13999
	14000	@@cat@{@@cat@{foo, bar@}, baz@}
	14001	@end group
	14002	@end example
	14003
	14004	@noindent
	14005	will produce the string @samp{foobarbaz}.
	14006
	14007	@item Otherwise, a comma should be explicitly quoted, as above, for it
	14008	to be treated as a part of an argument.
	14009	@end enumerate
	14010
	14011	@cindex Backslash, in macro arguments
	14012	@cindex Braces, in macro arguments
	14013	The backslash itself can be quoted in macro arguments with another
	14014	backslash. For example:
	14015
	14016	@example
	14017	@@@var{macname} @{\\bleh@}
	14018	@end example
	14019
	14020	@noindent
	14021	will pass the argument @samp{\bleh} to @var{macname}.
	14022
	14023	@command{makeinfo} also recognizes @samp{\@{} and @samp{\@}} sequences
	14024	for curly braces, but these are not recognized by the implementation in
	14025	@TeX{}. There should, however, rarely be a need for these, as they are
	14026	only needed when a macro argument contains unbalanced braces.
	14027
	14028	If a macro is defined to take exactly one argument, it can be
	14029	invoked without any braces, taking all of the line after the macro name
	14030	as the argument. For example:
	14031
	14032	@example
	14033	@@macro bar @{p@}
	14034	Twice: \p\ & \p\.
	14035	@@end macro
	14036	@@bar aah
	14037	@end example
	14038
	14039	@noindent produces:
	14040
	14041	@display
	14042	Twice: aah & aah.
	14043	@end display
	14044
	14045	@noindent
	14046	In these arguments, there is no escaping of special characters, so each
	14047	@samp{\} stands for itself.
	14048
	14049	If a macro is defined to take more than one argument, but is called
	14050	with only one (in braces), the remaining arguments are set to the
	14051	empty string, and no error is given. For example:
	14052
	14053	@example
	14054	@@macro addtwo @{p, q@}
	14055	Both: \p\\q\.
	14056	@@end macro
	14057	@@addtwo@{a@}
	14058	@end example
	14059
	14060	@noindent produces simply:
	14061
	14062	@display
	14063	Both: a.
	14064	@end display
	14065
	14066
	14067	@node Macro Details
	14068	@section Macro Details and Caveats
	14069	@cindex Macro details
	14070	@cindex Details of macro usage
	14071	@cindex Caveats for macro usage
	14072
	14073	@cindex Macro expansion, contexts for
	14074	@cindex Expansion of macros, contexts for
	14075	By design, macro expansion does not happen in the following contexts
	14076	in @command{makeinfo}:
	14077
	14078	@itemize @bullet
	14079	@item @code{@@macro} and @code{@@unmacro} lines;
	14080
	14081	@item @code{@@if...} lines, including @code{@@ifset} and similar;
	14082
	14083	@item @code{@@set}, @code{@@clear}, @code{@@value};
	14084
	14085	@item @code{@@clickstyle} lines;
	14086
	14087	@item @code{@@end} lines.
	14088	@end itemize
	14089
	14090	@noindent Unfortunately, @TeX{} may do some expansion in these situations,
	14091	possibly yielding errors.
	14092
	14093	Also, quite a few macro-related constructs cause problems with @TeX{};
	14094	some of the caveats are listed below. Thus, if you get macro-related
	14095	errors when producing the printed version of a manual, you might try
	14096	expanding the macros with @command{makeinfo} by invoking
	14097	@command{texi2dvi} with the @samp{-E} option (@pxref{Format with
	14098	@command{texi2dvi}}). Or, more reliably, eschew Texinfo macros altogether
	14099	and use a language designed for macro processing, such as M4
	14100	(@pxref{External Macro Processors}).
	14101
	14102	@itemize @bullet
	14103	@item
	14104	As mentioned earlier, macro names must consist entirely of letters.
	14105
	14106	@item
	14107	It is not advisable to redefine any @TeX{} primitive, plain, or
	14108	Texinfo command name as a macro. Unfortunately this is a large and
	14109	open-ended set of names, and the possible resulting errors are
	14110	unpredictable.
	14111
	14112	@item
	14113	Arguments to macros taking more than one argument cannot cross lines.
	14114
	14115	@item
	14116	Macros containing a command which must be on a line by itself, such as
	14117	a conditional, cannot be invoked in the middle of a line. Similarly,
	14118	macros containing line-oriented commands or text, such as
	14119	@code{@@example} environments, may behave unpredictably in @TeX{}.
	14120
	14121	@item
	14122	If you have problems using conditionals within a macro, an alternative
	14123	is to use separate macro definitions inside conditional blocks. For
	14124	example, instead of
	14125
	14126	@example
	14127	@@macro Mac
	14128	@@iftex
	14129	text for TeX output
	14130	@@end iftex
	14131	@@ifnottex
	14132	text for not TeX output
	14133	@@end ifnottex
	14134	@@end macro
	14135	@end example
	14136
	14137	@noindent you can do the following instead:
	14138
	14139	@example
	14140	@@iftex
	14141	@@macro Mac
	14142	text for TeX output
	14143	@@end macro
	14144	@@end iftex
	14145
	14146	@@ifnottex
	14147	@@macro Mac
	14148	text for not TeX output
	14149	@@end macro
	14150	@@end ifnottex
	14151	@end example
	14152
	14153	@item
	14154	Texinfo commands in the expansion of a macro in the text of an index
	14155	entry may end up being typeset as literal text (including an ``@@''
	14156	sign), instead of being interpreted with their intended meaning.
	14157
	14158	@item
	14159	White space is ignored at the beginnings of lines.
	14160
	14161	@item
	14162	Macros can't be reliably used in the argument to accent commands
	14163	(@pxref{Inserting Accents}).
	14164
	14165	@item
	14166	The backslash escape for commas in macro arguments does not work;
	14167	@code{@@comma@{@}} must be used.
	14168
	14169	@item
	14170	Likewise, if you want to pass an argument with the Texinfo command
	14171	@code{@@,} (to produce a cedilla, see @ref{Inserting Accents}), you have
	14172	to use @code{@@value} or another work-around. Otherwise, the comma
	14173	may be taken as separating the arguments. For example,
	14174
	14175	@example
	14176	@@macro mactwo@{argfirst, argsecond@}
	14177	\argfirst\+\argsecond\.
	14178	@@end macro
	14179	@@set fc Fran@@,cois
	14180	@@mactwo@{@@value@{fc@},@}
	14181	@end example
	14182
	14183	@noindent produces:
	14184
	14185	@display
	14186	Fran@,cois+.
	14187	@end display
	14188
	14189	@c currently @mactwo{Fran@,cois} works in TeX, but @mactwo{Franc@\,cois}
	14190	@c works in makeinfo. better to avoid commas altogether using this trick.
	14191	@c an alternative to @, could be invented if needed.
	14192
	14193	@item
	14194	Ending a macro body with @samp{@@c} may cause text following the macro
	14195	invocation to be ignored as a comment in @command{makeinfo}. This is
	14196	not the case when processing with @TeX{}. This was often done
	14197	to ``comment out'' an unwanted newline at the end of a macro body, but
	14198	this is not necessary any more, as the final newline before @samp{@@end
	14199	macro} is not included in the macro body anyway.
	14200
	14201	@item
	14202	In general, you can't arbitrarily substitute a macro (or
	14203	@code{@@value}) call for Texinfo command arguments, even when the text
	14204	is the same. Texinfo is not M4 (or even plain @TeX{}). It might work
	14205	with some commands, it fails with others. Best not to do it at all.
	14206	For instance, this fails:
	14207
	14208	@example
	14209	@@macro offmacro
	14210	off
	14211	@@end macro
	14212	@@headings @@offmacro
	14213	@end example
	14214
	14215	@noindent
	14216	This looks equivalent to @code{@@headings off}, but for @TeX{}nical
	14217	reasons, it fails with a mysterious error message (namely,
	14218	@samp{Paragraph ended before @@headings was complete}).
	14219
	14220	@item
	14221	Macros cannot define macros in the natural way. To do this, you must
	14222	use conditionals and raw @TeX{}. For example:
	14223
	14224	@example
	14225	@@ifnottex
	14226	@@macro ctor @{name, arg@}
	14227	@@macro \name\
	14228	something involving \arg\ somehow
	14229	@@end macro
	14230	@@end macro
	14231	@@end ifnottex
	14232	@@tex
	14233	\gdef\ctor#1@{\ctorx#1,@}
	14234	\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
	14235	@@end tex
	14236	@end example
	14237	@end itemize
	14238
	14239	The @command{makeinfo} implementation also has the following
	14240	limitations (by design):
	14241
	14242	@itemize
	14243	@item
	14244	@code{@@verbatim} and macros do not mix; for instance, you can't start
	14245	a verbatim block inside a macro and end it outside
	14246	(@pxref{@code{@@verbatim}}). Starting any environment inside a macro
	14247	and ending it outside may or may not work, for that matter.
	14248
	14249	@item
	14250	Macros that completely define macros are ok, but it's not possible to
	14251	have incompletely nested macro definitions. That is, @code{@@macro}
	14252	and @code{@@end macro} (likewise for @code{@@rmacro}) must be
	14253	correctly paired. For example, you cannot start a macro definition
	14254	within a macro, and then end that nested definition outside the macro.
	14255	@end itemize
	14256
	14257	In the @code{makeinfo} implementation before Texinfo 5.0, ends of
	14258	lines from expansion of a @code{@@macro} definition did not end an
	14259	@@-command line-delimited argument (@code{@@chapter}, @code{@@center},
	14260	etc.). This is no longer the case. For example:
	14261
	14262	@example
	14263	@@macro twolines@{@}
	14264	aaa
	14265	bbb
	14266	@@end macro
	14267	@@center @@twolines@{@}
	14268	@end example
	14269
	14270	In the current @code{makeinfo}, this is equivalent to:
	14271
	14272	@example
	14273	@@center aaa
	14274	bbb
	14275	@end example
	14276
	14277	@noindent with just @samp{aaa} as the argument to @code{@@center}. In
	14278	the earlier implementation, it would have been parsed as this:
	14279
	14280	@example
	14281	@@center aaa bbb
	14282	@end example
	14283
	14284
	14285	@node @code{@@alias}
	14286	@section @samp{@@alias @var{new}=@var{existing}}
	14287
	14288	@anchor{alias}@c old name
	14289	@cindex Aliases, command
	14290	@cindex Command aliases
	14291	@findex alias
	14292
	14293	The @samp{@@alias} command defines a new command to be just like an
	14294	existing one. This is useful for defining additional markup names,
	14295	thus preserving additional semantic information in the input even
	14296	though the output result may be the same.
	14297
	14298	Write the @samp{@@alias} command on a line by itself, followed by the
	14299	new command name, an equals sign, and the existing command name.
	14300	Whitespace around the equals sign is optional and ignored if present.
	14301	Thus:
	14302
	14303	@example
	14304	@@alias @var{new} = @var{existing}
	14305	@end example
	14306
	14307	For example, if your document contains citations for both books and
	14308	some other media (movies, for example), you might like to define a
	14309	macro @code{@@moviecite@{@}} that does the same thing as an ordinary
	14310	@code{@@cite@{@}} but conveys the extra semantic information as well.
	14311	You'd do this as follows:
	14312
	14313	@example
	14314	@@alias moviecite = cite
	14315	@end example
	14316
	14317	Macros do not always have the same effect as aliases, due to vagaries
	14318	of argument parsing. Also, aliases are much simpler to define than
	14319	macros. So the command is not redundant.
	14320
	14321	Unfortunately, it's not possible to alias Texinfo environments; for
	14322	example, @code{@@alias lang=example} is an error.
	14323
	14324	Aliases must not be recursive, directly or indirectly.
	14325
	14326	It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or
	14327	Texinfo command name as an alias. Unfortunately this is a very large
	14328	set of names, and the possible resulting errors from @TeX{} are
	14329	unpredictable.
	14330
	14331	@command{makeinfo} will accept the same identifiers for aliases as it
	14332	does for macro names, that is, alphanumerics and (except as the first
	14333	character) @samp{-}.
	14334
	14335
	14336	@node @code{@@definfoenclose}
	14337	@section @code{@@definfoenclose}: Customized Highlighting
	14338
	14339	@anchor{definfoenclose}@c old name
	14340	@cindex Highlighting, customized
	14341	@cindex Customized highlighting
	14342	@findex definfoenclose
	14343
	14344	An @code{@@definfoenclose} command may be used to define a
	14345	highlighting command for all the non-@TeX{} output formats. A command
	14346	defined using @code{@@definfoenclose} marks text by enclosing it in
	14347	strings that precede and follow the text. You can use this to get
	14348	closer control of your output.
	14349
	14350	Presumably, if you define a command with @code{@@definfoenclose}, you
	14351	will create a corresponding command for @TeX{}, either in
	14352	@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} or
	14353	@samp{@@tex} in your document.
	14354
	14355	Write a @code{@@definfoenclose} command at the beginning of a line
	14356	followed by three comma-separated arguments. The first argument to
	14357	@code{@@definfoenclose} is the @@-command name (without the
	14358	@code{@@}); the second argument is the start delimiter string; and the
	14359	third argument is the end delimiter string. The latter two arguments
	14360	enclose the highlighted text in the output.
	14361
	14362	A delimiter string may contain spaces. Neither the start nor end
	14363	delimiter is required. If you do not want a start delimiter but do
	14364	want an end delimiter, you must follow the command name with two
	14365	commas in a row; otherwise, the end delimiter string you intended will
	14366	naturally be (mis)interpreted as the start delimiter string.
	14367
	14368	If you do a @code{@@definfoenclose} on the name of a predefined
	14369	command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or
	14370	@code{@@i}), the enclosure definition will override the built-in
	14371	definition. We don't recommend this.
	14372
	14373	An enclosure command defined this way takes one argument in braces,
	14374	since it is intended for new markup commands (@pxref{Marking Text}).
	14375
	14376	@findex phoo
	14377	For example, you can write:
	14378
	14379	@example
	14380	@@definfoenclose phoo,//,\\
	14381	@end example
	14382
	14383	@noindent
	14384	near the beginning of a Texinfo file to define @code{@@phoo} as an Info
	14385	formatting command that inserts `//' before and `\\' after the argument
	14386	to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
	14387	want `//bar\\' highlighted in Info.
	14388
	14389	For @TeX{} formatting, you could write
	14390
	14391	@example
	14392	@@iftex
	14393	@@global@@let@@phoo=@@i
	14394	@@end iftex
	14395	@end example
	14396
	14397	@noindent
	14398	to define @code{@@phoo} as a command that causes @TeX{} to typeset the
	14399	argument to @code{@@phoo} in italics.
	14400
	14401	Each definition applies to its own formatter: one for @TeX{}, the
	14402	other for everything else. The raw @TeX{} commands need to be in
	14403	@samp{@@iftex}. @code{@@definfoenclose} command need not be within
	14404	@samp{@@ifinfo}, unless you want to use different definitions for
	14405	different output formats.
	14406
	14407	@findex headword
	14408	Here is another example: write
	14409
	14410	@example
	14411	@@definfoenclose headword, , :
	14412	@end example
	14413
	14414	@noindent
	14415	near the beginning of the file, to define @code{@@headword} as an Info
	14416	formatting command that inserts nothing before and a colon after the
	14417	argument to @code{@@headword}.
	14418
	14419	@samp{@@definfoenclose} definitions must not be recursive, directly or
	14420	indirectly.
	14421
	14422
	14423	@node External Macro Processors
	14424	@section External Macro Processors: Line Directives
	14425	@cindex External macro processors
	14426	@cindex Macro processors, external
	14427
	14428	Texinfo macros (and its other text substitution facilities) work fine
	14429	in straightforward cases. If your document needs unusually complex
	14430	processing, however, their fragility and limitations can be a problem.
	14431	In this case, you may want to use a different macro processor
	14432	altogether, such as M4 (@pxref{Top,,, m4, M4}) or CPP (@pxref{Top,,,
	14433	cpp, The C Preprocessor}).
	14434
	14435	With one exception, Texinfo does not need to know whether its input is
	14436	``original'' source or preprocessed from some other source file.
	14437	Therefore, you can arrange your build system to invoke whatever
	14438	programs you like to handle macro expansion or other preprocessing
	14439	needs. Texinfo does not offer built-in support for any particular
	14440	preprocessor, since no one program seemed likely to suffice for the
	14441	requirements of all documents.
	14442
	14443	@cindex Line numbers, in error messages
	14444	@cindex Error messages, line numbers in
	14445	The one exception is line numbers in error messages. In that case,
	14446	the line number should refer to the original source file, whatever it
	14447	may be. There's a well-known mechanism for this: the so-called
	14448	@samp{#line} directive. Texinfo supports this.
	14449
	14450	@menu
	14451	* @samp{#line} Directive::
	14452	* TeX: @samp{#line} and @TeX{}.
	14453	* Syntax: @samp{#line} Syntax Details.
	14454	@end menu
	14455
	14456
	14457	@node @samp{#line} Directive
	14458	@subsection @samp{#line} Directive
	14459
	14460	@cindex @samp{#line} directive
	14461
	14462	An input line such as this:
	14463
	14464	@example
	14465	@hashchar{}line 100 "foo.ptexi"
	14466	@end example
	14467
	14468	@noindent indicates that the next line was line 100 of the file
	14469	@file{foo.ptexi}, and so that's what an error message should refer to.
	14470	Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP
	14471	(@pxref{Line Control,,, cpp, The C Preprocessor}, and
	14472	@ref{Preprocessor Output,,, cpp, The C Preprocessor}) can generate
	14473	such lines.
	14474
	14475	@vindex CPP_LINE_DIRECTIVES
	14476	The @command{makeinfo} program recognizes these lines by default,
	14477	except within @code{@@verbatim} blocks (@pxref{@code{@@verbatim}}).
	14478	Their recognition can be turned off completely with
	14479	@code{CPP_LINE_DIRECTIVES} (@pxref{Other Customization Variables}),
	14480	though there is normally no reason to do so.
	14481
	14482	For those few programs (M4, CPP, Texinfo) which need to document
	14483	@samp{#line} directives and therefore have examples which would
	14484	otherwise match the pattern, the command @code{@@hashchar@{@}} can be
	14485	used (@pxref{Inserting a Hashsign}). The example line above looks
	14486	like this in the source for this manual:
	14487
	14488	@example
	14489	@@hashchar@{@}line 100 "foo.ptexi"
	14490	@end example
	14491
	14492	The @code{@@hashchar} command was added to Texinfo in 2013. If you
	14493	don't want to rely on it, you can also use @code{@@set} and
	14494	@code{@@value} to insert the literal @samp{#}:
	14495
	14496	@example
	14497	@@set hash #
	14498	@@value@{hash@}line 1 "example.c"
	14499	@end example
	14500
	14501	Or, if suitable, a @code{@@verbatim} environment can be used instead
	14502	of @code{@@example}. As mentioned above, @code{#line}-recognition is
	14503	disabled inside verbatim blocks.
	14504
	14505
	14506	@node @samp{#line} and @TeX{}
	14507	@subsection @samp{#line} and @TeX{}
	14508
	14509	@cindex @TeX{} and @samp{#line} directives
	14510	@cindex @samp{#line} directives, not processing with @TeX{}
	14511
	14512	As mentioned, @command{makeinfo} recognizes the @samp{#line}
	14513	directives described in the previous section. However,
	14514	@file{texinfo.tex} does not and cannot. Therefore, such a line will
	14515	be incorrectly typeset verbatim if @TeX{} sees it. The solution is to
	14516	use @command{makeinfo}'s macro expansion options before running
	14517	@TeX{}. There are three approaches:
	14518
	14519	@itemize @bullet
	14520	@item
	14521	If you run @command{texi2dvi} or its variants (@pxref{Format with
	14522	@command{texi2dvi}}), you can pass @option{-E} and @command{texi2dvi}
	14523	will run @command{makeinfo} first to expand macros and eliminate
	14524	@samp{#line}.
	14525
	14526	@item
	14527	If you run @command{makeinfo} or its variants (@pxref{Generic
	14528	Translator @command{texi2any}}), you can specify @option{--no-ifinfo
	14529	--iftex -E somefile.out}, and then give @file{somefile.out} to
	14530	@code{texi2dvi} in a separate command.
	14531
	14532	@item
	14533	Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf}
	14534	instead of @option{--dvi}.) @command{makeinfo} will then call
	14535	@command{texi2dvi -E}.
	14536	@end itemize
	14537
	14538	@findex errormsg@r{, and line numbers in @TeX{}}
	14539	One last caveat regarding use with @TeX{}: since the @code{#line}
	14540	directives are not recognized, the line numbers emitted by the
	14541	@code{@@errormsg@{@}} command (@pxref{Conditional Commands}), or by
	14542	@TeX{} itself, are the (incorrect) line numbers from the derived file
	14543	which @TeX{} is reading, rather than the preprocessor-specified line
	14544	numbers. This is another example of why we recommend running
	14545	@command{makeinfo} for the best diagnostics (@pxref{@command{makeinfo}
	14546	Advantages}).
	14547
	14548
	14549	@node @samp{#line} Syntax Details
	14550	@subsection @samp{#line} Syntax Details
	14551
	14552	@cindex @samp{#line} syntax details
	14553	@cindex Syntax details, @samp{#line}
	14554	@cindex Regular expression, for @samp{#line}
	14555
	14556	Syntax details for the @samp{#line} directive: the @samp{#} character
	14557	can be preceded or followed by whitespace, the word @samp{line} is
	14558	optional, and the file name can be followed by a whitespace-separated
	14559	list of integers (these are so-called ``flags'' output by CPP in some
	14560	cases). For those who like to know the gory details, the actual
	14561	(Perl) regular expression which is matched is this:
	14562
	14563	@example
	14564	/^\s#\s(line)? (\d+)(( "([^"]+)")(\s+\d+))?\s$/
	14565	@end example
	14566
	14567	As far as we've been able to tell, the trailing integer flags only
	14568	occur in conjunction with a filename, so that is reflected in the
	14569	regular expression.
	14570
	14571	As an example, the following is a syntactically valid @samp{#line}
	14572	directive, meaning line 1 of @file{/usr/include/stdio.h}:
	14573
	14574	@example
	14575	@hashchar{} 1 "/usr/include/stdio.h" 2 3 4
	14576	@end example
	14577
	14578	Unfortunately, the quoted filename (@samp{"..."}) has to be optional,
	14579	because M4 (especially) can often generate @samp{#line} directives
	14580	within a single file. Since the @samp{line} is also optional, the
	14581	result is that lines might match which you wouldn't expect, e.g.,
	14582
	14583	@example
	14584	@hashchar{} 1
	14585	@end example
	14586
	14587	The possible solutions are described above (@pxref{@samp{#line} Directive}).
	14588
	14589
	14590	@node Include Files
	14591	@chapter Include Files
	14592
	14593	@cindex Include files
	14594
	14595	When a Texinfo processor sees an @code{@@include} command in a Texinfo
	14596	file, it processes the contents of the file named by the
	14597	@code{@@include} and incorporates them into the output files being
	14598	created. Include files thus let you keep a single large document as a
	14599	collection of conveniently small parts.
	14600
	14601	@menu
	14602	* Using Include Files:: How to use the @code{@@include} command.
	14603	* @code{texinfo-multiple-files-update}:: How to create and update nodes and
	14604	menus when using included files.
	14605	* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
	14606	* Sample Include File:: A sample outer file with included files
	14607	within it; and a sample included file.
	14608	* @code{@@verbatiminclude}:: Including a file verbatim.
	14609	* Include Files Evolution:: How use of the @code{@@include} command
	14610	has changed over time.
	14611	@end menu
	14612
	14613
	14614	@node Using Include Files
	14615	@section How to Use Include Files
	14616
	14617	@findex include
	14618
	14619	To include another file within a Texinfo file, write the
	14620	@code{@@include} command at the beginning of a line and follow it on
	14621	the same line by the name of a file to be included. For example:
	14622
	14623	@example
	14624	@@include buffers.texi
	14625	@end example
	14626
	14627	@@-commands are expanded in file names. The one most likely to be
	14628	useful is @code{@@value} (@pxref{@code{@@set @@value}}), and even then
	14629	only in complicated situations.
	14630
	14631	An included file should simply be a segment of text that you expect to
	14632	be included as is into the overall or @dfn{outer} Texinfo file; it
	14633	should not contain the standard beginning and end parts of a Texinfo
	14634	file. In particular, you should not start an included file with a
	14635	line saying @samp{\input texinfo}; if you do, that text is inserted
	14636	into the output file literally. Likewise, you should not end an
	14637	included file with a @code{@@bye} command; nothing after @code{@@bye}
	14638	is formatted.
	14639
	14640	In the long-ago past, you were required to write an
	14641	@code{@@setfilename} line at the beginning of an included file, but no
	14642	longer. Now, it does not matter whether you write such a line. If an
	14643	@code{@@setfilename} line exists in an included file, it is ignored.
	14644
	14645
	14646	@node @code{texinfo-multiple-files-update}
	14647	@section @code{texinfo-multiple-files-update}
	14648
	14649	@findex texinfo-multiple-files-update
	14650
	14651	GNU Emacs Texinfo mode provides the
	14652	@code{texinfo-multiple-files-update} command. This command creates or
	14653	updates `Next', `Previous', and `Up' pointers of included files as
	14654	well as those in the outer or overall Texinfo file, and it creates or
	14655	updates a main menu in the outer file. Depending on whether you call
	14656	it with optional arguments, the command updates only the pointers in
	14657	the first @code{@@node} line of the included files or all of them:
	14658
	14659	@table @kbd
	14660	@item M-x texinfo-multiple-files-update
	14661	Called without any arguments:
	14662
	14663	@itemize @minus
	14664	@item
	14665	Create or update the `Next', `Previous', and `Up' pointers of the
	14666	first @code{@@node} line in each file included in an outer or overall
	14667	Texinfo file.
	14668
	14669	@item
	14670	Create or update the `Top' level node pointers of the outer or
	14671	overall file.
	14672
	14673	@item
	14674	Create or update a main menu in the outer file.
	14675	@end itemize
	14676
	14677	@item C-u M-x texinfo-multiple-files-update
	14678	Called with @kbd{C-u} as a prefix argument:
	14679
	14680	@itemize @minus{}
	14681	@item
	14682	Create or update pointers in the first @code{@@node} line in each
	14683	included file.
	14684
	14685	@item
	14686	Create or update the `Top' level node pointers of the outer file.
	14687
	14688	@item
	14689	Create and insert a master menu in the outer file. The master menu
	14690	is made from all the menus in all the included files.
	14691	@end itemize
	14692
	14693	@item C-u 8 M-x texinfo-multiple-files-update
	14694	Called with a numeric prefix argument, such as @kbd{C-u 8}:
	14695
	14696	@itemize @minus
	14697	@item
	14698	Create or update @emph{all} the `Next', `Previous', and `Up' pointers
	14699	of all the included files.
	14700
	14701	@item
	14702	Create or update @emph{all} the menus of all the included
	14703	files.
	14704
	14705	@item
	14706	Create or update the `Top' level node pointers of the outer or
	14707	overall file.
	14708
	14709	@item
	14710	And then create a master menu in the outer file. This is similar to
	14711	invoking @code{texinfo-master-menu} with an argument when you are
	14712	working with just one file.
	14713	@end itemize
	14714	@end table
	14715
	14716	Note the use of the prefix argument in interactive use: with a regular
	14717	prefix argument, just @w{@kbd{C-u}}, the
	14718	@code{texinfo-multiple-files-update} command inserts a master menu;
	14719	with a numeric prefix argument, such as @kbd{C-u 8}, the command
	14720	updates @emph{every} pointer and menu in @emph{all} the files and
	14721	then inserts a master menu.
	14722
	14723
	14724	@node Include Files Requirements
	14725	@section Include Files Requirements
	14726	@cindex Include files requirements
	14727	@cindex Requirements for include files
	14728
	14729	If you plan to use the @code{texinfo-multiple-files-update} command,
	14730	the outer Texinfo file that lists included files within it should
	14731	contain nothing but the beginning and end parts of a Texinfo file, and
	14732	a number of @code{@@include} commands listing the included files. It
	14733	should not even include indices, which should be listed in an included
	14734	file of their own.
	14735
	14736	Moreover, each of the included files must contain exactly one highest
	14737	level node (conventionally, @code{@@chapter} or equivalent),
	14738	and this node must be the first node in the included file.
	14739	Furthermore, each of these highest level nodes in each included file
	14740	must be at the same hierarchical level in the file structure.
	14741	Usually, each is a @code{@@chapter}, an @code{@@appendix}, or an
	14742	@code{@@unnumbered} node. Thus, normally, each included file contains
	14743	one, and only one, chapter or equivalent-level node.
	14744
	14745	The outer file should contain only @emph{one} node, the `Top' node. It
	14746	should @emph{not} contain any nodes besides the single `Top' node. The
	14747	@code{texinfo-multiple-files-update} command will not process
	14748	them.
	14749
	14750
	14751	@node Sample Include File
	14752	@section Sample File with @code{@@include}
	14753	@cindex Sample @code{@@include} file
	14754	@cindex Include file sample
	14755	@cindex @code{@@include} file sample
	14756
	14757	Here is an example of an outer Texinfo file with @code{@@include} files
	14758	within it before running @code{texinfo-multiple-files-update}, which
	14759	would insert a main or master menu:
	14760
	14761	@example
	14762	@group
	14763	\input texinfo @@c --texinfo--
	14764	@c %**start of header
	14765	@@settitle Include Example
	14766	@c %**end of header
	14767	@end group
	14768
	14769	... @xref{Sample Texinfo Files}, for
	14770	examples of the rest of the frontmatter ...
	14771
	14772	@group
	14773	@@ifnottex
	14774	@@node Top
	14775	@@top Include Example
	14776	@@end ifnottex
	14777	@end group
	14778
	14779	@group
	14780	@@include foo.texinfo
	14781	@@include bar.texinfo
	14782	@@include concept-index.texinfo
	14783	@@bye
	14784	@end group
	14785	@end example
	14786
	14787	An included file, such as @file{foo.texinfo}, might look like this:
	14788
	14789	@example
	14790	@group
	14791	@@node First
	14792	@@chapter First Chapter
	14793
	14794	Contents of first chapter @dots{}
	14795	@end group
	14796	@end example
	14797
	14798	The full contents of @file{concept-index.texinfo} might be as simple as this:
	14799
	14800	@example
	14801	@group
	14802	@@node Concept Index
	14803	@@unnumbered Concept Index
	14804
	14805	@@printindex cp
	14806	@end group
	14807	@end example
	14808
	14809	The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
	14810	Manual} is named @file{elisp.texi}. This outer file contains a master
	14811	menu with 417 entries and a list of 41 @code{@@include}
	14812	files.
	14813
	14814
	14815	@node @code{@@verbatiminclude}
	14816	@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
	14817
	14818	@anchor{verbatiminclude}@c old name
	14819	@findex verbatiminclude
	14820	@cindex Verbatim, include file
	14821	@cindex Including a file verbatim
	14822
	14823	You can include the exact contents of a file in the document with the
	14824	@code{@@verbatiminclude} command:
	14825
	14826	@example
	14827	@@verbatiminclude @var{filename}
	14828	@end example
	14829
	14830	The contents of @var{filename} is printed in a verbatim environment
	14831	(@pxref{@code{@@verbatim}}). Generally, the file is printed exactly
	14832	as it is, with all special characters and white space retained. No
	14833	indentation is added; if you want indentation, enclose the
	14834	@code{@@verbatiminclude} within @code{@@example}
	14835	(@pxref{@code{@@example}}).
	14836
	14837	The name of the file is taken literally, with a single exception:
	14838	@code{@@value@{@var{var}@}} references are expanded. This makes it
	14839	possible to include files in other directories within a distribution,
	14840	for instance:
	14841
	14842	@example
	14843	@@verbatiminclude @@value@{top_srcdir@}/NEWS
	14844	@end example
	14845
	14846	@noindent (You still have to get @code{top_srcdir} defined in the
	14847	first place.)
	14848
	14849	For a method on printing the file contents in a smaller font size, see
	14850	the end of the section on @code{@@verbatim}.
	14851
	14852
	14853	@node Include Files Evolution
	14854	@section Evolution of Include Files
	14855
	14856	When Info was first created, it was customary to create many small
	14857	Info files on one subject. Each Info file was formatted from its own
	14858	Texinfo source file. This custom meant that Emacs did not need to
	14859	make a large buffer to hold the whole of a large Info file when
	14860	someone wanted information; instead, Emacs allocated just enough
	14861	memory for the small Info file that contained the particular
	14862	information sought. This way, Emacs could avoid wasting memory.
	14863
	14864	References from one file to another were made by referring to the file
	14865	name as well as the node name. (@xref{Other Info Files, , Referring to
	14866	Other Info Files}. Also, see @ref{Four and Five Arguments, ,
	14867	@code{@@xref} with Four and Five Arguments}.)
	14868
	14869	Include files were designed primarily as a way to create a single,
	14870	large printed manual out of several smaller Info files. In a printed
	14871	manual, all the references were within the same document, so @TeX{}
	14872	could automatically determine the references' page numbers. The Info
	14873	formatting commands used include files only for creating joint
	14874	indices; each of the individual Texinfo files had to be formatted for
	14875	Info individually. (Each, therefore, required its own
	14876	@code{@@setfilename} line.)
	14877
	14878	However, because large Info files are now split automatically, it is
	14879	no longer necessary to keep them small.
	14880
	14881	Nowadays, multiple Texinfo files are used mostly for large documents,
	14882	such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
	14883	in which several different people write different sections of a
	14884	document simultaneously.
	14885
	14886	In addition, the Info formatting commands have been extended to work
	14887	with the @code{@@include} command so as to create a single large Info
	14888	file that is split into smaller files if necessary. This means that
	14889	you can write menus and cross-references without naming the different
	14890	Texinfo files.
	14891
	14892
	14893	@node Hardcopy
	14894	@chapter Formatting and Printing Hardcopy
	14895	@cindex Format and print hardcopy
	14896	@cindex Printing hardcopy
	14897	@cindex Hardcopy, printing it
	14898	@cindex Making a printed manual
	14899	@cindex Sorting indices
	14900	@cindex Indices, sorting
	14901	@cindex @TeX{} index sorting
	14902
	14903	Running the @command{texi2dvi} or @command{texi2pdf} command is the
	14904	simplest way to create printable output. These commands are installed
	14905	as part of the Texinfo package.
	14906
	14907	In more detail, three major shell commands are used to print formatted
	14908	output from a Texinfo manual: one converts the Texinfo source into
	14909	something printable, a second sorts indices, and a third actually
	14910	prints the formatted document. When you use the shell commands, you
	14911	can either work directly in the operating system shell or work within
	14912	a shell inside GNU Emacs (or some other computing environment).
	14913
	14914	If you are using GNU Emacs, you can use commands provided by Texinfo
	14915	mode instead of shell commands. In addition to the three commands to
	14916	format a file, sort the indices, and print the result, Texinfo mode
	14917	offers key bindings for commands to recenter the output buffer, show the
	14918	print queue, and delete a job from the print queue.
	14919
	14920	Details are in the following sections.
	14921
	14922	@menu
	14923	* Use @TeX{}:: Use @TeX{} to format for hardcopy.
	14924	* Format with @command{texi2dvi}:: The simplest way to format.
	14925	* Format with @command{tex}/@command{texindex}:: Formatting with explicit shell commands.
	14926	* Print with @command{lpr}:: How to print.
	14927	* Within Emacs:: How to format and print from an Emacs shell.
	14928	* Texinfo Mode Printing:: How to format and print in Texinfo mode.
	14929	* Compile-Command:: How to print using Emacs's compile command.
	14930	* Requirements Summary:: @TeX{} formatting requirements summary.
	14931	* Preparing for @TeX{}:: What to do before you use @TeX{}.
	14932	* Overfull hboxes:: What are and what to do with overfull hboxes.
	14933	* @code{@@smallbook}:: How to print small format books and manuals.
	14934	* A4 Paper:: How to print on A4 or A5 paper.
	14935	* @code{@@pagesizes}:: How to print with customized page sizes.
	14936	* Magnification:: How to print scaled up output.
	14937	* PDF Output:: Portable Document Format output.
	14938	* Obtaining @TeX{}:: How to obtain @TeX{}.
	14939	@end menu
	14940
	14941
	14942	@node Use @TeX{}
	14943	@section Use @TeX{}
	14944
	14945	The typesetting program called @TeX{} is used to format a Texinfo
	14946	document for printable output. @TeX{} is a very powerful typesetting
	14947	program and, when used correctly, does an exceptionally good job.
	14948
	14949	@xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It
	14950	is not included in the Texinfo package, being a vast suite of software
	14951	in itself.
	14952
	14953
	14954	@node Format with @command{texi2dvi}
	14955	@section Format with @command{texi2dvi}
	14956
	14957	@pindex texi2dvi @r{(shell script)}
	14958	@cindex DVI, output in
	14959
	14960	The @code{texi2dvi} program takes care of all the steps for producing
	14961	a @TeX{} DVI file from a Texinfo document. Similarly, @code{texi2pdf}
	14962	produces a PDF file.
	14963
	14964	To run @code{texi2dvi} or @code{texi2pdf} on an input file
	14965	@file{foo.texi}, do this (where @samp{prompt$ } is your shell prompt):
	14966
	14967	@example
	14968	prompt$ @kbd{texi2dvi foo.texi}
	14969	prompt$ @kbd{texi2pdf foo.texi}
	14970	@end example
	14971
	14972	As shown in this example, the input filenames to @code{texi2dvi} and
	14973	@code{texi2pdf} must include any extension, such as @samp{.texi}.
	14974	(Under MS-DOS and perhaps in other circumstances, you may need to run
	14975	@samp{sh texi2dvi foo.texi} instead of relying on the operating system
	14976	to invoke the shell on the @samp{texi2dvi} script.)
	14977
	14978	For a list of all the options, run @samp{texi2dvi --help}. Some of the
	14979	options are discussed below.
	14980
	14981	@opindex --pdf@r{, for @command{texi2dvi}}
	14982	@pindex pdftexi2dvi
	14983	With the @option{--pdf} option, @command{texi2dvi} produces PDF output
	14984	instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
	14985	instead of @command{tex}. Alternatively, the command
	14986	@command{texi2pdf} is an abbreviation for running @samp{texi2dvi
	14987	--pdf}. The command @command{pdftexi2dvi} is also provided as a
	14988	convenience for AUC-@TeX{} (@pxref{Top,,, auctex, AUC-@TeX{}}), as it
	14989	prefers to merely prepend @samp{pdf} to DVI producing tools to have
	14990	PDF producing tools.
	14991
	14992	@opindex --dvipdf@r{, for @command{texi2dvi}}
	14993	@pindex dvipdfmx
	14994	With the @option{--dvipdf} option, @command{texi2dvi} produces PDF
	14995	output by running @TeX{} and then a DVI-to-PDF program: if the
	14996	@env{DVIPDF} environment variable is set, that value is used, else the
	14997	first program extant among @code{dvipdfmx}, @code{dvipdfm},
	14998	@code{dvipdf}, @code{dvi2pdf}, @code{dvitopdf}. This method generally
	14999	supports CJK typesetting better than @command{pdftex}.
	15000
	15001	@opindex --ps@r{, for @command{texi2dvi}}
	15002	@pindex dvips
	15003	With the @option{--ps} option, @command{texi2dvi} produces PostScript
	15004	instead of DVI, by running @command{tex} and then @command{dvips}
	15005	(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS}
	15006	environment variable, if set.)
	15007
	15008	@opindex --language@r{, for @command{texi2dvi}}
	15009	@cindex @LaTeX{}, processing with @command{texi2dvi}
	15010	@command{texi2dvi} can also be used to process @LaTeX{} files.
	15011	Normally @command{texi2dvi} is able to guess the input file language
	15012	by its contents and file name extension; however, if it guesses wrong
	15013	you can explicitly specify the input language using
	15014	@option{--language=@var{lang}} command line option, where @var{lang}
	15015	is either @samp{latex} or @samp{texinfo}.
	15016
	15017	@opindex --command@r{, for @command{texi2dvi}}
	15018	One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}.
	15019	This inserts @var{cmd} on a line by itself at the start of the file
	15020	in a temporary copy of the input file, before
	15021	running @TeX{}. With this, you can specify different printing
	15022	formats, such as @code{@@smallbook} (@pxref{@code{@@smallbook}}),
	15023	@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
	15024	(@pxref{@code{@@pagesizes}}), without actually changing the document
	15025	source. (You can also do this on a site-wide basis with
	15026	@file{texinfo.cnf}; @pxref{Preparing for @TeX{}}).
	15027
	15028	The option @option{-E} (equivalently, @option{-e} and
	15029	@option{--expand}) does Texinfo macro expansion using
	15030	@command{makeinfo} instead of the @TeX{} implementation (@pxref{Macro
	15031	Details}). Each implementation has its own limitations and
	15032	advantages. If this option is used, no line in the source file
	15033	may begin with the string @code{@@c@tie{}_texi2dvi} or the
	15034	string @code{@@c@tie{}(_texi2dvi)}.
	15035
	15036	@command{texi2dvi} takes the @option{--build=@var{mode}} option to
	15037	specify where the @TeX{} compilation takes place, and, as a
	15038	consequence, how auxiliary files are treated. The build mode
	15039	can also be set using the environment variable
	15040	@env{TEXI2DVI_BUILD_MODE}. The valid values for @var{mode} are:
	15041
	15042	@table @samp
	15043	@item local
	15044	Compile in the current directory, leaving all the auxiliary
	15045	files around. This is the traditional TeX use.
	15046
	15047	@item tidy
	15048	Compile in a local @code{*.t2d} directory, where the auxiliary files
	15049	are left. Output files are copied back to the original file.
	15050
	15051	Using the @samp{tidy} mode brings several advantages:
	15052	@itemize -
	15053	@item the current directory is not cluttered with plethora of temporary files.
	15054	@item clutter can be even further reduced using @option{--build-dir=dir}: all
	15055	the @code{*.t2d} directories are stored there.
	15056	@item clutter can be reduced to zero using, e.g.,
	15057	@option{--build-dir=/tmp/\$USER.t2d} or @option {--build-dir=\$HOME/.t2d}.
	15058	@item the output file is updated after every successful @TeX{} run, for
	15059	sake of concurrent visualization of the output. In a @samp{local} build
	15060	the viewer stops during the whole @TeX{} run.
	15061	@item if the compilation fails, the previous state of the output file
	15062	is preserved.
	15063	@item @acronym{PDF} and @acronym{DVI} compilation are kept in separate
	15064	subdirectories
	15065	preventing any possibility of auxiliary file incompatibility.
	15066	@end itemize
	15067
	15068	On the other hand, because @samp{tidy} compilation takes place in another
	15069	directory, occasionally @TeX{} won't be able to find some files (e.g., when
	15070	using @code{\graphicspath}): in that case, use @option{-I} to specify the
	15071	additional directories to consider.
	15072
	15073	@item clean
	15074	Same as @samp{tidy}, but remove the auxiliary directory afterwards.
	15075	Every compilation therefore requires the full cycle.
	15076	@end table
	15077
	15078	@pindex etex
	15079	@pindex pdfetex
	15080	@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if
	15081	it is available, because it runs faster in some cases, and
	15082	provides additional tracing information when debugging
	15083	@file{texinfo.tex}. Nevertheless, this extended version of @TeX{} is
	15084	not required, and the DVI output is identical.
	15085	(These days, @command{pdftex} and @command{pdfetex} are exactly the
	15086	same, but we still run @command{pdfetex} to cater to ancient @TeX{}
	15087	installations.)
	15088
	15089	@cindex filename recorder for @TeX{}
	15090	@cindex @samp{\openout} line in log file
	15091	@command{texi2dvi} attempts to detect auxiliary files output by @TeX{},
	15092	either by using the @option{-recorder} option, or by scanning for
	15093	@samp{\openout} in the log file that a run of @TeX{} produces. You may
	15094	control how @command{texi2dvi} does this with the @env{TEXI2DVI_USE_RECORDER}
	15095	environment variable. Valid values are:
	15096
	15097	@table @samp
	15098	@item yes
	15099	use the @option{-recorder} option, no checks.
	15100
	15101	@item no
	15102	scan for @samp{\openout} in the log file, no checks.
	15103
	15104	@item yesmaybe
	15105	check whether @option{-recorder} option is supported, and if yes
	15106	use it, otherwise check for tracing @samp{\openout} in the log file is
	15107	supported, and if yes use it, else it is an error.
	15108
	15109	@item nomaybe
	15110	same as @samp{yesmaybe}, except that the @samp{\openout} trace in log
	15111	file is checked first.
	15112	@end table
	15113
	15114	The default is @samp{nomaybe}. This environment variable is provided
	15115	for troubleshooting purposes, and may change or disappear in the future.
	15116
	15117
	15118	@node Format with @command{tex}/@command{texindex}
	15119	@section Format with @command{tex}/@command{texindex}
	15120
	15121	@cindex Shell formatting with @code{tex} and @code{texindex}
	15122	@cindex Formatting with @code{tex} and @code{texindex}
	15123	@cindex DVI file
	15124
	15125	You can do the basic formatting of a Texinfo file with the shell
	15126	command @code{tex} followed by the name of the Texinfo file. For
	15127	example:
	15128
	15129	@example
	15130	tex foo.texi
	15131	@end example
	15132
	15133	@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
	15134	files containing information for indices, cross-references, etc. The
	15135	DVI file (for @dfn{DeVice Independent} file) can be printed on
	15136	virtually any device, perhaps after a further conversion (see the
	15137	previous section).
	15138
	15139	@pindex texindex
	15140	The @code{tex} formatting command itself does not sort the indices; it
	15141	writes an output file of unsorted index data. To generate a printed
	15142	index after running the @command{tex} command, you first need a sorted
	15143	index to work from. The @command{texindex} command sorts indices.
	15144	(@command{texi2dvi}, described in the previous section, runs
	15145	@command{tex} and @command{texindex} as necessary.)
	15146
	15147	@anchor{Names of index files}
	15148	@cindex Names of index files
	15149	@cindex Index file names
	15150	@code{tex} outputs unsorted index files under names following a
	15151	standard convention: the name of your main input file with any
	15152	@samp{.texi} or similar extension replaced by the two letter index
	15153	name. For example, the raw index output files for the input file
	15154	@file{foo.texi} would be, by default, @file{foo.cp}, @file{foo.vr},
	15155	@file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those
	15156	are exactly the arguments to give to @code{texindex}.
	15157
	15158	@need 1000
	15159	@cindex Wildcards
	15160	@cindex Globbing
	15161	Instead of specifying all the unsorted index file names explicitly,
	15162	it's typical to use @samp{??} as shell wildcards and give the command
	15163	in this form:
	15164
	15165	@example
	15166	texindex foo.??
	15167	@end example
	15168
	15169	@noindent
	15170	This command will run @code{texindex} on all the unsorted index files,
	15171	including any two letter indices that you have defined yourself using
	15172	@code{@@defindex} or @code{@@defcodeindex}. You can safely run
	15173	@samp{texindex foo.??} even if there are files with two letter
	15174	extensions that are not index files, such as @samp{foo.el}. The
	15175	@code{texindex} command reports but otherwise ignores such files.
	15176
	15177	For each file specified, @code{texindex} generates a sorted index file
	15178	whose name is made by appending @samp{s} to the input file name; for
	15179	example, @file{foo.cps} is made from @file{foo.cp}. The
	15180	@code{@@printindex} command looks for a file with that name
	15181	(@pxref{Printing Indices & Menus}). @TeX{} does not read the raw
	15182	index output file, and @code{texindex} does not alter it.
	15183
	15184	After you have sorted the indices, you need to rerun @code{tex} on the
	15185	Texinfo file. This regenerates the output file, this time with
	15186	up-to-date index entries.
	15187
	15188	Finally, you may need to run @code{tex} one more time, to get the page
	15189	numbers in the cross-references correct.
	15190
	15191	To summarize, this is a five step process. (Alternatively, it's a
	15192	one-step process: run @code{texi2dvi}; see the previous section.)
	15193
	15194	@enumerate
	15195	@item
	15196	Run @code{tex} on your Texinfo file. This generates a DVI file (with
	15197	undefined cross-references and no indices), and the raw index files
	15198	(with two letter extensions).
	15199
	15200	@item
	15201	Run @code{texindex} on the raw index files. This creates the
	15202	corresponding sorted index files (with three letter extensions).
	15203
	15204	@item
	15205	Run @code{tex} again on your Texinfo file. This regenerates the DVI
	15206	file, this time with indices and defined cross-references, but with
	15207	page numbers for the cross-references from the previous run, generally
	15208	incorrect.
	15209
	15210	@item
	15211	Sort the indices again, with @code{texindex}.
	15212
	15213	@item
	15214	Run @code{tex} one last time. This time the correct page numbers are
	15215	written for the cross-references.
	15216	@end enumerate
	15217
	15218	@menu
	15219	* Formatting Partial Documents::
	15220	* Details of @command{texindex}::
	15221	@end menu
	15222
	15223	@node Formatting Partial Documents
	15224	@subsection Formatting Partial Documents
	15225
	15226	@cindex Formatting partial documents
	15227	@cindex Partial documents, formatting
	15228	@cindex Chapters, formatting one at a time
	15229	@cindex Auxiliary files, omitting
	15230	@cindex Pointer validation, suppressing
	15231	@findex novalidate
	15232
	15233	Sometimes you may wish to print a document while you know it is
	15234	incomplete, or to print just one chapter of a document. In such a
	15235	case, the usual auxiliary files that @TeX{} creates and warnings
	15236	@TeX{} gives about undefined cross-references are just nuisances. You
	15237	can avoid them with the @code{@@novalidate} command, which you must
	15238	give @emph{before} any sectioning or cross-reference commands.
	15239
	15240	Thus, the beginning of your file would look approximately like this:
	15241
	15242	@example
	15243	\input texinfo
	15244	@@novalidate
	15245	@dots{}
	15246	@end example
	15247
	15248	@noindent @code{@@novalidate} also turns off validation in
	15249	@code{makeinfo}, just like its @code{--no-validate} option
	15250	(@pxref{Pointer Validation}).
	15251
	15252	Furthermore, you need not run @code{texindex} each time after you run
	15253	@code{tex}. The @code{tex} formatting command simply uses whatever
	15254	sorted index files happen to exist from a previous use of
	15255	@code{texindex}. If those are out of date, that is usually ok while
	15256	you are creating or debugging a document.
	15257
	15258
	15259	@node Details of @command{texindex}
	15260	@subsection Details of @command{texindex}
	15261
	15262	@cindex Braces, in index entries
	15263	In Texinfo version 6, released in 2015, the @command{texindex} program
	15264	was completely reimplemented. The principal functional difference is
	15265	that index entries beginning with a left brace or right brace
	15266	(@samp{@{} resp.@: @samp{@}}) can work properly. For example, these
	15267	simple index entries are processed correctly, including the ``index
	15268	initial'' shown in the index:
	15269
	15270	@example
	15271	@@cindex @@@{
	15272	@@cindex @@@}
	15273	...
	15274	@@printindex cp
	15275	@end example
	15276
	15277
	15278	@cindex Literate programming, with Texinfo and @code{awk}
	15279	@cindex Texinfo, and literate programming
	15280	@cindex Robbins, Arnold
	15281	@pindex texiwebjr
	15282	@pindex ti.twjr
	15283	Although not a matter of functionality, readers may be interested to
	15284	know that the new @command{texindex} is a literate program
	15285	(@url{http://en.wikipedia.org/wiki/Literate_programming}) using
	15286	Texinfo for documentation and (portable) @code{awk} for code. A
	15287	single source file, @file{texindex/ti.twjr} in this case, produces the
	15288	runnable program, a printable document, and an online document.
	15289
	15290	The system is called TexiWeb Jr.@: and was created by Arnold
	15291	Robbins, who also wrote the new @command{texindex}. Not
	15292	coincidentally, he is also the long-time maintainer of @command{gawk}
	15293	(GNU Awk, @pxref{Top,,, gawk, The GNU Awk User's Guide}). The file
	15294	@file{texindex/Makefile.am} shows example usage of the system.
	15295
	15296
	15297	@node Print with @command{lpr}
	15298	@section Print with @command{lpr} from Shell
	15299
	15300	@pindex lpr @r{(DVI print command)}
	15301
	15302	The way to print a DVI file depends on your system installation. Two
	15303	common ones are @samp{dvips foo.dvi -o} to make a PostScript file
	15304	first and then print that, and @samp{lpr -d foo.dvi} to print a DVI
	15305	file directly.
	15306
	15307	For example, the following commands will (probably) suffice to sort
	15308	the indices, format, and print this manual using the @code{texi2dvi}
	15309	shell script (@pxref{Format with @command{texi2dvi}}).
	15310
	15311	@example
	15312	@group
	15313	texi2dvi texinfo.texi
	15314	dvips texinfo.dvi -o
	15315	lpr texinfo.ps
	15316	@end group
	15317	@end example
	15318
	15319	Depending on the @code{lpr} setup on your machine, you might able to
	15320	combine the last two steps into @code{lpr -d texinfo.dvi}.
	15321
	15322	@cindex PCL file, for printing
	15323	You can also generate a PDF file by running @code{texi2pdf} instead of
	15324	@code{texi2dvi}; a PDF is often directly printable. Or you can
	15325	generate a PCL file by using @code{dvilj} instead of @code{dvips}, if
	15326	you have a printer that prefers that format.
	15327
	15328	@cindex Shell printing, on MS-DOS/MS-Windows
	15329	@cindex Printing DVI files, on MS-DOS/MS-Windows
	15330	@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
	15331	@code{lpr} is a standard program on Unix systems, but it is usually
	15332	absent on MS-DOS/MS-Windows. If so, just create a PostScript or PDF
	15333	or PCL file, whatever is most convenient, and print that in the usual
	15334	way for your machine (e.g., by sending to the appropriate port,
	15335	usually @samp{PRN}).
	15336
	15337
	15338	@node Within Emacs
	15339	@section Printing From an Emacs Shell
	15340	@cindex Print, format from Emacs shell
	15341	@cindex Format, print from Emacs shell
	15342	@cindex Shell, format, print from
	15343	@cindex Emacs shell, format, print from
	15344	@cindex GNU Emacs shell, format, print from
	15345
	15346	You can give formatting and printing commands from a shell within GNU
	15347	Emacs, just like any other shell command. To create a shell within
	15348	Emacs, type @kbd{M-x shell} (@pxref{Shell,,, emacs, The GNU Emacs
	15349	Manual}). In this shell, you can format and print the document.
	15350	@xref{Hardcopy, , Format and Print Hardcopy}, for details.
	15351
	15352	You can switch to and from the shell buffer while @code{tex} is
	15353	running and do other editing. If you are formatting a long document
	15354	on a slow machine, this can be very convenient.
	15355
	15356	For example, you can use @code{texi2dvi} from an Emacs shell. Here is
	15357	one way to use @code{texi2pdf} to format and print @cite{Using and
	15358	Porting GNU CC} from a shell within Emacs:
	15359
	15360	@example
	15361	@group
	15362	texi2pdf gcc.texi
	15363	lpr gcc.pdf
	15364	@end group
	15365	@end example
	15366
	15367	See the next section for more information about formatting
	15368	and printing in Texinfo mode.
	15369
	15370
	15371	@node Texinfo Mode Printing
	15372	@section Formatting and Printing in Texinfo Mode
	15373	@cindex Region printing in Texinfo mode
	15374	@cindex Format and print in Texinfo mode
	15375	@cindex Print and format in Texinfo mode
	15376
	15377	Texinfo mode provides several predefined key commands for @TeX{}
	15378	formatting and printing. These include commands for sorting indices,
	15379	looking at the printer queue, killing the formatting job, and
	15380	recentering the display of the buffer in which the operations
	15381	occur.
	15382
	15383	@table @kbd
	15384	@item C-c C-t C-b
	15385	@itemx M-x texinfo-tex-buffer
	15386	Run @code{texi2dvi} on the current buffer.
	15387
	15388	@item C-c C-t C-r
	15389	@itemx M-x texinfo-tex-region
	15390	Run @TeX{} on the current region.
	15391
	15392	@item C-c C-t C-i
	15393	@itemx M-x texinfo-texindex
	15394	Sort the indices of a Texinfo file formatted with
	15395	@code{texinfo-tex-region}.
	15396
	15397	@item C-c C-t C-p
	15398	@itemx M-x texinfo-tex-print
	15399	Print a DVI file that was made with @code{texinfo-tex-region} or
	15400	@code{texinfo-tex-buffer}.
	15401
	15402	@item C-c C-t C-q
	15403	@itemx M-x tex-show-print-queue
	15404	Show the print queue.
	15405
	15406	@item C-c C-t C-d
	15407	@itemx M-x texinfo-delete-from-print-queue
	15408	Delete a job from the print queue; you will be prompted for the job
	15409	number shown by a preceding @kbd{C-c C-t C-q} command
	15410	(@code{texinfo-show-tex-print-queue}).
	15411
	15412	@item C-c C-t C-k
	15413	@itemx M-x tex-kill-job
	15414	Kill the currently running @TeX{} job started by either
	15415	@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
	15416	process running in the Texinfo shell buffer.
	15417
	15418	@item C-c C-t C-x
	15419	@itemx M-x texinfo-quit-job
	15420	Quit a @TeX{} formatting job that has stopped because of an error by
	15421	sending an @key{x} to it. When you do this, @TeX{} preserves a record
	15422	of what it did in a @file{.log} file.
	15423
	15424	@item C-c C-t C-l
	15425	@itemx M-x tex-recenter-output-buffer
	15426	Redisplay the shell buffer in which the @TeX{} printing and formatting
	15427	commands are run to show its most recent output.
	15428	@end table
	15429
	15430	@need 1000
	15431	Thus, the usual sequence of commands for formatting a buffer is as
	15432	follows (with comments to the right):
	15433
	15434	@example
	15435	@group
	15436	C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
	15437	C-c C-t C-p @r{Print the DVI file.}
	15438	C-c C-t C-q @r{Display the printer queue.}
	15439	@end group
	15440	@end example
	15441
	15442	The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
	15443	called the @file{tex-shell}. The @code{texinfo-tex-command},
	15444	@code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
	15445	commands are all run in this shell.
	15446
	15447	You can watch the commands operate in the @samp{tex-shell} buffer,
	15448	and you can switch to and from and use the @samp{tex-shell} buffer
	15449	as you would any other shell buffer.
	15450
	15451	@need 1500
	15452	The formatting and print commands depend on the values of several variables.
	15453	The default values are:
	15454
	15455	@example
	15456	@group
	15457	@r{Variable} @r{Default value}
	15458
	15459	texinfo-texi2dvi-command "texi2dvi"
	15460	texinfo-tex-command "tex"
	15461	texinfo-texindex-command "texindex"
	15462	texinfo-delete-from-print-queue-command "lprm"
	15463	texinfo-tex-trailer "@@bye"
	15464	tex-start-of-header "%**start"
	15465	tex-end-of-header "%**end"
	15466	tex-dvi-print-command "lpr -d"
	15467	tex-show-queue-command "lpq"
	15468	@end group
	15469	@end example
	15470
	15471	You can change the values of these variables with the @kbd{M-x
	15472	set-variable} command (@pxref{Examining, , Examining and Setting
	15473	Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs}
	15474	initialization file (@pxref{Init File, , , emacs, The GNU Emacs
	15475	Manual}).
	15476
	15477	@cindex Customize Emacs package (@t{Development/Docs/Texinfo})
	15478	Beginning with version 20, GNU Emacs offers a user-friendly interface,
	15479	called @dfn{Customize}, for changing values of user-definable variables.
	15480	@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
	15481	Emacs Manual}, for more details about this. The Texinfo variables can
	15482	be found in the @samp{Development/Docs/Texinfo} group, once you invoke
	15483	the @kbd{M-x customize} command.
	15484
	15485
	15486	@node Compile-Command
	15487	@section Using the Local Variables List
	15488	@cindex Local variables
	15489	@cindex Compile command for formatting
	15490	@cindex Format with the compile command
	15491
	15492	Yet another way to apply the @TeX{} formatting command to a Texinfo file
	15493	is to put that command in a @dfn{local variables list} at the end of the
	15494	Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
	15495	commands as a @code{compile-command} and have Emacs run it by typing
	15496	@kbd{M-x compile}. This creates a special shell called the
	15497	@file{compilation} buffer in which Emacs runs the compile command.
	15498	For example, at the end of the @file{gdb.texi} file, after the
	15499	@code{@@bye}, you could put the following:
	15500
	15501	@example
	15502	@group
	15503	Local Variables:
	15504	compile-command: "texi2dvi gdb.texi"
	15505	End:
	15506	@end group
	15507	@end example
	15508
	15509	@noindent
	15510	This technique is most often used by programmers who also compile programs
	15511	this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.
	15512
	15513
	15514	@node Requirements Summary
	15515	@section @TeX{} Formatting Requirements Summary
	15516	@cindex Requirements for formatting
	15517	@cindex Minimal requirements for formatting
	15518	@cindex Formatting requirements
	15519
	15520	Every Texinfo file that is to be input to @TeX{} must begin with a
	15521	@code{\input} command:
	15522
	15523	@example
	15524	\input texinfo
	15525	@end example
	15526
	15527	@noindent
	15528	This instructs @TeX{} to load the macros it needs to process a Texinfo
	15529	file.
	15530
	15531	Every Texinfo file must end with a line that terminates @TeX{}'s
	15532	processing and forces out unfinished pages:
	15533
	15534	@example
	15535	@@bye
	15536	@end example
	15537
	15538	Strictly speaking, these two lines are all a Texinfo file needs to be
	15539	processed successfully by @TeX{}.
	15540
	15541	Usually, however, the beginning includes a @code{@@settitle} command
	15542	to define the title of the printed manual, a title page, a copyright
	15543	page, permissions, and a table of contents. Besides @code{@@bye}, the
	15544	end of a file usually includes indices. (Not to mention that most
	15545	manuals contain a body of text as well.)
	15546
	15547	For more information, see:
	15548
	15549	@itemize @bullet
	15550	@item @ref{@code{@@settitle}}.
	15551	@item @ref{@code{@@setchapternewpage}}.
	15552	@item @ref{Headings}.
	15553	@item @ref{Titlepage & Copyright Page}.
	15554	@item @ref{Printing Indices & Menus}.
	15555	@item @ref{Contents}.
	15556	@end itemize
	15557
	15558
	15559	@node Preparing for @TeX{}
	15560	@section Preparing for @TeX{}
	15561	@cindex Preparing for @TeX{}
	15562	@cindex @TeX{} input initialization
	15563	@cindex @sortas{profile init} @file{.profile} initialization file
	15564	@cindex @sortas{cshrc init} @file{.cshrc} initialization file
	15565	@cindex Initialization file for @TeX{} input
	15566
	15567	@TeX{} needs to find the @file{texinfo.tex} file that the
	15568	@samp{\input texinfo} command on the first line reads. The
	15569	@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
	15570	included in all standard GNU distributions. The latest version
	15571	released for general use is available
	15572	from the usual GNU servers and mirrors:
	15573
	15574	@display
	15575	@uref{http://ftp.gnu.org/gnu/texinfo/texinfo.tex}
	15576	@uref{http://ftpmirror.gnu.org/texinfo/texinfo.tex}
	15577	@end display
	15578
	15579	The latest development version is available from the Texinfo source
	15580	repository:
	15581
	15582	@display
	15583	@uref{http://git.savannah.gnu.org/cgit/texinfo.git/plain/doc/texinfo.tex}
	15584	@end display
	15585
	15586	@pindex texinfo.tex@r{, installing}
	15587	@file{texinfo.tex} is essentially a standalone file,
	15588	so, if you need or want to try a newer version
	15589	than came with your system, it nearly always suffices to download it
	15590	and put it anywhere that @TeX{} will find it. You can replace
	15591	any existing @file{texinfo.tex} with a newer version (of course saving
	15592	the original in case of disaster).
	15593
	15594	@pindex epsf.tex@r{, installing}
	15595	Also, you should install @file{epsf.tex}, if it is not already installed
	15596	from another distribution. More details are at the end of the description
	15597	of the @code{@@image} command (@pxref{Images}).
	15598
	15599	@cindex European Computer Modern fonts, installing
	15600	@cindex EC fonts, installing
	15601	@cindex CM-Super fonts, installing
	15602	To use quotation marks other than those used in English, you'll need
	15603	to have the European Computer Modern fonts (e.g., @file{ecrm1000}) and
	15604	(for PDF output) CM-Super fonts (@pxref{Inserting Quotation Marks}).
	15605
	15606	@pindex feymr10@r{, installing}
	15607	@cindex Euro font, installing
	15608	To use the @code{@@euro} command, you'll need the @samp{feym*} fonts
	15609	(e.g., @file{feymr10}). @xref{@code{@@euro}}.
	15610
	15611	All of the above files should be installed by default in a reasonable
	15612	@TeX{} installation.
	15613
	15614	@pindex texinfo.cnf @r{installation}
	15615	@cindex Customizing of @TeX{} for Texinfo
	15616	@cindex Site-wide Texinfo configuration file
	15617	Optionally, you may create a file @file{texinfo.cnf} for site configuration.
	15618	When processing a Texinfo file, @TeX{} looks for this file
	15619	in its search path, which includes the current directory and standard
	15620	installation directories.
	15621	You can use this file for local conventions. For example, if
	15622	@file{texinfo.cnf} contains the line
	15623	@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents
	15624	will be processed with that page size in effect. If you have nothing
	15625	to put in @file{texinfo.cnf}, you do not need to create it.
	15626
	15627	@cindex Environment variable @code{TEXINPUTS}
	15628	@vindex TEXINPUTS
	15629	You can set the @code{TEXINPUTS} environment variable
	15630	to allow @TeX{} to find @file{texinfo.cnf}.
	15631	(This also works for @file{texinfo.tex} and any other file @TeX{}
	15632	might read). For example, if you are using a Bourne shell-compatible shell
	15633	(@code{sh}, @code{bash}, @code{ksh}, @dots{}), your @file{.profile} file
	15634	could contain the lines:
	15635
	15636	@example
	15637	TEXINPUTS=.:/home/me/mylib:
	15638	export TEXINPUTS
	15639	@end example
	15640
	15641	@noindent
	15642	These settings would cause @TeX{} first to look for an @file{\input} file
	15643	in the current directory, indicated by the @samp{.}, then in a
	15644	hypothetical user @samp{me}'s @file{mylib} directory, and finally in
	15645	the system directories. (A leading, trailing, or doubled @samp{:}
	15646	indicates searching the system directories at that point.)
	15647
	15648	On MS-DOS/MS-Windows, you'd do this like this (note the use of the @samp{;}
	15649	character as directory separator, instead of @samp{:}):
	15650
	15651	@example
	15652	set TEXINPUTS=.;d:/home/me/mylib;c:
	15653	@end example
	15654
	15655	@noindent
	15656	It is customary for DOS/Windows users to put such commands in the
	15657	@file{autoexec.bat} file, or in the Windows registry.
	15658
	15659
	15660	@node Overfull hboxes
	15661	@section Overfull ``hboxes''
	15662	@cindex Overfull @samp{hboxes}
	15663	@cindex @samp{hbox}, overfull
	15664	@cindex Final output
	15665
	15666	@TeX{} is sometimes unable to typeset a line within the normal
	15667	margins. This most often occurs when @TeX{} comes upon what it
	15668	interprets as a long word that it cannot hyphenate, such as an
	15669	electronic mail network address or a very long identifier. When this
	15670	happens, @TeX{} prints an error message like this:
	15671
	15672	@example
	15673	Overfull @@hbox (20.76302pt too wide)
	15674	@end example
	15675
	15676	@findex hbox
	15677	@noindent
	15678	(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
	15679	@samp{@@hbox} is a @TeX{} primitive not used in the Texinfo language.)
	15680
	15681	@TeX{} also provides the line number in the Texinfo source file and
	15682	the text of the offending line, which is marked at all the places that
	15683	@TeX{} considered hyphenation. @xref{Debugging with @TeX{}}, for more
	15684	information about typesetting errors.
	15685
	15686	If the Texinfo file has an overfull hbox, you can rewrite the sentence
	15687	so the overfull hbox does not occur, or you can decide to leave it. A
	15688	small excursion into the right margin often does not matter and may not
	15689	even be noticeable.
	15690
	15691	If you have many overfull boxes and/or an antipathy to rewriting, you
	15692	can coerce @TeX{} into greatly increasing the allowable interword
	15693	spacing, thus (if you're lucky) avoiding many of the bad line breaks,
	15694	like this:
	15695
	15696	@findex \emergencystretch
	15697	@example
	15698	@@tex
	15699	\global\emergencystretch = .9\hsize
	15700	@@end tex
	15701	@end example
	15702
	15703	@noindent
	15704	(You should adjust the fraction as needed.) This huge value for
	15705	@code{\emergencystretch} cannot be the default, since then the typeset
	15706	output would generally be of noticeably lower quality; its default
	15707	value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
	15708	containing the current line width.
	15709
	15710	@cindex Black rectangle in hardcopy
	15711	@cindex Rectangle, black in hardcopy
	15712	@cindex Box, ugly black in hardcopy
	15713	@cindex Ugly black rectangles in hardcopy
	15714	For any overfull boxes you do have, @TeX{} will print a large, ugly,
	15715	black rectangle beside the line that contains the overfull hbox unless
	15716	told otherwise. This is so you will notice the location of the
	15717	problem if you are correcting a draft.
	15718
	15719	@findex finalout
	15720	To prevent such a monstrosity from marring your final printout, write
	15721	the following in the beginning of the Texinfo file on a line of its own,
	15722	before the @code{@@titlepage} command:
	15723
	15724	@example
	15725	@@finalout
	15726	@end example
	15727
	15728
	15729	@node @code{@@smallbook}
	15730	@section @code{@@smallbook}: Printing ``Small'' Books
	15731
	15732	@anchor{smallbook}@c old name
	15733	@findex smallbook
	15734	@cindex Small book size
	15735	@cindex Book, printing small
	15736	@cindex Page sizes for books
	15737	@cindex Size of printed book
	15738
	15739	By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
	15740	format. However, you can direct @TeX{} to typeset a document in a 7 by
	15741	9.25 inch format that is suitable for bound books by inserting the
	15742	following command on a line by itself at the beginning of the Texinfo
	15743	file, before the title page:
	15744
	15745	@example
	15746	@@smallbook
	15747	@end example
	15748
	15749	@noindent
	15750	(Since many books are about 7 by 9.25 inches, this command might better
	15751	have been called the @code{@@regularbooksize} command, but it came to be
	15752	called the @code{@@smallbook} command by comparison to the 8.5 by 11
	15753	inch format.)
	15754
	15755	If you write the @code{@@smallbook} command between the
	15756	start-of-header and end-of-header lines, the Texinfo mode @TeX{}
	15757	region formatting command, @code{texinfo-tex-region}, will format the
	15758	region in ``small'' book size (@pxref{Start of Header}).
	15759
	15760	@xref{@code{@@small@dots{}}}, for information about commands that make
	15761	it easier to produce examples for a smaller manual.
	15762
	15763	@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
	15764	for other ways to format with @code{@@smallbook} that do not require
	15765	changing the source file.
	15766
	15767
	15768	@node A4 Paper
	15769	@section Printing on A4 Paper
	15770	@cindex A4 paper, printing on
	15771	@cindex A5 paper, printing on
	15772	@cindex Paper size, A4
	15773	@cindex European A4 paper
	15774	@findex afourpaper
	15775	@findex afivepaper
	15776
	15777	You can tell @TeX{} to format a document for printing on European size
	15778	A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
	15779	command. Write the command on a line by itself near the beginning of
	15780	the Texinfo file, before the title page. For example, this is how you
	15781	would write the header for this manual:
	15782
	15783	@example
	15784	@group
	15785	\input texinfo @@c --texinfo--
	15786	@@c %**start of header
	15787	@@settitle Texinfo
	15788	@@afourpaper
	15789	@@c %**end of header
	15790	@end group
	15791	@end example
	15792
	15793	@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
	15794	for other ways to format for different paper sizes that do not require
	15795	changing the source file.
	15796
	15797	@findex afourlatex
	15798	@findex afourwide
	15799	You may or may not prefer the formatting that results from the command
	15800	@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
	15801	wide format.
	15802
	15803
	15804	@node @code{@@pagesizes}
	15805	@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
	15806	@anchor{pagesizes}@c old node name
	15807
	15808	@findex pagesizes
	15809	@cindex Custom page sizes
	15810	@cindex Page sizes, customized
	15811	@cindex Text width and height
	15812	@cindex Width of text area
	15813	@cindex Height of text area
	15814	@cindex Depth of text area
	15815
	15816	You can explicitly specify the height and (optionally) width of the main
	15817	text area on the page with the @code{@@pagesizes} command. Write this
	15818	on a line by itself near the beginning of the Texinfo file, before the
	15819	title page. The height comes first, then the width if desired,
	15820	separated by a comma. Examples:
	15821
	15822	@example
	15823	@@pagesizes 200mm,150mm @c for b5 paper
	15824	@end example
	15825	@noindent and
	15826	@example
	15827	@@pagesizes 11.5in @c for legal paper
	15828	@end example
	15829
	15830	@cindex B5 paper, printing on
	15831	@cindex Legal paper, printing on
	15832	This would be reasonable for printing on B5-size paper. To emphasize,
	15833	this command specifies the size of the @emph{text area}, not the size of
	15834	the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
	15835	8.5@dmn{in} for legal).
	15836
	15837	@cindex Margins on page, not controllable
	15838	To make more elaborate changes, such as changing any of the page
	15839	margins, you must define a new command in @file{texinfo.tex} or
	15840	@file{texinfo.cnf}.
	15841
	15842	@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
	15843	for other ways to specify @code{@@pagesizes} that do not require
	15844	changing the source file.
	15845
	15846
	15847	@node Magnification
	15848	@section Magnification
	15849	@anchor{Cropmarks and Magnification} @c old name
	15850
	15851	@findex \mag @r{(raw @TeX{} magnification)}
	15852	@cindex Magnified printing
	15853	@cindex Larger or smaller pages
	15854	You can attempt to direct @TeX{} to typeset pages larger or smaller
	15855	than usual with the @code{\mag} @TeX{} command. Everything that is
	15856	typeset is scaled proportionally larger or smaller. (@code{\mag}
	15857	stands for ``magnification''.) This is @emph{not} a Texinfo
	15858	@@-command, but is a raw @TeX{} command that is prefixed with a
	15859	backslash. You have to write this command between @code{@@tex} and
	15860	@code{@@end tex} (@pxref{Raw Formatter Commands}).
	15861
	15862	Follow the @code{\mag} command with an @samp{=} and then a number that
	15863	is 1000 times the magnification you desire. For example, to print pages
	15864	at 1.2 normal size, write the following near the beginning of the
	15865	Texinfo file, before the title page:
	15866
	15867	@example
	15868	@group
	15869	@@tex
	15870	\global\mag=1200
	15871	@@end tex
	15872	@end group
	15873	@end example
	15874
	15875	With some printing technologies, you can print normal-sized copies that
	15876	look better than usual by giving a larger-than-normal master to your
	15877	print shop. They do the reduction, thus effectively increasing the
	15878	resolution.
	15879
	15880	Depending on your system, DVI files prepared with a
	15881	nonstandard-@code{\mag} may not print or may print only with certain
	15882	magnifications. Be prepared to experiment.
	15883
	15884
	15885	@node PDF Output
	15886	@section PDF Output
	15887	@cindex PDF output
	15888	@cindex Output, in PDF
	15889
	15890	@pindex pdftex
	15891	The simplest way to generate PDF output from Texinfo source is to run
	15892	the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
	15893	this executes the @command{texi2dvi} script with the @option{--pdf}
	15894	option (@pxref{Format with @command{texi2dvi}}). If for some reason you
	15895	want to process the document by hand, you can run the @command{pdftex}
	15896	program instead of plain @command{tex}. That is, run @samp{pdftex
	15897	foo.texi} instead of @samp{tex foo.texi}.
	15898
	15899	@dfn{PDF} stands for `Portable Document Format'. It was invented by
	15900	Adobe Systems some years ago for document interchange, based on their
	15901	PostScript language. Related links:
	15902
	15903	@itemize
	15904	@item
	15905	GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF
	15906	reader}. (It can also preview PostScript documents.)
	15907
	15908	@item
	15909	@code{xpdf}, a freely available standalone
	15910	@uref{http://www.foolabs.com/xpdf/, PDF reader} for the X window
	15911	system.
	15912
	15913	@item
	15914	@uref{https://en.wikipedia.org/wiki/Portable_Document_Format, PDF at
	15915	Wikipedia}.
	15916
	15917	@end itemize
	15918
	15919	At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf}
	15920	commands as for the other output formats, since PDF documents contain
	15921	many internal low-level offsets and cross-references that would be
	15922	hard or impossible to specify at the Texinfo source level.
	15923
	15924	PDF files require dedicated software to be displayed, unlike the plain
	15925	ASCII formats (Info, HTML) that Texinfo supports. They also tend to
	15926	be much larger than the DVI files output by @TeX{} by default.
	15927	Nevertheless, a PDF file does define an actual typeset document in a
	15928	self-contained file, notably including all the fonts that are used, so
	15929	it has its place.
	15930
	15931
	15932	@node Obtaining @TeX{}
	15933	@section Obtaining @TeX{}
	15934	@cindex Obtaining @TeX{}
	15935	@cindex @TeX{}, how to obtain
	15936
	15937	@TeX{} is a document formatter that is used by the FSF for its
	15938	documentation. It is the easiest way to get printed output (e.g., PDF
	15939	and PostScript) for Texinfo manuals. TeX is freely redistributable,
	15940	and you can get it over the Internet or on physical media. See
	15941	@url{http://tug.org/texlive}.
	15942
	15943	@c please keep that text in sync with www.gnu.org/prep/FTP
	15944
	15945
	15946	@node Generic Translator @command{texi2any}
	15947	@chapter @command{texi2any}: The Generic Translator for Texinfo
	15948
	15949	@command{texi2any} is the generic translator for Texinfo that can
	15950	produce different output formats and is highly customizable. It
	15951	supports these formats:
	15952
	15953	@table @asis
	15954	@item Info (by default, or with @option{--info}),
	15955
	15956	@item HTML (with @option{--html}),
	15957
	15958	@item plain text (with @option{--plaintext}),
	15959
	15960	@item Docbook (with @option{--docbook}),
	15961
	15962	@item Texinfo XML (with @option{--xml}).
	15963	@end table
	15964
	15965	@command{makeinfo} is an alias for @command{texi2any}. By default,
	15966	both @command{texi2any} and @command{makeinfo} generate Info output;
	15967	indeed, there are no differences in behavior based on the name.
	15968
	15969	Beside these default formats, command line options to
	15970	@command{texi2any} can change many aspects of the output. Beyond
	15971	that, initialization files provide even more control over the final
	15972	output---nearly anything not specified in the Texinfo input file.
	15973	Initialization files are written in Perl, like the main program, and
	15974	anything which can be specified on the command line can also be
	15975	specified within a initialization file.
	15976
	15977	The rest of this chapter goes into the details.
	15978
	15979	@menu
	15980	* Reference Implementation:: @command{texi2any}: the reference implementation.
	15981	* Invoking @command{texi2any}:: Running the translator from a shell.
	15982	* @command{texi2any} Environment Variables::
	15983	* @command{texi2any} Printed Output:: Calling @command{texi2dvi}.
	15984	* Pointer Validation:: How to check that pointers point somewhere.
	15985	* Customization Variables:: Configuring @command{texi2any}.
	15986	* Internationalization of Document Strings:: Translating program-inserted text.
	15987	* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo.
	15988	* @command{texi2html}:: An ancestor of @command{texi2any}.
	15989	@end menu
	15990
	15991
	15992	@node Reference Implementation
	15993	@section @command{texi2any}: A Texinfo Reference Implementation
	15994
	15995	@cindex @command{texi2any}, as reference implementation
	15996	@cindex Reference implementation
	15997	@cindex Implementation, @command{texi2any} as reference
	15998
	15999	Above, we called @command{texi2any} ``the'' translator for Texinfo
	16000	instead of just ``a'' translator, even though (of course) it's
	16001	technically and legally possible for other implementations to be
	16002	written. The reason is that alternative implementations are very
	16003	likely to have subtle, or not-so-subtle, differences in behavior, and
	16004	thus Texinfo documents would become dependent on the processor.
	16005	Therefore, it is important to have a reference implementation that
	16006	defines parts of the language not fully specified by the manual (often
	16007	intentionally so). It is equally important to have consistent
	16008	command-line options and other behavior for all processors.
	16009
	16010	@cindex Tree representation of documents
	16011	@cindex Syntax tree representation of documents
	16012	@cindex Abstract syntax tree representation of documents
	16013	For this reason, the once-independent @command{texi2html} Perl Texinfo
	16014	processor was made compatible with the C implementation of
	16015	@command{makeinfo}, to avoid continuing with two different
	16016	implementations (@pxref{History}). The current implementation,
	16017	@command{texi2any}, serves as the reference implementation. It
	16018	inherited the design of customization and other features from
	16019	@command{texi2html} (for more on @command{texi2html} compatibility,
	16020	@pxref{@command{texi2html}}). However, @code{texi2any} is a full
	16021	reimplementation: it constructs a tree-based representation of the
	16022	input document for all back-ends to work from.
	16023
	16024	@cindex Texinfo language tests
	16025	@cindex Tests, of Texinfo language
	16026	Extensive tests of the language were developed at the same time as
	16027	@command{texi2any}; we plead with anyone thinking of writing a program
	16028	to parse Texinfo input to at least make use of these tests.
	16029
	16030	@cindex Examples of using @command{texi2any}
	16031	@findex Texinfo::Parser module
	16032	The @command{texi2html} wrapper script (@pxref{@command{texi2html}})
	16033	provides a very simple example of calling @command{texi2any} from a
	16034	shell script; it's in @file{util/texi2html} in the Texinfo sources.
	16035	More consequentially, @command{texi-elements-by-size} is an example
	16036	Perl script using the @code{Texinfo::Parser} module interface; it's
	16037	also in the @file{util} source directory. (Its functionality may also
	16038	be useful to authors; @pxref{texi-elements-by-size}.)
	16039
	16040	@cindex Future of Texinfo implementations
	16041	With the release of @command{texi2any} as the reference
	16042	implementation, development of both the C implementation of
	16043	@command{makeinfo} and @command{texi2html} has been halted. Going
	16044	forward, we ask authors of Texinfo documents to use only
	16045	@command{texi2any}.
	16046
	16047
	16048	@node Invoking @command{texi2any}
	16049	@section Invoking @command{texi2any}/@command{makeinfo} from a Shell
	16050
	16051	@anchor{Invoking makeinfo}
	16052	@pindex makeinfo
	16053	@pindex texi2any
	16054
	16055	To process a Texinfo file, invoke @command{texi2any} or
	16056	@command{makeinfo} (the two names are synonyms for the same program;
	16057	we'll use the names interchangeably) followed by the name of the
	16058	Texinfo file. Also select the format you want to output with the
	16059	appropriate command line option (default is Info). Thus, to create
	16060	the Info file for Bison, type the following to the shell:
	16061
	16062	@example
	16063	texi2any --info bison.texinfo
	16064	@end example
	16065
	16066	You can specify more than one input file name; each is processed in
	16067	turn. If an input file name is @samp{-}, standard input is read.
	16068
	16069	@anchor{@command{makeinfo} Options}
	16070	@c anchor{makeinfo options}@c prev name, but case-insensitive clash
	16071	@cindex @code{makeinfo} options
	16072	@cindex Options for @code{makeinfo}
	16073	@anchor{texi2any Options}
	16074	@cindex @code{texi2any} options
	16075	@cindex Options for @code{texi2any}
	16076
	16077	The @command{texi2any} program accepts many options. Perhaps the
	16078	most basic are those that change the output format. By default,
	16079	@command{texi2any} outputs Info.
	16080
	16081	Each command line option is either a long name preceded by @samp{--}
	16082	or a single letter preceded by @samp{-}. You can use abbreviations
	16083	for the long option names as long as they are unique.
	16084
	16085	For example, you could use the following shell command to create an
	16086	Info file for @file{bison.texinfo} in which lines are filled to only
	16087	68 columns:
	16088
	16089	@example
	16090	texi2any --fill-column=68 bison.texinfo
	16091	@end example
	16092
	16093	You can write two or more options in sequence, like this:
	16094
	16095	@example
	16096	texi2any --no-split --fill-column=70 @dots{}
	16097	@end example
	16098
	16099	@noindent
	16100	(This would keep the Info file together as one possibly very long
	16101	file and would also set the fill column to 70.)
	16102
	16103	The options are (approximately in alphabetical order):
	16104
	16105	@table @code
	16106	@item --commands-in-node-names
	16107	@opindex --commands-in-node-names
	16108	This option now does nothing, but remains for compatibility. (It used
	16109	to ensure that @@-commands in node names were expanded throughout the
	16110	document, especially @code{@@value}. This is now done by default.)
	16111
	16112	@item --conf-dir=@var{path}
	16113	@opindex --conf-dir=@var{path}
	16114	Prepend @var{path} to the directory search list for finding
	16115	customization files that may be loaded with @option{--init-file} (see
	16116	below). The @var{path} value can be a single directory, or a list of
	16117	several directories separated by the usual path separator character
	16118	(@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading
	16119	@c Init Files}.
	16120
	16121	@item --css-include=@var{file}
	16122	@opindex --css-include
	16123	When producing HTML, literally include the contents of @var{file},
	16124	which should contain W3C cascading style sheets specifications, in the
	16125	@samp{<style>} block of the HTML output. If @var{file} is @samp{-},
	16126	read standard input. @xref{HTML CSS}.
	16127
	16128	@item --css-ref=@var{url}
	16129	@opindex --css-ref
	16130	When producing HTML, add a @samp{<link>} tag to the output which
	16131	references a cascading style sheet at @var{url}. This allows using
	16132	standalone style sheets.
	16133
	16134	@item -D @var{var}
	16135	@itemx -D '@var{var} @var{value}'
	16136	@opindex -D @var{var}
	16137	Cause the Texinfo variable @var{var} to be defined. This is
	16138	equivalent to @code{@@set @var{var}} in the Texinfo file
	16139	(@pxref{@code{@@set @@clear @@value}}).
	16140
	16141	The argument to the option is always one word to the shell; if it
	16142	contains internal whitespace, the first word is taken as the variable
	16143	name and the remainder as the value. For example, @code{-D 'myvar
	16144	someval'} is equivalent to @code{@@set myvar someval}.
	16145
	16146	@item --disable-encoding
	16147	@itemx --enable-encoding
	16148	@opindex --disable-encoding
	16149	@opindex --enable-encoding
	16150	By default, or with @option{--enable-encoding}, output accented and
	16151	special characters in Info and plain text output based on
	16152	@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit
	16153	ASCII transliterations are output. @xref{@code{@@documentencoding}},
	16154	and @ref{Inserting Accents}.
	16155
	16156	@item --docbook
	16157	@opindex --docbook
	16158	Generate Docbook output (rather than Info).
	16159
	16160	@item --document-language=@var{lang}
	16161	@opindex --document-language
	16162	Use @var{lang} to translate Texinfo keywords which end up in the
	16163	output document. The default is the locale specified by the
	16164	@code{@@documentlanguage} command if there is one, otherwise English
	16165	(@pxref{@code{@@documentlanguage}}).
	16166
	16167	@item --dvi
	16168	@opindex --dvi
	16169	Generate a TeX DVI file using @command{texi2dvi}, rather than Info
	16170	(@pxref{@command{texi2any} Printed Output}).
	16171
	16172	@item --dvipdf
	16173	@opindex --dvipdf
	16174	Generate a PDF file using @command{texi2dvi --dvipdf}, rather than
	16175	Info (@pxref{@command{texi2any} Printed Output}).
	16176
	16177	@item --error-limit=@var{limit}
	16178	@itemx -e @var{limit}
	16179	@opindex --error-limit=@var{limit}
	16180	@opindex -e @var{limit}
	16181	Report @var{LIMIT} errors before aborting (on the assumption that
	16182	continuing would be useless); default 100.
	16183
	16184	@item --fill-column=@var{width}
	16185	@itemx -f @var{width}
	16186	@opindex --fill-column=@var{width}
	16187	@opindex -f @var{width}
	16188	Specify the maximum number of columns in a line; this is the
	16189	right-hand edge of a line. Paragraphs that are filled will be filled
	16190	to this width. (Filling is the process of breaking up and connecting
	16191	lines so that lines are the same length as or shorter than the number
	16192	specified as the fill column. Lines are broken between words.) The
	16193	default value is 72.
	16194
	16195	@item --footnote-style=@var{style}
	16196	@itemx -s @var{style}
	16197	@opindex --footnote-style=@var{style}
	16198	@opindex -s @var{style}
	16199	Set the footnote style to @var{style}: either @samp{end} for the end
	16200	node style (the default) or @samp{separate} for the separate node
	16201	style. The value set by this option overrides the value set in a
	16202	Texinfo file by a @code{@@footnotestyle} command (@pxref{Footnote
	16203	Styles}).
	16204
	16205	When the footnote style is @samp{separate}, @code{makeinfo} makes a
	16206	new node containing the footnotes found in the current node. When the
	16207	footnote style is @samp{end}, @code{makeinfo} places the footnote
	16208	references at the end of the current node.
	16209
	16210	In HTML, when the footnote style is @samp{end}, or if the output is
	16211	not split, footnotes are put at the end of the output. If set to
	16212	@samp{separate}, and the output is split, they are placed in a
	16213	separate file.
	16214
	16215	@item --force
	16216	@itemx -F
	16217	@opindex --force
	16218	@opindex -F
	16219	Ordinarily, if the input file has errors, the output files are not
	16220	created. With this option, they are preserved.
	16221
	16222	@item --help
	16223	@itemx -h
	16224	@opindex --help@r{, for @command{texi2any}}
	16225	@opindex -h
	16226	Print a message with available options and basic usage, then exit
	16227	successfully.
	16228
	16229	@item --html
	16230	@opindex --html
	16231	Generate HTML output (rather than Info). By default, the HTML output
	16232	is split into one output file per Texinfo source node, and the split
	16233	output is written into a subdirectory based on the name of the
	16234	top-level Info file. @xref{Generating HTML}.
	16235
	16236	@item -I @var{path}
	16237	@opindex -I @var{path}
	16238	Append @var{path} to the directory search list for finding files that
	16239	are included using the @code{@@include} command. By default,
	16240	@code{texi2any} searches only the current directory. If @var{path} is
	16241	not given, the current directory is appended. The @var{path} value
	16242	can be a single directory or a list of several directories separated
	16243	by the usual path separator character (@samp{:} on Unix-like systems,
	16244	@samp{;} on Windows).
	16245
	16246	@item --ifdocbook
	16247	@opindex --ifdocbook
	16248	@itemx --ifhtml
	16249	@opindex --ifhtml
	16250	@itemx --ifinfo
	16251	@opindex --ifinfo
	16252	@itemx --ifplaintext
	16253	@opindex --ifplaintext
	16254	@itemx --iftex
	16255	@opindex --iftex
	16256	@itemx --ifxml
	16257	@opindex --ifxml
	16258	For the given format, process @samp{@@if@var{format}} and
	16259	@samp{@@@var{format}} commands, and do not process
	16260	@samp{@@ifnot@var{format}}, regardless of the format being output.
	16261	For instance, if @option{--iftex} is given, then @samp{@@iftex} and
	16262	@samp{@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be
	16263	ignored.
	16264
	16265	@item --info
	16266	@opindex --info
	16267	Generate Info output. By default, if the output file contains more
	16268	than about 300,000 bytes, it is split into shorter subfiles of about
	16269	that size. The name of the output file and any subfiles is determined
	16270	by @code{@@setfilename} (@pxref{@code{@@setfilename}}). @xref{Tag and
	16271	Split Files}.
	16272
	16273	@item --init-file=@var{file}
	16274	@opindex --init-file=@var{file}
	16275	Load @var{file} as code to modify the behavior and output of the
	16276	generated manual. It is customary to use the @code{.pm} or the
	16277	@code{.init} extensions for these customization files, but that is not
	16278	enforced; the @var{file} name can be anything. The
	16279	@option{--conf-dir} option (see above) can be used to add to the list
	16280	of directories in which these customization files are searched for.
	16281	@c @xref{Loading Init Files}.
	16282
	16283	@item --internal-links=@var{file}
	16284	@opindex --internal-links=@var{file}
	16285	@cindex Internal links, of HTML
	16286	In HTML mode, output a tab-separated file containing three columns:
	16287	the internal link to an indexed item or item in the table of contents,
	16288	the name of the index (or table of contents) in which it occurs, and
	16289	the term which was indexed or entered. The items are in the natural
	16290	sorting order for the given element. This dump can be useful for
	16291	post-processors.
	16292
	16293	@item --macro-expand=@var{file}
	16294	@itemx -E @var{file}
	16295	@opindex --macro-expand=@var{file}
	16296	@opindex -E @var{file}
	16297	Output the Texinfo source, with all Texinfo macros expanded, to
	16298	@var{file}. Normally, the result of macro expansion is used
	16299	internally by @code{makeinfo} and then discarded.
	16300
	16301	@item --no-headers
	16302	@opindex --no-headers
	16303	@cindex Node separators, omitting with @option{--no-headers}
	16304	@cindex Generating plain text files with @option{--no-headers}
	16305	@cindex Menus, omitting with @option{--no-headers}
	16306	Do not include menus or node separator lines in the output.
	16307
	16308	When generating Info, this is the same as using @option{--plaintext},
	16309	resulting in a simple plain text file. Furthermore,
	16310	@code{@@setfilename} is ignored, and output is to standard output
	16311	unless overridden with @option{-o}. (This behavior is for backward
	16312	compatibility.)
	16313
	16314	@cindex Navigation links, omitting
	16315	When generating HTML, and output is split, also output navigation
	16316	links only at the beginning of each file. If output is not split, do
	16317	not include navigation links at the top of each node at all.
	16318	@xref{Generating HTML}.
	16319
	16320	@item --no-ifdocbook
	16321	@opindex --no-ifdocbook
	16322	@itemx --no-ifhtml
	16323	@opindex --no-ifhtml
	16324	@itemx --no-ifinfo
	16325	@opindex --no-ifinfo
	16326	@itemx --no-ifplaintext
	16327	@opindex --no-ifplaintext
	16328	@itemx --no-iftex
	16329	@opindex --no-iftex
	16330	@itemx --no-ifxml
	16331	@opindex --no-ifxml
	16332	For the given format, do not process @samp{@@if@var{format}} and
	16333	@samp{@@@var{format}} commands, and do process
	16334	@samp{@@ifnot@var{format}}, regardless of the format being output.
	16335	For instance, if @option{--no-ifhtml} is given, then @samp{@@ifhtml}
	16336	and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml}
	16337	blocks will be.
	16338
	16339	@item --no-node-files
	16340	@itemx --node-files
	16341	@opindex --no-node-files
	16342	@opindex --node-files
	16343	When generating HTML, create redirection files for anchors and any
	16344	nodes not already output with the file name corresponding to the node
	16345	name (@pxref{HTML Xref Node Name Expansion}). This makes it possible
	16346	for section- and chapter-level cross-manual references to succeed
	16347	(@pxref{HTML Xref Configuration}).
	16348
	16349	If the output is split, this is enabled by default. If the output is
	16350	not split, @option{--node-files} enables the creation of the
	16351	redirection files, in addition to the monolithic main output file.
	16352	@option{--no-node-files} suppresses the creation of redirection files
	16353	in any case. This option has no effect with any output format other
	16354	than HTML@. @xref{Generating HTML}.
	16355
	16356	@item --no-number-footnotes
	16357	@opindex --no-number-footnotes
	16358	Suppress automatic footnote numbering. By default, footnotes are
	16359	numbered sequentially within a node, i.e., the current footnote number
	16360	is reset to 1 at the start of each node.
	16361
	16362	@item --no-number-sections
	16363	@itemx --number-sections
	16364	@opindex --no-number-sections
	16365	@opindex --number-sections
	16366	With @option{--number_sections} (the default), output chapter,
	16367	section, and appendix numbers as in printed manuals. This works only
	16368	with hierarchically-structured manuals. You should specify
	16369	@code{--no-number-sections} if your manual is not normally structured.
	16370
	16371	@item --no-pointer-validate
	16372	@itemx --no-validate
	16373	@opindex --no-pointer-validate
	16374	@opindex --no-validate
	16375	@cindex Pointer validation, suppressing from command line
	16376	Suppress the pointer-validation phase of @code{makeinfo}---a dangerous
	16377	thing to do. This can also be done with the @code{@@novalidate}
	16378	command (@pxref{Use @TeX{}}). Normally, consistency checks are made
	16379	to ensure that cross-references can be resolved, etc. @xref{Pointer
	16380	Validation}.
	16381
	16382	@item --no-warn
	16383	@opindex --no-warn
	16384	Suppress warning messages (but not error messages).
	16385
	16386	@item --output=@var{file}
	16387	@itemx -o @var{file}
	16388	@opindex --output=@var{file}
	16389	@opindex -o @var{file}
	16390	Specify that the output should be directed to @var{file}. This
	16391	overrides any file name specified in a @code{@@setfilename} command
	16392	found in the Texinfo source. If neither @code{@@setfilename} nor this
	16393	option are specified, the input file name is used to determine the
	16394	output name. @xref{@code{@@setfilename}}.
	16395
	16396	If @var{file} is @samp{-}, output goes to standard output and
	16397	@samp{--no-split} is implied.
	16398
	16399	If @var{file} is a directory or ends with a @samp{/} the usual rules
	16400	are used to determine the output file name (namely, use
	16401	@code{@@setfilename} or the input file name) but the files are written
	16402	to the @var{file} directory. For example, @samp{makeinfo -o bar/
	16403	foo.texi}, with or without @option{--no-split}, will write
	16404	@file{bar/foo.info}, and possibly other files, under @file{bar/}.
	16405
	16406	When generating HTML and output is split, @var{file} is used as the
	16407	name for the directory into which all files are written. For example,
	16408	@samp{makeinfo -o bar --html foo.texi} will write
	16409	@file{bar/index.html}, among other files.
	16410
	16411	@item --output-indent=@var{val}
	16412	@opindex --outputindent
	16413	This option now does nothing, but remains for compatibility. (It used
	16414	to alter indentation in XML/Docbook output.)
	16415
	16416	@item -P @var{path}
	16417	@opindex -P @var{path}
	16418	Prepend @var{path} to the directory search list for @code{@@include}.
	16419	If @var{path} is not given, the current directory is prepended. See
	16420	@samp{-I} above.
	16421
	16422	@item --paragraph-indent=@var{indent}
	16423	@itemx -p @var{indent}
	16424	@opindex --paragraph-indent=@var{indent}
	16425	@opindex -p @var{indent}
	16426	Set the paragraph indentation style to @var{indent}. The value set by
	16427	this option overrides the value set in a Texinfo file by an
	16428	@code{@@paragraphindent} command (@pxref{@code{@@paragraphindent}}).
	16429	The value of @var{indent} is interpreted as follows:
	16430
	16431	@table @asis
	16432	@item @samp{asis}
	16433	Preserve any existing indentation (or lack thereof) at the beginnings
	16434	of paragraphs.
	16435
	16436	@item @samp{0} or @samp{none}
	16437	Delete any existing indentation.
	16438
	16439	@item @var{num}
	16440	Indent each paragraph by @var{num} spaces.
	16441	@end table
	16442
	16443	The default is to indent by two spaces, except for paragraphs
	16444	following a section heading, which are not indented.
	16445
	16446	@item --pdf
	16447	@opindex --pdf
	16448	Generate a PDF file using @command{texi2dvi --pdf}, rather than Info
	16449	(@pxref{@command{texi2any} Printed Output}).
	16450
	16451	@item --plaintext
	16452	@opindex --plaintext
	16453	@cindex Plain text output with @option{--plaintext}
	16454	@cindex ASCII text output with @option{--plaintext}
	16455	@cindex Generating plain text files with @option{--plaintext}
	16456	@cindex Node separators, omitting with @option{--plaintext}
	16457	@cindex Menus, omitting with @option{--plaintext}
	16458	@cindex @file{INSTALL} file, generating
	16459	Output a plain text file (rather than Info): do not include menus or
	16460	node separator lines in the output. This results in a straightforward
	16461	plain text file that you can (for example) send in email without
	16462	complications, or include in a distribution (for example, an
	16463	@file{INSTALL} file).
	16464
	16465	With this option, @code{@@setfilename} is ignored and the output goes
	16466	to standard output by default; this can be overridden with @option{-o}.
	16467
	16468	@item --ps
	16469	@opindex --ps
	16470	Generate a PostScript file using @command{texi2dvi --ps}, rather than
	16471	Info (@pxref{@command{texi2any} Printed Output}).
	16472
	16473	@item --set-customization-variable @var{var}=@var{value}
	16474	@itemx -c @var{var}=@var{value}
	16475	@opindex --set-customization-variable @var{var}=@var{value}
	16476	@opindex -c @var{var}=@var{value}
	16477	Set the customization variable @var{var} to @var{value}. The @code{=}
	16478	is optional, but both @var{var} and @var{value} must be quoted to the
	16479	shell as necessary so the result is a single word. Many aspects of
	16480	@command{texi2any} behavior and output may be controlled by
	16481	customization variables, beyond what can be set in the document by
	16482	@@-commands and with other command line switches. @xref{Customization
	16483	Variables}.
	16484
	16485	@item --split=@var{how}
	16486	@itemx --no-split
	16487	@opindex --split=@var{how}
	16488	@opindex --no-split
	16489	@cindex Splitting of output files
	16490	@cindex Output file splitting
	16491	@anchor{Splitting Output}
	16492	@c
	16493	When generating Info, by default large output files are split into
	16494	smaller subfiles, of approximately 300k bytes. When generating HTML,
	16495	by default each output file contains one node (@pxref{Generating
	16496	HTML}). @option{--no-split} suppresses this splitting of the output.
	16497
	16498	Alternatively, @option{--split=@var{how}} may be used to specify at
	16499	which level the HTML output should be split. The possible values for
	16500	@var{how} are:
	16501
	16502	@table @samp
	16503	@item chapter
	16504	The output is split at @code{@@chapter} and other sectioning
	16505	@@-commands at this level (@code{@@appendix}, etc.).
	16506
	16507	@item section
	16508	The output is split at @code{@@section} and similar.
	16509
	16510	@item node
	16511	The output is split at every node. This is the default.
	16512	@end table
	16513
	16514	Plain text output can be split similarly to HTML@. This may be useful
	16515	for extracting sections from a Texinfo document and making them
	16516	available as separate files.
	16517
	16518	@item --split-size=@var{num}
	16519	@opindex --split-size=@var{num}
	16520	Keep Info files to at most @var{num} characters if possible; default
	16521	is 300,000. (However, a single node will never be split across Info
	16522	files.)
	16523
	16524	@item --transliterate-file-names
	16525	@opindex --transliterate-file-names
	16526	Enable transliteration of 8-bit characters in node names for the
	16527	purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}.
	16528
	16529	@item -U @var{var}
	16530	Cause @var{var} to be undefined. This is equivalent to @code{@@clear
	16531	@var{var}} in the Texinfo file (@pxref{@code{@@set @@clear @@value}}).
	16532
	16533	@item --verbose
	16534	@opindex --verbose
	16535	Cause @code{makeinfo} to display messages saying what it is doing.
	16536	Normally, @code{makeinfo} only outputs messages if there are errors or
	16537	warnings.
	16538
	16539	@item --version
	16540	@itemx -V
	16541	@opindex --version@r{, for @command{texi2any}}
	16542	@opindex -V
	16543	Print the version number, then exit successfully.
	16544
	16545	@item --Xopt @var{str}
	16546	@opindex --Xopt @var{str}
	16547	Pass @var{str} (a single shell word) to @command{texi2dvi}; may be
	16548	repeated (@pxref{@command{texi2any} Printed Output}).
	16549
	16550	@item --xml
	16551	@opindex --xml
	16552	Generate Texinfo XML output (rather than Info).
	16553
	16554	@end table
	16555
	16556
	16557	@node @command{texi2any} Environment Variables
	16558	@section Environment Variables Recognized by @command{texi2any}
	16559
	16560	@vindex TEXINFO_OUTPUT_FORMAT
	16561	@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT}
	16562	@command{makeinfo} also reads the environment variable
	16563	@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not
	16564	overridden by a command line option. The value should be one of:
	16565
	16566	@example
	16567	docbook dvi dvipdf html info pdf plaintext ps xml
	16568	@end example
	16569
	16570	If not set or otherwise specified, Info output is the default.
	16571
	16572	The customization variable of the same name is also read; if set, that
	16573	overrides an environment variable setting, but not a command-line
	16574	option. @xref{Customization Variables and Options}.
	16575
	16576	@vindex TEXINFO_XS
	16577	@cindex Perl extension modules (XS)
	16578	You can control @command{texi2any}'s use of Perl extension modules
	16579	by setting the @env{TEXINFO_XS} environment variable. These modules
	16580	are compiled native code that the interpreted Perl code can use.
	16581	Ideally, these extension modules should just work, and the only noticable
	16582	difference they should make is that @command{texi2any} finishes running
	16583	sooner. However, you can use this environment variable for the purposes
	16584	of troubleshooting: for example, if you have problems with the output of
	16585	@command{texi2any} varying depending on whether the extension modules are
	16586	in use.
	16587
	16588	The following values of @env{TEXINFO_XS} are recognized by
	16589	@command{texi2any}:
	16590
	16591	@table @samp
	16592	@item default
	16593	The default behavior. Try to load extension modules, and silently fall
	16594	back to the interpreted Perl implementations if this fails.
	16595
	16596	@item warn
	16597	Try to load extension modules, and if this fails, give a warning message
	16598	before falling back to the interpreted Perl implementations.
	16599
	16600	@item debug
	16601	Try to load extension modules, printing many messages while doing so.
	16602
	16603	@item omit
	16604	Do not use extension modules.
	16605
	16606	@end table
	16607
	16608	@vindex TEXINFO_XS_PARSER
	16609	Set @env{TEXINFO_XS_PARSER} to @samp{1} to enable the use of the native
	16610	code implementation of the parser module. This is the part of
	16611	@command{texi2any} that converts Texinfo input into an internal tree
	16612	format used for further processing into output formats. This is not
	16613	enabled by default due to the greater complexity of this module compared
	16614	with the other modules that have a native code implementation, and the
	16615	lack of confidence we have that the native code implementation matches
	16616	the Perl code in all significant aspects. Despite the lack of maturity
	16617	of this module in terms of development and testing, it may be useful for
	16618	decreasing @command{texi2any} run times when working on Texinfo
	16619	documentation files. Note that some error and warning messages will not
	16620	be translated from English if this module is used.
	16621
	16622
	16623	@node @command{texi2any} Printed Output
	16624	@section @command{texi2any} Printed Output
	16625
	16626	@cindex Printed output, through @command{texi2any}
	16627	@cindex Output, printed through @command{texi2any}
	16628
	16629	To justify the name Texinfo-to-@emph{any}, @command{texi2any} has
	16630	basic support for creating printed output in the various formats:
	16631	@TeX{} DVI, PDF, and PostScript. This is done via the simple method
	16632	of executing the @command{texi2dvi} program when those output formats
	16633	are requested, after checking the validity of the input to give users
	16634	the benefit of @command{texi2any}'s error checking. If you don't want
	16635	such error checking, perhaps because your manual plays advanced @TeX{}
	16636	tricks together with @file{texinfo.tex}, just invoke
	16637	@command{texi2dvi} directly.
	16638
	16639	The output format options for this are @option{--dvi},
	16640	@option{--dvipdf}, @option{--pdf}, and @option{--ps}. @xref{Format
	16641	with @command{texi2dvi}}, for more details on these options and general
	16642	@command{texi2dvi} operation. In addition, the @option{--verbose},
	16643	@option{--silent}, and @option{--quiet} options are passed on if
	16644	specified; the @option{-I} and @option{-o} options are likewise passed
	16645	on with their arguments, and @option{--debug} without its argument.
	16646
	16647	The only option remaining that is related to the @command{texi2dvi}
	16648	invocation is @option{--Xopt}. Here, just the argument is passed on
	16649	and multiple @option{--Xopt} options accumulate. This provides a way
	16650	to construct an arbitrary command line for @command{texi2dvi}. For
	16651	example, running
	16652
	16653	@example
	16654	texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi
	16655	@end example
	16656
	16657	@noindent is equivalent to running
	16658
	16659	@example
	16660	texi2dvi -t @@a4paper --pdf foo.texi
	16661	@end example
	16662
	16663	@noindent except for the validity check.
	16664
	16665	Although one might wish that other options to @command{texi2any} would
	16666	take effect, they don't. For example, running @samp{texi2any
	16667	--no-number-sections --dvi foo.texi} still results in a DVI file with
	16668	numbered sections. (Perhaps this could be improved in the future, if
	16669	requests are received.)
	16670
	16671	The actual name of the command that is invoked is specified by the
	16672	@code{TEXI2DVI} customization variable (@pxref{Other Customization
	16673	Variables}). As you might guess, the default is @samp{texi2dvi}.
	16674
	16675	@command{texi2any} itself does not generate any normal output when it
	16676	invokes @command{texi2dvi}, only diagnostic messages.
	16677
	16678
	16679	@node Pointer Validation
	16680	@section Pointer Validation
	16681	@cindex Pointer validation with @code{makeinfo}
	16682	@cindex Validation of pointers
	16683
	16684	If you do not suppress pointer validation with the
	16685	@samp{--no-validate} option or the @code{@@novalidate} command in the
	16686	source file (@pxref{Use @TeX{}}), @code{makeinfo} will check the
	16687	validity of the Texinfo file.
	16688
	16689	Most validation checks are different depending on whether node
	16690	pointers are explicitly or implicitly determined. With explicit node
	16691	pointers, here is the list of what is checked:
	16692
	16693	@enumerate
	16694	@item
	16695	If a `Next', `Previous', or `Up' node reference is a reference to a
	16696	node in the current file and is not an external reference such as to
	16697	@file{(dir)}, then the referenced node must exist.
	16698
	16699	@item
	16700	Every node except the `Top' node must have an `Up' pointer.
	16701
	16702	@item
	16703	The node referenced by an `Up' pointer must itself reference the
	16704	current node through a menu item, unless the node referenced by `Up'
	16705	has the form @samp{(@var{file})}.
	16706	@end enumerate
	16707
	16708	With implicit node pointers, the above error cannot occur, as such.
	16709	(Which is a major reason why we recommend using this feature of
	16710	@code{makeinfo}, and not specifying any node pointers yourself.)
	16711
	16712	Instead, @code{makeinfo} checks that the tree constructed from the
	16713	document's menus matches the tree constructed from the sectioning
	16714	commands. For example, if a chapter-level menu mentions nodes
	16715	@var{n1} and @var{n2}, in that order, nodes @var{n1} and @var{n2} must
	16716	be associated with @code{@@section} commands in the chapter.
	16717
	16718	Finally, with both explicit and implicit node pointers,
	16719	@code{makeinfo} checks that every node except the `Top' node is
	16720	referenced in a menu.
	16721
	16722
	16723	@node Customization Variables
	16724	@section Customization Variables
	16725
	16726	@quotation Warning
	16727	These customization variable names and meanings may change in any
	16728	Texinfo release. We always try to avoid incompatible changes, but we
	16729	cannot absolutely promise, since needs change over time.
	16730	@end quotation
	16731
	16732	Many aspects of the behavior and output of @command{texi2any} may be
	16733	modified by modifying so-called @dfn{customization variables}. These
	16734	fall into a few general categories:
	16735
	16736	@itemize @bullet
	16737	@item
	16738	Those associated with @@-commands; for example,
	16739	@code{@@documentlanguage}.
	16740
	16741	@item
	16742	Those associated with command-line options; for example, the
	16743	customization variable @code{SPLIT} is associated with the
	16744	@option{--split} command-line option, and @code{TEXINFO_OUTPUT_FORMAT}
	16745	allows specifying the output format.
	16746
	16747	@item
	16748	Those associated with customizing the HTML output.
	16749
	16750	@item
	16751	Other ad hoc variables.
	16752	@end itemize
	16753
	16754	Customization variables may set on the command line using
	16755	@code{--set-customization-variable '@var{var} @var{value}'} (quoting
	16756	the variable/value pair to the shell) or
	16757	@code{--set-customization-variable @var{var}=@var{value}} (using
	16758	@code{=}). A special @var{value} is @samp{undef}, which sets the
	16759	variable to this special ``undefined'' Perl value.
	16760
	16761	The sections below give the details for each of these.
	16762
	16763	@menu
	16764	* Commands: Customization Variables for @@-Commands.
	16765	* Options: Customization Variables and Options.
	16766	* HTML: HTML Customization Variables.
	16767	* latex2html: @command{latex2html} Customization Variables.
	16768	* Other: Other Customization Variables.
	16769	@end menu
	16770
	16771
	16772	@node Customization Variables for @@-Commands
	16773	@subsection Customization Variables for @@-Commands
	16774
	16775	@cindex Customization variables for @@-commands
	16776	@cindex @@-commands, customization variables for
	16777
	16778	Each of the following @@-commands has an associated customization
	16779	variable with the same name (minus the leading @code{@@}):
	16780
	16781	@smallexample
	16782	@@allowcodebreaks @@clickstyle
	16783	@@codequotebacktick @@codequoteundirected
	16784	@@contents @@deftypefnnewline
	16785	@@documentdescription @@documentencoding @@documentlanguage
	16786	@@exampleindent @@firstparagraphindent
	16787	@@footnotestyle @@frenchspacing
	16788	@@kbdinputstyle @@novalidate
	16789	@@paragraphindent @@setfilename
	16790	@@shortcontents @@urefbreakstyle
	16791	@@validatemenus @@xrefautomaticsectiontitle
	16792	@end smallexample
	16793
	16794	@c Relevant to TeX only.
	16795	@c @@evenfooting @@evenfootingmarks
	16796	@c @@evenheading @@evenheadingmarks
	16797	@c @@everyfooting @@everyfootingmarks
	16798	@c @@everyheading @@everyheadingmarks
	16799	@c @@fonttextsize
	16800	@c @@headings
	16801	@c @@oddfooting @@oddfootingmarks
	16802	@c @@oddheading @@oddheadingmarks
	16803	@c @@pagesizes
	16804	@c @@setchapternewpage
	16805
	16806	Setting such a customization variable to a value @samp{foo} is similar
	16807	to executing @code{@@@var{cmd} foo}. It is not exactly the same,
	16808	though, since any side effects of parsing the Texinfo source are not
	16809	redone. Also, some variables do not take Texinfo code when generating
	16810	particular formats, but an argument that is already formatted. This
	16811	is the case, for example, for HTML for @code{documentdescription}.
	16812
	16813	Note that if @command{texi2any} is invoked to process the file with
	16814	@TeX{} (e.g., with the @option{--pdf} option), then these customization
	16815	variables may not be passed on to @TeX{}.
	16816
	16817
	16818	@node Customization Variables and Options
	16819	@subsection Customization Variables and Options
	16820
	16821	@cindex Customization variables for options
	16822	@cindex Options, customization variables for
	16823
	16824	The following table gives the customization variables associated with
	16825	some command line options. @xref{Invoking @command{texi2any}}, for the
	16826	meaning of the options.
	16827
	16828	@multitable @columnfractions 0.5 0.5
	16829	@headitem Option @tab Variable
	16830	@item
	16831	@vindex ENABLE_ENCODING
	16832	@option{--enable-encoding} @tab @code{ENABLE_ENCODING}
	16833	@item
	16834	@option{--document-language} @tab @code{documentlanguage}
	16835	@item
	16836	@vindex ERROR_LIMIT
	16837	@option{--error-limit} @tab @code{ERROR_LIMIT}
	16838	@item
	16839	@vindex FILLCOLUMN
	16840	@option{--fill-column} @tab @code{FILLCOLUMN}
	16841	@vindex footnotestyle
	16842	@item
	16843	@option{--footnote-style} @tab @code{footnotestyle}
	16844	@item
	16845	@vindex FORCE
	16846	@option{--force} @tab @code{FORCE}
	16847	@vindex INTERNAL_LINKS
	16848	@item
	16849	@option{--internal-links} @tab @code{INTERNAL_LINKS}
	16850	@item
	16851	@vindex MACRO_EXPAND
	16852	@option{--macro-expand} @tab @code{MACRO_EXPAND}
	16853	@item
	16854	@option{--headers} @tab @code{HEADERS}, @code{SHOW_MENU}
	16855	@item
	16856	@vindex NO_WARN
	16857	@option{--no-warn} @tab @code{NO_WARN}
	16858	@item
	16859	@vindex novalidate
	16860	@option{--no-validate} @tab @code{novalidate}
	16861	@item
	16862	@vindex NUMBER_FOOTNOTES
	16863	@option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES}
	16864	@item
	16865	@vindex NUMBER_SECTIONS
	16866	@option{--number-sections} @tab @code{NUMBER_SECTIONS}
	16867	@item
	16868	@vindex NODE_FILES
	16869	@option{--node-files} @tab @code{NODE_FILES}
	16870	@item
	16871	@vindex OUTFILE
	16872	@vindex SUBDIR
	16873	@option{--output} @tab @code{OUTFILE}, @code{SUBDIR}
	16874	@item
	16875	@vindex paragraphindent
	16876	@option{--paragraph-indent} @tab @code{paragraphindent}
	16877	@item
	16878	@vindex SILENT
	16879	@option{--silent} @tab @code{SILENT}
	16880	@item
	16881	@vindex SPLIT
	16882	@option{--split} @tab @code{SPLIT}
	16883	@item
	16884	@vindex SPLIT_SIZE
	16885	@option{--split-size} @tab @code{SPLIT_SIZE}
	16886	@item
	16887	@vindex TRANSLITERATE_FILE_NAMES
	16888	@option{--transliterate-file-names} @tab @code{TRANSLITERATE_FILE_NAMES}
	16889	@item
	16890	@vindex VERBOSE
	16891	@option{--verbose} @tab @code{VERBOSE}
	16892	@end multitable
	16893
	16894	Setting such a customization variable to a value @samp{foo} is
	16895	essentially the same as specifying the @code{--@var{opt}=foo} if the
	16896	option takes an argument, or @code{--@var{opt}} if not.
	16897
	16898	@vindex TEXINFO_OUTPUT_FORMAT
	16899	In addition, the customization variable @code{TEXINFO_OUTPUT_FORMAT}
	16900	allows specifying what @code{makeinfo} outputs, either one of the usual
	16901	output formats that can be specified with options, or various other
	16902	forms:
	16903
	16904	@ftable @samp
	16905	@item docbook
	16906	@itemx dvi
	16907	@itemx dvipdf
	16908	@itemx html
	16909	@itemx info
	16910	@itemx pdf
	16911	@itemx plaintext
	16912	@itemx ps
	16913	@itemx xml
	16914	These correspond to the command-line options (and
	16915	@code{TEXINFO_OUTPUT_FORMAT} environment variable values) of the same
	16916	name. @xref{Invoking @command{texi2any}}.
	16917
	16918	@item debugtree
	16919	@cindex tree representation, for debugging
	16920	@cindex debugging document, with tree representation
	16921	Instead of generating a regular output format, output a text representation
	16922	of the tree obtained by parsing the input texinfo document.
	16923
	16924	@item parse
	16925	Do only Texinfo source parsing; there is no output.
	16926
	16927	@item plaintexinfo
	16928	Output the Texinfo source with all the macros, @code{@@include} and
	16929	@code{@@value@{@}} expanded. This is similar to setting
	16930	@option{--macro-expand}, but instead of being output in addition to
	16931	the normal conversion, output of Texinfo is the main output.
	16932
	16933	@item rawtext
	16934	@cindex raw text output
	16935	Output raw text, with minimal formatting. For example, footnotes are
	16936	ignored and there is no paragraph filling. This is used by the parser
	16937	for file names and copyright text in HTML comments, for example.
	16938
	16939	@item structure
	16940	Do only Texinfo source parsing and determination of the document
	16941	structure; there is no output.
	16942
	16943	@item texinfosxml
	16944	@cindex SXML output
	16945	@cindex S-expressions, output format
	16946	Output the document in TexinfoSXML representation, a syntax for
	16947	writing XML data using Lisp S-expressions.
	16948
	16949	@item textcontent
	16950	@cindex spell checking
	16951	@cindex word counting
	16952	@pindex detexinfo
	16953	@cindex stripping Texinfo commands
	16954	Output the text content only, stripped of commands; this is useful for
	16955	spell checking or word counting, for example. The trivial
	16956	@code{detexinfo} script setting this is in the @file{util} directory
	16957	of the Texinfo source as an example. It's one line:
	16958
	16959	@example
	16960	exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@"
	16961	@end example
	16962	@end ftable
	16963
	16964
	16965	@node HTML Customization Variables
	16966	@subsection HTML Customization Variables
	16967
	16968	This table gives the customization variables which apply to HTML
	16969	output only. A few other customization variable apply to both HTML
	16970	and other output formats; see @ref{Other Customization Variables}.
	16971
	16972	@vtable @code
	16973	@item AVOID_MENU_REDUNDANCY
	16974	If set, and the menu entry and menu description are the
	16975	same, then do not print the menu description; default false.
	16976
	16977	@item AFTER_BODY_OPEN
	16978	If set, the corresponding text will appear at the
	16979	beginning of each HTML file; default unset.
	16980
	16981	@item AFTER_ABOUT
	16982	For HTML, when an About-element is output. If set, the corresponding
	16983	text will appear at the end of the About element; default unset.
	16984
	16985	@item AFTER_OVERVIEW
	16986	@itemx AFTER_TOC_LINES
	16987	If set, the corresponding text is output after the short
	16988	table of contents for @code{AFTER_OVERVIEW} and after the table of
	16989	contents for @code{AFTER_TOC_LINES}; otherwise, a default string is
	16990	used. At the time of writing, a @code{</div>} element is closed.
	16991
	16992	In general, you should set @code{BEFORE_OVERVIEW} if
	16993	@code{AFTER_OVERVIEW} is set, and you should set
	16994	@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set.
	16995
	16996
	16997	@item BASEFILENAME_LENGTH
	16998	The maximum length of the base filenames; default 245.
	16999	Changing this would make cross-manual references to such long node
	17000	names invalid (@pxref{HTML Xref Link Basics}).
	17001
	17002	@item BEFORE_OVERVIEW
	17003	@itemx BEFORE_TOC_LINES
	17004	If set, the corresponding text is output before the short
	17005	table of contents for @code{BEFORE_OVERVIEW} and before the table of
	17006	contents for @code{BEFORE_TOC_LINES}, otherwise a default string is
	17007	used. At the time of writing, a @code{<div ...>} element is opened.
	17008
	17009	In general you should set @code{AFTER_OVERVIEW} if
	17010	@code{BEFORE_OVERVIEW} is set, and you should set
	17011	@code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set.
	17012
	17013
	17014	@item BIG_RULE
	17015	Rule used after and before the top element and before
	17016	special elements, but not for footers and headers; default
	17017	@code{<hr>}.
	17018
	17019	@item BODYTEXT
	17020	@cindex @code{<body>} text, customizing
	17021	@opindex lang@r{, HTML attribute}
	17022	The text appearing in @code{<body>}. By default, sets the
	17023	HTML @code{lang} attribute to the document language
	17024	(@pxref{@code{@@documentlanguage}}).
	17025
	17026	@item CASE_INSENSITIVE_FILENAMES
	17027	Construct output file names as if the filesystem were case
	17028	insensitive (@pxref{HTML Splitting}); default false.
	17029
	17030	@item CHAPTER_HEADER_LEVEL
	17031	Header formatting level used for chapter level sectioning
	17032	commands; default @samp{2}.
	17033
	17034	@item CHECK_HTMLXREF
	17035	Check that manuals which are the target of external
	17036	cross-references (@pxref{Four and Five Arguments}) are present in
	17037	@file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false.
	17038
	17039	@item COMPLEX_FORMAT_IN_TABLE
	17040	If set, use tables for indentation of complex formats; default
	17041	false.
	17042
	17043	@item CSS_LINES
	17044	CSS output, automatically determined by default (@pxref{HTML CSS}).
	17045
	17046	@item DATE_IN_HEADER
	17047	Put the document generation date in the header; off by default.
	17048
	17049	@item DEF_TABLE
	17050	If set, a @code{<table>} construction for @code{@@deffn}
	17051	and similar @@-commands is used (looking more like the @TeX{} output),
	17052	instead of definition lists; default false.
	17053
	17054	@item DEFAULT_RULE
	17055	Rule used between element, except before and after the
	17056	top element, and before special elements, and for footers and headers;
	17057	default @code{<hr>}.
	17058
	17059	@item DO_ABOUT
	17060	If set to 0 never do an About special element;
	17061	if set to 1 always do an About special element;
	17062	default 0.
	17063	@c @xref{Output Elements Defined}.
	17064
	17065	@item EXTERNAL_DIR
	17066	Base directory for external manuals; default none. It is
	17067	better to use the general external cross-reference mechanism
	17068	(@pxref{HTML Xref Configuration}) than this variable.
	17069
	17070	@item EXTRA_HEAD
	17071	Additional text appearing within @code{<head>}; default unset.
	17072
	17073	@item FOOTNOTE_END_HEADER_LEVEL
	17074	Header formatting level used for the footnotes header with
	17075	the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}.
	17076
	17077	@item FOOTNOTE_SEPARATE_HEADER_LEVEL
	17078	Header formatting level used for the footnotes header with
	17079	the `separate' footnotestyle; default @samp{4}. @xref{Footnote
	17080	Styles}.
	17081
	17082	@item FRAMES
	17083	If set, a file describing the frame layout is generated,
	17084	together with a file with the short table of contents; default false.
	17085
	17086	@item FRAMESET_DOCTYPE
	17087	Same as DOCTYPE, but for the file containing the frame
	17088	description.
	17089
	17090	@item HEADER_IN_TABLE
	17091	Use tables for header formatting rather than a simple
	17092	@code{<div>} element; default false.
	17093
	17094	@item ICONS
	17095	Use icons for the navigation panel; default false.
	17096
	17097	@item IMAGE_LINK_PREFIX
	17098	If set, the associated value is prepended to the image file
	17099	links; default unset.
	17100
	17101	@item INLINE_CONTENTS
	17102	If set, output the contents where the @code{@@contents} and
	17103	similar @@-commands are located; default true. This is ignored if
	17104	@code{@@set*contentsaftertitlepage} is set (@pxref{Contents}).
	17105
	17106	@item INLINE_CSS_STYLE
	17107	Put CSS directly in HTML elements rather than at the
	17108	beginning of the output; default false.
	17109
	17110	@item KEEP_TOP_EXTERNAL_REF
	17111	If set, do not ignore @samp{Top} as the first
	17112	argument for an external ref to a manual, as is done by default.
	17113	@xref{Referring to a Manual as a Whole}.
	17114
	17115	@item MAX_HEADER_LEVEL
	17116	Maximum header formatting level used (higher header
	17117	formatting level numbers correspond to lower sectioning levels);
	17118	default @samp{4}.
	17119
	17120	@item MENU_SYMBOL
	17121	Symbol used in front of menu entries when node names are used
	17122	for menu entries formatting; default @samp{•}.
	17123
	17124	@item MONOLITHIC
	17125	Output only one file including the table of contents. Set
	17126	by default, but only relevant when the output is not split.
	17127
	17128	@item NO_CSS
	17129	Do not use CSS; default false. @xref{HTML CSS}.
	17130
	17131	@item PRE_ABOUT
	17132	Used when an About element is output. If set to a text string,
	17133	this text will appear at the beginning of the About element. If set
	17134	to a reference on a subroutine, the result of the subroutine call will
	17135	appear at the beginning of the About element. If not set (the
	17136	default), default text is used.
	17137
	17138	@item PRE_BODY_CLOSE
	17139	If set, the given text will appear at the footer of each
	17140	HTML file; default unset.
	17141
	17142	@item PROGRAM_NAME_IN_FOOTER
	17143	If set, output the program name and miscellaneous related
	17144	information in the page footers; default false.
	17145
	17146	@item SECTION_NAME_IN_TITLE
	17147	If set, when output is split, use the argument of the chapter
	17148	structuring command (e.g., @code{@@chapter} or @code{@@section})
	17149	in the @code{<title>} instead of the argument to @code{@@node}.
	17150
	17151	@item SHOW_TITLE
	17152	If set, output the title at the beginning of the document;
	17153	default true.
	17154
	17155	@item SIMPLE_MENU
	17156	If set, use a simple preformatted style for the menu,
	17157	instead of breaking down the different parts of the menu; default false.
	17158	@xref{Menu Parts}.
	17159
	17160	@item TOC_LINKS
	17161	If set, links from headings to toc entries are created;
	17162	default false.
	17163
	17164	@item TOP_FILE
	17165	This file name may be used for the top-level file. The extension is
	17166	set appropriately, if necessary. This is used to override the default,
	17167	and is, in general, only taken into account when output is split, and
	17168	for HTML@.
	17169
	17170	@item TOP_NODE_FILE_TARGET
	17171	File name used for the Top node in cross-references;
	17172	default is @code{index.html}.
	17173
	17174	@item TOP_NODE_UP_URL
	17175	A url used for Top node up references; the default is
	17176	@code{undef}, in that case no Top node Up reference is generated.
	17177	For more about the Top node pointers, @pxref{First Node}. For
	17178	overriding the Up pointer name in cas @code{TOP_NODE_UP_URL} is set
	17179	and for other formats, see @code{TOP_NODE_UP} in
	17180	@ref{Other Customization Variables}.
	17181
	17182	@item USE_ACCESSKEY
	17183	@cindex @code{accesskey}, customization variable for
	17184	Use @code{accesskey} in cross-references; default true.
	17185
	17186	@item USE_ISO
	17187	Use entities for doubled single-quote characters
	17188	(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
	17189	(@pxref{Conventions}); default true.
	17190
	17191	@item USE_LINKS
	17192	@cindex @code{<link>} HTML tag, in @code{<head>}
	17193	@cindex @code{<head>} HTML tag, and @code{<link>}
	17194	Generate @code{<link>} elements in the HTML @code{<head>}
	17195	output; default true.
	17196
	17197	@item USE_REL_REV
	17198	Use @code{rel} in cross-references; default true.
	17199
	17200	@item VERTICAL_HEAD_NAVIGATION
	17201	If set, a vertical navigation panel is used; default false.
	17202
	17203	@item WORDS_IN_PAGE
	17204	@cindex Navigation panel, bottom of page
	17205	@cindex Navigation footer
	17206	When output is split by nodes, specifies the approximate
	17207	minimum page length at which a navigation panel is placed at the
	17208	bottom of a page. To avoid ever having the navigation buttons at the
	17209	bottom of a page, set this to a sufficiently large number. The
	17210	default is 300.
	17211
	17212	@item XREF_USE_FLOAT_LABEL
	17213	If set, for the float name in cross-references, use the
	17214	float label instead of the type followed by the float number
	17215	(@pxref{@code{@@float}}). The default is off.
	17216
	17217	@item XREF_USE_NODE_NAME_ARG
	17218	Only relevant for cross-reference commands with no cross
	17219	reference name (second argument). If set to@tie{}1, use the node name
	17220	(first) argument in cross-reference @@-commands for the text displayed
	17221	as the hyperlink. If set to@tie{}0, use the node name if
	17222	@code{USE_NODES} is set, otherwise the section name. If set to
	17223	@samp{undef}, use the first argument in preformatted environments,
	17224	otherwise use the node name or section name depending on
	17225	@code{USE_NODES}. The default is @samp{undef}.
	17226
	17227	@end vtable
	17228
	17229
	17230	@node @command{latex2html} Customization Variables
	17231	@subsection @command{latex2html} Customization Variables
	17232
	17233	This table lists the customization variables which can be used when
	17234	@command{latex2html} is being used.
	17235
	17236	@vtable @code
	17237	@item L2H
	17238	For HTML@. If set, @command{latex2html} is used to convert @code{@@math}
	17239	and @code{@@tex} sections; default false. Best used with @option{--iftex}.
	17240
	17241	@item L2H_CLEAN
	17242	(Relevant only if @code{L2H} is set.) If set, the intermediate files
	17243	generated in relation with @command{latex2html} are removed; default
	17244	true.
	17245
	17246	@item L2H_FILE
	17247	(Relevant only if @code{L2H} is set.) If set, the given file is used
	17248	as @command{latex2html}'s init file; default unset.
	17249
	17250	@item L2H_HTML_VERSION
	17251	(Relevant only if @code{L2H} is set.) The HTML version used in the
	17252	@command{latex2html} call; default unset.
	17253
	17254	@item L2H_L2H
	17255	(Relevant only if @code{L2H} is set.) The program invoked as
	17256	@command{latex2html}; default is @code{latex2html}.
	17257
	17258	@item L2H_SKIP
	17259	(Relevant only if @code{L2H} is set.) If set to a true value, the
	17260	actual call to @command{latex2html} is skipped; previously generated
	17261	content is reused instead. If set to 0, the cache is not used at all.
	17262	If set to @samp{undef}, the cache is used for as many @TeX{} fragments as
	17263	possible and for any remaining the command is run. The default is
	17264	@samp{undef}.
	17265
	17266	@item L2H_TMP
	17267	(Relevant only if @code{L2H} is set.) Set the directory used for
	17268	temporary files. None of the file name components in this directory
	17269	name may start with @samp{.}; otherwise, @command{latex2html} will
	17270	fail (because of @command{dvips}). The default is the empty string,
	17271	which means the current directory.
	17272
	17273	@end vtable
	17274
	17275
	17276
	17277	@node Other Customization Variables
	17278	@subsection Other Customization Variables
	17279
	17280	This table gives the remaining customization variables, which apply to
	17281	multiple formats, or affect global behavior, or otherwise don't fit
	17282	into the categories of the previous sections.
	17283
	17284	@vtable @code
	17285	@item CLOSE_QUOTE_SYMBOL
	17286	When a closing quote is needed, use this character; default @code{’}
	17287	in HTML, @code{’} in Docbook. The default for Info is the same
	17288	as @code{OPEN_QUOTE_SYMBOL} (see below).
	17289
	17290	@c @item COMPLETE_IMAGE_PATHS
	17291	@c If set, the image files are computed to be relative from the document
	17292	@c directory to the source manual directory, and then to the image.
	17293
	17294	@item CPP_LINE_DIRECTIVES
	17295	Recognize @code{#line} directives in a ``preprocessing'' pass
	17296	(@pxref{External Macro Processors}); on by default.
	17297
	17298	@item DEBUG
	17299	If set, debugging output is generated; default is off (zero).
	17300	@c The integer value specifies what kinds of debugging output are
	17301	@c generated. It is a bitmask. Setting it to 255 ensures having all
	17302	@c available debugging output.
	17303
	17304	@item DOCTYPE
	17305	@vindex SystemLiteral
	17306	For Docbook, HTML, XML@. Specifies the @code{SystemLiteral}, the
	17307	entity's system identifier. This is a URI which may be used to
	17308	retrieve the entity, and identifies the canonical DTD for the
	17309	document. The default value is different for each of HTML, Docbook
	17310	and Texinfo@tie{}XML.
	17311
	17312	@item DUMP_TEXI
	17313	For debugging. If set, no conversion is done, only parsing and macro
	17314	expansion. If the option @option{--macro-expand} is set, the Texinfo
	17315	source is also expanded to the corresponding file. Default false.
	17316
	17317	@item DUMP_TREE
	17318	For debugging. If set, the tree constructed upon parsing a Texinfo
	17319	document is output to standard error; default false.
	17320
	17321	@item ENABLE_ENCODING_USE_ENTITY
	17322	For HTML, XML@. If @option{--enable-encoding} is set, and there is an
	17323	entity corresponding with the letter or the symbol being output,
	17324	prefer the entity. Set by default for HTML, but not XML.
	17325
	17326	@item EXTERNAL_CROSSREF_SPLIT
	17327	For cross-references to other manuals, this determines if the other
	17328	manual is considered to be split or monolithic. By default, it is set
	17329	based on the value of @code{SPLIT}. @xref{HTML Xref}, and @pxref{HTML
	17330	Xref Configuration}.
	17331
	17332	@item EXTENSION
	17333	The extension added to the output file name. The default is different
	17334	for each output format.
	17335
	17336	@c @item IDX_SUMMARY
	17337	@c If set, for each @code{@@printindex} a file named
	17338	@c @file{@var{docname}_@var{idxname}.idx} is created, containing lines of
	17339	@c the form:
	17340	@c
	17341	@c @example
	17342	@c @var{key} @var{reference}
	17343	@c @end example
	17344	@c
	17345	@c @noindent sorted alphabetically (case matters).
	17346
	17347	@item IGNORE_BEFORE_SETFILENAME
	17348	If set, begin outputting at @code{@@setfilename}, if
	17349	@code{@@setfilename} is present; default true.
	17350
	17351	@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME
	17352	If set, spaces are ignored after an @@-command that takes braces.
	17353	Default true, matching the @TeX{} behavior.
	17354
	17355	@item INDEX_ENTRY_COLON
	17356	Symbol used between the index entry and the associated node or section;
	17357	default @samp{:}.
	17358
	17359	@item INDEX_SPECIAL_CHARS_WARNING
	17360	If set, warn about @samp{:} in index entry, as it leads to invalid entries in
	17361	index menus in output Info files. For Info and plaintext only.
	17362
	17363	@anchor{INFO_SPECIAL_CHARS_QUOTE}
	17364	@item INFO_SPECIAL_CHARS_QUOTE
	17365	If set, whenever there are problematic characters for Info output in
	17366	places such as node names or menu items, surround the part of the
	17367	construct where they appear with quoting characters, as described in
	17368	@ref{Info Format Specification}. @xref{Node Line Requirements}.
	17369
	17370	@item INFO_SPECIAL_CHARS_WARNING
	17371	If set, warn about problematic constructs for Info output (such as the
	17372	string @samp{::}) in node names, menu items, and cross-references;
	17373	default true. Do not warn about index entries, since parsing problems
	17374	there don't prevent navigation; readers can still relatively easily
	17375	find their way to the node in question.
	17376
	17377	@item MAX_MACRO_CALL_NESTING
	17378	The maximal number of recursive calls of @@-commands defined through
	17379	@code{@@rmacro}; default 100000. The purpose of this variable is to
	17380	avoid infinite recursions.
	17381
	17382	@item MENU_ENTRY_COLON
	17383	Symbol used between the menu entry and the description; default
	17384	empty.
	17385
	17386	@item NO_USE_SETFILENAME
	17387	If set, do not use @code{@@setfilename} to set the document name;
	17388	instead, base the output document name only on the input file name.
	17389	The default is false.
	17390
	17391	@item NODE_NAME_IN_INDEX
	17392	If set, use node names in index entries, otherwise prefer section names;
	17393	default true.
	17394
	17395	@item NODE_NAME_IN_MENU
	17396	If set, use node names in menu entries, otherwise prefer section names;
	17397	default true.
	17398
	17399	@item OPEN_QUOTE_SYMBOL
	17400	When an opening quote is needed, e.g., for @samp{@@samp} output, use
	17401	the specified character; default @code{‘} for HTML,
	17402	@code{‘} for Docbook. For Info, the default depends on the
	17403	enabled document encoding (@pxref{@code{@@documentencoding}}); if no
	17404	document encoding is set, or the encoding is US-ASCII, etc., @samp{'}
	17405	is used. This character usually appears as an undirected single quote
	17406	on modern systems. If the document encoding is Unicode, the Info
	17407	output uses a Unicode left quote.
	17408
	17409	@item OUTPUT_ENCODING_NAME
	17410	Normalized encoding name used for output files. Should be a usable
	17411	charset name in HTML, typically one of the preferred IANA encoding
	17412	names. By default, if an input encoding is set (typically through
	17413	@code{@@documentencoding}), this information is used to set the output
	17414	encoding name. If no input encoding is specified, the default output
	17415	encoding name may be set by the output format. In particular, the
	17416	XML-based formats use @code{utf-8} for @code{OUTPUT_ENCODING_NAME} if
	17417	the encoding is not otherwise specified. @xref{@code{@@documentencoding}}.
	17418
	17419	@item OVERVIEW_LINK_TO_TOC
	17420	If set, the cross-references in the Overview link to the corresponding
	17421	Table of Contents entries; default true.
	17422
	17423	@item PACKAGE
	17424	@itemx PACKAGE_VERSION
	17425	@itemx PACKAGE_AND_VERSION
	17426	@itemx PACKAGE_URL
	17427	@itemx PACKAGE_NAME
	17428	The implementation's short package name, package version, package name
	17429	and version concatenated, package url, and full package name,
	17430	respectively. By default, these variables are all set through
	17431	Autoconf, Automake, and @code{configure}.
	17432
	17433	@item PREFIX
	17434	The output file prefix, which is prepended to some output file names.
	17435	By default it is set by @code{@@setfilename} or from the input file
	17436	(@pxref{@code{@@setfilename}}). How this value is used depends on the
	17437	value of other customization variables or command line options, such
	17438	as whether the output is split. The default is unset.
	17439
	17440	@item PROGRAM
	17441	Name of the program used. By default, it is set to the name of the
	17442	program launched, with a trailing @samp{.pl} removed.
	17443
	17444	@item SHOW_MENU
	17445	@vindex HEADERS
	17446	@opindex --no-headers
	17447	If set, Texinfo menus are output. By default, it is set unless
	17448	generating Docbook or if @option{--no-headers} is specified.
	17449
	17450	@item SORT_ELEMENT_COUNT
	17451	@pindex texi-elements-by-size
	17452	@cindex Longest nodes, finding
	17453	@cindex Sorting nodes by size
	17454	If set, the name of a file to which a list of elements (nodes or
	17455	sections, depending on the output format) is dumped, sorted by the
	17456	number of lines they contain after removal of @@-commands; default
	17457	unset. This is used by the program @code{texi-elements-by-size} in
	17458	the @file{util/} directory of the Texinfo source distribution
	17459	(@pxref{texi-elements-by-size}).
	17460
	17461	@item SORT_ELEMENT_COUNT_WORDS
	17462	When dumping the elements-by-size file (see preceding item), use word
	17463	counts instead of line counts; default false.
	17464
	17465	@c @item SPLIT_INDEX
	17466	@c For HTML@. If set, the output is split, and the output from
	17467	@c @code{@@printindex} happens in a sectioning element at the level of
	17468	@c splitting, then split index pages at the next letter after they have
	17469	@c more than that many entries. If set to 0, no index splitting.
	17470
	17471	@item TEST
	17472	If set to true, some variables which are normally dynamically
	17473	generated anew for each run (date, program name, version) are set to
	17474	fixed and given values. This is useful to compare the output to a
	17475	reference file, as is done for the tests. The default is false.
	17476
	17477	@item TEXI2DVI
	17478	Name of the command used to produce PostScript, PDF, and DVI; default
	17479	@samp{texi2dvi}. @xref{@command{texi2any} Printed Output}.
	17480
	17481	@item TEXI2HTML
	17482	@cindex compatibility, with @command{texi2html}
	17483	Generate HTML and try to be as compatible as possible with
	17484	@command{texi2html}; default false.
	17485
	17486	@item TEXINFO_DTD_VERSION
	17487	For XML@. Version of the DTD used in the XML output preamble. The
	17488	default is set based on a variable in @file{configure.ac}.
	17489
	17490	@item TEXTCONTENT_COMMENT
	17491	For stripped text content output (i.e., when
	17492	@code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}). If set,
	17493	also output comments. Default false.
	17494
	17495	@item TOP_NODE_UP
	17496	Up node for the Top node; default @samp{(dir)}. This node name is
	17497	supposed to be already formatted for the output format. In HTML
	17498	can be used in attribute, so should not contain any element. Used for
	17499	HTML output only if @code{TOP_NODE_UP_URL} is set to override the url,
	17500	see @code{TOP_NODE_UP_URL} in @ref{HTML Customization Variables}.
	17501
	17502	@item TREE_TRANSFORMATIONS
	17503	The associated value is a comma separated list of transformations that
	17504	can be applied to the Texinfo tree prior to outputting the result. If
	17505	more than one is specified, the ordering is irrelevant; each is always
	17506	applied at the necessary point during processing.
	17507
	17508	The only one executed by default is
	17509	@samp{move_index_entries_after_items} for HTML and Docbook output.
	17510	Here's an example of updating the master menu in a document:
	17511
	17512	@example
	17513	makeinfo \
	17514	-c TREE_TRANSFORMATIONS=regenerate_master_menu \
	17515	-c PLAINTEXINFO=1 \
	17516	mydoc.texi \
	17517	-o /tmp/out
	17518	@end example
	17519
	17520	@noindent (Caveat: Since @code{PLAINTEXINFO} output does expand
	17521	Texinfo macros and conditionals, it's necessary to remove any such
	17522	differences before installing the updates in the original document.
	17523	This will be remedied in a future release.)
	17524
	17525	The following transformations are currently supported (many are used
	17526	in the @code{pod2texi} utility distributed with Texinfo;
	17527	@pxref{Invoking @command{pod2texi}}):
	17528
	17529	@ftable @samp
	17530	@item complete_tree_nodes_menus
	17531	Add menu entries or whole menus for nodes associated with sections of
	17532	any level, based on the sectioning tree.
	17533
	17534	@item fill_gaps_in_sectioning
	17535	Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in
	17536	sectioning. For example, an @code{@@unnumberedsec} will be inserted
	17537	if a @code{@@chapter} is followed by a @code{@@subsection}.
	17538
	17539	@item insert_nodes_for_sectioning_commands
	17540	Insert nodes for sectioning commands lacking a corresponding node.
	17541
	17542	@item move_index_entries_after_items
	17543	In @code{@@enumerate} and @code{@@itemize}, move index entries
	17544	appearing just before an @code{@@item} to just after the
	17545	@code{@@item}. Comment lines between index entries are moved too. As
	17546	mentioned, this is always done for HTML and Docbook output.
	17547
	17548	@item regenerate_master_menu
	17549	Update the Top node master menu, either replacing the (first)
	17550	@code{@@detailmenu} in the Top node menu, or creating it at the end of
	17551	the Top node menu.
	17552
	17553	@item simple_menu
	17554	Mostly the same as @code{SIMPLE_MENU}: use a simple preformatted style
	17555	for the menu. It differs from setting @code{SIMPLE_MENU} in that
	17556	@code{SIMPLE_MENU} only has an effect in HTML output.
	17557
	17558	@end ftable
	17559
	17560	@item USE_NODES
	17561	Preferentially use nodes to decide where elements are separated. If
	17562	set to false, preferentially use sectioning to decide where elements
	17563	are separated. The default is true.
	17564
	17565	@item USE_NODE_TARGET
	17566	If set, use the node associated with a section for the section target
	17567	in cross-references; default true.
	17568
	17569	@item USE_NUMERIC_ENTITY
	17570	For HTML and XML@. If set, use numeric entities instead of ASCII
	17571	characters when there is no named entity. By default, set to true for
	17572	HTML.
	17573
	17574	@item USE_UP_NODE_FOR_ELEMENT_UP
	17575	Fill in up sectioning direction with node direction when there is no
	17576	sectioning up direction. In practice this can only happen when there
	17577	is no @@top section. Not set by default.
	17578
	17579	@item USE_SETFILENAME_EXTENSION
	17580	Default is on for Info, off for other output. If set, use exactly
	17581	what @code{@@setfilename} gives for the output file name, including
	17582	the extension. You should not need to explicitly set this variable.
	17583
	17584	@item USE_TITLEPAGE_FOR_TITLE
	17585	Use the full @code{@@titlepage} as the title, not a simple title string;
	17586	default false.
	17587
	17588	@item USE_UNIDECODE
	17589	@pindex Text::Unidecode
	17590	If set to false, do not use the @code{Text::Unidecode} Perl module to
	17591	transliterate more characters; default true.
	17592
	17593	@end vtable
	17594
	17595
	17596	@node Internationalization of Document Strings
	17597	@section Internationalization of Document Strings
	17598
	17599	@cindex I18n, of document strings
	17600	@cindex Internationalization of document strings
	17601	@cindex Document strings, internationalization of
	17602	@cindex Output document strings, internationalization of
	17603	@cindex Translating strings in output documents
	17604
	17605	@vindex documentlanguage @r{customization variable}
	17606	@command{texi2any} writes fixed strings into the output document at
	17607	various places: cross-references, page footers, the help page,
	17608	alternate text for images, and so on. The string chosen depends on
	17609	the value of the @code{documentlanguage} at the time of the string
	17610	being output (@pxref{@code{@@documentlanguage}}, for the Texinfo
	17611	command interface).
	17612
	17613	@pindex libintl-perl @r{Gettext implementation}
	17614	The Gettext framework is used for those strings (@pxref{Top,,,
	17615	gettext, Gettext}). The @code{libintl-perl} package is used as the
	17616	@code{gettext} implementation; more specifically, the pure Perl
	17617	implementation is used, so Texinfo can support consistent behavior
	17618	across all platforms and installations, which would not otherwise be
	17619	possible. @code{libintl-perl} is included in the Texinfo distribution
	17620	and always installed, to ensure that it is available if needed. It is
	17621	also possible to use the system @code{gettext} (the choice can be made
	17622	at build-time).
	17623
	17624	@vindex texinfo_document @r{Gettext domain}
	17625	@cindex Perl format strings for translation
	17626	The Gettext domain @samp{texinfo_document} is used for the strings.
	17627	Translated strings are written as Texinfo, and may include
	17628	@@-commands. In translated strings, the varying parts of the string
	17629	are not usually denoted by @code{%s} and the like, but by
	17630	@samp{@{arg_name@}}. (This convention is common for @code{gettext} in
	17631	Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
	17632	Format Strings, gettext, GNU Gettext}.) For example, in the
	17633	following, @samp{@{section@}} will be replaced by the section name:
	17634
	17635	@example
	17636	see @{section@}
	17637	@end example
	17638
	17639	These Perl-style brace format strings are used for two reasons: first,
	17640	changing the order of @code{printf} arguments is only available since
	17641	Perl@tie{}5.8.0; second, and more importantly, the order of arguments
	17642	is unpredictable, since @@-command expansion may lead to different
	17643	orders depending on the output format.
	17644
	17645	The expansion of a translation string is done like this:
	17646
	17647	@enumerate
	17648	@item First, the string is translated. The locale
	17649	is @var{@@documentlanguage}@code{.}@var{@@documentencoding}.
	17650
	17651	@cindex @code{us-ascii} encoding, and translations
	17652	If the @var{@@documentlanguage} has the form @samp{ll_CC}, that is
	17653	tried first, and then just @samp{ll}. If that does not exist, and the
	17654	encoding is not @code{us-ascii}, then @code{us-ascii} is tried.
	17655
	17656	The idea is that if there is a @code{us-ascii} encoding, it means that
	17657	all the characters in the charset may be expressed as @@-commands.
	17658	For example, there is a @code{fr.us-ascii} locale that can accommodate
	17659	any encoding, since all the Latin@tie{}1 characters have associated
	17660	@@-commands. On the other hand, Japanese has only a translation
	17661	@code{ja.utf-8}, since there are no @@-commands for Japanese
	17662	characters.
	17663
	17664	@item Next, the string is expanded as Texinfo, and converted.
	17665	The arguments are substituted; for example, @samp{@{arg_name@}} is
	17666	replaced by the corresponding actual argument.
	17667
	17668	@end enumerate
	17669
	17670	In the following example, @samp{@{date@}}, @samp{@{program_homepage@}}
	17671	and @samp{@{program@}} are the arguments of the string. Since they
	17672	are used in @code{@@uref}, their order is not predictable.
	17673	@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are
	17674	substituted after the expansion:
	17675
	17676	@example
	17677	Generated on @@emph@{@{date@}@} using
	17678	@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.
	17679	@end example
	17680
	17681	This approach is admittedly a bit complicated. Its usefulness is that
	17682	it supports having translations available in different encodings for
	17683	encodings which can be covered by @@-commands, and also specifying how
	17684	the formatting for some commands is done, independently of the output
	17685	format---yet still be language-dependent. For example, the
	17686	@samp{@@pxref} translation string can be like this:
	17687
	17688	@example
	17689	see @{node_file_href@} section `@{section@}\' in @@cite@{@{book@}@}
	17690	@end example
	17691
	17692	@noindent
	17693	which allows for specifying a string independently of the output
	17694	format, while nevertheless with rich formatting it may be translated
	17695	appropriately in many languages.
	17696
	17697
	17698	@node Invoking @command{pod2texi}
	17699	@section Invoking @command{pod2texi}: Convert POD to Texinfo
	17700
	17701	@pindex pod2texi
	17702	@cindex Invoking @code{pod2texi}
	17703	@cindex POD, converting to Texinfo
	17704	@cindex Perl POD, converting to Texinfo
	17705
	17706	The @code{pod2texi} program translates Perl pod documentation file(s)
	17707	to Texinfo. There are two basic modes of operation: generating a
	17708	standalone manual from each input pod, or (if @code{--base-level=1} or
	17709	higher is given) generating Texinfo subfiles suitable for use
	17710	with @code{@@include}.
	17711
	17712	Although ordinarily this documentation in the Texinfo manual would be
	17713	the best place to look, in this case we have documented all the
	17714	options and examples in the @code{pod2texi} program itself, since it
	17715	may be useful outside of the rest of Texinfo. Thus, please see the
	17716	output of @code{pod2texi --help}, the version on the web at
	17717	@url{http://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc.
	17718
	17719	For an example of using @code{pod2texi} to make Texinfo out of the
	17720	Perl documentation itself, see
	17721	@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo,
	17722	@file{contrib/perldoc-all}} in the Texinfo source distribution (the
	17723	output is available at @url{http://www.gnu.org/software/perl/manual}).
	17724
	17725
	17726	@node @command{texi2html}
	17727	@section @command{texi2html}: Ancestor of @command{texi2any}
	17728
	17729	@pindex texi2html
	17730
	17731	@cindex Cons, Lionel
	17732	Conceptually, the @command{texi2html} program is the parent of today's
	17733	@command{texi2any} program. @command{texi2html} was developed
	17734	independently, originally by Lionel Cons in 1998; at the time,
	17735	@command{makeinfo} could not generate HTML@. Many other people
	17736	contributed to @command{texi2html} over the years.
	17737
	17738	The present @command{texi2any} uses little of the actual code of
	17739	@command{texi2html}, and has quite a different basic approach to the
	17740	implementation (namely, parsing the Texinfo document into a tree), but
	17741	still, there is a family resemblance.
	17742
	17743	By design, @command{texi2any} supports nearly all the features of
	17744	@command{texi2html} in some way. However, we did not attempt to
	17745	maintain strict compatibility, so no @command{texi2html} executable is
	17746	installed by the Texinfo package. An approximation can be run with an
	17747	invocation like this (available as @file{util/texi2html} in the
	17748	Texinfo source):
	17749
	17750	@example
	17751	texi2any --set-customization-variable TEXI2HTML=1 ...
	17752	@end example
	17753
	17754	@noindent but, to emphasize, this is @emph{not} a drop-in replacement
	17755	for the previous @command{texi2html}. Here are the biggest differences:
	17756
	17757	@itemize @bullet
	17758	@item Most blatantly, the command line options of @command{texi2html}
	17759	are now customization variables, for the most part. A table of
	17760	approximate equivalents is given below.
	17761
	17762	@item The program-level customization API is very different in
	17763	@command{texi2any}.
	17764
	17765	@item Indices cannot be split.
	17766
	17767	@item Translated strings cannot be customized; we hope to introduce
	17768	this feature in @command{texi2any} in the future.
	17769
	17770	@end itemize
	17771
	17772	Aside from the last, we do not intend to reimplement these
	17773	differences. Therefore, the route forward for authors is alter
	17774	manuals and build processes as necessary to use the new features and
	17775	methods of @command{texi2any}. The @command{texi2html} maintainers
	17776	(one of whom is the principal author of @command{texi2any}) do not
	17777	intend to make further releases.
	17778
	17779	@cindex Options of @command{texi2html}
	17780	@cindex Command-line options of @command{texi2html}
	17781	Here is the table showing @command{texi2html} options and
	17782	corresponding @command{texi2any} customization variables.
	17783	@c (@pxref{texi2any Output Customization,, @command{texi2any} Output
	17784	@c Customization}).
	17785
	17786	@multitable {@option{--ignore-preamble-text}} {@code{IGNORE_PREAMBLE_TEXT}}
	17787	@item @option{--toc-links} @tab @code{TOC_LINKS}
	17788	@item @option{--short-ext} @tab @code{SHORTEXTN}
	17789	@item @option{--prefix} @tab @code{PREFIX}
	17790	@item @option{--short-ref} @tab @code{SHORT_REF}
	17791	@item @option{--idx-sum} @tab @code{IDX_SUMMARY}
	17792	@item @option{--def-table} @tab @code{DEF_TABLE}
	17793	@item @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT}
	17794	@item @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR}
	17795	@item @option{--l2h} @tab @code{L2H}
	17796	@item @option{--l2h-l2h} @tab @code{L2H_L2H}
	17797	@item @option{--l2h-skip} @tab @code{L2H_SKIP}
	17798	@item @option{--l2h-tmp} @tab @code{L2H_TMP}
	17799	@item @option{--l2h-file} @tab @code{L2H_FILE}
	17800	@item @option{--l2h-clean} @tab @code{L2H_CLEAN}
	17801	@item @option{--use-nodes} @tab @code{USE_NODES}
	17802	@item @option{--monolithic} @tab @code{MONOLITHIC}
	17803	@item @option{--top-file} @tab @code{TOP_FILE}
	17804	@item @option{--toc-file} @tab @code{TOC_FILE}
	17805	@item @option{--frames} @tab @code{FRAMES}
	17806	@item @option{--menu} @tab @code{SHOW_MENU}
	17807	@item @option{--debug} @tab @code{DEBUG}
	17808	@item @option{--doctype} @tab @code{DOCTYPE}
	17809	@item @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE}
	17810	@item @option{--test} @tab @code{TEST}
	17811	@end multitable
	17812
	17813	@cindex @file{texi2oldapi.texi}, for @command{texi2any}
	17814	Finally, any @command{texi2html} users seeking more detailed
	17815	information can check the draft file @file{doc/texi2oldapi.texi} in
	17816	the Texinfo source repository. It consists mainly of very rough
	17817	notes, but may still be useful to some.
	17818
	17819
	17820	@node Creating and Installing Info Files
	17821	@chapter Creating and Installing Info Files
	17822
	17823	This chapter describes how to create and install Info files.
	17824	@xref{Info Files}, for general information about the file format
	17825	itself.
	17826
	17827	@menu
	17828	* Creating an Info File::
	17829	* Installing an Info File::
	17830	@end menu
	17831
	17832
	17833	@node Creating an Info File
	17834	@section Creating an Info File
	17835	@cindex Creating an Info file
	17836	@cindex Info, creating an online file
	17837	@cindex Formatting a file for Info
	17838
	17839	@code{makeinfo} is a program that converts a Texinfo file into an Info
	17840	file, HTML file, or plain text. @code{texinfo-format-region} and
	17841	@code{texinfo-format-buffer} are GNU Emacs functions that convert
	17842	Texinfo to Info.
	17843
	17844	For information on installing the Info file in the Info system,
	17845	@pxref{Installing an Info File}.
	17846
	17847	@menu
	17848	* @command{makeinfo} Advantages:: @command{makeinfo} provides better error checking.
	17849	* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
	17850	* @code{texinfo-format} commands:: Two Info formatting commands written
	17851	in Emacs Lisp are an alternative
	17852	to @code{makeinfo}.
	17853	* Batch Formatting:: How to format for Info in Emacs batch mode.
	17854	* Tag and Split Files:: How tagged and split files help Info
	17855	to run better.
	17856	@end menu
	17857
	17858
	17859	@node @command{makeinfo} Advantages
	17860	@subsection @code{makeinfo} Advantages
	17861
	17862	@anchor{makeinfo advantages}@c old name
	17863
	17864	The @code{makeinfo} utility creates an Info file from a Texinfo source
	17865	providing better error messages than either of the Emacs formatting
	17866	commands. We recommend it. The @code{makeinfo} program is
	17867	independent of Emacs. You can run @code{makeinfo} in any of three
	17868	ways: from an operating system shell, from a shell inside Emacs, or by
	17869	typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in
	17870	Texinfo mode in Emacs.
	17871
	17872	The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
	17873	commands may be useful if you cannot run @code{makeinfo}.
	17874
	17875
	17876	@node @code{makeinfo} in Emacs
	17877	@subsection Running @code{makeinfo} Within Emacs
	17878
	17879	@c anchor{makeinfo in Emacs}@c prev name
	17880	@cindex Running @code{makeinfo} in Emacs
	17881	@cindex @code{makeinfo} inside Emacs
	17882	@cindex Shell, running @code{makeinfo} in
	17883
	17884	You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
	17885	@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
	17886	Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
	17887	C-m C-b} by default.
	17888
	17889	@table @kbd
	17890	@item C-c C-m C-r
	17891	@itemx M-x makeinfo-region
	17892	Format the current region for Info.
	17893	@findex makeinfo-region
	17894
	17895	@item C-c C-m C-b
	17896	@itemx M-x makeinfo-buffer
	17897	Format the current buffer for Info.
	17898	@findex makeinfo-buffer
	17899	@end table
	17900
	17901	When you invoke @code{makeinfo-region} the output goes to a temporary
	17902	buffer. When you invoke @code{makeinfo-buffer} output goes to the
	17903	file set with @code{@@setfilename} (@pxref{@code{@@setfilename}}).
	17904
	17905	The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
	17906	run the @code{makeinfo} program in a temporary shell buffer. If
	17907	@code{makeinfo} finds any errors, Emacs displays the error messages in
	17908	the temporary buffer.
	17909
	17910	@cindex Errors, parsing
	17911	@cindex Parsing errors
	17912	@findex next-error
	17913	You can parse the error messages by typing @kbd{C-x `}
	17914	(@code{next-error}). This causes Emacs to go to and position the
	17915	cursor on the line in the Texinfo source that @code{makeinfo} thinks
	17916	caused the error. @xref{Compilation, , Running @code{make} or
	17917	Compilers Generally, emacs, The GNU Emacs Manual}, for more
	17918	information about using the @code{next-error} command.
	17919
	17920	In addition, you can kill the shell in which the @code{makeinfo}
	17921	command is running or make the shell buffer display its most recent
	17922	output.
	17923
	17924	@table @kbd
	17925	@item C-c C-m C-k
	17926	@itemx M-x makeinfo-kill-job
	17927	@findex makeinfo-kill-job
	17928	Kill the current running @code{makeinfo} job
	17929	(from @code{makeinfo-region} or @code{makeinfo-buffer}).
	17930
	17931	@item C-c C-m C-l
	17932	@itemx M-x makeinfo-recenter-output-buffer
	17933	@findex makeinfo-recenter-output-buffer
	17934	Redisplay the @code{makeinfo} shell buffer to display its most recent
	17935	output.
	17936	@end table
	17937
	17938	@noindent
	17939	(Note that the parallel commands for killing and recentering a @TeX{}
	17940	job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
	17941	Printing}.)
	17942
	17943	You can specify options for @code{makeinfo} by setting the
	17944	@code{makeinfo-options} variable with either the @kbd{M-x
	17945	customize} or the @kbd{M-x set-variable} command, or by setting the
	17946	variable in your @file{.emacs} initialization file.
	17947
	17948	For example, you could write the following in your @file{.emacs} file:
	17949
	17950	@example
	17951	@group
	17952	(setq makeinfo-options
	17953	"--paragraph-indent=0 --no-split
	17954	--fill-column=70 --verbose")
	17955	@end group
	17956	@end example
	17957
	17958	@noindent
	17959	@c Writing these three cross-references using xref results in
	17960	@c three references to the same named manual, which looks strange.
	17961	@iftex
	17962	For more information, see @ref{@command{makeinfo} Options}, as well as
	17963	``Easy Customization Interface,'' ``Examining and Setting Variables,''
	17964	and ``Init File'' in @cite{The GNU Emacs Manual}.
	17965	@end iftex
	17966	@ifnottex
	17967	For more information, see@*
	17968	@ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs Manual},@*
	17969	@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
	17970	@ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
	17971	@ref{@command{makeinfo} Options}.
	17972	@end ifnottex
	17973
	17974
	17975	@node @code{texinfo-format} commands
	17976	@subsection The @code{texinfo-format@dots{}} Commands
	17977
	17978	@c anchor{texinfo-format commands}@c prev name
	17979
	17980	In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
	17981	file with the @code{texinfo-format-region} command. This formats the
	17982	current region and displays the formatted text in a temporary buffer
	17983	called @samp{Info Region}.
	17984
	17985	Similarly, you can format a buffer with the
	17986	@code{texinfo-format-buffer} command. This command creates a new
	17987	buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
	17988	save the Info file under the name specified by the
	17989	@code{@@setfilename} line which must be near the beginning of the
	17990	Texinfo file.
	17991
	17992	@table @kbd
	17993	@item C-c C-e C-r
	17994	@itemx @code{texinfo-format-region}
	17995	@findex texinfo-format-region
	17996	Format the current region for Info.
	17997
	17998	@item C-c C-e C-b
	17999	@itemx @code{texinfo-format-buffer}
	18000	@findex texinfo-format-buffer
	18001	Format the current buffer for Info.
	18002	@end table
	18003
	18004	The @code{texinfo-format-region} and @code{texinfo-format-buffer}
	18005	commands provide you with some error checking, and other functions can
	18006	provide you with further help in finding formatting errors. These
	18007	procedures are described in an appendix; see @ref{Catching Mistakes}.
	18008	However, the @code{makeinfo} program provides better error checking
	18009	(@pxref{@code{makeinfo} in Emacs}).
	18010
	18011	A peculiarity of the @code{texinfo-format-buffer} and
	18012	@code{texinfo-format-region} commands is that they do not indent (nor
	18013	fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
	18014
	18015
	18016	@node Batch Formatting
	18017	@subsection Batch Formatting
	18018	@cindex Batch formatting for Info
	18019	@cindex Info batch formatting
	18020
	18021	You can format Texinfo files for Info using @code{batch-texinfo-format}
	18022	and Emacs batch mode. You can run Emacs in batch mode from any shell,
	18023	including a shell inside of Emacs. (@xref{Initial Options,,,
	18024	emacs, The GNU Emacs Manual}.)
	18025
	18026	Here is a shell command to format all the files that end in
	18027	@file{.texinfo} in the current directory:
	18028
	18029	@example
	18030	emacs -batch -funcall batch-texinfo-format *.texinfo
	18031	@end example
	18032
	18033	@noindent
	18034	Emacs processes all the files listed on the command line, even if an
	18035	error occurs while attempting to format some of them.
	18036
	18037	Run @code{batch-texinfo-format} only with Emacs in batch mode as shown;
	18038	it is not interactive. It kills the batch mode Emacs on completion.
	18039
	18040	@code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
	18041	and want to format several Texinfo files at once. When you use Batch
	18042	mode, you create a new Emacs process. This frees your current Emacs, so
	18043	you can continue working in it. (When you run
	18044	@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
	18045	use that Emacs for anything else until the command finishes.)
	18046
	18047	@node Tag and Split Files
	18048	@subsection Tag Files and Split Files
	18049	@cindex Making a tag table automatically
	18050	@cindex Tag table, making automatically
	18051
	18052	If a Texinfo file has more than 30,000 bytes,
	18053	@code{texinfo-format-buffer} automatically creates a tag table
	18054	for its Info file; @code{makeinfo} always creates a tag table. With
	18055	a @dfn{tag table}, Info can jump to new nodes more quickly than it can
	18056	otherwise.
	18057
	18058	@cindex Indirect subfiles
	18059	In addition, if the Texinfo file contains more than about 300,000
	18060	bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
	18061	large Info file into shorter @dfn{indirect} subfiles of about 300,000
	18062	bytes each. Big files are split into smaller files so that Emacs does
	18063	not need to make a large buffer to hold the whole of a large Info
	18064	file; instead, Emacs allocates just enough memory for the small, split-off
	18065	file that is needed at the time. This way, Emacs avoids wasting
	18066	memory when you run Info. (Before splitting was implemented, Info
	18067	files were always kept short and @dfn{include files} were designed as
	18068	a way to create a single, large printed manual out of the smaller Info
	18069	files. @xref{Include Files}, for more information. Include files are
	18070	still used for very large documents, such as @cite{The Emacs Lisp
	18071	Reference Manual}, in which each chapter is a separate file.)
	18072
	18073	When a file is split, Info itself makes use of a shortened version of
	18074	the original file that contains just the tag table and references to
	18075	the files that were split off. The split-off files are called
	18076	@dfn{indirect} files.
	18077
	18078	The split-off files have names that are created by appending @w{@samp{-1}},
	18079	@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
	18080	@code{@@setfilename} command. The shortened version of the original file
	18081	continues to have the name specified by @code{@@setfilename}.
	18082
	18083	At one stage in writing this document, for example, the Info file was saved
	18084	as the file @file{test-texinfo} and that file looked like this:
	18085
	18086	@example
	18087	@group
	18088	Info file: test-texinfo, --Text--
	18089	produced by texinfo-format-buffer
	18090	from file: new-texinfo-manual.texinfo
	18091
	18092	^_
	18093	Indirect:
	18094	test-texinfo-1: 102
	18095	test-texinfo-2: 50422
	18096	@end group
	18097	@group
	18098	test-texinfo-3: 101300
	18099	^_^L
	18100	Tag table:
	18101	(Indirect)
	18102	Node: overview^?104
	18103	Node: info file^?1271
	18104	@end group
	18105	@group
	18106	Node: printed manual^?4853
	18107	Node: conventions^?6855
	18108	@dots{}
	18109	@end group
	18110	@end example
	18111
	18112	@noindent
	18113	(But @file{test-texinfo} had far more nodes than are shown here.) Each of
	18114	the split-off, indirect files, @file{test-texinfo-1},
	18115	@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
	18116	after the line that says @samp{Indirect:}. The tag table is listed after
	18117	the line that says @samp{Tag table:}.
	18118
	18119	In the list of indirect files, the number following the file name
	18120	records the cumulative number of bytes in the preceding indirect
	18121	files, not counting the file list itself, the tag table, or any
	18122	permissions text in the first file. In the tag table, the number
	18123	following the node name records the location of the beginning of the
	18124	node, in bytes from the beginning of the (unsplit) output.
	18125
	18126	If you are using @code{texinfo-format-buffer} to create Info files,
	18127	you may want to run the @code{Info-validate} command. (The
	18128	@code{makeinfo} command does such a good job on its own, you do not
	18129	need @code{Info-validate}.) However, you cannot run the @kbd{M-x
	18130	Info-validate} node-checking command on indirect files. For
	18131	information on how to prevent files from being split and how to
	18132	validate the structure of the nodes, see @ref{Using
	18133	@code{Info-validate}}.
	18134
	18135
	18136	@node Installing an Info File
	18137	@section Installing an Info File
	18138	@cindex Installing an Info file
	18139	@cindex Info file installation
	18140	@cindex @file{dir} directory for Info installation
	18141
	18142	Info files are usually kept in the @file{info} directory. You can
	18143	read Info files using the standalone Info program or the Info reader
	18144	built into Emacs. (@xref{Top,,, info, Info}, for an introduction to
	18145	Info.)
	18146
	18147	@menu
	18148	* Directory File:: The top level menu for all Info files.
	18149	* New Info File:: Listing a new Info file.
	18150	* Other Info Directories:: How to specify Info files that are
	18151	located in other directories.
	18152	* Installing Dir Entries:: How to specify what menu entry to add
	18153	to the Info directory.
	18154	* Invoking @command{install-info}:: @code{install-info} options.
	18155	@end menu
	18156
	18157
	18158	@node Directory File
	18159	@subsection The Directory File @file{dir}
	18160
	18161	For Info to work, the @file{info} directory must contain a file that
	18162	serves as a top level directory for the Info system. By convention,
	18163	this file is called @file{dir}. (You can find the location of this file
	18164	within Emacs by typing @kbd{C-h i} to enter Info and then typing
	18165	@kbd{C-x C-f} to see the pathname to the @file{info} directory.)
	18166
	18167	The @file{dir} file is itself an Info file. It contains the top level
	18168	menu for all the Info files in the system. The menu looks like
	18169	this:
	18170
	18171	@example
	18172	@group
	18173	* Menu:
	18174	* Info: (info). Documentation browsing system.
	18175	* Emacs: (emacs). The extensible, self-documenting
	18176	text editor.
	18177	* Texinfo: (texinfo). With one source file, make
	18178	either a printed manual using
	18179	@@TeX@{@} or an Info file.
	18180	@dots{}
	18181	@end group
	18182	@end example
	18183
	18184	Each of these menu entries points to the `Top' node of the Info file
	18185	that is named in parentheses. (The menu entry does not need to
	18186	specify the `Top' node, since Info goes to the `Top' node if no node
	18187	name is mentioned. @xref{Other Info Files, , Nodes in Other Info
	18188	Files}.)
	18189
	18190	Thus, the @samp{Info} entry points to the `Top' node of the
	18191	@file{info} file and the @samp{Emacs} entry points to the `Top' node
	18192	of the @file{emacs} file.
	18193
	18194	In each of the Info files, the `Up' pointer of the `Top' node refers
	18195	back to the @code{dir} file. For example, the line for the `Top'
	18196	node of the Emacs manual looks like this in Info:
	18197
	18198	@example
	18199	File: emacs Node: Top, Up: (DIR), Next: Distrib
	18200	@end example
	18201
	18202	@noindent
	18203	In this case, the @file{dir} file name is written in uppercase
	18204	letters---it can be written in either upper- or lowercase. This is not
	18205	true in general, it is a special case for @file{dir}.
	18206
	18207
	18208	@node New Info File
	18209	@subsection Listing a New Info File
	18210	@cindex Adding a new Info file
	18211	@cindex Listing a new Info file
	18212	@cindex New Info file, listing it in @file{dir} file
	18213	@cindex Info file, listing a new
	18214	@cindex @file{dir} file listing
	18215
	18216	To add a new Info file to your system, you must write a menu entry to
	18217	add to the menu in the @file{dir} file in the @file{info} directory.
	18218	For example, if you were adding documentation for GDB, you would write
	18219	the following new entry:
	18220
	18221	@example
	18222	* GDB: (gdb). The source-level C debugger.
	18223	@end example
	18224
	18225	@noindent
	18226	The first part of the menu entry is the menu entry name, followed by a
	18227	colon. The second part is the name of the Info file, in parentheses,
	18228	followed by a period. The third part is the description.
	18229
	18230	The name of an Info file often has a @file{.info} extension. Thus, the
	18231	Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
	18232	The Info reader programs automatically try the file name both with and
	18233	without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
	18234	try the @file{.inf} extension as well.}; so it is better to avoid
	18235	clutter and not to write @samp{.info} explicitly in the menu entry. For
	18236	example, the GDB menu entry should use just @samp{gdb} for the file
	18237	name, not @samp{gdb.info}.
	18238
	18239
	18240	@node Other Info Directories
	18241	@subsection Info Files in Other Directories
	18242	@cindex Installing Info in another directory
	18243	@cindex Info installed in another directory
	18244	@cindex Another Info directory
	18245	@cindex @file{dir} files and Info directories
	18246
	18247	If an Info file is not in the @file{info} directory, there are three
	18248	ways to specify its location:
	18249
	18250	@enumerate
	18251	@item
	18252	Write the pathname in the @file{dir} file as the second part of the menu.
	18253
	18254	@item
	18255	Specify the Info directory name in the @code{INFOPATH} environment
	18256	variable in your @file{.profile} or @file{.cshrc} initialization file.
	18257	(Only you and others who set this environment variable will be able to
	18258	find Info files whose location is specified this way.)
	18259
	18260	@item
	18261	If you are using Emacs, list the name of the file in a second @file{dir}
	18262	file, in its directory; and then add the name of that directory to the
	18263	@code{Info-directory-list} variable in your personal or site
	18264	initialization file.
	18265
	18266	This variable tells Emacs where to look for @file{dir} files (the files
	18267	must be named @file{dir}). Emacs merges the files named @file{dir} from
	18268	each of the listed directories. (In Emacs version 18, you can set the
	18269	@code{Info-directory} variable to the name of only one
	18270	directory.)
	18271	@end enumerate
	18272
	18273	For example, to reach a test file in the @file{/home/bob/info}
	18274	directory, you could add an entry like this to the menu in the
	18275	standard @file{dir} file:
	18276
	18277	@example
	18278	* Test: (/home/bob/info/info-test). Bob's own test file.
	18279	@end example
	18280
	18281	@noindent
	18282	In this case, the absolute file name of the @file{info-test} file is
	18283	written as the second part of the menu entry.
	18284
	18285	@vindex INFOPATH
	18286	@cindex Environment variable @code{INFOPATH}
	18287	If you don't want to edit the system @file{dir} file, you can tell
	18288	Info where to look by setting the @code{INFOPATH} environment variable
	18289	in your shell startup file. This works with both the Emacs and
	18290	standalone Info readers.
	18291
	18292	Specifically, if you use a Bourne-compatible shell such as @code{sh}
	18293	or @code{bash} for your shell command interpreter, you set the
	18294	@code{INFOPATH} environment variable in the @file{.profile}
	18295	initialization file; but if you use @code{csh} or @code{tcsh}, you set
	18296	the variable in the @file{.cshrc} initialization file. On
	18297	MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in your
	18298	@file{autoexec.bat} file or in the registry. Each type of shell uses
	18299	a different syntax.
	18300
	18301	@itemize @bullet
	18302	@item
	18303	In a @file{.cshrc} file, you could set the @code{INFOPATH}
	18304	variable as follows:
	18305
	18306	@smallexample
	18307	setenv INFOPATH .:~/info:/usr/local/emacs/info
	18308	@end smallexample
	18309
	18310	@item
	18311	In a @file{.profile} file, you would achieve the same effect by writing:
	18312
	18313	@smallexample
	18314	INFOPATH=.:$HOME/info:/usr/local/emacs/info
	18315	export INFOPATH
	18316	@end smallexample
	18317
	18318	@item
	18319	@pindex autoexec.bat
	18320	In a @file{autoexec.bat} file, you write this command (note the
	18321	use of @samp{;} as the directory separator, and a different syntax for
	18322	using values of other environment variables):
	18323
	18324	@smallexample
	18325	set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
	18326	@end smallexample
	18327	@end itemize
	18328
	18329	@noindent
	18330	The @samp{.} indicates the current directory as usual. Emacs uses the
	18331	@code{INFOPATH} environment variable to initialize the value of Emacs's
	18332	own @code{Info-directory-list} variable. The standalone Info reader
	18333	merges any files named @file{dir} in any directory listed in the
	18334	@env{INFOPATH} variable into a single menu presented to you in the node
	18335	called @samp{(dir)Top}.
	18336
	18337	@cindex Colon, last in @env{INFOPATH}
	18338	However you set @env{INFOPATH}, if its last character is a colon (on
	18339	MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced
	18340	by the default (compiled-in) path. This gives you a way to augment
	18341	the default path with new directories without having to list all the
	18342	standard places. For example (using @code{sh} syntax):
	18343
	18344	@example
	18345	INFOPATH=/home/bob/info:
	18346	export INFOPATH
	18347	@end example
	18348
	18349	@noindent
	18350	will search @file{/home/bob/info} first, then the standard directories.
	18351	Leading or doubled colons are not treated specially.
	18352
	18353	@cindex @file{dir} file, creating your own
	18354	When you create your own @file{dir} file for use with
	18355	@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
	18356	copying an existing @file{dir} file and replace all the text after the
	18357	@samp{* Menu:} with your desired entries. That way, the punctuation
	18358	and special @kbd{CTRL-_} characters that Info needs will be present.
	18359
	18360	As one final alternative, which works only with Emacs Info, you can
	18361	change the @code{Info-directory-list} variable. For example:
	18362
	18363	@example
	18364	(add-hook 'Info-mode-hook '(lambda ()
	18365	(add-to-list 'Info-directory-list
	18366	(expand-file-name "~/info"))))
	18367	@end example
	18368
	18369
	18370	@node Installing Dir Entries
	18371	@subsection Installing Info Directory Files
	18372
	18373	When you install an Info file onto your system, you can use the program
	18374	@code{install-info} to update the Info directory file @file{dir}.
	18375	Normally the makefile for the package runs @code{install-info}, just
	18376	after copying the Info file into its proper installed location.
	18377
	18378	@findex dircategory
	18379	@findex direntry
	18380	In order for the Info file to work with @code{install-info}, you include
	18381	the commands @code{@@dircategory} and
	18382	@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
	18383	file. Use @code{@@direntry} to specify the menu entries to add to the
	18384	Info directory file, and use @code{@@dircategory} to specify which part
	18385	of the Info directory to put it in. Here is how these commands are used
	18386	in this manual:
	18387
	18388	@smallexample
	18389	@@dircategory Texinfo documentation system
	18390	@@direntry
	18391	* Texinfo: (texinfo). The GNU documentation format.
	18392	* install-info: (texinfo)Invoking install-info. @dots{}
	18393	@dots{}
	18394	@@end direntry
	18395	@end smallexample
	18396
	18397	Here's what this produces in the Info file:
	18398
	18399	@smallexample
	18400	INFO-DIR-SECTION Texinfo documentation system
	18401	START-INFO-DIR-ENTRY
	18402	* Texinfo: (texinfo). The GNU documentation format.
	18403	* install-info: (texinfo)Invoking install-info. @dots{}
	18404	@dots{}
	18405	END-INFO-DIR-ENTRY
	18406	@end smallexample
	18407
	18408	@noindent
	18409	The @code{install-info} program sees these lines in the Info file, and
	18410	that is how it knows what to do.
	18411
	18412	Always use the @code{@@direntry} and @code{@@dircategory} commands near
	18413	the beginning of the Texinfo input, before the first @code{@@node}
	18414	command. If you use them later on in the input, @code{install-info}
	18415	will not notice them.
	18416
	18417	@code{install-info} will automatically reformat the description of the
	18418	menu entries it is adding. As a matter of convention, the description
	18419	of the main entry (above, @samp{The GNU documentation format}) should
	18420	start at column 32, starting at zero (as in
	18421	@code{what-cursor-position} in Emacs). This will make it align with
	18422	most others. Description for individual utilities best start in
	18423	column 48, where possible. For more information about formatting see
	18424	the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
	18425	@ref{Invoking @command{install-info}}.
	18426
	18427	If you use @code{@@dircategory} more than once in the Texinfo source,
	18428	each usage specifies the `current' category; any subsequent
	18429	@code{@@direntry} commands will add to that category.
	18430
	18431	@cindex Free Software Directory
	18432	@cindex Dir categories, choosing
	18433	@cindex Categories, choosing
	18434	When choosing a category name for the @code{@@dircategory} command, we
	18435	recommend consulting the @uref{http://www.gnu.org/directory,
	18436	Free Software Directory}. If your program is not listed there,
	18437	or listed incorrectly or incompletely, please report the situation to
	18438	the directory maintainers (@url{http://directory.fsf.org}) so that the
	18439	category names can be kept in sync.
	18440
	18441	Here are a few examples (see the @file{util/dir-example} file in the
	18442	Texinfo distribution for large sample @code{dir} file):
	18443
	18444	@display
	18445	Emacs
	18446	Localization
	18447	Printing
	18448	Software development
	18449	Software libraries
	18450	Text creation and manipulation
	18451	@end display
	18452
	18453	@cindex Invoking nodes, including in dir file
	18454	Each `Invoking' node for every program installed should have a
	18455	corresponding @code{@@direntry}. This lets users easily find the
	18456	documentation for the different programs they can run, as with the
	18457	traditional @command{man} system.
	18458
	18459
	18460	@node Invoking @command{install-info}
	18461	@subsection Invoking @command{install-info}
	18462
	18463	@pindex install-info
	18464
	18465	@code{install-info} inserts menu entries from an Info file into the
	18466	top-level @file{dir} file in the Info system (see the previous sections
	18467	for an explanation of how the @file{dir} file works). @code{install-info}
	18468	also removes menu entries from the @file{dir} file. It's most often
	18469	run as part of software installation, or when constructing a @file{dir} file
	18470	for all manuals on a system. Synopsis:
	18471
	18472	@example
	18473	install-info [@var{option}@dots{}] [@var{info-file} [@var{dir-file}]]
	18474	@end example
	18475
	18476	If @var{info-file} or @var{dir-file} are not specified, the options
	18477	(described below) that define them must be. There are no compile-time
	18478	defaults, and standard input is never used. @code{install-info} can
	18479	read only one Info file and write only one @file{dir} file per invocation.
	18480
	18481	@cindex @file{dir}, created by @code{install-info}
	18482	If @var{dir-file} (however specified) does not exist,
	18483	@code{install-info} creates it if possible (with no entries).
	18484
	18485	@cindex Compressed dir files, reading
	18486	@cindex XZ-compressed dir files, reading
	18487	@cindex Bzipped dir files, reading
	18488	@cindex Lzip-compressed dir files, reading
	18489	@cindex LZMA-compressed dir files, reading
	18490	@cindex Dir files, compressed
	18491	If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip,
	18492	Gzip}), @code{install-info} automatically uncompresses it for reading.
	18493	And if @var{dir-file} is compressed, @code{install-info} also
	18494	automatically leaves it compressed after writing any changes. If
	18495	@var{dir-file} itself does not exist, @code{install-info} tries to
	18496	open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz},
	18497	@file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and
	18498	@file{@var{dir-file}.lzma}, in that order.
	18499
	18500	Options:
	18501
	18502	@table @code
	18503	@item --add-once
	18504	@opindex --add-once@r{, for @command{install-info}}
	18505	Specifies that the entry or entries will only be put into a single section.
	18506
	18507	@item --align=@var{column}
	18508	@opindex --align=@var{column}@r{, for @command{install-info}}
	18509	Specifies the column that the second and subsequent lines of menu entry's
	18510	description will be formatted to begin at. The default for this option is
	18511	@samp{35}. It is used in conjunction with the @samp{--max-width} option.
	18512	@var{column} starts counting at 1.
	18513
	18514	@item --append-new-sections
	18515	@opindex --append-new-sections@r{, for @command{install-info}}
	18516	Instead of alphabetizing new sections, place them at the end of the DIR file.
	18517
	18518	@item --calign=@var{column}
	18519	@opindex --calign=@var{column}@r{, for @command{install-info}}
	18520	Specifies the column that the first line of menu entry's description will
	18521	be formatted to begin at. The default for this option is @samp{33}. It is
	18522	used in conjunction with the @samp{--max-width} option.
	18523	When the name of the menu entry exceeds this column, entry's description
	18524	will start on the following line.
	18525	@var{column} starts counting at 1.
	18526
	18527	@item --debug
	18528	@opindex --debug@r{, for @command{install-info}}
	18529	Report what is being done.
	18530
	18531	@item --delete
	18532	@opindex --delete@r{, for @command{install-info}}
	18533	Delete the entries in @var{info-file} from @var{dir-file}. The file
	18534	name in the entry in @var{dir-file} must be @var{info-file} (except for
	18535	an optional @samp{.info} in either one). Don't insert any new entries.
	18536	Any empty sections that result from the removal are also removed.
	18537
	18538	@item --description=@var{text}
	18539	@opindex --description=@var{text}@r{, for @command{install-info}}
	18540	Specify the explanatory portion of the menu entry. If you don't specify
	18541	a description (either via @samp{--entry}, @samp{--item} or this option),
	18542	the description is taken from the Info file itself.
	18543
	18544	@item --dir-file=@var{name}
	18545	@opindex --dir-file=@var{name}@r{, for @command{install-info}}
	18546	Specify file name of the Info directory file. This is equivalent to
	18547	using the @var{dir-file} argument.
	18548
	18549	@item --dry-run
	18550	@opindex --dry-run@r{, for @command{install-info}}
	18551	Same as @samp{--test}.
	18552
	18553	@item --entry=@var{text}
	18554	@opindex --entry=@var{text}@r{, for @command{install-info}}
	18555	Insert @var{text} as an Info directory entry; @var{text} should have the
	18556	form of an Info menu item line plus zero or more extra lines starting
	18557	with whitespace. If you specify more than one entry, they are all
	18558	added. If you don't specify any entries, they are determined from
	18559	information in the Info file itself.
	18560
	18561	@item --help
	18562	@opindex --help@r{, for @command{texindex}}
	18563	Display a usage message with basic usage and all available options,
	18564	then exit successfully.
	18565
	18566	@item --info-file=@var{file}
	18567	@opindex --info-file=@var{file}@r{, for @command{install-info}}
	18568	Specify Info file to install in the directory. This is
	18569	equivalent to using the @var{info-file} argument.
	18570
	18571	@item --info-dir=@var{dir}
	18572	@opindex --info-dir=@var{dir}@r{, for @command{install-info}}
	18573	Specify the directory where the directory file @file{dir} resides.
	18574	Equivalent to @samp{--dir-file=@var{dir}/dir}.
	18575
	18576	@item --infodir=@var{dir}
	18577	@opindex --infodir=@var{dir}@r{, for @command{install-info}}
	18578	Same as @samp{--info-dir}.
	18579
	18580	@item --item=@var{text}
	18581	@opindex --item=@var{text}@r{, for @command{install-info}}
	18582	Same as @samp{--entry=@var{text}}. An Info directory entry is actually
	18583	a menu item.
	18584
	18585	@item --keep-old
	18586	@opindex --keep-old@r{, for @command{install-info}}
	18587	Do not replace pre-existing menu entries. When @samp{--remove} is specified,
	18588	this option means that empty sections are not removed.
	18589
	18590	@item --max-width=@var{column}
	18591	@opindex --max-width=@var{column}@r{, for @command{install-info}}
	18592	Specifies the column that the menu entry's description will be word-wrapped
	18593	at. @var{column} starts counting at 1.
	18594
	18595	@item --maxwidth=@var{column}
	18596	@opindex --maxwidth=@var{column}@r{, for @command{install-info}}
	18597	Same as @samp{--max-width}.
	18598
	18599	@item --menuentry=@var{text}
	18600	@opindex --menuentry=@var{text}@r{, for @command{install-info}}
	18601	Same as @samp{--name}.
	18602
	18603	@item --name=@var{text}
	18604	@opindex --name=@var{text}@r{, for @command{install-info}}
	18605	Specify the name portion of the menu entry. If the @var{text} does
	18606	not start with an asterisk @samp{*}, it is presumed to be the text
	18607	after the @samp{*} and before the parentheses that specify the Info
	18608	file. Otherwise @var{text} is taken verbatim, and is taken as
	18609	defining the text up to and including the first period (a space is
	18610	appended if necessary). If you don't specify the name (either via
	18611	@samp{--entry}, @samp{--item} or this option), it is taken from the
	18612	Info file itself. If the Info does not contain the name, the basename
	18613	of the Info file is used.
	18614
	18615	@item --no-indent
	18616	@opindex --no-indent@r{, for @command{install-info}}
	18617	Suppress formatting of new entries into the @file{dir} file.
	18618
	18619	@item --quiet
	18620	@itemx --silent
	18621	@opindex --quiet@r{, for @command{install-info}}
	18622	@opindex --silent@r{, for @command{install-info}}
	18623	Suppress warnings, etc., for silent operation.
	18624
	18625	@item --remove
	18626	@opindex --remove@r{, for @command{install-info}}
	18627	Same as @samp{--delete}.
	18628
	18629	@item --remove-exactly
	18630	@opindex --remove-exactly@r{, for @command{install-info}}
	18631	Also like @samp{--delete}, but only entries if the Info file name
	18632	matches exactly; @code{.info} and/or @code{.gz} suffixes are
	18633	@emph{not} ignored.
	18634
	18635	@item --section=@var{sec}
	18636	@opindex --section=@var{sec}@r{, for @command{install-info}}
	18637	Put this file's entries in section @var{sec} of the directory. If you
	18638	specify more than one section, all the entries are added in each of the
	18639	sections. If you don't specify any sections, they are determined from
	18640	information in the Info file itself. If the Info file doesn't specify
	18641	a section, the menu entries are put into the Miscellaneous section.
	18642
	18643	@item --section @var{regex} @var{sec}
	18644	@opindex --section @var{regex} @var{sec}@r{, for @command{install-info}}
	18645	Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
	18646
	18647	@code{install-info} tries to detect when this alternate syntax is used,
	18648	but does not always guess correctly. Here is the heuristic that
	18649	@code{install-info} uses:
	18650	@enumerate
	18651	@item
	18652	If the second argument to @code{--section} starts with a hyphen, the
	18653	original syntax is presumed.
	18654
	18655	@item
	18656	If the second argument to @code{--section} is a file that can be
	18657	opened, the original syntax is presumed.
	18658
	18659	@item
	18660	Otherwise the alternate syntax is used.
	18661	@end enumerate
	18662
	18663	When the heuristic fails because your section title starts with a
	18664	hyphen, or it happens to be a filename that can be opened, the syntax
	18665	should be changed to @samp{--regex=@var{regex} --section=@var{sec}
	18666	--add-once}.
	18667
	18668	@item --regex=@var{regex}
	18669	@opindex --regex=@var{regex}@r{, for @command{install-info}}
	18670	Put this file's entries into any section that matches @var{regex}. If
	18671	more than one section matches, all of the entries are added in each of the
	18672	sections. Specify @var{regex} using basic regular expression syntax, more
	18673	or less as used with @command{grep}, for example.
	18674
	18675	@item --test
	18676	@opindex --test@r{, for @command{install-info}}
	18677	Suppress updating of the directory file.
	18678
	18679	@item --version
	18680	@opindex --version@r{, for @command{install-info}}
	18681	@cindex Version number, for install-info
	18682	Display version information and exit successfully.
	18683
	18684	@end table
	18685
	18686
	18687	@node Generating HTML
	18688	@chapter Generating HTML
	18689
	18690	@cindex Generating HTML
	18691	@cindex Outputting HTML
	18692
	18693	@command{makeinfo} generates Info output by default, but given the
	18694	@option{--html} option, it will generate HTML, for web browsers and
	18695	other programs. This chapter gives some details on such HTML output.
	18696
	18697	@command{makeinfo} has many user-definable customization variables
	18698	with which you can influence the HTML output. @xref{Customization
	18699	Variables}.
	18700
	18701	@command{makeinfo} can also produce output in XML and Docbook formats,
	18702	but we do not as yet describe these in detail. @xref{Output Formats},
	18703	for a brief overview of all the output formats.
	18704
	18705	@menu
	18706	* HTML Translation:: Details of the HTML output.
	18707	* HTML Splitting:: How HTML output is split.
	18708	* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
	18709	* HTML Xref:: Cross-references in HTML output.
	18710	@end menu
	18711
	18712
	18713	@node HTML Translation
	18714	@section HTML Translation
	18715
	18716	@cindex HTML translation
	18717
	18718	@cindex HTML output, browser compatibility of
	18719	First, the HTML generated by @command{makeinfo} is standard
	18720	HTML@tie{}4. When first written, it also tried to be compatible with
	18721	earlier standards (e.g., HTML@tie{}2.0, RFC-1866).
	18722
	18723	Please report output from an
	18724	error-free run of @code{makeinfo} which has practical browser
	18725	portability problems as a bug (@pxref{Reporting Bugs}).
	18726
	18727	@pindex html32.pm
	18728	Some known exceptions to HTML@tie{}3.2 (using
	18729	@samp{--init-file=html32.pm} produced strict HTML@tie{}3.2 output, but
	18730	this has not been tested lately;
	18731	@pxref{Invoking @command{texi2any}}):
	18732
	18733	@enumerate
	18734	@item
	18735	HTML@tie{}3.2 tables are generated for the @code{@@multitable} command
	18736	(@pxref{Multi-column Tables}), but they should degrade reasonably in
	18737	browsers without table support.
	18738
	18739	@item
	18740	The HTML@tie{}4 @samp{id} attribute is used.
	18741
	18742	@item
	18743	The HTML@tie{}4 @samp{lang} attribute on the @samp{<html>} attribute
	18744	is used.
	18745
	18746	@item
	18747	Entities that are not in the HTML@tie{}3.2 standard are also used.
	18748
	18749	@item
	18750	CSS is used (@pxref{HTML CSS}).
	18751
	18752	@item
	18753	Some HTML@tie{}4 elements are used: @code{span}, @code{thead},
	18754	@code{abbr}, @code{acronym}.
	18755
	18756	@end enumerate
	18757
	18758	To achieve maximum portability and accessibility among browsers (both
	18759	graphical and text-based), systems, and users, the HTML output is
	18760	intentionally quite plain and generic. It has always been our goal
	18761	for users to be able to customize the output to their wishes via CSS
	18762	(@pxref{HTML CSS}) or other means (@pxref{Customization Variables}).
	18763	If you cannot accomplish a reasonable customization, feel free to
	18764	report that.
	18765
	18766	However, we do not wish to depart from our basic goal of widest
	18767	readability for the core output. For example, using fancy CSS may
	18768	make it possible for the HTML output to more closely resemble the
	18769	@TeX{} output in some details, but this result is not even close to
	18770	being worth the ensuing difficulties.
	18771
	18772	It is also intentionally not our goal, and not even possible, to pass
	18773	through every conceivable validation test without any diagnostics.
	18774	Different validation tests have different goals, often about pedantic
	18775	enforcement of some standard or another. Our overriding goal is to
	18776	help users, not blindly comply with standards.
	18777
	18778	To repeat what was said at the top: please report output from an
	18779	error-free run of @code{makeinfo} which has @emph{practical} browser
	18780	portability problems as a bug (@pxref{Reporting Bugs}).
	18781
	18782	A few other general points about the HTML output follow.
	18783
	18784	@cindex Navigation bar, in HTML output
	18785	@strong{Navigation bar:} By default, a navigation bar is inserted at the
	18786	start of each node, analogous to Info output. If the
	18787	@samp{--no-headers} option is used, the navigation bar is only
	18788	inserted at the beginning of split files. Header @code{<link>}
	18789	elements in split output can support Info-like navigation with
	18790	browsers like Lynx and @w{Emacs W3} which implement this HTML@tie{}1.0
	18791	feature.
	18792
	18793	@cindex Footnote styles, in HTML
	18794	@strong{Footnotes:} for HTML, when the footnote style is @samp{end},
	18795	or if the output is not split, footnotes are put at the end of the
	18796	output. If the footnote style is set to @samp{separate}, and the
	18797	output is split, they are placed in a separate file. @xref{Footnote
	18798	Styles}.
	18799
	18800	@cindex Escaping to HTML
	18801	@cindex Raw HTML
	18802	@strong{Raw HTML}: @command{makeinfo} will include segments of Texinfo
	18803	source between @code{@@ifhtml} and @code{@@end ifhtml} in the HTML
	18804	output (but not any of the other conditionals, by default). Source
	18805	between @code{@@html} and @code{@@end html} is passed without change
	18806	to the output (i.e., suppressing the normal escaping of input
	18807	@samp{<}, @samp{>} and @samp{&} characters which have special
	18808	significance in HTML)@. @xref{Conditional Commands}.
	18809
	18810
	18811	@node HTML Splitting
	18812	@section HTML Splitting
	18813	@cindex Split HTML output
	18814	@cindex HTML output, split
	18815
	18816	When splitting output at nodes (which is the default),
	18817	@command{makeinfo} writes HTML output into (basically) one output file
	18818	per Texinfo source @code{@@node}.
	18819
	18820	Each output file name is the node name with spaces replaced by
	18821	@samp{-}'s and special characters changed to @samp{_} followed by
	18822	their code point in hex (@pxref{HTML Xref}). This is to make it
	18823	portable and easy to use as a filename. In the unusual case of two
	18824	different nodes having the same name after this treatment, they are
	18825	written consecutively to the same file, with HTML anchors so each can
	18826	be referred to independently.
	18827
	18828	If @command{makeinfo} is run on a system which does not distinguish
	18829	case in file names, nodes which are the same except for case (e.g.,
	18830	@samp{index} and @samp{Index}) will also be folded into the same
	18831	output file with anchors. You can also pretend to be on a case
	18832	insensitive filesystem by setting the customization variable
	18833	@code{CASE_INSENSITIVE_FILENAMES}.
	18834
	18835	It is also possible to split at chapters or sections with
	18836	@option{--split} (@pxref{Invoking @command{texi2any}}). In that case,
	18837	the file names are constructed after the name of the node associated
	18838	with the relevant sectioning command. Also, unless
	18839	@option{--no-node-files} is specified, a redirection file is output
	18840	for every node in order to more reliably support cross-references to
	18841	that manual (@pxref{HTML Xref}).
	18842
	18843	When splitting, the HTML output files are written into a subdirectory,
	18844	with the name chosen as follows:
	18845
	18846	@enumerate
	18847	@item
	18848	@command{makeinfo} first tries the subdirectory with the base name
	18849	from @code{@@setfilename} (that is, any extension is removed). For
	18850	example, HTML output for @code{@@setfilename gcc.info} would be
	18851	written into a subdirectory named @samp{gcc/}.
	18852
	18853	@item
	18854	If that directory cannot be created for any reason, then
	18855	@command{makeinfo} tries appending @samp{.html} to the directory name.
	18856	For example, output for @code{@@setfilename texinfo} would be written
	18857	to @samp{texinfo.html/}.
	18858
	18859	@item
	18860	If the @samp{@var{name}.html} directory can't be created either,
	18861	@code{makeinfo} gives up.
	18862
	18863	@end enumerate
	18864
	18865	@noindent In any case, the top-level output file within the directory
	18866	is always named @samp{index.html}.
	18867
	18868	Monolithic output (@code{--no-split}) is named according to
	18869	@code{@@setfilename} (with any @samp{.info} extension is replaced with
	18870	@samp{.html}), @code{--output} (the argument is used literally), or
	18871	based on the input file name as a last resort
	18872	(@pxref{@code{@@setfilename}}).
	18873
	18874
	18875	@node HTML CSS
	18876	@section HTML CSS
	18877	@cindex HTML, and CSS
	18878	@cindex CSS, and HTML output
	18879	@cindex Cascading Style Sheets, and HTML output
	18880
	18881	Cascading Style Sheets (CSS for short) is an Internet standard for
	18882	influencing the display of HTML documents: see
	18883	@uref{http://www.w3.org/Style/CSS/}.
	18884
	18885	By default, @command{makeinfo} includes a few simple CSS commands to
	18886	better implement the appearance of some Texinfo environments. Here
	18887	are two of them, as an example:
	18888
	18889	@example
	18890	pre.display @{ font-family:inherit @}
	18891	pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
	18892	@end example
	18893
	18894	A full explanation of CSS is (far) beyond this manual; please see the
	18895	reference above. In brief, however, the above tells the web browser
	18896	to use a `smaller' font size for @code{@@smalldisplay} text, and to
	18897	use the same font as the main document for both @code{@@smalldisplay}
	18898	and @code{@@display}. By default, the HTML @samp{<pre>} command uses
	18899	a monospaced font.
	18900
	18901	You can influence the CSS in the HTML output with two
	18902	@command{makeinfo} options: @option{--css-include=@var{file}} and
	18903	@option{--css-ref=@var{url}}.
	18904
	18905	@pindex texinfo-bright-colors.css
	18906	@cindex Visualizing Texinfo CSS
	18907	The option @option{--css-ref=@var{url}} adds to each output HTML file
	18908	a @samp{<link>} tag referencing a CSS at the given @var{url}. This
	18909	allows using external style sheets. You may find the file
	18910	@file{texi2html/examples/texinfo-bright-colors.css} useful for
	18911	visualizing the CSS elements in Texinfo output.
	18912
	18913	The option @option{--css-include=@var{file}} includes the contents
	18914	@var{file} in the HTML output, as you might expect. However, the
	18915	details are somewhat tricky, as described in the following, to provide
	18916	maximum flexibility.
	18917
	18918	@cindex @samp{@@import} specifications, in CSS files
	18919	The CSS file may begin with so-called @samp{@@import} directives,
	18920	which link to external CSS specifications for browsers to use when
	18921	interpreting the document. Again, a full description is beyond our
	18922	scope here, but we'll describe how they work syntactically, so we can
	18923	explain how @command{makeinfo} handles them.
	18924
	18925	@cindex Comments, in CSS files
	18926	There can be more than one @samp{@@import}, but they have to come
	18927	first in the file, with only whitespace and comments interspersed, no
	18928	normal definitions. (Technical exception: a @samp{@@charset}
	18929	directive may precede the @samp{@@import}'s. This does not alter
	18930	@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if
	18931	present.) Comments in CSS files are delimited by @samp{/* ... */}, as
	18932	in C@. An @samp{@@import} directive must be in one of these two forms:
	18933
	18934	@example
	18935	@@import url(http://example.org/foo.css);
	18936	@@import "http://example.net/bar.css";
	18937	@end example
	18938
	18939	As far as @command{makeinfo} is concerned, the crucial characters are
	18940	the @samp{@@} at the beginning and the semicolon terminating the
	18941	directive. When reading the CSS file, it simply copies any such
	18942	@samp{@@}-directive into the output, as follows:
	18943
	18944	@itemize
	18945	@item If @var{file} contains only normal CSS declarations, it is
	18946	included after @command{makeinfo}'s default CSS, thus overriding it.
	18947
	18948	@item If @var{file} begins with @samp{@@import} specifications (see
	18949	below), then the @samp{import}'s are included first (they have to come
	18950	first, according to the standard), and then @command{makeinfo}'s
	18951	default CSS is included. If you need to override @command{makeinfo}'s
	18952	defaults from an @samp{@@import}, you can do so with the @samp{!@:
	18953	important} CSS construct, as in:
	18954	@example
	18955	pre.smallexample @{ font-size: inherit ! important @}
	18956	@end example
	18957
	18958	@item If @var{file} contains both @samp{@@import} and inline CSS
	18959	specifications, the @samp{@@import}'s are included first, then
	18960	@command{makeinfo}'s defaults, and lastly the inline CSS from
	18961	@var{file}.
	18962
	18963	@item Any @@-directive other than @samp{@@import} and @samp{@@charset}
	18964	is treated as a CSS declaration, meaning @command{makeinfo} includes
	18965	its default CSS and then the rest of the file.
	18966	@end itemize
	18967
	18968	If the CSS file is malformed or erroneous, @command{makeinfo}'s output
	18969	is unspecified. @command{makeinfo} does not try to interpret the
	18970	meaning of the CSS file in any way; it just looks for the special
	18971	@samp{@@} and @samp{;} characters and blindly copies the text into the
	18972	output. Comments in the CSS file may or may not be included in the
	18973	output.
	18974
	18975	In addition to the possibilities offered by CSS, @command{makeinfo}
	18976	has many user-definable customization variables with which you can
	18977	influence the HTML output. @xref{Customization Variables}.
	18978
	18979
	18980	@node HTML Xref
	18981	@section HTML Cross-references
	18982	@cindex HTML cross-references
	18983	@cindex Cross-references, in HTML output
	18984
	18985	Cross-references between Texinfo manuals in HTML format become, in the
	18986	end, a standard HTML @code{<a>} link, but the details are
	18987	unfortunately complex. This section describes the algorithm used in
	18988	detail, so that Texinfo can cooperate with other programs, such as
	18989	@command{texi2html}, by writing mutually compatible HTML files.
	18990
	18991	This algorithm may or may not be used for links @emph{within} HTML
	18992	output for a Texinfo file. Since no issues of compatibility arise in
	18993	such cases, we do not need to specify this.
	18994
	18995	We try to support references to such ``external'' manuals in both
	18996	monolithic and split forms. A @dfn{monolithic} (mono) manual is
	18997	entirely contained in one file, and a @dfn{split} manual has a file
	18998	for each node. (@xref{HTML Splitting}.)
	18999
	19000	@cindex Dumas, Patrice
	19001	The algorithm was primarily devised by Patrice Dumas in 2003--04.
	19002
	19003	@menu
	19004	* Link Basics: HTML Xref Link Basics.
	19005	* Node Expansion: HTML Xref Node Name Expansion.
	19006	* Command Expansion: HTML Xref Command Expansion.
	19007	* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
	19008	* Mismatch: HTML Xref Mismatch.
	19009	* Configuration: HTML Xref Configuration. htmlxref.cnf.
	19010	@end menu
	19011
	19012
	19013	@node HTML Xref Link Basics
	19014	@subsection HTML Cross-reference Link Basics
	19015	@cindex HTML cross-reference link basics
	19016
	19017	For our purposes, an HTML link consists of four components: a host
	19018	name, a directory part, a file part, and a target part. We
	19019	always assume the @code{http} protocol. For example:
	19020
	19021	@example
	19022	http://@var{host}/@var{dir}/@var{file}.html#@var{target}
	19023	@end example
	19024
	19025	The information to construct a link comes from the node name and
	19026	manual name in the cross-reference command in the Texinfo source
	19027	(@pxref{Cross References}), and from @dfn{external information}
	19028	(@pxref{HTML Xref Configuration}).
	19029
	19030	We now consider each part in turn.
	19031
	19032	The @var{host} is hardwired to be the local host. This could either
	19033	be the literal string @samp{localhost}, or, according to the rules for
	19034	HTML links, the @samp{http://localhost/} could be omitted entirely.
	19035
	19036	The @var{dir} and @var{file} parts are more complicated, and depend on
	19037	the relative split/mono nature of both the manual being processed and
	19038	the manual that the cross-reference refers to. The underlying idea is
	19039	that there is one directory for Texinfo manuals in HTML, and a given
	19040	@var{manual} is either available as a monolithic file
	19041	@file{@var{manual}.html}, or a split subdirectory
	19042	@file{@var{manual}/*.html}. Here are the cases:
	19043
	19044	@itemize @bullet
	19045	@item
	19046	If the present manual is split, and the referent manual is also split,
	19047	the directory is @samp{../@var{referent/}} and the file is the
	19048	expanded node name (described later).
	19049
	19050	@item
	19051	If the present manual is split, and the referent manual is mono, the
	19052	directory is @samp{../} and the file is @file{@var{referent}.html}.
	19053
	19054	@item
	19055	If the present manual is mono, and the referent manual is split, the
	19056	directory is @file{@var{referent}/} and the file is the expanded node
	19057	name.
	19058
	19059	@item
	19060	If the present manual is mono, and the referent manual is also mono,
	19061	the directory is @file{./} (or just the empty string), and the file is
	19062	@file{@var{referent}.html}.
	19063
	19064	@end itemize
	19065
	19066	@vindex BASEFILENAME_LENGTH
	19067	Another rule, that only holds for filenames, is that base filenames
	19068	are truncated to 245 characters, to allow for an extension to be
	19069	appended and still comply with the 255-character limit which is common
	19070	to many filesystems. Although technically this can be changed with
	19071	the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other
	19072	Customization Variables}), doing so would make cross-manual references
	19073	to such nodes invalid.
	19074
	19075	Any directory part in the filename argument of the source cross
	19076	reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} and
	19077	@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. This
	19078	is because any such attempted hardwiring of the directory is very
	19079	unlikely to be useful for both Info and HTML output.
	19080
	19081	Finally, the @var{target} part is always the expanded node name.
	19082
	19083	Whether the present manual is split or mono is determined by user
	19084	option; @command{makeinfo} defaults to split, with the
	19085	@option{--no-split} option overriding this.
	19086
	19087	Whether the referent manual is split or mono, however, is another bit
	19088	of the external information (@pxref{HTML Xref Configuration}). By
	19089	default, @command{makeinfo} uses the same form of the referent manual
	19090	as the present manual.
	19091
	19092	Thus, there can be a mismatch between the format of the referent
	19093	manual that the generating software assumes, and the format it's
	19094	actually present in. @xref{HTML Xref Mismatch}.
	19095
	19096
	19097	@node HTML Xref Node Name Expansion
	19098	@subsection HTML Cross-reference Node Name Expansion
	19099	@cindex HTML cross-reference node name expansion
	19100	@cindex node name expansion, in HTML cross-references
	19101	@cindex expansion, of node names in HTML cross-references
	19102
	19103	As mentioned in the previous section, the key part of the HTML cross
	19104	reference algorithm is the conversion of node names in the Texinfo
	19105	source into strings suitable for XHTML identifiers and filenames. The
	19106	restrictions are similar for each: plain ASCII letters, numbers, and
	19107	the @samp{-} and @samp{_} characters are all that can be used.
	19108	(Although HTML anchors can contain most characters, XHTML is more
	19109	restrictive.)
	19110
	19111	Cross-references in Texinfo can refer either to nodes or anchors
	19112	(@pxref{@code{@@anchor}}). However, anchors are treated identically
	19113	to nodes in this context, so we'll continue to say ``node'' names for
	19114	simplicity.
	19115
	19116	A special exception: the Top node (@pxref{The Top Node}) is always
	19117	mapped to the file @file{index.html}, to match web server software.
	19118	However, the HTML @emph{target} is @samp{Top}. Thus (in the split case):
	19119
	19120	@example
	19121	@@xref@{Top,,, emacs, The GNU Emacs Manual@}.
	19122	@result{} <a href="emacs/index.html#Top">
	19123	@end example
	19124
	19125	@enumerate
	19126	@item
	19127	The standard ASCII letters (a-z and A-Z) are not modified. All other
	19128	characters may be changed as specified below.
	19129
	19130	@item
	19131	The standard ASCII numbers (0-9) are not modified except when a number
	19132	is the first character of the node name. In that case, see below.
	19133
	19134	@item
	19135	Multiple consecutive space, tab and newline characters are transformed
	19136	into just one space. (It's not possible to have newlines in node
	19137	names with the current implementation, but we specify it anyway, just
	19138	in case.)
	19139
	19140	@item
	19141	Leading and trailing spaces are removed.
	19142
	19143	@item
	19144	After the above has been applied, each remaining space character is
	19145	converted into a @samp{-} character.
	19146
	19147	@item
	19148	Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}},
	19149	where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
	19150	This includes @samp{_}, which is mapped to @samp{_005f}.
	19151
	19152	@item
	19153	If the node name does not begin with a letter, the literal string
	19154	@samp{g_t} is prefixed to the result. (Due to the rules above, that
	19155	string can never occur otherwise; it is an arbitrary choice, standing
	19156	for ``GNU Texinfo''.) This is necessary because XHTML requires that
	19157	identifiers begin with a letter.
	19158
	19159	@end enumerate
	19160
	19161	For example:
	19162
	19163	@example
	19164	@@node A node --- with _'%
	19165	@result{} A-node-_002d_002d_002d-with-_005f_0027_0025
	19166	@end example
	19167
	19168	Example translations of common characters:
	19169
	19170	@itemize @bullet
	19171	@item @samp{_} @result{} @samp{_005f}
	19172	@item @samp{-} @result{} @samp{_002d}
	19173	@item @samp{A node} @result{} @samp{A-node}
	19174	@end itemize
	19175
	19176	On case-folding computer systems, nodes differing only by case will be
	19177	mapped to the same file. In particular, as mentioned above, Top
	19178	always maps to the file @file{index.html}. Thus, on a case-folding
	19179	system, Top and a node named `Index' will both be written to
	19180	@file{index.html}. Fortunately, the targets serve to distinguish
	19181	these cases, since HTML target names are always case-sensitive,
	19182	independent of operating system.
	19183
	19184
	19185	@node HTML Xref Command Expansion
	19186	@subsection HTML Cross-reference Command Expansion
	19187	@cindex HTML cross-reference command expansion
	19188
	19189	Node names may contain @@-commands (@pxref{Node Line Requirements}).
	19190	This section describes how they are handled.
	19191
	19192	First, comments are removed.
	19193
	19194	Next, any @code{@@value} commands (@pxref{@code{@@set @@value}}) and
	19195	macro invocations (@pxref{Invoking Macros}) are fully expanded.
	19196
	19197	Then, for the following commands, the command name and braces are removed,
	19198	and the text of the argument is recursively transformed:
	19199
	19200	@example
	19201	@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
	19202	@@emph @@env @@file @@i @@indicateurl @@kbd @@key
	19203	@@samp @@sansserif @@sc @@slanted @@strong @@sub @@sup
	19204	@@t @@U @@var @@verb @@w
	19205	@end example
	19206
	19207	@noindent For @code{@@sc}, any letters are capitalized.
	19208
	19209	In addition, the following commands are replaced by constant text, as
	19210	shown below. If any of these commands have non-empty arguments, as in
	19211	@code{@@TeX@{bad@}}, it is an error, and the result is unspecified.
	19212	In this table, `(space)' means a space character and `(nothing)' means
	19213	the empty string. The notation `U+@var{hhhh}' means Unicode code
	19214	point @var{hhhh} (in hex, as usual).
	19215
	19216	There are further transformations of many of these expansions to yield
	19217	the final file or other target name, such as space characters to
	19218	@samp{-}, etc., according to the other rules.
	19219
	19220	@multitable @columnfractions .3 .5
	19221	@item @code{@@(newline)} @tab (space)
	19222	@item @code{@@(space)} @tab (space)
	19223	@item @code{@@(tab)} @tab (space)
	19224	@item @code{@@!} @tab @samp{!}
	19225	@item @code{@@*} @tab (space)
	19226	@item @code{@@-} @tab (nothing)
	19227	@item @code{@@.} @tab @samp{.}
	19228	@item @code{@@:} @tab (nothing)
	19229	@item @code{@@?} @tab @samp{?}
	19230	@item @code{@@@@} @tab @samp{@@}
	19231	@item @code{@@@{} @tab @samp{@{}
	19232	@item @code{@@@}} @tab @samp{@}}
	19233	@item @code{@@LaTeX} @tab @samp{LaTeX}
	19234	@item @code{@@TeX} @tab @samp{TeX}
	19235	@item @code{@@arrow} @tab U+2192
	19236	@item @code{@@bullet} @tab U+2022
	19237	@item @code{@@comma} @tab @samp{,}
	19238	@item @code{@@copyright} @tab U+00A9
	19239	@item @code{@@dots} @tab U+2026
	19240	@item @code{@@enddots} @tab @samp{...}
	19241	@item @code{@@equiv} @tab U+2261
	19242	@item @code{@@error} @tab @samp{error-->}
	19243	@item @code{@@euro} @tab U+20AC
	19244	@item @code{@@exclamdown} @tab U+00A1
	19245	@item @code{@@expansion} @tab U+21A6
	19246	@item @code{@@geq} @tab U+2265
	19247	@item @code{@@leq} @tab U+2264
	19248	@item @code{@@minus} @tab U+2212
	19249	@item @code{@@ordf} @tab U+00AA
	19250	@item @code{@@ordm} @tab U+00BA
	19251	@item @code{@@point} @tab U+2605
	19252	@item @code{@@pounds} @tab U+00A3
	19253	@item @code{@@print} @tab U+22A3
	19254	@item @code{@@questiondown} @tab U+00BF
	19255	@item @code{@@registeredsymbol} @tab U+00AE
	19256	@item @code{@@result} @tab U+21D2
	19257	@item @code{@@textdegree} @tab U+00B0
	19258	@item @code{@@tie} @tab (space)
	19259	@end multitable
	19260
	19261	Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like),
	19262	are likewise replaced by their Unicode values. Normal quotation
	19263	@emph{characters} (e.g., ASCII ` and ') are not altered.
	19264	@xref{Inserting Quotation Marks}.
	19265
	19266	Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and
	19267	@code{@@image} commands are replaced by their first argument. (For
	19268	these commands, all subsequent arguments are optional, and ignored
	19269	here.) @xref{@code{@@acronym}}, and @ref{@code{@@email}}, and @ref{Images}.
	19270
	19271	Accents are handled according to the next section.
	19272
	19273	Any other command is an error, and the result is unspecified.
	19274
	19275
	19276	@node HTML Xref 8-bit Character Expansion
	19277	@subsection HTML Cross-reference 8-bit Character Expansion
	19278	@cindex HTML cross-reference 8-bit character expansion
	19279	@cindex 8-bit characters, in HTML cross-references
	19280	@cindex Expansion of 8-bit characters in HTML cross-references
	19281	@cindex Transliteration of 8-bit characters in HTML cross-references
	19282
	19283	Usually, characters other than plain 7-bit ASCII are transformed into
	19284	the corresponding Unicode code point(s) in Normalization Form@tie{}C,
	19285	which uses precomposed characters where available. (This is the
	19286	normalization form recommended by the W3C and other bodies.) This
	19287	holds when that code point is @code{0xffff} or less, as it almost
	19288	always is.
	19289
	19290	These will then be further transformed by the rules above into the
	19291	string @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex.
	19292
	19293	For example, combining this rule and the previous section:
	19294
	19295	@example
	19296	@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@}
	19297	@result{} A-TeX-B_0306-_2605_002e_002e_002e
	19298	@end example
	19299
	19300	Notice: 1)@tie{}@code{@@enddots} expands to three periods which in
	19301	turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B'
	19302	with a breve accent, which does not exist as a pre-accented Unicode
	19303	character, therefore expands to @samp{B_0306} (B with combining
	19304	breve).
	19305
	19306	When the Unicode code point is above @code{0xffff}, the transformation
	19307	is @samp{__@var{xxxxxx}}, that is, two leading underscores followed by
	19308	six hex digits. Since Unicode has declared that their highest code
	19309	point is @code{0x10ffff}, this is sufficient. (We felt it was better
	19310	to define this extra escape than to always use six hex digits, since
	19311	the first two would nearly always be zeros.)
	19312
	19313	This method works fine if the node name consists mostly of ASCII
	19314	characters and contains only few 8-bit ones. But if the document is
	19315	written in a language whose script is not based on the Latin alphabet
	19316	(for example, Ukrainian), it will create file names consisting almost
	19317	entirely of @samp{_@var{xxxx}} notations, which is inconvenient and
	19318	all but unreadable. To handle such cases, @command{makeinfo} offers
	19319	the @option{--transliterate-file-names} command line option. This
	19320	option enables @dfn{transliteration} of node names into ASCII
	19321	characters for the purposes of file name creation and referencing.
	19322	The transliteration is based on phonetic principles, which makes the
	19323	generated file names more easily understanable.
	19324
	19325	@cindex Normalization Form C, Unicode
	19326	For the definition of Unicode Normalization Form@tie{}C, see Unicode
	19327	report UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many
	19328	related documents and implementations are available elsewhere on the
	19329	web.
	19330
	19331
	19332	@node HTML Xref Mismatch
	19333	@subsection HTML Cross-reference Mismatch
	19334	@cindex HTML cross-reference mismatch
	19335	@cindex Mismatched HTML cross-reference source and target
	19336
	19337	As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
	19338	software may need to guess whether a given manual being cross
	19339	referenced is available in split or monolithic form---and, inevitably,
	19340	it might guess wrong. However, when the @emph{referent} manual is
	19341	generated, it is possible to handle at least some mismatches.
	19342
	19343	In the case where we assume the referent is split, but it is actually
	19344	available in mono, the only recourse would be to generate a
	19345	@file{manual/} subdirectory full of HTML files which redirect back to
	19346	the monolithic @file{manual.html}. Since this is essentially the same
	19347	as a split manual in the first place, it's not very appealing.
	19348
	19349	On the other hand, in the case where we assume the referent is mono,
	19350	but it is actually available in split, it is possible to use
	19351	JavaScript to redirect from the putatively monolithic
	19352	@file{manual.html} to the different @file{manual/node.html} files.
	19353	Here's an example:
	19354
	19355	@example
	19356	function redirect() @{
	19357	switch (location.hash) @{
	19358	case "#Node1":
	19359	location.replace("manual/Node1.html#Node1"); break;
	19360	case "#Node2" :
	19361	location.replace("manual/Node2.html#Node2"); break;
	19362	@dots{}
	19363	default:;
	19364	@}
	19365	@}
	19366	@end example
	19367
	19368	Then, in the @code{<body>} tag of @file{manual.html}:
	19369
	19370	@example
	19371	<body onLoad="redirect();">
	19372	@end example
	19373
	19374	Once again, this is something the software which generated the
	19375	@emph{referent} manual has to do in advance, it's not something the
	19376	software generating the cross-reference in the present manual can
	19377	control.
	19378
	19379
	19380	@node HTML Xref Configuration
	19381	@subsection HTML Cross-reference Configuration: @file{htmlxref.cnf}
	19382
	19383	@pindex htmlxref.cnf
	19384	@cindex HTML cross-reference configuration
	19385	@cindex Cross-reference configuration, for HTML
	19386	@cindex Configuration, for HTML cross-manual references
	19387
	19388	@command{makeinfo} reads a file named @file{htmlxref.cnf} to gather
	19389	information for cross-references to other manuals in HTML output. It
	19390	is looked for in the following directories:
	19391
	19392	@table @file
	19393	@item ./
	19394	(the current directory)
	19395
	19396	@item ./.texinfo/
	19397	(under the current directory)
	19398
	19399	@item ~/.texinfo/
	19400	(where @code{~} is the current user's home directory)
	19401
	19402	@item @var{sysconfdir}/texinfo/
	19403	(where @var{sysconfdir} is the system configuration directory
	19404	specified at compile-time, e.g., @file{/usr/local/etc})
	19405
	19406	@item @var{datadir}/texinfo/
	19407	(likewise specified at compile time, e.g., @file{/usr/local/share})
	19408	@end table
	19409
	19410	All files found are used, with earlier entries overriding later ones.
	19411	The Texinfo distribution includes a default file which handles many
	19412	GNU manuals; it is installed in the last of the above directories,
	19413	i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}.
	19414
	19415	The file is line-oriented. Lines consisting only of whitespace are
	19416	ignored. Comments are indicated with a @samp{#} at the beginning of a
	19417	line, optionally preceded by whitespace. Since @samp{#} can occur in
	19418	urls (like almost any character), it does not otherwise start a
	19419	comment.
	19420
	19421	Each non-blank non-comment line must be either a @dfn{variable
	19422	assignment} or @dfn{manual information}.
	19423
	19424	A variable assignment line looks like this:
	19425
	19426	@example
	19427	@var{varname} = @var{varvalue}
	19428	@end example
	19429
	19430	Whitespace around the @samp{=} is optional and ignored. The
	19431	@var{varname} should consist of letters; case is significant. The
	19432	@var{varvalue} is an arbitrary string, continuing to the end of the
	19433	line. Variables are then referenced with @samp{$@{@var{varname}@}};
	19434	variable references can occur in the @var{varvalue}.
	19435
	19436	A manual information line looks like this:
	19437
	19438	@example
	19439	@var{manual} @var{keyword} @var{urlprefix}
	19440	@end example
	19441
	19442	@noindent
	19443	with @var{manual} the short identifier for a manual, @var{keyword}
	19444	being one of: @code{mono}, @code{node}, @code{section},
	19445	@code{chapter}, and @var{urlprefix} described below. Variable
	19446	references can occur only in the @var{urlprefix}. For example (used
	19447	in the canonical @file{htmlxref.cnf}):
	19448
	19449	@smallexample
	19450	G = http://www.gnu.org
	19451	GS = $@{G@}/software
	19452	hello mono $@{GS@}/hello/manual/hello.html
	19453	hello chapter $@{GS@}/hello/manual/html_chapter/
	19454	hello section $@{GS@}/hello/manual/html_section/
	19455	hello node $@{GS@}/hello/manual/html_node/
	19456	@end smallexample
	19457
	19458	@cindex monolithic manuals, for HTML cross-references
	19459	If the keyword is @code{mono}, @var{urlprefix} gives the host,
	19460	directory, and file name for @var{manual} as one monolithic file.
	19461
	19462	@cindex split manuals, for HTML cross-references
	19463	If the keyword is @code{node}, @code{section}, or @code{chapter},
	19464	@var{urlprefix} gives the host and directory for @var{manual} split
	19465	into nodes, sections, or chapters, respectively.
	19466
	19467	When available, @command{makeinfo} will use the ``corresponding''
	19468	value for cross-references between manuals. That is, when generating
	19469	monolithic output (@option{--no-split}), the @code{mono} url will be
	19470	used, when generating output that is split by node, the @code{node}
	19471	url will be used, etc. However, if a manual is not available in that
	19472	form, anything that is available can be used. Here is the search
	19473	order for each style:
	19474
	19475	@smallexample
	19476	node @result{} node, section, chapter, mono
	19477	section @result{} section, chapter, node, mono
	19478	chapter @result{} chapter, section, node, mono
	19479	mono @result{} mono, chapter, section, node
	19480	@end smallexample
	19481
	19482	@opindex --node-files@r{, and HTML cross-references}
	19483	These section- and chapter-level cross-manual references can succeed
	19484	only when the target manual was created using @option{--node-files};
	19485	this is the default for split output.
	19486
	19487	If you have additions or corrections to the @file{htmlxref.cnf}
	19488	distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
	19489	usual. You can get the latest version from
	19490	@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
	19491
	19492
	19493	@node @@-Command Details
	19494	@appendix @@-Command Details
	19495
	19496	Here are the details of @@-commands: information about their syntax, a
	19497	list of commands, and information about where commands can appear.
	19498
	19499	@node Command Syntax
	19500	@section @@-Command Syntax
	19501	@cindex @@-command syntax
	19502	@cindex Syntax, of @@-commands
	19503	@cindex Command syntax
	19504
	19505	Texinfo has the following types of @@-command:
	19506
	19507	@table @asis
	19508	@item 1. Brace commands
	19509	These commands start with @@ followed by a letter or a word, followed by an
	19510	argument within braces. For example, the command @code{@@dfn} indicates
	19511	the introductory or defining use of a term; it is used as follows: @samp{In
	19512	Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}
	19513
	19514	@item 2. Line commands
	19515	These commands occupy an entire line. The line starts with @@,
	19516	followed by the name of the command (a word); for example, @code{@@center}
	19517	or @code{@@cindex}. If no argument is needed, the word is followed by
	19518	the end of the line. If there is an argument, it is separated from
	19519	the command name by a space. Braces are not used.
	19520
	19521	@item 3. Block commands
	19522	These commands are written at the start of a line, with general text on
	19523	following lines, terminated by a matching @code{@@end} command on a
	19524	line of its own. For example, @code{@@example}, then the lines of a
	19525	coding example, then @code{@@end example}. Some of these block commands
	19526	take arguments as line commands do; for example, @code{@@enumerate A}
	19527	opening an environment terminated by @code{@@end enumerate}. Here
	19528	@samp{A} is the argument.
	19529
	19530	@item 4. Symbol insertion commands with no arguments
	19531	These commands start with @@ followed by a word followed by a
	19532	left and right- brace. These commands insert special symbols in
	19533	the document; they do not take arguments. Some examples:
	19534	@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
	19535	@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', and
	19536	@code{@@bullet@{@}} @result{} @samp{@bullet{}}.
	19537
	19538	@item 5. Non-alphabetic commands
	19539	The names of commands in all of the above categories consist of
	19540	alphabetic characters, almost entirely in lower-case. Unlike those, the
	19541	non-alphabetic commands commands consist of an @@ followed by a
	19542	punctuation mark or other character that is not part of the Latin
	19543	alphabet. Non-alphabetic commands are almost always part of text
	19544	within a paragraph. The non-alphabetic commands include @code{@@@@},
	19545	@code{@@@{}, @code{@@@}}, @code{@@.}, @code{@@@kbd{SPACE}}, and most of
	19546	the accent commands.
	19547
	19548	@item 6. Miscellaneous commands
	19549	There are a handful of commands that don't fit into any of the above
	19550	categories; for example, the obsolete command @code{@@refill}, which is
	19551	always used at the end of a paragraph immediately following the final
	19552	period or other punctuation character. @code{@@refill} takes no
	19553	argument and does not require braces. Likewise, @code{@@tab} used in a
	19554	@code{@@multitable} block does not take arguments, and is not followed
	19555	by braces.
	19556	@end table
	19557
	19558	@cindex Braces and argument syntax
	19559	Thus, the alphabetic commands fall into classes that have
	19560	different argument syntaxes. You cannot tell to which class a command
	19561	belongs by the appearance of its name, but you can tell by the
	19562	command's meaning: if the command stands for a glyph, it is in
	19563	class 4 and does not require an argument; if it makes sense to use the
	19564	command among other text as part of a paragraph, the command
	19565	is in class 1 and must be followed by an argument in braces. The
	19566	non-alphabetic commands, such as @code{@@:}, are exceptions to the
	19567	rule; they do not need braces.
	19568
	19569	The purpose of having different syntax for commands is to make Texinfo
	19570	files easier to read, and also to help the GNU Emacs paragraph and
	19571	filling commands work properly.
	19572
	19573
	19574	@node Command List
	19575	@section @@-Command List
	19576	@cindex Alphabetical @@-command list
	19577	@cindex List of @@-commands
	19578	@cindex @@-command list
	19579	@cindex Reference to @@-commands
	19580
	19581	Here is an alphabetical list of the @@-commands in Texinfo. Square
	19582	brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
	19583	@samp{@dots{}}, indicates repeated text.
	19584
	19585	@table @code
	19586	@item @@@var{whitespace}
	19587	An @code{@@} followed by a space, tab, or newline produces a normal,
	19588	stretchable, interword space. @xref{Multiple Spaces}.
	19589
	19590	@item @@!
	19591	Produce an exclamation point that ends a sentence (usually after an
	19592	end-of-sentence capital letter). @xref{Ending a Sentence}.
	19593
	19594	@item @@"
	19595	@itemx @@'
	19596	Generate an umlaut or acute accent, respectively, over the next
	19597	character, as in @"o and @'o. @xref{Inserting Accents}.
	19598
	19599	@item @@&
	19600	@itemx @@ampchar@{@}
	19601	Generate an ampersand. @xref{Inserting an Ampersand}.
	19602
	19603	@item @@*
	19604	Force a line break. @xref{Line Breaks}.
	19605
	19606	@item @@,@{@var{c}@}
	19607	Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
	19608	Accents}.
	19609
	19610	@item @@-
	19611	Insert a discretionary hyphenation point. @xref{@code{@@- @@hyphenation}}.
	19612
	19613	@item @@.
	19614	Produce a period that ends a sentence (usually after an
	19615	end-of-sentence capital letter). @xref{Ending a Sentence}.
	19616
	19617	@item @@/
	19618	Produces no output, but allows a line break. @xref{Line Breaks}.
	19619
	19620	@item @@:
	19621	Tell @TeX{} to refrain from inserting extra whitespace after an
	19622	immediately preceding period, question mark, exclamation mark, or
	19623	colon, as @TeX{} normally would. @xref{Not Ending a Sentence}.
	19624
	19625	@item @@=
	19626	Generate a macron (bar) accent over the next character, as in @=o.
	19627	@xref{Inserting Accents}.
	19628
	19629	@item @@?
	19630	Produce a question mark that ends a sentence (usually after an
	19631	end-of-sentence capital letter). @xref{Ending a Sentence}.
	19632
	19633	@item @@@@
	19634	@itemx @@atchar@{@}
	19635	Insert an at sign, @samp{@@}. @xref{Inserting an Atsign}.
	19636
	19637	@item @@\
	19638	@itemx @@backslashchar@{@}
	19639	Insert a backslash, @samp{\}; @code{@@backslashchar@{@}} works
	19640	anywhere, while @code{@@\} works only inside @code{@@math}.
	19641	@xref{Inserting a Backslash}, and @ref{Inserting Math}.
	19642
	19643	@item @@^
	19644	@itemx @@`
	19645	Generate a circumflex (hat) or grave accent, respectively, over the next
	19646	character, as in @^o and @`e.
	19647	@xref{Inserting Accents}.
	19648
	19649	@item @@@{
	19650	@itemx @@lbracechar@{@}
	19651	Insert a left brace, @samp{@{}. @xref{Inserting Braces}.
	19652
	19653	@item @@@}
	19654	@itemx @@rbracechar@{@}
	19655	Insert a right brace, @samp{@}}. @xref{Inserting Braces}.
	19656
	19657	@item @@~
	19658	Generate a tilde accent over the next character, as in @~N.
	19659	@xref{Inserting Accents}.
	19660
	19661	@item @@AA@{@}
	19662	@itemx @@aa@{@}
	19663	Generate the uppercase and lowercase Scandinavian A-ring letters,
	19664	respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
	19665
	19666	@item @@abbr@{@var{abbreviation}@}
	19667	Indicate a general abbreviation, such as `Comput.'.
	19668	@xref{@code{@@abbr}}.
	19669
	19670	@item @@acronym@{@var{acronym}@}
	19671	Indicate an acronym in all capital letters, such as `NASA'.
	19672	@xref{@code{@@acronym}}.
	19673
	19674	@item @@AE@{@}
	19675	@itemx @@ae@{@}
	19676	Generate the uppercase and lowercase AE ligatures, respectively:
	19677	@AE{}, @ae{}. @xref{Inserting Accents}.
	19678
	19679	@item @@afivepaper
	19680	Change page dimensions for the A5 paper size. @xref{A4 Paper}.
	19681
	19682	@item @@afourlatex
	19683	@itemx @@afourpaper
	19684	@itemx @@afourwide
	19685	Change page dimensions for the A4 paper size. @xref{A4 Paper}.
	19686
	19687	@item @@alias @var{new}=@var{existing}
	19688	Make the command @samp{@@@var{new}} a synonym for the existing command
	19689	@samp{@@@var{existing}}. @xref{@code{@@alias}}.
	19690
	19691	@item @@allowcodebreaks @var{true-false}
	19692	Control breaking at @samp{-} and @samp{_} in @TeX{}.
	19693	@xref{@code{@@allowcodebreaks}}.
	19694
	19695	@item @@anchor@{@var{name}@}
	19696	Define @var{name} as the current location for use as a cross-reference
	19697	target. @xref{@code{@@anchor}}.
	19698
	19699	@item @@appendix @var{title}
	19700	Begin an appendix. The title appears in the table of contents. In
	19701	Info, the title is underlined with asterisks.
	19702	@xref{@code{@@unnumbered @@appendix}}.
	19703
	19704	@item @@appendixsec @var{title}
	19705	@itemx @@appendixsection @var{title}
	19706	Begin an appendix section within an appendix. The section title
	19707	appears in the table of contents. In Info, the title is underlined
	19708	with equal signs. @code{@@appendixsection} is a longer spelling of
	19709	the @code{@@appendixsec} command. @xref{@code{@@unnumberedsec
	19710	@@appendixsec @@heading}}.
	19711
	19712	@item @@appendixsubsec @var{title}
	19713	Begin an appendix subsection. The title appears in the table of
	19714	contents. In Info, the title is underlined with hyphens.
	19715	@xref{@code{@@unnumberedsubsec @@appendixsubsec @@subheading}}.
	19716
	19717	@item @@appendixsubsubsec @var{title}
	19718	Begin an appendix subsubsection. The title appears in the table of
	19719	contents. In Info, the title is underlined with periods.
	19720	@xref{@code{@@subsubsection}}.
	19721
	19722	@item @@arrow@{@}
	19723	Generate a right arrow glyph: @samp{@arrow{}}. Used by default
	19724	for @code{@@click}. @xref{Click Sequences}.
	19725
	19726	@item @@asis
	19727	Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
	19728	print the table's first column without highlighting (``as is'').
	19729	@xref{@code{@@asis}}.
	19730
	19731	@item @@author @var{author}
	19732	Typeset @var{author} flushleft and underline it. @xref{@code{@@title
	19733	@@subtitle @@author}}.
	19734
	19735	@item @@b@{@var{text}@}
	19736	Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}.
	19737
	19738	@item @@bullet@{@}
	19739	Generate a large round dot, @bullet{} (@samp{*} in Info). Often used
	19740	with @code{@@table}. @xref{@code{@@bullet}}.
	19741
	19742	@item @@bye
	19743	Stop formatting a file. The formatters do not see anything in the
	19744	input file following @code{@@bye}. @xref{Ending a File}.
	19745
	19746	@item @@c @var{comment}
	19747	Begin a comment in Texinfo. The rest of the line does not appear in
	19748	any output. A synonym for @code{@@comment}. @kbd{DEL} also
	19749	starts a comment. @xref{Comments}.
	19750
	19751	@item @@caption
	19752	Define the full caption for a @code{@@float}. @xref{@code{@@caption
	19753	@@shortcaption}}.
	19754
	19755	@item @@cartouche
	19756	Highlight an example or quotation by drawing a box with rounded
	19757	corners around it. Pair with @code{@@end cartouche}. No effect in
	19758	Info. @xref{@code{@@cartouche}}.
	19759
	19760	@item @@center @var{line-of-text}
	19761	Center the line of text following the command.
	19762	@xref{@code{@@titlefont @@center @@sp}}.
	19763
	19764	@item @@centerchap @var{line-of-text}
	19765	Like @code{@@chapter}, but centers the chapter title. @xref{@code{@@chapter}}.
	19766
	19767	@item @@chapheading @var{title}
	19768	Print an unnumbered chapter-like heading, but omit from the table of
	19769	contents. In Info, the title is underlined with asterisks.
	19770	@xref{@code{@@majorheading @@chapheading}}.
	19771
	19772	@item @@chapter @var{title}
	19773	Begin a numbered chapter. The chapter title appears in the table of
	19774	contents. In Info, the title is underlined with asterisks.
	19775	@xref{@code{@@chapter}}.
	19776
	19777	@item @@cindex @var{entry}
	19778	Add @var{entry} to the index of concepts. @xref{Index Entries, ,
	19779	Defining the Entries of an Index}.
	19780
	19781	@item @@cite@{@var{reference}@}
	19782	Highlight the name of a book or other reference that has no companion
	19783	Info file. @xref{@code{@@cite}}.
	19784
	19785	@item @@clear @var{flag}
	19786	Unset @var{flag}, preventing the Texinfo formatting commands from
	19787	formatting text between subsequent pairs of @code{@@ifset @var{flag}}
	19788	and @code{@@end ifset} commands, and preventing
	19789	@code{@@value@{@var{flag}@}} from expanding to the value to which
	19790	@var{flag} is set. @xref{@code{@@set @@clear @@value}}.
	19791
	19792	@item @@click@{@}
	19793	Represent a single ``click'' in a GUI@. Used within
	19794	@code{@@clicksequence}. @xref{Click Sequences}.
	19795
	19796	@item @@clicksequence@{@var{action} @@click@{@} @var{action}@}
	19797	Represent a sequence of clicks in a GUI@. @xref{Click Sequences}.
	19798
	19799	@item @@clickstyle @@@var{cmd}
	19800	Execute @@@var{cmd} for each @code{@@click}; the default is
	19801	@code{@@arrow}. The usual following empty braces on @@@var{cmd} are
	19802	omitted. @xref{Click Sequences}.
	19803
	19804	@item @@code@{@var{sample-code}@}
	19805	Indicate an expression, a syntactically complete token of a program,
	19806	or a program name. Unquoted in Info output. @xref{@code{@@code}}.
	19807
	19808	@item @@codequotebacktick @var{on-off}
	19809	@itemx @@codequoteundirected @var{on-off}
	19810	Control output of @code{`} and @code{'} in code examples.
	19811	@xref{Inserting Quote Characters}.
	19812
	19813	@item @@comma@{@}
	19814	Insert a comma `,' character; only needed when a literal comma would
	19815	be taken as an argument separator. @xref{Inserting a Comma}.
	19816
	19817	@item @@command@{@var{command-name}@}
	19818	Indicate a command name, such as @command{ls}. @xref{@code{@@command}}.
	19819
	19820	@item @@comment @var{comment}
	19821	Begin a comment in Texinfo. The rest of the line does not appear in
	19822	any output. A synonym for @code{@@c}.
	19823	@xref{Comments}.
	19824
	19825	@item @@contents
	19826	Print a complete table of contents. Has no effect in Info, which uses
	19827	menus instead. @xref{Contents, , Generating a Table of Contents}.
	19828
	19829	@item @@copying
	19830	Specify copyright holders and copying conditions for the document. Pair
	19831	with @code{@@end copying}. @xref{@code{@@copying}}.
	19832
	19833	@item @@copyright@{@}
	19834	Generate the copyright symbol @copyright{}.
	19835	@xref{@code{@@copyright}}.
	19836
	19837	@item @@defcodeindex @var{index-name}
	19838	Define a new index and its indexing command. Print entries in an
	19839	@code{@@code} font. @xref{New Indices, , Defining New Indices}.
	19840
	19841	@item @@defcv @var{category} @var{class} @var{name}
	19842	@itemx @@defcvx @var{category} @var{class} @var{name}
	19843	Format a description for a variable associated with a class in
	19844	object-oriented programming. Takes three arguments: the category of
	19845	thing being defined, the class to which it belongs, and its name.
	19846	@xref{Definition Commands}.
	19847
	19848	@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
	19849	@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
	19850	Format a description for a function, interactive command, or similar
	19851	entity that may take arguments. @code{@@deffn} takes as arguments the
	19852	category of entity being described, the name of this particular
	19853	entity, and its arguments, if any. @xref{Definition Commands}.
	19854
	19855	@item @@defindex @var{index-name}
	19856	Define a new index and its indexing command. Print entries in a roman
	19857	font. @xref{New Indices, , Defining New Indices}.
	19858
	19859	@item @@definfoenclose @var{newcmd}, @var{before}, @var{after}
	19860	Must be used within @code{@@ifinfo}; create a new command
	19861	@code{@@@var{newcmd}} for Info that marks text by enclosing it in
	19862	strings that precede and follow the text.
	19863	@xref{@code{@@definfoenclose}}.
	19864
	19865	@item @@defivar @var{class} @var{instance-variable-name}
	19866	@itemx @@defivarx @var{class} @var{instance-variable-name}
	19867	Format a description for an instance variable in object-oriented
	19868	programming. The command is equivalent to @samp{@@defcv @{Instance
	19869	Variable@} @dots{}}. @xref{Definition Commands}.
	19870
	19871	@item @@defmac @var{macroname} @var{arguments}@dots{}
	19872	@itemx @@defmacx @var{macroname} @var{arguments}@dots{}
	19873	Format a description for a macro; equivalent to @samp{@@deffn Macro
	19874	@dots{}}. @xref{Definition Commands}.
	19875
	19876	@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
	19877	@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
	19878	Format a description for a method in object-oriented programming;
	19879	equivalent to @samp{@@defop Method @dots{}}. @xref{Definition
	19880	Commands}.
	19881
	19882	@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
	19883	@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
	19884	Format a description for an operation in object-oriented programming.
	19885	@code{@@defop} takes as arguments the name of the category of
	19886	operation, the name of the operation's class, the name of the
	19887	operation, and its arguments, if any. @xref{Definition Commands}, and
	19888	@ref{Abstract Objects}.
	19889
	19890	@item @@defopt @var{option-name}
	19891	@itemx @@defoptx @var{option-name}
	19892	Format a description for a user option; equivalent to @samp{@@defvr
	19893	@{User Option@} @dots{}}. @xref{Definition Commands}.
	19894
	19895	@item @@defspec @var{special-form-name} @var{arguments}@dots{}
	19896	@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
	19897	Format a description for a special form; equivalent to @samp{@@deffn
	19898	@{Special Form@} @dots{}}. @xref{Definition Commands}.
	19899
	19900	@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
	19901	@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
	19902	Format a description for a data type; its arguments are the category,
	19903	the name of the type (e.g., @samp{int}) , and then the names of
	19904	attributes of objects of that type. @xref{Definition Commands}, and
	19905	@ref{Data Types}.
	19906
	19907	@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
	19908	@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name}
	19909	Format a description for a typed class variable in object-oriented programming.
	19910	@xref{Definition Commands}, and @ref{Abstract Objects}.
	19911
	19912	@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
	19913	@itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
	19914	Format a description for a function or similar entity that may take
	19915	arguments and that is typed. @code{@@deftypefn} takes as arguments the
	19916	category of entity being described, the type, the name of the
	19917	entity, and its arguments, if any. @xref{Definition Commands}.
	19918
	19919	@item @@deftypefnnewline @var{on-off}
	19920	Specifies whether return types for @code{@@deftypefn} and similar are
	19921	printed on lines by themselves; default is off. @xref{Typed
	19922	Functions,, Functions in Typed Languages}.
	19923
	19924	@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
	19925	@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
	19926	Format a description for a function in a typed language.
	19927	The command is equivalent to @samp{@@deftypefn Function @dots{}}.
	19928	@xref{Definition Commands}.
	19929
	19930	@item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
	19931	@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
	19932	Format a description for a typed instance variable in object-oriented
	19933	programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
	19934
	19935	@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
	19936	@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
	19937	Format a description for a typed method in object-oriented programming.
	19938	@xref{Definition Commands}.
	19939
	19940	@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
	19941	@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
	19942	Format a description for a typed operation in object-oriented programming.
	19943	@xref{Definition Commands}, and @ref{Abstract Objects}.
	19944
	19945	@item @@deftypevar @var{data-type} @var{variable-name}
	19946	@itemx @@deftypevarx @var{data-type} @var{variable-name}
	19947	Format a description for a variable in a typed language. The command is
	19948	equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
	19949	Commands}.
	19950
	19951	@item @@deftypevr @var{category} @var{data-type} @var{name}
	19952	@itemx @@deftypevrx @var{category} @var{data-type} @var{name}
	19953	Format a description for something like a variable in a typed
	19954	language---an entity that records a value. Takes as arguments the
	19955	category of entity being described, the type, and the name of the
	19956	entity. @xref{Definition Commands}.
	19957
	19958	@item @@defun @var{function-name} @var{arguments}@dots{}
	19959	@itemx @@defunx @var{function-name} @var{arguments}@dots{}
	19960	Format a description for a function; equivalent to
	19961	@samp{@@deffn Function @dots{}}. @xref{Definition Commands}.
	19962
	19963	@item @@defvar @var{variable-name}
	19964	@itemx @@defvarx @var{variable-name}
	19965	Format a description for a variable; equivalent to @samp{@@defvr
	19966	Variable @dots{}}. @xref{Definition Commands}.
	19967
	19968	@item @@defvr @var{category} @var{name}
	19969	@itemx @@defvrx @var{category} @var{name}
	19970	Format a description for any kind of variable. @code{@@defvr} takes
	19971	as arguments the category of the entity and the name of the entity.
	19972	@xref{Definition Commands}.
	19973
	19974	@item @@detailmenu
	19975	Mark the (optional) detailed node listing in a master menu.
	19976	@xref{Master Menu Parts}.
	19977
	19978	@item @@dfn@{@var{term}@}
	19979	Indicate the introductory or defining use of a term. @xref{@code{@@dfn}}.
	19980
	19981	@item @@DH@{@}
	19982	@itemx @@dh@{@}
	19983	Generate the uppercase and lowercase Icelandic letter eth, respectively:
	19984	@DH{}, @dh{}. @xref{Inserting Accents}.
	19985
	19986	@item @@dircategory @var{dirpart}
	19987	Specify a part of the Info directory menu where this file's entry should
	19988	go. @xref{Installing Dir Entries}.
	19989
	19990	@item @@direntry
	19991	Begin the Info directory menu entry for this file. Pair with
	19992	@code{@@end direntry}. @xref{Installing Dir Entries}.
	19993
	19994	@item @@display
	19995	Begin a kind of example. Like @code{@@example} (indent text, do not
	19996	fill), but do not select a new font. Pair with @code{@@end display}.
	19997	@xref{@code{@@display}}.
	19998
	19999	@item @@dmn@{@var{dimension}@}
	20000	Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
	20001	thin space before @var{dimension}. No effect in Info.
	20002	@xref{@code{@@dmn}}.
	20003
	20004	@item @@docbook
	20005	Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw
	20006	Formatter Commands}.
	20007
	20008	@item @@documentdescription
	20009	Set the document description text, included in the HTML output. Pair
	20010	with @code{@@end documentdescription}. @xref{@code{@@documentdescription}}.
	20011
	20012	@item @@documentencoding @var{enc}
	20013	Declare the input encoding to be @var{enc}.
	20014	@xref{@code{@@documentencoding}}.
	20015
	20016	@item @@documentlanguage @var{CC}
	20017	Declare the document language as the two-character ISO-639 abbreviation
	20018	@var{CC}. @xref{@code{@@documentlanguage}}.
	20019
	20020	@item @@dotaccent@{@var{c}@}
	20021	Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
	20022	@xref{Inserting Accents}.
	20023
	20024	@item @@dotless@{@var{i-or-j}@}
	20025	Generate dotless i (`@dotless{i}') and dotless j (`@dotless{j}').
	20026	@xref{Inserting Accents}.
	20027
	20028	@item @@dots@{@}
	20029	Generate an ellipsis, @samp{@dots{}}.
	20030	@xref{@code{@@dots}}.
	20031
	20032	@item @@email@{@var{address}[, @var{displayed-text}]@}
	20033	Indicate an electronic mail address. @xref{@code{@@email}}.
	20034
	20035	@item @@emph@{@var{text}@}
	20036	Emphasize @var{text}, by using @emph{italics} where possible, and
	20037	enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}.
	20038
	20039	@item @@end @var{environment}
	20040	Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
	20041	Commands,,@@-commands}.
	20042
	20043	@item @@enddots@{@}
	20044	Generate an end-of-sentence ellipsis, like this: @enddots{}
	20045	@xref{@code{@@dots}}.
	20046
	20047	@item @@enumerate [@var{number-or-letter}]
	20048	Begin a numbered list, using @code{@@item} for each entry.
	20049	Optionally, start list with @var{number-or-letter}. Pair with
	20050	@code{@@end enumerate}. @xref{@code{@@enumerate}}.
	20051
	20052	@item @@env@{@var{environment-variable}@}
	20053	Indicate an environment variable name, such as @env{PATH}.
	20054	@xref{@code{@@env}}.
	20055
	20056	@item @@equiv@{@}
	20057	Indicate to the reader the exact equivalence of two forms with a
	20058	glyph: @samp{@equiv{}}. @xref{@code{@@equiv}}.
	20059
	20060	@item @@error@{@}
	20061	Indicate to the reader with a glyph that the following text is
	20062	an error message: @samp{@error{}}. @xref{@code{@@error}}.
	20063
	20064	@item @@errormsg@{@var{msg}@}
	20065	Report @var{msg} as an error to standard error, and exit unsuccessfully.
	20066	Texinfo commands within @var{msg} are expanded to plain text.
	20067	@xref{Conditionals}, and @ref{External Macro Processors}.
	20068
	20069	@item @@euro@{@}
	20070	Generate the Euro currency sign. @xref{@code{@@euro}}.
	20071
	20072	@item @@evenfooting [@var{left}] @@\| [@var{center}] @@\| [@var{right}]
	20073	@itemx @@evenheading [@var{left}] @@\| [@var{center}] @@\| [@var{right}]
	20074	Specify page footings resp.@: headings for even-numbered (left-hand)
	20075	pages. @xref{Custom Headings, ,
	20076	How to Make Your Own Headings}.
	20077
	20078	@item @@everyfooting [@var{left}] @@\| [@var{center}] @@\| [@var{right}]
	20079	@itemx @@everyheading [@var{left}] @@\| [@var{center}] @@\| [@var{right}]
	20080	Specify page footings resp.@: headings for every page. Not relevant to
	20081	Info. @xref{Custom Headings, , How to Make Your Own Headings}.
	20082
	20083	@item @@example
	20084	Begin an example. Indent text, do not fill, and select fixed-width
	20085	font. Pair with @code{@@end example}. @xref{@code{@@example}}.
	20086
	20087	@item @@exampleindent @var{indent}
	20088	Indent example-like environments by @var{indent} number of spaces
	20089	(perhaps 0). @xref{@code{@@exampleindent}}.
	20090
	20091	@item @@exclamdown@{@}
	20092	Generate an upside-down exclamation point. @xref{Inserting Accents}.
	20093
	20094	@item @@exdent @var{line-of-text}
	20095	Remove any indentation a line might have. @xref{@code{@@exdent}}.
	20096
	20097	@item @@expansion@{@}
	20098	Indicate the result of a macro expansion to the reader with a special
	20099	glyph: @samp{@expansion{}}. @xref{@code{@@expansion}}.
	20100
	20101	@item @@file@{@var{filename}@}
	20102	Highlight the name of a file, buffer, node, directory, etc.
	20103	@xref{@code{@@file}}.
	20104
	20105	@item @@finalout
	20106	Prevent @TeX{} from printing large black warning rectangles beside
	20107	over-wide lines. @xref{Overfull hboxes}.
	20108
	20109	@item @@findex @var{entry}
	20110	Add @var{entry} to the index of functions. @xref{Index Entries, ,
	20111	Defining the Entries of an Index}.
	20112
	20113	@item @@firstparagraphindent @var{word}
	20114	Control indentation of the first paragraph after section headers
	20115	according to @var{word}, one of `none' or `insert'.
	20116	@xref{@code{@@firstparagraphindent}}.
	20117
	20118	@item @@float
	20119	Environment to define floating material. Pair with @code{@@end float}.
	20120	@xref{Floats}.
	20121
	20122	@item @@flushleft
	20123	@itemx @@flushright
	20124	Do not fill text; left (right) justify every line while leaving the
	20125	right (left) end ragged. Leave font as is. Pair with @code{@@end
	20126	flushleft} (@code{@@end flushright}). @xref{@code{@@flushleft
	20127	@@flushright}}.
	20128
	20129	@item @@fonttextsize @var{10-11}
	20130	Change the size of the main body font in the @TeX{} output.
	20131	@xref{Fonts}.
	20132
	20133	@item @@footnote@{@var{text-of-footnote}@}
	20134	Enter a footnote. Footnote text is printed at the bottom of the page
	20135	by @TeX{}; Info may format in either `End' node or `Separate' node style.
	20136	@xref{Footnotes}.
	20137
	20138	@item @@footnotestyle @var{style}
	20139	Specify an Info file's footnote style, either @samp{end} for the end
	20140	node style or @samp{separate} for the separate node style.
	20141	@xref{Footnotes}.
	20142
	20143	@item @@format
	20144	Begin a kind of example. Like @code{@@display}, but do not indent.
	20145	Pair with @code{@@end format}. @xref{@code{@@example}}.
	20146
	20147	@item @@frenchspacing @var{on-off}
	20148	Control spacing after punctuation. @xref{@code{@@frenchspacing}}.
	20149
	20150	@item @@ftable @var{formatting-command}
	20151	Begin a two-column table, using @code{@@item} for each entry.
	20152	Automatically enter each of the items in the first column into the
	20153	index of functions. Pair with @code{@@end ftable}. The same as
	20154	@code{@@table}, except for indexing. @xref{@code{@@ftable @@vtable}}.
	20155
	20156	@item @@geq@{@}
	20157	Generate a greater-than-or-equal sign, `@geq{}'. @xref{@code{@@geq @@leq}}.
	20158
	20159	@item @@group
	20160	Disallow page breaks within following text. Pair with @code{@@end
	20161	group}. Ignored in Info. @xref{@code{@@group}}.
	20162
	20163	@item @@guillemetleft@{@}
	20164	@itemx @@guillemetright@{@}
	20165	@item @@guillemotleft@{@}
	20166	@itemx @@guillemotright@{@}
	20167	@itemx @@guilsinglleft@{@}
	20168	@itemx @@guilsinglright@{@}
	20169	Double and single angle quotation marks: @guillemetleft{}
	20170	@guillemetright{} @guilsinglleft{} @guilsinglright{}.
	20171	@code{@@guillemotleft} and @code{@@guillemotright} are synonyms for
	20172	@code{@@guillemetleft} and @code{@@guillemetright}. @xref{Inserting
	20173	Quotation Marks}.
	20174
	20175	@item @@H@{@var{c}@}
	20176	Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
	20177
	20178	@item @@hashchar@{@}
	20179	Insert a hash `#' character; only needed when a literal hash would
	20180	introduce @code{#line} directive. @xref{Inserting a Hashsign}, and
	20181	@ref{External Macro Processors}.
	20182
	20183	@item @@heading @var{title}
	20184	Print an unnumbered section-like heading, but omit from the table of
	20185	contents. In Info, the title is underlined with equal signs.
	20186	@xref{@code{@@unnumberedsec @@appendixsec @@heading}}.
	20187
	20188	@item @@headings @var{on-off-single-double}
	20189	Turn page headings on or off, and/or specify single-sided or double-sided
	20190	page headings for printing. @xref{@code{@@headings}}.
	20191
	20192	@item @@headitem
	20193	Begin a heading row in a multitable. @xref{Multitable Rows}.
	20194
	20195	@item @@headitemfont@{@var{text}@}
	20196	Set @var{text} in the font used for multitable heading rows; mostly
	20197	useful in multitable templates. @xref{Multitable Rows}.
	20198
	20199	@item @@html
	20200	Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
	20201	Formatter Commands}.
	20202
	20203	@item @@hyphenation@{@var{hy-phen-a-ted words}@}
	20204	Explicitly define hyphenation points. @xref{@code{@@- @@hyphenation}}.
	20205
	20206	@item @@i@{@var{text}@}
	20207	Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}.
	20208
	20209	@item @@ifclear @var{txivar}
	20210	If the Texinfo variable @var{txivar} is not set, format the following
	20211	text. Pair with @code{@@end ifclear}. @xref{@code{@@set @@clear
	20212	@@value}}.
	20213
	20214	@item @@ifcommanddefined @var{txicmd}
	20215	@itemx @@ifcommandnotdefined @var{txicmd}
	20216	If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the
	20217	follow text. Pair with the corresponding @code{@@end ifcommand...}.
	20218	@xref{Testing for Texinfo Commands}.
	20219
	20220	@item @@ifdocbook
	20221	@itemx @@ifhtml
	20222	@itemx @@ifinfo
	20223	Begin text that will appear only in the given output format.
	20224	@code{@@ifinfo} output appears in both Info and (for historical
	20225	compatibility) plain text output. Pair with @code{@@end ifdocbook}
	20226	resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
	20227	@xref{Conditionals}.
	20228
	20229	@item @@ifnotdocbook
	20230	@itemx @@ifnothtml
	20231	@itemx @@ifnotplaintext
	20232	@itemx @@ifnottex
	20233	@itemx @@ifnotxml
	20234	Begin text to be ignored in one output format but not the others.
	20235	@code{@@ifnothtml} text is omitted from HTML output, etc. Pair with
	20236	the corresponding @code{@@end ifnot@var{format}}.
	20237	@xref{Conditionals}.
	20238
	20239	@item @@ifnotinfo
	20240	Begin text to appear in output other than Info and (for historical
	20241	compatibility) plain text. Pair with @code{@@end ifnotinfo}.
	20242	@xref{Conditionals}.
	20243
	20244	@item @@ifplaintext
	20245	Begin text that will appear only in the plain text output.
	20246	Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
	20247
	20248	@item @@ifset @var{txivar}
	20249	If the Texinfo variable @var{txivar} is set, format the following
	20250	text. Pair with @code{@@end ifset}. @xref{@code{@@set @@clear
	20251	@@value}}.
	20252
	20253	@item @@iftex
	20254	Begin text to appear only in the @TeX{} output. Pair with @code{@@end
	20255	iftex}. @xref{Conditionals, , Conditionally Visible Text}.
	20256
	20257	@item @@ifxml
	20258	Begin text that will appear only in the XML output. Pair with
	20259	@code{@@end ifxml}. @xref{Conditionals}.
	20260
	20261	@item @@ignore
	20262	Begin text that will not appear in any output. Pair with @code{@@end
	20263	ignore}. @xref{Comments, , Comments and Ignored Text}.
	20264
	20265	@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
	20266	Include graphics image in external @var{filename} scaled to the given
	20267	@var{width} and/or @var{height}, using @var{alt} text and looking for
	20268	@samp{@var{filename}.@var{ext}} in HTML@. @xref{Images}.
	20269
	20270	@item @@include @var{filename}
	20271	Read the contents of Texinfo source file @var{filename}. @xref{Include Files}.
	20272
	20273	@item @@indent
	20274	Insert paragraph indentation. @xref{@code{@@indent}}.
	20275
	20276	@item @@indentedblock
	20277	Indent a block of arbitary text on the left. Pair with @code{@@end
	20278	indentedblock}. @xref{@code{@@indentedblock}}.
	20279
	20280	@item @@indicateurl@{@var{indicateurl}@}
	20281	Indicate text that is a uniform resource locator for the World Wide
	20282	Web. @xref{@code{@@indicateurl}}.
	20283
	20284	@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
	20285	Make a cross-reference to an Info file for which there is no printed
	20286	manual. @xref{@code{@@inforef}}.
	20287
	20288	@item @@inlinefmt@{@var{fmt}, @var{text}@}
	20289	Insert @var{text} only if the output format is @var{fmt}.
	20290	@xref{Inline Conditionals}.
	20291
	20292	@item @@inlinefmtifelse@{@var{fmt}, @var{text}, @var{else-text}@}
	20293	Insert @var{text} if the output format is @var{fmt}, else @var{else-text}.
	20294
	20295	@item @@inlineifclear@{@var{var}, @var{text}@}
	20296	@itemx @@inlineifset@{@var{var}, @var{text}@}
	20297	Insert @var{text} only if the Texinfo variable @var{var} is (not) set.
	20298
	20299	@item @@inlineraw@{@var{fmt}, @var{raw-text}@}
	20300	Insert @var{text} as in a raw conditional, only if the output format
	20301	is @var{fmt}.
	20302
	20303	@item \input @var{macro-definitions-file}
	20304	Use the specified macro definitions file. This command is used only
	20305	in the first line of a Texinfo file to cause @TeX{} to make use of the
	20306	@file{texinfo} macro definitions file. The @code{\} in @code{\input}
	20307	is used instead of an @code{@@} because @TeX{} does not recognize
	20308	@code{@@} until after it has read the definitions file. @xref{Texinfo
	20309	File Header}.
	20310
	20311	@item @@insertcopying
	20312	Insert the text previously defined with the @code{@@copying}
	20313	environment. @xref{@code{@@insertcopying}}.
	20314
	20315	@item @@item
	20316	Indicate the beginning of a marked paragraph for @code{@@itemize} and
	20317	@code{@@enumerate}; indicate the beginning of the text of a first column
	20318	entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
	20319	@xref{Lists and Tables}.
	20320
	20321	@item @@itemize @var{mark-generating-character-or-command}
	20322	Begin an unordered list: indented paragraphs with a mark, such as
	20323	@code{@@bullet}, inside the left margin at the beginning of each item.
	20324	Pair with @code{@@end itemize}. @xref{@code{@@itemize}}.
	20325
	20326	@item @@itemx
	20327	Like @code{@@item} but do not generate extra vertical space above the
	20328	item text. Thus, when several items have the same description, use
	20329	@code{@@item} for the first and @code{@@itemx} for the others.
	20330	@xref{@code{@@itemx}}.
	20331
	20332	@item @@kbd@{@var{keyboard-characters}@}
	20333	Indicate characters of input to be typed by users. @xref{@code{@@kbd}}.
	20334
	20335	@item @@kbdinputstyle @var{style}
	20336	Specify when @code{@@kbd} should use a font distinct from
	20337	@code{@@code} according to @var{style}: @code{code}, @code{distinct},
	20338	@code{example}. @xref{@code{@@kbd}}.
	20339
	20340	@item @@key@{@var{key-name}@}
	20341	Indicate the name of a key on a keyboard. @xref{@code{@@key}}.
	20342
	20343	@item @@kindex @var{entry}
	20344	Add @var{entry} to the index of keys.
	20345	@xref{Index Entries, , Defining the Entries of an Index}.
	20346
	20347	@item @@L@{@}
	20348	@itemx @@l@{@}
	20349	Generate the uppercase and lowercase Polish suppressed-L letters,
	20350	respectively: @L{}, @l{}.
	20351
	20352	@item @@LaTeX@{@}
	20353	Generate the @LaTeX{} logo. @xref{@code{@@TeX @@LaTeX}}.
	20354
	20355	@item @@leq@{@}
	20356	Generate a less-than-or-equal sign, `@leq{}'. @xref{@code{@@geq @@leq}}.
	20357
	20358	@item @@lisp
	20359	Begin an example of Lisp code. Indent text, do not fill, and select
	20360	fixed-width font. Pair with @code{@@end lisp}. @xref{@code{@@lisp}}.
	20361
	20362	@item @@listoffloats
	20363	Produce a table-of-contents-like listing of @code{@@float}s.
	20364	@xref{@code{@@listoffloats}}.
	20365
	20366	@item @@lowersections
	20367	Change subsequent chapters to sections, sections to subsections, and so
	20368	on. @xref{Raise/lower sections, , @code{@@raisesections} and
	20369	@code{@@lowersections}}.
	20370
	20371	@item @@macro @var{macroname} @{@var{params}@}
	20372	Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
	20373	Pair with @code{@@end macro}. @xref{Defining Macros}.
	20374
	20375	@item @@majorheading @var{title}
	20376	Print an unnumbered chapter-like heading, but omit from the table of
	20377	contents. This generates more vertical whitespace before the heading
	20378	than the @code{@@chapheading} command. @xref{@code{@@majorheading
	20379	@@chapheading}}.
	20380
	20381	@item @@math@{@var{mathematical-expression}@}
	20382	Format a mathematical expression. @xref{Inserting Math}.
	20383
	20384	@item @@menu
	20385	Mark the beginning of a menu of nodes. No effect in a printed manual.
	20386	Pair with @code{@@end menu}. @xref{Menus}.
	20387
	20388	@item @@minus@{@}
	20389	Generate a minus sign, `@minus{}'. @xref{@code{@@minus}}.
	20390
	20391	@item @@multitable @var{column-width-spec}
	20392	Begin a multi-column table. Begin each row with @code{@@item} or
	20393	@code{@@headitem}, and separate columns with @code{@@tab}. Pair with
	20394	@code{@@end multitable}. @xref{Multitable Column Widths}.
	20395
	20396	@item @@need @var{n}
	20397	Start a new page in a printed manual if fewer than @var{n} mils
	20398	(thousandths of an inch) remain on the current page.
	20399	@xref{@code{@@need}}.
	20400
	20401	@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
	20402	Begin a new node. @xref{Writing a Node}.
	20403
	20404	@item @@noindent
	20405	Prevent text from being indented as if it were a new paragraph.
	20406	@xref{@code{@@noindent}}.
	20407
	20408	@item @@novalidate
	20409	Suppress validation of node references and omit creation of auxiliary
	20410	files with @TeX{}. Use before any sectioning or cross-reference
	20411	commands. @xref{Pointer Validation}.
	20412
	20413	@item @@O@{@}
	20414	@itemx @@o@{@}
	20415	Generate the uppercase and lowercase O-with-slash letters, respectively:
	20416	@O{}, @o{}.
	20417
	20418	@item @@oddfooting [@var{left}] @@\| [@var{center}] @@\| [@var{right}]
	20419	@itemx @@oddheading [@var{left}] @@\| [@var{center}] @@\| [@var{right}]
	20420	Specify page footings resp.@: headings for odd-numbered (right-hand)
	20421	pages. @xref{Custom Headings, ,
	20422	How to Make Your Own Headings}.
	20423
	20424	@item @@OE@{@}
	20425	@itemx @@oe@{@}
	20426	Generate the uppercase and lowercase OE ligatures, respectively:
	20427	@OE{}, @oe{}. @xref{Inserting Accents}.
	20428
	20429	@item @@ogonek@{@var{c}@}
	20430	Generate an ogonek diacritic under the next character, as in
	20431	@ogonek{a}. @xref{Inserting Accents}.
	20432
	20433	@item @@option@{@var{option-name}@}
	20434	Indicate a command-line option, such as @option{-l} or
	20435	@option{--help}. @xref{@code{@@option}}.
	20436
	20437	@item @@ordf@{@}
	20438	@itemx @@ordm@{@}
	20439	Generate the feminine and masculine Spanish ordinals, respectively:
	20440	@ordf{}, @ordm{}. @xref{Inserting Accents}.
	20441
	20442	@item @@page
	20443	Start a new page in a printed manual. No effect in Info.
	20444	@xref{@code{@@page}}.
	20445
	20446	@item @@pagesizes [@var{width}][, @var{height}]
	20447	Change page dimensions. @xref{pagesizes}.
	20448
	20449	@item @@paragraphindent @var{indent}
	20450	Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
	20451	source file indentation if @var{indent} is @code{asis}.
	20452	@xref{@code{@@paragraphindent}}.
	20453
	20454	@item @@part @var{title}
	20455	Begin a group of chapters or appendixes; included in the tables of
	20456	contents and produces a page of its own in printed output.
	20457	@xref{@code{@@part}}.
	20458
	20459	@item @@pindex @var{entry}
	20460	Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
	20461	the Entries of an Index}.
	20462
	20463	@item @@point@{@}
	20464	Indicate the position of point in a buffer to the reader with a glyph:
	20465	@samp{@point{}}. @xref{@code{@@point}}.
	20466
	20467	@item @@pounds@{@}
	20468	Generate the pounds sterling currency sign.
	20469	@xref{@code{@@pounds}}.
	20470
	20471	@item @@print@{@}
	20472	Indicate printed output to the reader with a glyph: @samp{@print{}}.
	20473	@xref{@code{@@print}}.
	20474
	20475	@item @@printindex @var{index-name}
	20476	Generate the alphabetized index for @var{index-name} (using two
	20477	columns in a printed manual). @xref{Printing Indices & Menus}.
	20478
	20479	@item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
	20480	Make a reference that starts with a lowercase `see' in a printed
	20481	manual. Use within parentheses only. Only the first argument is
	20482	mandatory. @xref{@code{@@pxref}}.
	20483
	20484	@item @@questiondown@{@}
	20485	Generate an upside-down question mark. @xref{Inserting Accents}.
	20486
	20487	@item @@quotation
	20488	Narrow the margins to indicate text that is quoted from another work.
	20489	Takes optional argument specifying prefix text, e.g., an author name.
	20490	Pair with @code{@@end quotation}. @xref{@code{@@quotation}}.
	20491
	20492	@item @@quotedblleft@{@}
	20493	@itemx @@quotedblright@{@}
	20494	@itemx @@quoteleft@{@}
	20495	@itemx @@quoteright@{@}
	20496	@itemx @@quotedblbase@{@}
	20497	@itemx @@quotesinglbase@{@}
	20498	Produce various quotation marks: @quotedblleft{} @quotedblright{}
	20499	@quoteleft{} @quoteright{} @quotedblbase{} @quotesinglbase{}.
	20500	@xref{Inserting Quotation Marks}.
	20501
	20502	@item @@r@{@var{text}@}
	20503	Set @var{text} in the regular @r{roman} font. No effect in Info.
	20504	@xref{Fonts}.
	20505
	20506	@item @@raggedright
	20507	Fill text; left justify every line while leaving the right end ragged.
	20508	Leave font as is. Pair with @code{@@end raggedright}. No effect in
	20509	Info. @xref{@code{@@raggedright}}.
	20510
	20511	@item @@raisesections
	20512	Change subsequent sections to chapters, subsections to sections, and so
	20513	on. @xref{Raise/lower sections}.
	20514
	20515	@item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
	20516	Make a plain reference that does not start with any special text.
	20517	Follow command with a punctuation mark. Only the first argument is
	20518	mandatory. @xref{@code{@@ref}}.
	20519
	20520	@item @@refill
	20521	@findex refill
	20522	This command used to refill and indent the paragraph after all the
	20523	other processing has been done. It is no longer needed, since all
	20524	formatters now automatically refill as needed, but you may still see
	20525	it in the source to some manuals, as it does no harm.
	20526
	20527	@item @@registeredsymbol@{@}
	20528	Generate the legal symbol @registeredsymbol{}.
	20529	@xref{@code{@@registeredsymbol}}.
	20530
	20531	@item @@result@{@}
	20532	Indicate the result of an expression to the reader with a special
	20533	glyph: @samp{@result{}}. @xref{@code{@@result}}.
	20534
	20535	@item @@ringaccent@{@var{c}@}
	20536	Generate a ring accent over the next character, as in @ringaccent{o}.
	20537	@xref{Inserting Accents}.
	20538
	20539	@item @@samp@{@var{text}@}
	20540	Indicate a literal example of a sequence of characters, in general.
	20541	Quoted in Info output. @xref{@code{@@samp}}.
	20542
	20543	@item @@sansserif@{@var{text}@}
	20544	Set @var{text} in a @sansserif{sans serif} font if possible. No
	20545	effect in Info. @xref{Fonts}.
	20546
	20547	@item @@sc@{@var{text}@}
	20548	Set @var{text} in a small caps font in printed output, and uppercase
	20549	in Info. @xref{Smallcaps}.
	20550
	20551	@item @@section @var{title}
	20552	Begin a section within a chapter. The section title appears in the
	20553	table of contents. In Info, the title is underlined with equal signs.
	20554	Within @code{@@chapter} and @code{@@appendix}, the section title is
	20555	numbered; within @code{@@unnumbered}, the section is unnumbered.
	20556	@xref{@code{@@section}}.
	20557
	20558	@item @@set @var{txivar} [@var{string}]
	20559	Define the Texinfo variable @var{txivar}, optionally to the value
	20560	@var{string}. @xref{@code{@@set @@clear @@value}}.
	20561
	20562	@item @@setchapternewpage @var{on-off-odd}
	20563	Specify whether chapters start on new pages, and if so, whether on
	20564	odd-numbered (right-hand) new pages. @xref{@code{@@setchapternewpage}}.
	20565
	20566	@item @@setfilename @var{info-file-name}
	20567	Provide a name to be used for the output files. This command is ignored
	20568	for @TeX{} formatting. @xref{@code{@@setfilename}}.
	20569
	20570	@item @@settitle @var{title}
	20571	Specify the title for page headers in a printed manual, and the
	20572	default document title for HTML @samp{<head>}.
	20573	@xref{@code{@@settitle}}.
	20574
	20575	@item @@shortcaption
	20576	Define the short caption for a @code{@@float}. @xref{@code{@@caption
	20577	@@shortcaption}}.
	20578
	20579	@item @@shortcontents
	20580	Print a short table of contents, with chapter-level entries only. Not
	20581	relevant to Info, which uses menus rather than tables of contents.
	20582	@xref{Contents, , Generating a Table of Contents}.
	20583
	20584	@item @@shorttitlepage @var{title}
	20585	Generate a minimal title page. @xref{@code{@@titlepage}}.
	20586
	20587	@item @@slanted@{@var{text}@}
	20588	Set @var{text} in a @slanted{slanted} font if possible. No effect
	20589	in Info. @xref{Fonts}.
	20590
	20591	@item @@smallbook
	20592	Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
	20593	rather than the regular 8.5 by 11 inch format.
	20594	@xref{@code{@@smallbook}}. Also, see @ref{@code{@@small@dots{}}}.
	20595
	20596	@item @@smalldisplay
	20597	Begin a kind of example. Like @code{@@display}, but use a smaller
	20598	font size where possible. Pair with @code{@@end smalldisplay}.
	20599	@xref{@code{@@small@dots{}}}.
	20600
	20601	@item @@smallexample
	20602	Begin an example. Like @code{@@example}, but use a smaller font size
	20603	where possible. Pair with @code{@@end smallexample}.
	20604	@xref{@code{@@small@dots{}}}.
	20605
	20606	@item @@smallformat
	20607	Begin a kind of example. Like @code{@@format}, but use a smaller font
	20608	size where possible. Pair with @code{@@end smallformat}.
	20609	@xref{@code{@@small@dots{}}}.
	20610
	20611	@item @@smallindentedblock
	20612	Like @code{@@indentedblock}, but use a smaller font size where
	20613	possible. Pair with @code{@@end smallindentedblock}.
	20614	@xref{@code{@@small@dots{}}}.
	20615
	20616	@item @@smalllisp
	20617	Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
	20618	with @code{@@end smalllisp}. @xref{@code{@@small@dots{}}}.
	20619
	20620	@item @@smallquotation
	20621	Like @code{@@quotation}, but use a smaller font size where possible.
	20622	Pair with @code{@@end smallquotation}. @xref{@code{@@small@dots{}}}.
	20623
	20624	@item @@sortas @{@var{key}@}
	20625	Used in the arguments to index commands to give a string by which the
	20626	index entry should be sorted. @xref{Indexing Commands}.
	20627
	20628	@item @@sp @var{n}
	20629	Skip @var{n} blank lines. @xref{@code{@@sp}}.
	20630
	20631	@item @@ss@{@}
	20632	Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
	20633
	20634	@item @@strong @{@var{text}@}
	20635	Emphasize @var{text} more strongly than @code{@@emph}, by using
	20636	@strong{boldface} where possible; enclosed in asterisks in Info.
	20637	@xref{emph & strong, , Emphasizing Text}.
	20638
	20639	@item @@sub @{@var{text}@}
	20640	Set @var{text} as a subscript. @xref{Inserting Subscripts and Superscripts}.
	20641
	20642	@item @@subheading @var{title}
	20643	Print an unnumbered subsection-like heading, but omit from the table
	20644	of contents of a printed manual. In Info, the title is underlined
	20645	with hyphens. @xref{@code{@@unnumberedsubsec @@appendixsubsec @@subheading}}.
	20646
	20647	@item @@subsection @var{title}
	20648	Begin a subsection within a section. The subsection title appears in
	20649	the table of contents. In Info, the title is underlined with hyphens.
	20650	Same context-dependent numbering as @code{@@section}.
	20651	@xref{@code{@@subsection}}.
	20652
	20653	@item @@subsubheading @var{title}
	20654	Print an unnumbered subsubsection-like heading, but omit from the
	20655	table of contents of a printed manual. In Info, the title is
	20656	underlined with periods. @xref{@code{@@subsubsection}}.
	20657
	20658	@item @@subsubsection @var{title}
	20659	Begin a subsubsection within a subsection. The subsubsection title
	20660	appears in the table of contents. In Info, the title is underlined
	20661	with periods. Same context-dependent numbering as @code{@@section}.
	20662	@xref{@code{@@subsubsection}}.
	20663
	20664	@item @@subtitle @var{title}
	20665	In a printed manual, set a subtitle in a normal sized font flush to
	20666	the right-hand side of the page. Not relevant to Info, which does not
	20667	have title pages. @xref{@code{@@title @@subtitle @@author}}.
	20668
	20669	@item @@summarycontents
	20670	Print a short table of contents. Synonym for @code{@@shortcontents}.
	20671	@xref{Contents, , Generating a Table of Contents}.
	20672
	20673	@item @@sup @{@var{text}@}
	20674	Set @var{text} as a superscript. @xref{Inserting Subscripts and Superscripts}.
	20675
	20676	@item @@syncodeindex @var{from-index} @var{to-index}
	20677	Merge the index named in the first argument into the index named in
	20678	the second argument, formatting the entries from the first index with
	20679	@code{@@code}. @xref{Combining Indices}.
	20680
	20681	@item @@synindex @var{from-index} @var{to-index}
	20682	Merge the index named in the first argument into the index named in
	20683	the second argument. Do not change the font of @var{from-index}
	20684	entries. @xref{Combining Indices}.
	20685
	20686	@item @@t@{@var{text}@}
	20687	Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect
	20688	in Info. @xref{Fonts}.
	20689
	20690	@item @@tab
	20691	Separate columns in a row of a multitable. @xref{Multitable Rows}.
	20692
	20693	@item @@table @var{formatting-command}
	20694	Begin a two-column table (description list), using @code{@@item} for
	20695	each entry. Write each first column entry on the same line as
	20696	@code{@@item}. First column entries are printed in the font resulting
	20697	from @var{formatting-command}. Pair with @code{@@end table}.
	20698	@xref{Two-column Tables, , Making a Two-column Table}. Also see
	20699	@ref{@code{@@ftable @@vtable}}, and @ref{@code{@@itemx}}.
	20700
	20701	@item @@TeX@{@}
	20702	Generate the @TeX{} logo. @xref{@code{@@TeX @@LaTeX}}.
	20703
	20704	@item @@tex
	20705	Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
	20706	Formatter Commands}.
	20707
	20708	@item @@textdegree@{@}
	20709	Generate the degree symbol. @xref{@code{@@textdegree}}.
	20710
	20711	@item @@thischapter
	20712	@itemx @@thischaptername
	20713	@itemx @@thischapternum
	20714	@itemx @@thisfile
	20715	@itemx @@thispage
	20716	@itemx @@thistitle
	20717	Only allowed in a heading or footing. Stands for, respectively, the
	20718	number and name of the current chapter (in the format `Chapter 1:
	20719	Title'), the current chapter name only, the current chapter number
	20720	only, the filename, the current page number, and the title of the
	20721	document, respectively. @xref{Custom Headings, , How to Make Your Own
	20722	Headings}.
	20723
	20724	@item @@TH@{@}
	20725	@itemx @@th@{@}
	20726	Generate the uppercase and lowercase Icelandic letter thorn, respectively:
	20727	@TH{}, @th{}. @xref{Inserting Accents}.
	20728
	20729	@item @@tie@{@}
	20730	Generate a normal interword space at which a line break is not
	20731	allowed. @xref{@code{@@tie}}.
	20732
	20733	@item @@tieaccent@{@var{cc}@}
	20734	Generate a tie-after accent over the next two characters @var{cc}, as in
	20735	`@tieaccent{oo}'. @xref{Inserting Accents}.
	20736
	20737	@item @@tindex @var{entry}
	20738	Add @var{entry} to the index of data types. @xref{Index Entries, ,
	20739	Defining the Entries of an Index}.
	20740
	20741	@item @@title @var{title}
	20742	In a printed manual, set a title flush to the left-hand side of the
	20743	page in a larger than normal font and underline it with a black rule.
	20744	Not relevant to Info, which does not have title pages.
	20745	@xref{@code{@@title @@subtitle @@author}}.
	20746
	20747	@item @@titlefont@{@var{text}@}
	20748	In a printed manual, print @var{text} in a larger than normal font.
	20749	@xref{@code{@@titlefont @@center @@sp}}.
	20750
	20751	@item @@titlepage
	20752	Begin the title page. Write the command on a line of its own, paired
	20753	with @code{@@end titlepage}. Nothing between @code{@@titlepage} and
	20754	@code{@@end titlepage} appears in Info. @xref{@code{@@titlepage}}.
	20755
	20756	@item @@today@{@}
	20757	Insert the current date, in `1 Jan 1900' style. @xref{Custom
	20758	Headings, , How to Make Your Own Headings}.
	20759
	20760	@item @@top @var{title}
	20761	Mark the topmost @code{@@node} in the file, which must be defined on
	20762	the line immediately preceding the @code{@@top} command. The title is
	20763	formatted as a chapter-level heading. The entire top node, including
	20764	the @code{@@node} and @code{@@top} lines, are normally enclosed with
	20765	@code{@@ifnottex ... @@end ifnottex}. In @TeX{} and
	20766	@code{texinfo-format-buffer}, the @code{@@top} command is merely a
	20767	synonym for @code{@@unnumbered}. @xref{@command{makeinfo} Pointer
	20768	Creation}.
	20769
	20770	@item @@U@{@var{hex}@}
	20771	Output a representation of Unicode character U+@var{hex}.
	20772	@xref{Inserting Unicode}.
	20773
	20774	@item @@u@{@var{c}@}
	20775	@itemx @@ubaraccent@{@var{c}@}
	20776	@itemx @@udotaccent@{@var{c}@}
	20777	Generate a breve, underbar, or underdot accent, respectively, over or
	20778	under the character @var{c}, as in @u{o}, @ubaraccent{o},
	20779	@udotaccent{o}. @xref{Inserting Accents}.
	20780
	20781	@item @@unmacro @var{macroname}
	20782	Undefine the macro @code{@@@var{macroname}} if it has been defined.
	20783	@xref{Defining Macros}.
	20784
	20785	@item @@unnumbered @var{title}
	20786	Begin a chapter that appears without chapter numbers of any kind. The
	20787	title appears in the table of contents. In Info, the title is
	20788	underlined with asterisks. @xref{@code{@@unnumbered @@appendix}}.
	20789
	20790	@item @@unnumberedsec @var{title}
	20791	Begin a section that appears without section numbers of any kind. The
	20792	title appears in the table of contents of a printed manual. In Info,
	20793	the title is underlined with equal signs. @xref{@code{@@unnumberedsec
	20794	@@appendixsec @@heading}}.
	20795
	20796	@item @@unnumberedsubsec @var{title}
	20797	Begin an unnumbered subsection. The title appears in the table of
	20798	contents. In Info, the title is underlined with hyphens.
	20799	@xref{@code{@@unnumberedsubsec @@appendixsubsec @@subheading}}.
	20800
	20801	@item @@unnumberedsubsubsec @var{title}
	20802	Begin an unnumbered subsubsection. The title appears in the table of
	20803	contents. In Info, the title is underlined with periods.
	20804	@xref{@code{@@subsubsection}}.
	20805
	20806	@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
	20807	@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
	20808	Define a cross-reference to an external uniform resource locator,
	20809	e.g., for the World Wide Web. @xref{@code{@@url}}.
	20810
	20811	@item @@urefbreakstyle @var{style}
	20812	Specify how @code{@@uref}/@code{@@url} should break at special
	20813	characters: @code{after}, @code{before}, @code{none}.
	20814	@xref{@code{@@url}}.
	20815
	20816	@item @@v@{@var{c}@}
	20817	Generate check accent over the character @var{c}, as in @v{o}.
	20818	@xref{Inserting Accents}.
	20819
	20820	@item @@validatemenus @var{on-off}
	20821	Control whether menus can be automatically generated. @xref{Writing a
	20822	Menu}.
	20823
	20824	@item @@value@{@var{txivar}@}
	20825	Insert the value, if any, of the Texinfo variable @var{txivar},
	20826	previously defined by @code{@@set}. @xref{@code{@@set @@clear
	20827	@@value}}.
	20828
	20829	@item @@var@{@var{metasyntactic-variable}@}
	20830	Highlight a metasyntactic variable, which is something that stands for
	20831	another piece of text. @xref{@code{@@var}}.
	20832
	20833	@item @@verb@{@var{delim} @var{literal} @var{delim}@}
	20834	Output @var{literal}, delimited by the single character @var{delim},
	20835	exactly as is (in the fixed-width font), including any whitespace or
	20836	Texinfo special characters. @xref{@code{@@verb}}.
	20837
	20838	@item @@verbatim
	20839	Output the text of the environment exactly as is (in the fixed-width
	20840	font). Pair with @code{@@end verbatim}. @xref{@code{@@verbatim}}.
	20841
	20842	@item @@verbatiminclude @var{filename}
	20843	Output the contents of @var{filename} exactly as is (in the
	20844	fixed-width font). @xref{@code{@@verbatiminclude}}.
	20845
	20846	@item @@vindex @var{entry}
	20847	Add @var{entry} to the index of variables. @xref{Index Entries, ,
	20848	Defining the Entries of an Index}.
	20849
	20850	@item @@vskip @var{amount}
	20851	In a printed manual, insert whitespace so as to push text on the
	20852	remainder of the page towards the bottom of the page. Used in
	20853	formatting the copyright page with the argument @samp{0pt plus
	20854	1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
	20855	only in contexts ignored for Info. @xref{Copyright}.
	20856
	20857	@item @@vtable @var{formatting-command}
	20858	Begin a two-column table, using @code{@@item} for each entry.
	20859	Automatically enter each of the items in the first column into the
	20860	index of variables. Pair with @code{@@end vtable}. The same as
	20861	@code{@@table}, except for indexing. @xref{@code{@@ftable @@vtable}}.
	20862
	20863	@item @@w@{@var{text}@}
	20864	Disallow line breaks within @var{text}. @xref{@code{@@w}}.
	20865
	20866	@item @@xml
	20867	Enter XML completely. Pair with @code{@@end xml}. @xref{Raw
	20868	Formatter Commands}.
	20869
	20870	@item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
	20871	Make a reference that starts with `See' in a printed manual. Follow
	20872	command with a punctuation mark. Only the first argument is
	20873	mandatory. @xref{@code{@@xref}}.
	20874
	20875	@item @@xrefautomaticsectiontitle @var{on-off}
	20876	By default, use the section title instead of the node name in cross
	20877	references. @xref{Three Arguments}.
	20878
	20879	@end table
	20880
	20881
	20882	@node Command Contexts
	20883	@section @@-Command Contexts
	20884
	20885	@cindex Contexts, of @@-commands
	20886
	20887	Here we describe approximately which @@-commands can be used in which
	20888	contexts. It not exhaustive or meant to be a complete reference.
	20889	Discrepancies between the information here and the @code{makeinfo} or
	20890	@TeX{} implementations are most likely to be resolved in favor of the
	20891	implementation.
	20892
	20893	By @dfn{general text} below, we mean anything except sectioning and
	20894	other such outer-level document commands, such as @code{@@section},
	20895	@code{@@node}, and @code{@@setfilename}.
	20896
	20897	@code{@@c}, @code{@@comment} and @code{@@if ... @@end if} conditional
	20898	commands may appear anywhere (except the conditionals must still be on
	20899	lines by themselves). @code{@@caption} may only appear in
	20900	@code{@@float} but may contain general text. @code{@@footnote}
	20901	content likewise.
	20902
	20903	@@-commands with braces marking text (such as @code{@@strong},
	20904	@code{@@sc}, @code{@@asis}) may contain raw formatter commands such as
	20905	@code{@@html} but no other block commands (other commands terminated
	20906	by @code{@@end}) and may not be split across paragraphs, but may
	20907	otherwise contain general text.
	20908
	20909	In addition to the block command restriction, on @code{@@center},
	20910	@code{@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands
	20911	that makes only sense in a paragraph are not accepted, such as
	20912	@code{@@indent}.
	20913
	20914	In addition to the above, sectioning commands cannot contain
	20915	@code{@@anchor}, @code{@@footnote} or @code{@@verb}.
	20916
	20917	In addition to the above, remaining commands (@code{@@node},
	20918	@code{@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math},
	20919	@code{@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot
	20920	contain cross-reference commands (@code{@@ref}, @code{@@xref},
	20921	@code{@@pxref} and @code{@@inforef}). In one last addition,
	20922	@code{@@shortcaption} may only appear inside @code{@@float}.
	20923
	20924	For precise and complete information, we suggest looking into the
	20925	test suite in the sources, which exhaustively tries combinations.
	20926
	20927
	20928	@node Obsolete @@-Commands
	20929	@section Obsolete @@-Commands
	20930
	20931	Here are Texinfo @@-commands which are obsolete or have been removed
	20932	completely. This section is for historical purposes.
	20933
	20934	@ftable @code
	20935	@item @@setcontentsaftertitlepage
	20936	@cindex Contents, after title page
	20937	@cindex Table of contents, after title page
	20938	In the past, the contents commands were sometimes placed at the end of
	20939	the file, after any indices and just before the @code{@@bye}, but we
	20940	no longer recommend this.
	20941	This command could be used by a user printing a manual, to force the
	20942	contents to be printed after the title page
	20943	(after the @samp{@@end titlepage} line)
	20944	even if the @code{@@contents} command was at the end of the manual. It
	20945	now does nothing.
	20946
	20947	@item @@setshortcontentsaftertitlepage
	20948	This placed the short table of contents after the @samp{@@end titlepage}
	20949	command even if the @code{@@shortcontents} command was at the end. It
	20950	now does nothing.
	20951	@end ftable
	20952
	20953
	20954	@node Tips
	20955	@appendix Tips and Hints
	20956
	20957	Here are some tips for writing Texinfo documentation:
	20958
	20959	@cindex Tips
	20960	@cindex Usage tips
	20961	@cindex Hints
	20962	@itemize @bullet
	20963	@item
	20964	Write in the present tense, not in the past or the future.
	20965
	20966	@item
	20967	Write actively! For example, write ``We recommend that @dots{}'' rather
	20968	than ``It is recommended that @dots{}''.
	20969
	20970	@item
	20971	Use 70 or 72 as your fill column. Longer lines are hard to read.
	20972
	20973	@item
	20974	Include a copyright notice and copying permissions.
	20975	@end itemize
	20976
	20977
	20978	@subsubheading Index, Index, Index!
	20979
	20980	Write many index entries, in different ways.
	20981	Readers like indices; they are helpful and convenient.
	20982
	20983	Although it is easiest to write index entries as you write the body of
	20984	the text, some people prefer to write entries afterwards. In either
	20985	case, write an entry before the paragraph to which it applies. This
	20986	way, an index entry points to the first page of a paragraph that is
	20987	split across pages.
	20988
	20989	Here are more index-related hints we have found valuable:
	20990
	20991	@itemize @bullet
	20992	@item
	20993	Write each index entry differently, so each entry refers to a different
	20994	place in the document.
	20995
	20996	@item
	20997	Write index entries only where a topic is discussed significantly. For
	20998	example, it is not useful to index ``debugging information'' in a
	20999	chapter on reporting bugs. Someone who wants to know about debugging
	21000	information will certainly not find it in that chapter.
	21001
	21002	@item
	21003	Consistently capitalize the first word of every concept index entry,
	21004	or else consistently use lowercase. Terse entries often call for
	21005	lowercase; longer entries for capitalization. Whichever case
	21006	convention you use, please use one or the other consistently! Mixing
	21007	the two styles looks bad.
	21008
	21009	@item
	21010	Always capitalize or use uppercase for those words in an index for
	21011	which this is proper, such as names of countries or acronyms. Always
	21012	use the appropriate case for case-sensitive names, such as those in C or
	21013	Lisp.
	21014
	21015	@item
	21016	Write the indexing commands that refer to a whole section immediately
	21017	after the section command, and write the indexing commands that refer to
	21018	a paragraph before that paragraph.
	21019
	21020	In the example that follows, a blank line comes after the index
	21021	entry for ``Leaping'':
	21022
	21023	@example
	21024	@group
	21025	@@section The Dog and the Fox
	21026	@@cindex Jumping, in general
	21027	@@cindex Leaping
	21028
	21029	@@cindex Dog, lazy, jumped over
	21030	@@cindex Lazy dog jumped over
	21031	@@cindex Fox, jumps over dog
	21032	@@cindex Quick fox jumps over dog
	21033	The quick brown fox jumps over the lazy dog.
	21034	@end group
	21035	@end example
	21036
	21037	@noindent
	21038	(Note that the example shows entries for the same concept that are
	21039	written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
	21040	readers can look up the concept in different ways.)
	21041	@end itemize
	21042
	21043
	21044	@subsubheading Blank Lines
	21045
	21046	@itemize @bullet
	21047	@item
	21048	Insert a blank line between a sectioning command and the first following
	21049	sentence or paragraph, or between the indexing commands associated with
	21050	the sectioning command and the first following sentence or paragraph, as
	21051	shown in the tip on indexing. It makes the source easier to read.
	21052
	21053	@item
	21054	Always insert a blank line before a @code{@@table} command and after an
	21055	@code{@@end table} command; but never insert a blank line after an
	21056	@code{@@table} command.
	21057
	21058	@need 1000
	21059	For example,
	21060
	21061	@example
	21062	@group
	21063	Types of fox:
	21064
	21065	@@table @@samp
	21066	@@item Quick
	21067	Jump over lazy dogs.
	21068	@end group
	21069
	21070	@group
	21071	@@item Brown
	21072	Also jump over lazy dogs.
	21073	@@end table
	21074
	21075	@end group
	21076	@group
	21077	@@noindent
	21078	On the other hand, @dots{}
	21079	@end group
	21080	@end example
	21081
	21082	Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
	21083	itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
	21084	same way.
	21085	@end itemize
	21086
	21087
	21088	@subsubheading Complete Phrases
	21089
	21090	Complete phrases are easier to read than @dots{}
	21091
	21092	@itemize @bullet
	21093	@item
	21094	Write entries in an itemized list as complete sentences; or at least, as
	21095	complete phrases. Incomplete expressions @dots{} awkward @dots{} like
	21096	this.
	21097
	21098	@item
	21099	Write the prefatory sentence or phrase for a multi-item list or table as
	21100	a complete expression. Do not write ``You can set:''; instead, write
	21101	``You can set these variables:''. The former expression sounds cut off.
	21102	@end itemize
	21103
	21104
	21105	@subsubheading Editions, Dates and Versions
	21106
	21107	Include edition numbers, version numbers, and dates in the
	21108	@code{@@copying} text (for people reading the Texinfo file, and for the
	21109	legal copyright in the output files). Then use @code{@@insertcopying}
	21110	in the @code{@@titlepage} section for people reading the printed
	21111	output (@pxref{Short Sample}).
	21112
	21113	It is easiest to handle such version information using @code{@@set}
	21114	and @code{@@value}. @xref{@code{@@value} Example}, and @ref{GNU
	21115	Sample Texts}.
	21116
	21117
	21118	@subsubheading Definition Commands
	21119
	21120	Definition commands are @code{@@deffn}, @code{@@defun},
	21121	@code{@@defmac}, and the like, and enable you to write descriptions in
	21122	a uniform format.
	21123
	21124	@itemize @bullet
	21125	@item
	21126	Write just one definition command for each entity you define with a
	21127	definition command. The automatic indexing feature creates an index
	21128	entry that leads the reader to the definition.
	21129
	21130	@item
	21131	Use @code{@@table} @dots{} @code{@@end table} in an appendix that
	21132	contains a summary of functions, not @code{@@deffn} or other definition
	21133	commands.
	21134	@end itemize
	21135
	21136
	21137	@subsubheading Capitalization
	21138
	21139	@itemize @bullet
	21140	@item
	21141	Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
	21142	@samp{i} in uppercase.
	21143
	21144	@item
	21145	Capitalize ``Info''; it is a name.
	21146
	21147	@item
	21148	Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
	21149	@samp{T} and @samp{X}. This command causes the formatters to
	21150	typeset the name according to the wishes of Donald Knuth, who wrote
	21151	@TeX{}. (Likewise @code{@@LaTeX@{@}} for @LaTeX{}.)
	21152	@end itemize
	21153
	21154
	21155	@subsubheading Spaces
	21156
	21157	Do not use spaces to format a Texinfo file, except inside of
	21158	@code{@@example} @dots{} @code{@@end example} and other literal
	21159	environments and commands.
	21160
	21161	@need 700
	21162	For example, @TeX{} fills the following:
	21163
	21164	@example
	21165	@group
	21166	@@kbd@{C-x v@}
	21167	@@kbd@{M-x vc-next-action@}
	21168	Perform the next logical operation
	21169	on the version-controlled file
	21170	corresponding to the current buffer.
	21171	@end group
	21172	@end example
	21173
	21174	@need 950
	21175	@noindent
	21176	so it looks like this:
	21177
	21178	@iftex
	21179	@quotation
	21180	@kbd{C-x v}
	21181	@kbd{M-x vc-next-action}
	21182	Perform the next logical operation on the version-controlled file
	21183	corresponding to the current buffer.
	21184	@end quotation
	21185	@end iftex
	21186	@ifnottex
	21187	@quotation
	21188	`C-x v' `M-x vc-next-action' Perform the next logical operation on the
	21189	version-controlled file corresponding to the current buffer.
	21190	@end quotation
	21191	@end ifnottex
	21192
	21193	@noindent
	21194	In this case, the text should be formatted with
	21195	@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
	21196
	21197
	21198	@subsubheading @@code, @@samp, @@var, and @samp{---}
	21199
	21200	@itemize @bullet
	21201	@item
	21202	Use @code{@@code} around Lisp symbols, including command names.
	21203	For example,
	21204
	21205	@example
	21206	The main function is @@code@{vc-next-action@}, @dots{}
	21207	@end example
	21208
	21209	@item
	21210	Avoid putting letters such as @samp{s} immediately after an
	21211	@samp{@@code}. Such letters look bad.
	21212
	21213	@item
	21214	Use @code{@@var} around meta-variables. Do not write angle brackets
	21215	around them.
	21216
	21217	@item
	21218	Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
	21219	typesets these as a long dash and the Info formatters reduce three
	21220	hyphens to two.
	21221	@end itemize
	21222
	21223
	21224	@subsubheading Periods Outside of Quotes
	21225
	21226	Place periods and other punctuation marks @emph{outside} of quotations,
	21227	unless the punctuation is part of the quotation. This practice goes
	21228	against some publishing conventions in the United States, but enables the
	21229	reader to distinguish between the contents of the quotation and the
	21230	whole passage.
	21231
	21232	For example, you should write the following sentence with the period
	21233	outside the end quotation marks:
	21234
	21235	@example
	21236	Evidently, @samp{au} is an abbreviation for ``author''.
	21237	@end example
	21238
	21239	@noindent
	21240	since @samp{au} does @emph{not} serve as an abbreviation for
	21241	@samp{author.} (with a period following the word).
	21242
	21243
	21244	@subsubheading Introducing New Terms
	21245
	21246	@itemize @bullet
	21247	@item
	21248	Introduce new terms so that a reader who does not know them can
	21249	understand them from context; or write a definition for the term.
	21250
	21251	For example, in the following, the terms ``check in'', ``register'' and
	21252	``delta'' are all appearing for the first time; the example sentence should be
	21253	rewritten so they are understandable.
	21254
	21255	@quotation
	21256	The major function assists you in checking in a file to your
	21257	version control system and registering successive sets of changes to
	21258	it as deltas.
	21259	@end quotation
	21260
	21261	@item
	21262	Use the @code{@@dfn} command around a word being introduced, to indicate
	21263	that the reader should not expect to know the meaning already, and
	21264	should expect to learn the meaning from this passage.
	21265	@end itemize
	21266
	21267
	21268	@subsubheading Program Invocation Nodes
	21269
	21270	You can invoke programs such as Emacs, GCC, and @code{gawk} from a
	21271	shell. The documentation for each program should contain a section that
	21272	describes this. Unfortunately, if the node names and titles for these
	21273	sections are all different, they are difficult for users to find.
	21274
	21275	So, there is a convention to name such sections with a phrase beginning
	21276	with the word `Invoking', as in `Invoking Emacs'; this way, users can
	21277	find the section easily.
	21278
	21279
	21280	@subsubheading ANSI C Syntax
	21281
	21282	When you use @code{@@example} to describe a C function's calling
	21283	conventions, use the ANSI C syntax, like this:
	21284
	21285	@example
	21286	void dld_init (char *@@var@{path@});
	21287	@end example
	21288
	21289	@noindent
	21290	And in the subsequent discussion, refer to the argument values by
	21291	writing the same argument names, again highlighted with
	21292	@code{@@var}.
	21293
	21294	@need 800
	21295	Avoid the obsolete style that looks like this:
	21296
	21297	@example
	21298	#include <dld.h>
	21299
	21300	dld_init (path)
	21301	char *path;
	21302	@end example
	21303
	21304	Also, it is best to avoid writing @code{#include} above the
	21305	declaration just to indicate that the function is declared in a
	21306	header file. The practice may give the misimpression that the
	21307	@code{#include} belongs near the declaration of the function. Either
	21308	state explicitly which header file holds the declaration or, better
	21309	yet, name the header file used for a group of functions at the
	21310	beginning of the section that describes the functions.
	21311
	21312	@anchor{texi-elements-by-size}
	21313	@subsubheading Node Length
	21314
	21315	Keep nodes (sections) to a reasonable length, whatever reasonable
	21316	might be in the given context. Don't hesitate to break up long nodes
	21317	into subnodes and have an extensive tree structure; that's what it's
	21318	there for. Many times, readers will probably try to find a single
	21319	specific point in the manual, using search, indexing, or just plain
	21320	guessing, rather than reading the whole thing from beginning to end.
	21321
	21322	You can use the @command{texi-elements-by-size} utility to see a list
	21323	of all nodes (or sections) in the document, sorted by size (either
	21324	lines or words), to find candidates for splitting. It's in the
	21325	@file{util/} subdirectory of the Texinfo sources.
	21326
	21327
	21328	@subsubheading Bad Examples
	21329
	21330	Here are several examples of bad writing to avoid:
	21331
	21332	In this example, say, `` @dots{} you must @code{@@dfn}@{check
	21333	in@} the new version.'' That flows better.
	21334
	21335	@quotation
	21336	When you are done editing the file, you must perform a
	21337	@code{@@dfn}@{check in@}.
	21338	@end quotation
	21339
	21340	In the following example, say, ``@dots{} makes a unified interface such as VC
	21341	mode possible.''
	21342
	21343	@quotation
	21344	SCCS, RCS and other version-control systems all perform similar
	21345	functions in broadly similar ways (it is this resemblance which makes
	21346	a unified control mode like this possible).
	21347	@end quotation
	21348
	21349	And in this example, you should specify what `it' refers to:
	21350
	21351	@quotation
	21352	If you are working with other people, it assists in coordinating
	21353	everyone's changes so they do not step on each other.
	21354	@end quotation
	21355
	21356
	21357	@subsubheading And Finally @dots{}
	21358
	21359	@itemize @bullet
	21360	@item
	21361	Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
	21362	sound in the name `Bach'. But pronounce Texinfo as in `speck':
	21363	``teckinfo''.
	21364
	21365	@item
	21366	Write notes for yourself at the very end of a Texinfo file after the
	21367	@code{@@bye}. None of the formatters process text after the
	21368	@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
	21369	@code{@@end ignore}.
	21370	@end itemize
	21371
	21372
	21373	@node Sample Texinfo Files
	21374	@appendix Sample Texinfo Files
	21375	@cindex Sample Texinfo files
	21376
	21377	The first example from the first chapter (@pxref{Short Sample}) is
	21378	given here in its entirety, without commentary. The second example
	21379	includes the full texts to be used in GNU manuals.
	21380
	21381	@menu
	21382	* Short Sample Texinfo File::
	21383	* GNU Sample Texts::
	21384	* Verbatim Copying License::
	21385	* All-permissive Copying License::
	21386	@end menu
	21387
	21388
	21389	@node Short Sample Texinfo File
	21390	@section Short Sample
	21391	@cindex Sample Texinfo file, no comments
	21392
	21393	Here is a complete, short sample Texinfo file. You can see this file,
	21394	with comments, in the first chapter. @xref{Short Sample}.
	21395
	21396	In a nutshell: The @command{makeinfo} program transforms a Texinfo
	21397	source file such as this into an Info file or HTML; and @TeX{} typesets
	21398	it for a printed manual.
	21399
	21400
	21401	@sp 1
	21402	@example
	21403	\input texinfo
	21404	@@settitle Sample Manual 1.0
	21405
	21406	@@copying
	21407	This is a short example of a complete Texinfo file.
	21408
	21409	Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
	21410	@@end copying
	21411
	21412	@@titlepage
	21413	@@title Sample Title
	21414	@@page
	21415	@@vskip 0pt plus 1filll
	21416	@@insertcopying
	21417	@@end titlepage
	21418
	21419	@@c Output the table of the contents at the beginning.
	21420	@@contents
	21421
	21422	@@ifnottex
	21423	@@node Top
	21424	@@top GNU Sample
	21425
	21426	This manual is for GNU Sample
	21427	(version @@value@{VERSION@}, @@value@{UPDATED@}).
	21428	@@end ifnottex
	21429
	21430	@@menu
	21431	* First Chapter:: The first chapter is the
	21432	only chapter in this sample.
	21433	* Index:: Complete index.
	21434	@@end menu
	21435
	21436
	21437	@@node First Chapter
	21438	@@chapter First Chapter
	21439
	21440	@@cindex chapter, first
	21441
	21442	This is the first chapter.
	21443	@@cindex index entry, another
	21444
	21445	Here is a numbered list.
	21446
	21447	@@enumerate
	21448	@@item
	21449	This is the first item.
	21450
	21451	@@item
	21452	This is the second item.
	21453	@@end enumerate
	21454
	21455
	21456	@@node Index
	21457	@@unnumbered Index
	21458
	21459	@@printindex cp
	21460
	21461	@@bye
	21462	@end example
	21463
	21464
	21465	@node GNU Sample Texts
	21466	@section GNU Sample Texts
	21467
	21468	@cindex GNU sample texts
	21469	@cindex Sample texts, GNU
	21470	@cindex Full texts, GNU
	21471
	21472	Following is a sample Texinfo document with the full texts that should
	21473	be used (adapted as necessary) in GNU manuals.
	21474
	21475	As well as the legal texts, it also serves as a practical example of how
	21476	many elements in a GNU system can affect the manual. If you're not
	21477	familiar with all these different elements, don't worry. They're not
	21478	required and a perfectly good manual can be written without them.
	21479	They're included here nonetheless because many manuals do (or could)
	21480	benefit from them.
	21481
	21482	@xref{Short Sample}, for a minimal example of a Texinfo file.
	21483	@xref{Beginning and Ending a File}, for a full explanation of that
	21484	minimal example.
	21485
	21486	Here are some notes on the example:
	21487
	21488	@itemize @bullet
	21489	@item
	21490	@cindex $Id
	21491	@cindex CVS $Id
	21492	@cindex RCS $Id
	21493	@cindex Documentation identification
	21494	@cindex Identification of documentation
	21495	The @samp{$Id:} comment is for the CVS
	21496	(@url{http://www.nongnu.org/cvs/}), RCS (@pxref{Top,,, rcs, Revision
	21497	Control System}) and other version control systems, which expand it
	21498	into a string such as:
	21499
	21500	@example
	21501	$Id$
	21502	@end example
	21503
	21504	(This is potentially useful in all sources that use version control,
	21505	not just manuals.) You may wish to include the @samp{$Id:} comment in
	21506	the @code{@@copying} text, if you want a completely unambiguous
	21507	reference to the documentation source version.
	21508
	21509	If you want to literally write @t{@w{$}Id$}, use @code{@@w}:
	21510	@code{@@w@{$@}Id$}. Unfortunately, this technique does not work in
	21511	plain text output, where it's not clear what should be done.
	21512
	21513	@item
	21514	@pindex automake@r{, and version info}
	21515	@vindex UPDATED @r{Automake variable}
	21516	@vindex UPDATED-MONTH @r{Automake variable}
	21517	@vindex VERSION @r{Automake variable}
	21518	@pindex time-stamp.el
	21519	The @file{version.texi} in the @code{@@include} command is maintained
	21520	automatically by Automake (@pxref{Texinfo,,, automake, GNU Automake}).
	21521	It sets the @samp{VERSION}, @samp{UPDATED} and @samp{UPDATED-MONTH}
	21522	values used elsewhere. If your distribution doesn't use Automake, but
	21523	you do use Emacs, you may find the time-stamp.el package helpful
	21524	(@pxref{Time Stamps,,, emacs, The GNU Emacs Manual}).
	21525
	21526	@item
	21527	The @code{@@syncodeindex} command reflects the recommendation to use
	21528	only one index where possible, to make it easier for readers to look up
	21529	index entries.
	21530
	21531	@item
	21532	The @code{@@dircategory} is for constructing the Info directory.
	21533	@xref{Installing Dir Entries}, which includes a variety of recommended
	21534	category names.
	21535
	21536	@item
	21537	The `Invoking' node is a GNU standard to help users find the basic
	21538	information about command-line usage of a given program. @xref{Manual
	21539	Structure Details,,, standards, GNU Coding Standards}.
	21540
	21541	@item
	21542	@cindex GNU Free Documentation License, including entire
	21543	@cindex Free Documentation License, including entire
	21544	It is best to include the entire GNU Free Documentation License in a GNU
	21545	manual, unless the manual is only a few pages long. Of course this
	21546	sample is even shorter than that, but it includes the FDL anyway in
	21547	order to show one conventional way to do so. The @file{fdl.texi} file
	21548	is available on the GNU machines and in the Texinfo and other GNU
	21549	source distributions.
	21550
	21551	The FDL provides for omitting itself under certain conditions, but in
	21552	that case the sample texts given here have to be modified. @xref{GNU
	21553	Free Documentation License}.
	21554
	21555	@item
	21556	If the FSF is not the copyright holder, then use the appropriate name.
	21557
	21558	@item
	21559	If your manual is published on paper by the FSF or is longer than 400
	21560	pages, you should include the standard FSF cover texts (@pxref{License
	21561	Notices for Documentation,,, maintain, GNU Maintainer Information}).
	21562
	21563	@item
	21564	For documents that express your personal views, feelings or
	21565	experiences, it is more appropriate to use a license permitting only
	21566	verbatim copying, rather than the FDL@. @xref{Verbatim Copying
	21567	License}.
	21568
	21569	@end itemize
	21570
	21571	Here is the sample document:
	21572
	21573	@verbatim
	21574	\input texinfo @c --texinfo--
	21575	@comment $Id@w{$}
	21576	@comment %**start of header
	21577	@include version.texi
	21578	@settitle GNU Sample @value{VERSION}
	21579	@syncodeindex pg cp
	21580	@comment %**end of header
	21581	@copying
	21582	This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
	21583	which is an example in the Texinfo documentation.
	21584
	21585	Copyright @copyright{} 2016 Free Software Foundation, Inc.
	21586
	21587	@quotation
	21588	Permission is granted to copy, distribute and/or modify this document
	21589	under the terms of the GNU Free Documentation License, Version 1.3 or
	21590	any later version published by the Free Software Foundation; with no
	21591	Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
	21592	Texts. A copy of the license is included in the section entitled
	21593	``GNU Free Documentation License''.
	21594	@end quotation
	21595	@end copying
	21596
	21597	@dircategory Texinfo documentation system
	21598	@direntry
	21599	* sample: (sample)Invoking sample.
	21600	@end direntry
	21601
	21602	@titlepage
	21603	@title GNU Sample
	21604	@subtitle for version @value{VERSION}, @value{UPDATED}
	21605	@author A.U. Thor (@email{bug-sample@@gnu.org})
	21606	@page
	21607	@vskip 0pt plus 1filll
	21608	@insertcopying
	21609	@end titlepage
	21610
	21611	@contents
	21612
	21613	@ifnottex
	21614	@node Top
	21615	@top GNU Sample
	21616
	21617	This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
	21618	@end ifnottex
	21619
	21620	@menu
	21621	* Invoking sample::
	21622	* GNU Free Documentation License::
	21623	* Index::
	21624	@end menu
	21625
	21626
	21627	@node Invoking sample
	21628	@chapter Invoking sample
	21629
	21630	@pindex sample
	21631	@cindex invoking @command{sample}
	21632
	21633	This is a sample manual. There is no sample program to
	21634	invoke, but if there were, you could see its basic usage
	21635	and command line options here.
	21636
	21637
	21638	@node GNU Free Documentation License
	21639	@appendix GNU Free Documentation License
	21640
	21641	@include fdl.texi
	21642
	21643
	21644	@node Index
	21645	@unnumbered Index
	21646
	21647	@printindex cp
	21648
	21649	@bye
	21650	@end verbatim
	21651
	21652
	21653	@node Verbatim Copying License
	21654	@section Verbatim Copying License
	21655
	21656	@cindex Verbatim copying license
	21657	@cindex License for verbatim copying
	21658
	21659	For software manuals and other documentation, it is critical to use a
	21660	license permitting free redistribution and updating, so that when a free
	21661	program is changed, the documentation can be updated as well.
	21662
	21663	On the other hand, for documents that express your personal views,
	21664	feelings or experiences, it is more appropriate to use a license
	21665	permitting only verbatim copying.
	21666
	21667	Here is sample text for such a license permitting verbatim copying only.
	21668	This is just the license text itself. For a complete sample document,
	21669	see the previous sections.
	21670
	21671	@verbatim
	21672	@copying
	21673	This document is a sample for allowing verbatim copying only.
	21674
	21675	Copyright @copyright{} 2016 Free Software Foundation, Inc.
	21676
	21677	@quotation
	21678	Permission is granted to make and distribute verbatim copies
	21679	of this entire document without royalty provided the
	21680	copyright notice and this permission notice are preserved.
	21681	@end quotation
	21682	@end copying
	21683	@end verbatim
	21684
	21685
	21686	@node All-permissive Copying License
	21687	@section All-permissive Copying License
	21688
	21689	@cindex All-permissive copying license
	21690	@cindex License for all-permissive copying
	21691
	21692	For software manuals and other documentation, it is important to use a
	21693	license permitting free redistribution and updating, so that when a free
	21694	program is changed, the documentation can be updated as well.
	21695
	21696	On the other hand, for small supporting files, short manuals (under 300
	21697	lines long) and rough documentation (README files, INSTALL files, etc.),
	21698	the full FDL would be overkill. They can use a simple all-permissive
	21699	license.
	21700
	21701	Here is sample text for such an all-permissive license. This is just
	21702	the license text itself. For a complete sample document, see the
	21703	previous sections.
	21704
	21705	@example
	21706	Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
	21707
	21708	Copying and distribution of this file, with or without modification,
	21709	are permitted in any medium without royalty provided the copyright
	21710	notice and this notice are preserved.
	21711	@end example
	21712
	21713
	21714	@node Texinfo Mode
	21715	@appendix Using Texinfo Mode
	21716	@cindex Texinfo mode
	21717	@cindex Mode, using Texinfo
	21718	@cindex GNU Emacs
	21719	@cindex Emacs
	21720
	21721	You may edit a Texinfo file with any text editor you choose. A Texinfo
	21722	file is no different from any other ASCII file. However, GNU Emacs
	21723	comes with a special mode, called Texinfo mode, that provides Emacs
	21724	commands and tools to help ease your work.
	21725
	21726	@menu
	21727	* Texinfo Mode Overview:: How Texinfo mode can help you.
	21728	* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
	21729	purpose editing features.
	21730	* Inserting:: How to insert frequently used @@-commands.
	21731	* Showing the Structure:: How to show the structure of a file.
	21732	* Updating Nodes and Menus:: How to update or create new nodes and menus.
	21733	* Info Formatting:: How to format for Info.
	21734	* Printing:: How to format and print part or all of a file.
	21735	* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
	21736	@end menu
	21737
	21738	@node Texinfo Mode Overview
	21739	@section Texinfo Mode Overview
	21740
	21741	Texinfo mode provides special features for working with Texinfo files.
	21742	You can:
	21743
	21744	@itemize @bullet
	21745	@item
	21746	Insert frequently used @@-commands.
	21747
	21748	@item
	21749	Automatically create @code{@@node} lines.
	21750
	21751	@item
	21752	Show the structure of a Texinfo source file.
	21753
	21754	@item
	21755	Automatically create or update the `Next',
	21756	`Previous', and `Up' pointers of a node.
	21757
	21758	@item
	21759	Automatically create or update menus.
	21760
	21761	@item
	21762	Automatically create a master menu.
	21763
	21764	@item
	21765	Format a part or all of a file for Info.
	21766
	21767	@item
	21768	Typeset and print part or all of a file.
	21769	@end itemize
	21770
	21771	Perhaps the two most helpful features are those for inserting frequently
	21772	used @@-commands and for creating node pointers and menus.
	21773
	21774	@node Emacs Editing
	21775	@section The Usual GNU Emacs Editing Commands
	21776
	21777	In most cases, the usual Text mode commands work the same in Texinfo
	21778	mode as they do in Text mode. Texinfo mode adds new editing commands
	21779	and tools to GNU Emacs' general purpose editing features. The major
	21780	difference concerns filling. In Texinfo mode, the paragraph
	21781	separation variable and syntax table are redefined so that Texinfo
	21782	commands that should be on lines of their own are not inadvertently
	21783	included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
	21784	command will refill a paragraph but not mix an indexing command on a
	21785	line adjacent to it into the paragraph.
	21786
	21787	In addition, Texinfo mode sets the @code{page-delimiter} variable to
	21788	the value of @code{texinfo-chapter-level-regexp}; by default, this is
	21789	a regular expression matching the commands for chapters and their
	21790	equivalents, such as appendices. With this value for the page
	21791	delimiter, you can jump from chapter title to chapter title with the
	21792	@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
	21793	(@code{backward-page}) commands and narrow to a chapter with the
	21794	@kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
	21795	The GNU Emacs Manual}, for details about the page commands.)
	21796
	21797	You may name a Texinfo file however you wish, but the convention is to
	21798	end a Texinfo file name with one of the extensions
	21799	@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
	21800	extension is preferred, since it is explicit, but a shorter extension
	21801	may be necessary for operating systems that limit the length of file
	21802	names. GNU Emacs automatically enters Texinfo mode when you visit a
	21803	file with a @file{.texinfo}, @file{.texi} or @file{.txi}
	21804	extension. Also, Emacs switches to Texinfo mode
	21805	when you visit a
	21806	file that has @samp{--texinfo--} in its first line. If ever you are
	21807	in another mode and wish to switch to Texinfo mode, type @code{M-x
	21808	texinfo-mode}.
	21809
	21810	Like all other Emacs features, you can customize or enhance Texinfo
	21811	mode as you wish. In particular, the keybindings are very easy to
	21812	change. The keybindings described here are the default or standard
	21813	ones.
	21814
	21815	@node Inserting
	21816	@section Inserting Frequently Used Commands
	21817	@cindex Inserting frequently used commands
	21818	@cindex Frequently used commands, inserting
	21819	@cindex Commands, inserting them
	21820
	21821	Texinfo mode provides commands to insert various frequently used
	21822	@@-commands into the buffer. You can use these commands to save
	21823	keystrokes.
	21824
	21825	The insert commands are invoked by typing @kbd{C-c} twice and then the
	21826	first letter of the @@-command:
	21827
	21828	@table @kbd
	21829	@item C-c C-c c
	21830	@itemx M-x texinfo-insert-@@code
	21831	@findex texinfo-insert-@@code
	21832	Insert @code{@@code@{@}} and put the
	21833	cursor between the braces.
	21834
	21835	@item C-c C-c d
	21836	@itemx M-x texinfo-insert-@@dfn
	21837	@findex texinfo-insert-@@dfn
	21838	Insert @code{@@dfn@{@}} and put the
	21839	cursor between the braces.
	21840
	21841	@item C-c C-c e
	21842	@itemx M-x texinfo-insert-@@end
	21843	@findex texinfo-insert-@@end
	21844	Insert @code{@@end} and attempt to insert the correct following word,
	21845	such as @samp{example} or @samp{table}. (This command does not handle
	21846	nested lists correctly, but inserts the word appropriate to the
	21847	immediately preceding list.)
	21848
	21849	@item C-c C-c i
	21850	@itemx M-x texinfo-insert-@@item
	21851	@findex texinfo-insert-@@item
	21852	Insert @code{@@item} and put the
	21853	cursor at the beginning of the next line.
	21854
	21855	@item C-c C-c k
	21856	@itemx M-x texinfo-insert-@@kbd
	21857	@findex texinfo-insert-@@kbd
	21858	Insert @code{@@kbd@{@}} and put the
	21859	cursor between the braces.
	21860
	21861	@item C-c C-c n
	21862	@itemx M-x texinfo-insert-@@node
	21863	@findex texinfo-insert-@@node
	21864	Insert @code{@@node} and a comment line
	21865	listing the sequence for the `Next',
	21866	`Previous', and `Up' nodes.
	21867	Leave point after the @code{@@node}.
	21868
	21869	@item C-c C-c o
	21870	@itemx M-x texinfo-insert-@@noindent
	21871	@findex texinfo-insert-@@noindent
	21872	Insert @code{@@noindent} and put the
	21873	cursor at the beginning of the next line.
	21874
	21875	@item C-c C-c r
	21876	@itemx M-x texinfo-insert-dwim-@@ref
	21877	@findex texinfo-insert-dwim-@@ref
	21878	This function and binding were added in Emacs 27.1.
	21879	Inserts one of @code{@@pxref@{@}}, @code{@@xref@{@}}, or
	21880	@code{@@ref@{@}} based on the text around point; calling it near an
	21881	unclosed preceding open parenthesis results in @code{@@pxref@{@}}, at
	21882	the beginning of a sentence or at @code{(point-min)} yields
	21883	@code{@@xref@{@}}, any other location (including inside a word), will
	21884	result in @code{@@ref@{@}}. A numeric argument says how many words
	21885	the braces should surround. Puts the cursor between the braces.
	21886
	21887	@item C-c C-c s
	21888	@itemx M-x texinfo-insert-@@samp
	21889	@findex texinfo-insert-@@samp
	21890	Insert @code{@@samp@{@}} and put the
	21891	cursor between the braces.
	21892
	21893	@item C-c C-c t
	21894	@itemx M-x texinfo-insert-@@table
	21895	@findex texinfo-insert-@@table
	21896	Insert @code{@@table} followed by a @key{SPC}
	21897	and leave the cursor after the @key{SPC}.
	21898
	21899	@item C-c C-c v
	21900	@itemx M-x texinfo-insert-@@var
	21901	@findex texinfo-insert-@@var
	21902	Insert @code{@@var@{@}} and put the
	21903	cursor between the braces.
	21904
	21905	@item C-c C-c x
	21906	@itemx M-x texinfo-insert-@@example
	21907	@findex texinfo-insert-@@example
	21908	Insert @code{@@example} and put the
	21909	cursor at the beginning of the next line.
	21910
	21911	@c M-@{ was the binding for texinfo-insert-braces;
	21912	@c in Emacs 19, backward-paragraph will take this binding.
	21913	@item C-c C-c @{
	21914	@itemx M-x texinfo-insert-braces
	21915	@findex texinfo-insert-braces
	21916	Insert @code{@{@}} and put the cursor between the braces.
	21917
	21918	@item C-c @}
	21919	@itemx C-c ]
	21920	@itemx M-x up-list
	21921	@findex up-list
	21922	Move from between a pair of braces forward past the closing brace.
	21923	Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
	21924	is, however, more mnemonic; hence the two keybindings. (Also, you can
	21925	move out from between braces by typing @kbd{C-f}.)
	21926	@end table
	21927
	21928	To put a command such as @w{@code{@@code@{@dots{}@}}} around an
	21929	@emph{existing} word, position the cursor in front of the word and type
	21930	@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
	21931	The value of the prefix argument tells Emacs how many words following
	21932	point to include between braces---@samp{1} for one word, @samp{2} for
	21933	two words, and so on. Use a negative argument to enclose the previous
	21934	word or words. If you do not specify a prefix argument, Emacs inserts
	21935	the @@-command string and positions the cursor between the braces. This
	21936	feature works only for those @@-commands that operate on a word or words
	21937	within one line, such as @code{@@kbd} and @code{@@var}.
	21938
	21939	This set of insert commands was created after analyzing the frequency
	21940	with which different @@-commands are used in the @cite{GNU Emacs
	21941	Manual} and the @cite{GDB Manual}. If you wish to add your own insert
	21942	commands, you can bind a keyboard macro to a key, use abbreviations,
	21943	or extend the code in @file{texinfo.el}.
	21944
	21945	@findex texinfo-start-menu-description
	21946	@cindex Menu description, start
	21947	@cindex Description for menu, start
	21948	@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
	21949	command that works differently from the other insert commands. It
	21950	inserts a node's section or chapter title in the space for the
	21951	description in a menu entry line. (A menu entry has three parts, the
	21952	entry name, the node name, and the description. Only the node name is
	21953	required, but a description helps explain what the node is about.
	21954	@xref{Menu Parts, , The Parts of a Menu}.)
	21955
	21956	To use @code{texinfo-start-menu-description}, position point in a menu
	21957	entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
	21958	the title that goes with the node name, and inserts the title as a
	21959	description; it positions point at beginning of the inserted text so you
	21960	can edit it. The function does not insert the title if the menu entry
	21961	line already contains a description.
	21962
	21963	This command is only an aid to writing descriptions; it does not do the
	21964	whole job. You must edit the inserted text since a title tends to use
	21965	the same words as a node name but a useful description uses different
	21966	words.
	21967
	21968	@node Showing the Structure
	21969	@section Showing the Sectioning Structure of a File
	21970	@cindex Showing the sectioning structure of a file
	21971	@cindex Sectioning structure of a file, showing
	21972	@cindex Structure of a file, showing
	21973	@cindex Outline of file structure, showing
	21974	@cindex Contents-like outline of file structure
	21975	@cindex File sectioning structure, showing
	21976	@cindex Texinfo file sectioning structure, showing
	21977
	21978	You can show the sectioning structure of a Texinfo file by using the
	21979	@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
	21980	lists the lines that begin with the @@-commands for @code{@@chapter},
	21981	@code{@@section}, and the like. It constructs what amounts to a table
	21982	of contents. These lines are displayed in another buffer called the
	21983	@samp{Occur} buffer. In that buffer, you can position the cursor
	21984	over one of the lines and use the @kbd{C-c C-c} command
	21985	(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
	21986	in the Texinfo file.
	21987
	21988	@table @kbd
	21989	@item C-c C-s
	21990	@itemx M-x texinfo-show-structure
	21991	@findex texinfo-show-structure
	21992	Show the @code{@@chapter}, @code{@@section}, and such lines of a
	21993	Texinfo file.
	21994
	21995	@item C-c C-c
	21996	@itemx M-x occur-mode-goto-occurrence
	21997	@findex occur-mode-goto-occurrence
	21998	Go to the line in the Texinfo file corresponding to the line under the
	21999	cursor in the @file{Occur} buffer.
	22000	@end table
	22001
	22002	If you call @code{texinfo-show-structure} with a prefix argument by
	22003	typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
	22004	@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
	22005	also the @code{@@node} lines. You can use @code{texinfo-show-structure}
	22006	with a prefix argument to check whether the `Next', `Previous', and `Up'
	22007	pointers of an @code{@@node} line are correct.
	22008
	22009	Often, when you are working on a manual, you will be interested only
	22010	in the structure of the current chapter. In this case, you can mark
	22011	off the region of the buffer that you are interested in by using the
	22012	@kbd{C-x n n} (@code{narrow-to-region}) command and
	22013	@code{texinfo-show-structure} will work on only that region. To see
	22014	the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
	22015	(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
	22016	information about the narrowing commands.)
	22017
	22018	@vindex page-delimiter
	22019	@cindex Page delimiter in Texinfo mode
	22020	In addition to providing the @code{texinfo-show-structure} command,
	22021	Texinfo mode sets the value of the page delimiter variable to match
	22022	the chapter-level @@-commands. This enables you to use the @kbd{C-x
	22023	]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
	22024	commands to move forward and backward by chapter, and to use the
	22025	@kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter.
	22026	@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
	22027	about the page commands.
	22028
	22029
	22030	@node Updating Nodes and Menus
	22031	@section Updating Nodes and Menus
	22032
	22033	@cindex Updating nodes and menus
	22034	@cindex Create nodes, menus automatically
	22035	@cindex Insert nodes, menus automatically
	22036	@cindex Automatically insert nodes, menus
	22037
	22038	Texinfo mode provides commands for automatically creating or updating
	22039	menus and node pointers. The commands are called ``update'' commands
	22040	because their most frequent use is for updating a Texinfo file after you
	22041	have worked on it; but you can use them to insert the `Next',
	22042	`Previous', and `Up' pointers into an @code{@@node} line that has none
	22043	and to create menus in a file that has none.
	22044
	22045	If you do not use any updating commands, you need to write menus by
	22046	hand, which is a tedious task.
	22047
	22048	@menu
	22049	* Updating Commands:: Five major updating commands.
	22050	* Updating Requirements:: How to structure a Texinfo file for
	22051	using the updating command.
	22052	* Other Updating Commands:: How to indent descriptions, insert
	22053	missing nodes lines, and update
	22054	nodes in sequence.
	22055	@end menu
	22056
	22057	@node Updating Commands
	22058	@subsection The Updating Commands
	22059
	22060	You can use the updating commands to:
	22061
	22062	@itemize @bullet
	22063	@item
	22064	insert or update the `Next', `Previous', and `Up' pointers of a node,
	22065
	22066	@item
	22067	insert or update the menu for a section, and
	22068
	22069	@item
	22070	create a master menu for a Texinfo source file.
	22071	@end itemize
	22072
	22073	You can also use the commands to update all the nodes and menus in a
	22074	region or in a whole Texinfo file.
	22075
	22076	The updating commands work only with conventional Texinfo files, which
	22077	are structured hierarchically like books. In such files, a structuring
	22078	command line must follow closely after each @code{@@node} line, except
	22079	for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
	22080	a line beginning with @code{@@chapter}, @code{@@section}, or other
	22081	similar command.)
	22082
	22083	You can write the structuring command line on the line that follows
	22084	immediately after an @code{@@node} line or else on the line that
	22085	follows after a single @code{@@comment} line or a single
	22086	@code{@@ifinfo} line. You cannot interpose more than one line between
	22087	the @code{@@node} line and the structuring command line; and you may
	22088	interpose only a @code{@@comment} line or an @code{@@ifinfo} line.
	22089
	22090	Commands which work on a whole buffer require that the `Top' node be
	22091	followed by a node with a @code{@@chapter} or equivalent-level command.
	22092	The menu updating commands will not create a main or master menu for a
	22093	Texinfo file that has only @code{@@chapter}-level nodes! The menu
	22094	updating commands only create menus @emph{within} nodes for lower level
	22095	nodes. To create a menu of chapters, you must provide a `Top'
	22096	node.
	22097
	22098	The menu updating commands remove menu entries that refer to other Info
	22099	files since they do not refer to nodes within the current buffer. This
	22100	is a deficiency. Rather than use menu entries, you can use cross
	22101	references to refer to other Info files. None of the updating commands
	22102	affect cross-references.
	22103
	22104	Texinfo mode has five updating commands that are used most often: two
	22105	are for updating the node pointers or menu of a single node (or a
	22106	region); two are for updating every node pointer and menu in a file;
	22107	and one, the @code{texinfo-master-menu} command, is for creating a
	22108	master menu for a complete file, and optionally, for updating every
	22109	node and menu in the whole Texinfo file.
	22110
	22111	The @code{texinfo-master-menu} command is the primary command:
	22112
	22113	@table @kbd
	22114	@item C-c C-u m
	22115	@itemx M-x texinfo-master-menu
	22116	@findex texinfo-master-menu
	22117	Create or update a master menu that includes all the other menus
	22118	(incorporating the descriptions from pre-existing menus, if
	22119	any).
	22120
	22121	With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
	22122	update all the nodes and all the regular menus in the buffer before
	22123	constructing the master menu. (@xref{The Top Node, , The Top Node and
	22124	Master Menu}, for more about a master menu.)
	22125
	22126	For @code{texinfo-master-menu} to work, the Texinfo file must have a
	22127	`Top' node and at least one subsequent node.
	22128
	22129	After extensively editing a Texinfo file, you can type the following:
	22130
	22131	@example
	22132	C-u M-x texinfo-master-menu
	22133	@exdent or
	22134	C-u C-c C-u m
	22135	@end example
	22136
	22137	@noindent
	22138	This updates all the nodes and menus completely and all at once.
	22139	@end table
	22140
	22141	The other major updating commands do smaller jobs and are designed for
	22142	the person who updates nodes and menus as he or she writes a Texinfo
	22143	file.
	22144
	22145	@need 1000
	22146	The commands are:
	22147
	22148	@table @kbd
	22149	@item C-c C-u C-n
	22150	@itemx M-x texinfo-update-node
	22151	@findex texinfo-update-node
	22152	Insert the `Next', `Previous', and `Up' pointers for the node that point is
	22153	within (i.e., for the @code{@@node} line preceding point). If the
	22154	@code{@@node} line has pre-existing `Next', `Previous', or `Up'
	22155	pointers in it, the old pointers are removed and new ones inserted.
	22156	With an argument (prefix argument, @kbd{C-u}, if interactive), this command
	22157	updates all @code{@@node} lines in the region (which is the text
	22158	between point and mark).
	22159
	22160	@item C-c C-u C-m
	22161	@itemx M-x texinfo-make-menu
	22162	@findex texinfo-make-menu
	22163	Create or update the menu in the node that point is within.
	22164	With an argument (@kbd{C-u} as prefix argument, if
	22165	interactive), the command makes or updates menus for the
	22166	nodes which are either within or a part of the
	22167	region.
	22168
	22169	Whenever @code{texinfo-make-menu} updates an existing menu, the
	22170	descriptions from that menu are incorporated into the new menu. This
	22171	is done by copying descriptions from the existing menu to the entries
	22172	in the new menu that have the same node names. If the node names are
	22173	different, the descriptions are not copied to the new menu.
	22174
	22175	@item C-c C-u C-e
	22176	@itemx M-x texinfo-every-node-update
	22177	@findex texinfo-every-node-update
	22178	Insert or update the `Next', `Previous', and `Up' pointers for every
	22179	node in the buffer.
	22180
	22181	@item C-c C-u C-a
	22182	@itemx M-x texinfo-all-menus-update
	22183	@findex texinfo-all-menus-update
	22184	Create or update all the menus in the buffer. With an argument
	22185	(@kbd{C-u} as prefix argument, if interactive), first insert
	22186	or update all the node
	22187	pointers before working on the menus.
	22188
	22189	If a master menu exists, the @code{texinfo-all-menus-update} command
	22190	updates it; but the command does not create a new master menu if none
	22191	already exists. (Use the @code{texinfo-master-menu} command for
	22192	that.)
	22193
	22194	When working on a document that does not merit a master menu, you can
	22195	type the following:
	22196
	22197	@example
	22198	C-u C-c C-u C-a
	22199	@exdent or
	22200	C-u M-x texinfo-all-menus-update
	22201	@end example
	22202
	22203	@noindent
	22204	This updates all the nodes and menus.
	22205	@end table
	22206
	22207	The @code{texinfo-column-for-description} variable specifies the
	22208	column to which menu descriptions are indented. By default, the value
	22209	is 32 although it can be useful to reduce it to as low as 24. You
	22210	can set the variable via customization (@pxref{Customization,,,
	22211	emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable}
	22212	command (@pxref{Examining, , Examining and Setting Variables, emacs,
	22213	The GNU Emacs Manual}).
	22214
	22215	Also, the @code{texinfo-indent-menu-description} command may be used to
	22216	indent existing menu descriptions to a specified column. Finally, if
	22217	you wish, you can use the @code{texinfo-insert-node-lines} command to
	22218	insert missing @code{@@node} lines into a file. (@xref{Other Updating
	22219	Commands}, for more information.)
	22220
	22221	@node Updating Requirements
	22222	@subsection Updating Requirements
	22223	@cindex Updating requirements
	22224	@cindex Requirements for updating commands
	22225
	22226	To use the updating commands, you must organize the Texinfo file
	22227	hierarchically with chapters, sections, subsections, and the like.
	22228	When you construct the hierarchy of the manual, do not `jump down'
	22229	more than one level at a time: you can follow the `Top' node with a
	22230	chapter, but not with a section; you can follow a chapter with a
	22231	section, but not with a subsection. However, you may `jump up' any
	22232	number of levels at one time---for example, from a subsection to a
	22233	chapter.
	22234
	22235	Each @code{@@node} line, with the exception of the line for the `Top'
	22236	node, must be followed by a line with a structuring command such as
	22237	@code{@@chapter}, @code{@@section}, or
	22238	@code{@@unnumberedsubsec}.
	22239
	22240	Each @code{@@node} line/structuring-command line combination
	22241	must look either like this:
	22242
	22243	@example
	22244	@group
	22245	@@node Comments, Minimum, Conventions, Overview
	22246	@@comment node-name, next, previous, up
	22247	@@section Comments
	22248	@end group
	22249	@end example
	22250
	22251	or like this (without the @code{@@comment} line):
	22252
	22253	@example
	22254	@group
	22255	@@node Comments, Minimum, Conventions, Overview
	22256	@@section Comments
	22257	@end group
	22258	@end example
	22259
	22260	or like this (without the explicit node pointers):
	22261
	22262	@example
	22263	@group
	22264	@@node Comments
	22265	@@section Comments
	22266	@end group
	22267	@end example
	22268
	22269	@noindent
	22270	In this example, `Comments' is the name of both the node and the
	22271	section. The next node is called `Minimum' and the previous node is
	22272	called `Conventions'. The `Comments' section is within the `Overview'
	22273	node, which is specified by the `Up' pointer. (Instead of an
	22274	@code{@@comment} line, you may also write an @code{@@ifinfo} line.)
	22275
	22276	If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
	22277	and be the first node in the file.
	22278
	22279	The menu updating commands create a menu of sections within a chapter,
	22280	a menu of subsections within a section, and so on. This means that
	22281	you must have a `Top' node if you want a menu of chapters.
	22282
	22283	Incidentally, the @code{makeinfo} command will create an Info file for a
	22284	hierarchically organized Texinfo file that lacks `Next', `Previous' and
	22285	`Up' pointers. Thus, if you can be sure that your Texinfo file will be
	22286	formatted with @code{makeinfo}, you have no need for the update node
	22287	commands. (@xref{Creating an Info File}, for more information about
	22288	@code{makeinfo}.)
	22289
	22290
	22291	@node Other Updating Commands
	22292	@subsection Other Updating Commands
	22293
	22294	In addition to the five major updating commands, Texinfo mode
	22295	possesses several less frequently used updating commands:
	22296
	22297	@table @kbd
	22298	@item M-x texinfo-insert-node-lines
	22299	@findex texinfo-insert-node-lines
	22300	Insert @code{@@node} lines before the @code{@@chapter},
	22301	@code{@@section}, and other sectioning commands wherever they are
	22302	missing throughout a region in a Texinfo file.
	22303
	22304	With an argument (@kbd{C-u} as prefix argument, if interactive), the
	22305	command @code{texinfo-insert-node-lines} not only inserts
	22306	@code{@@node} lines but also inserts the chapter or section titles as
	22307	the names of the corresponding nodes. In addition, it inserts the
	22308	titles as node names in pre-existing @code{@@node} lines that lack
	22309	names. Since node names should be more concise than section or
	22310	chapter titles, you must manually edit node names so inserted.
	22311
	22312	For example, the following marks a whole buffer as a region and inserts
	22313	@code{@@node} lines and titles throughout:
	22314
	22315	@example
	22316	C-x h C-u M-x texinfo-insert-node-lines
	22317	@end example
	22318
	22319	This command inserts titles as node names in @code{@@node} lines; the
	22320	@code{texinfo-start-menu-description} command (@pxref{Inserting,
	22321	Inserting Frequently Used Commands}) inserts titles as descriptions in
	22322	menu entries, a different action. However, in both cases, you need to
	22323	edit the inserted text.
	22324
	22325	@item M-x texinfo-multiple-files-update
	22326	@findex texinfo-multiple-files-update @r{(in brief)}
	22327	Update nodes and menus in a document built from several separate files.
	22328	With @kbd{C-u} as a prefix argument, create and insert a master menu in
	22329	the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
	22330	update all the menus and all the `Next', `Previous', and `Up' pointers
	22331	of all the included files before creating and inserting a master menu in
	22332	the outer file. The @code{texinfo-multiple-files-update} command is
	22333	described in the appendix on @code{@@include} files.
	22334	@xref{@code{texinfo-multiple-files-update}}.
	22335
	22336	@item M-x texinfo-indent-menu-description
	22337	@findex texinfo-indent-menu-description
	22338	Indent every description in the menu following point to the specified
	22339	column. You can use this command to give yourself more space for
	22340	descriptions. With an argument (@kbd{C-u} as prefix argument, if
	22341	interactive), the @code{texinfo-indent-menu-description} command indents
	22342	every description in every menu in the region. However, this command
	22343	does not indent the second and subsequent lines of a multi-line
	22344	description.
	22345
	22346	@item M-x texinfo-sequential-node-update
	22347	@findex texinfo-sequential-node-update
	22348	Insert the names of the nodes immediately following and preceding the
	22349	current node as the `Next' or `Previous' pointers regardless of those
	22350	nodes' hierarchical level. This means that the `Next' node of a
	22351	subsection may well be the next chapter. Sequentially ordered nodes are
	22352	useful for novels and other documents that you read through
	22353	sequentially. (However, in Info, the @kbd{g *} command lets
	22354	you look through the file sequentially, so sequentially ordered nodes
	22355	are not strictly necessary.) With an argument (prefix argument, if
	22356	interactive), the @code{texinfo-sequential-node-update} command
	22357	sequentially updates all the nodes in the region.
	22358	@end table
	22359
	22360	@node Info Formatting
	22361	@section Formatting for Info
	22362	@cindex Formatting for Info
	22363	@cindex Running an Info formatter
	22364	@cindex Info formatting
	22365
	22366	Texinfo mode provides several commands for formatting part or all of a
	22367	Texinfo file for Info. Often, when you are writing a document, you
	22368	want to format only part of a file---that is, a region.
	22369
	22370	You can use either the @code{texinfo-format-region} or the
	22371	@code{makeinfo-region} command to format a region:
	22372
	22373	@table @kbd
	22374	@findex texinfo-format-region
	22375	@item C-c C-e C-r
	22376	@itemx M-x texinfo-format-region
	22377	@itemx C-c C-m C-r
	22378	@itemx M-x makeinfo-region
	22379	Format the current region for Info.
	22380	@end table
	22381
	22382	You can use either the @code{texinfo-format-buffer} or the
	22383	@code{makeinfo-buffer} command to format a whole buffer:
	22384
	22385	@table @kbd
	22386	@findex texinfo-format-buffer
	22387	@item C-c C-e C-b
	22388	@itemx M-x texinfo-format-buffer
	22389	@itemx C-c C-m C-b
	22390	@itemx M-x makeinfo-buffer
	22391	Format the current buffer for Info.
	22392	@end table
	22393
	22394	@need 1000
	22395	For example, after writing a Texinfo file, you can type the following:
	22396
	22397	@example
	22398	C-u C-c C-u m
	22399	@exdent or
	22400	C-u M-x texinfo-master-menu
	22401	@end example
	22402
	22403	@noindent
	22404	This updates all the nodes and menus. Then type the following to create
	22405	an Info file:
	22406
	22407	@example
	22408	C-c C-m C-b
	22409	@exdent or
	22410	M-x makeinfo-buffer
	22411	@end example
	22412
	22413	@xref{Creating an Info File} for details about Info formatting.
	22414
	22415	@node Printing
	22416	@comment node-name, next, previous, up
	22417	@section Printing
	22418	@cindex Formatting for printing
	22419	@cindex Printing a region or buffer
	22420	@cindex Region formatting and printing
	22421	@cindex Buffer formatting and printing
	22422	@cindex Part of file formatting and printing
	22423
	22424	Typesetting and printing a Texinfo file is a multi-step process in
	22425	which you first create a file for printing (called a DVI file), and
	22426	then print the file. Optionally, you may also create indices. To do
	22427	this, you must run the @code{texindex} command after first running the
	22428	@code{tex} typesetting command; and then you must run the @code{tex}
	22429	command again. Or else run the @code{texi2dvi} command which
	22430	automatically creates indices as needed (@pxref{Format with
	22431	@command{texi2dvi}}).
	22432
	22433	Often, when you are writing a document, you want to typeset and print
	22434	only part of a file to see what it will look like. You can use the
	22435	@code{texinfo-tex-region} and related commands for this purpose. Use
	22436	the @code{texinfo-tex-buffer} command to format all of a
	22437	buffer.
	22438
	22439	@table @kbd
	22440	@item C-c C-t C-b
	22441	@itemx M-x texinfo-tex-buffer
	22442	@findex texinfo-tex-buffer
	22443	Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
	22444	buffer, this command automatically creates or updates indices as
	22445	needed.
	22446
	22447	@item C-c C-t C-r
	22448	@itemx M-x texinfo-tex-region
	22449	@findex texinfo-tex-region
	22450	Run @TeX{} on the region.
	22451
	22452	@item C-c C-t C-i
	22453	@itemx M-x texinfo-texindex
	22454	Run @code{texindex} to sort the indices of a Texinfo file formatted with
	22455	@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
	22456	not run @code{texindex} automatically; it only runs the @code{tex}
	22457	typesetting command. You must run the @code{texinfo-tex-region} command
	22458	a second time after sorting the raw index files with the @code{texindex}
	22459	command. (Usually, you do not format an index when you format a region,
	22460	only when you format a buffer. Now that the @code{texi2dvi} command
	22461	exists, there is little or no need for this command.)
	22462
	22463	@item C-c C-t C-p
	22464	@itemx M-x texinfo-tex-print
	22465	@findex texinfo-tex-print
	22466	Print the file (or the part of the file) previously formatted with
	22467	@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.
	22468	@end table
	22469
	22470	For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
	22471	file @emph{must} start with a @samp{\input texinfo} line and must
	22472	include a @code{@@settitle} line. The file must end with @code{@@bye}
	22473	on a line by itself. (When you use @code{texinfo-tex-region}, you must
	22474	surround the @code{@@settitle} line with start-of-header and
	22475	end-of-header lines.)
	22476
	22477	@xref{Hardcopy}, for a description of the other @TeX{} related
	22478	commands, such as @code{tex-show-print-queue}.
	22479
	22480	@node Texinfo Mode Summary
	22481	@section Texinfo Mode Summary
	22482
	22483	In Texinfo mode, each set of commands has default keybindings that
	22484	begin with the same keys. All the commands that are custom-created
	22485	for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
	22486	mnemonic.
	22487
	22488	@subheading Insert Commands
	22489
	22490	The insert commands are invoked by typing @kbd{C-c} twice and then the
	22491	first letter of the @@-command to be inserted. (It might make more
	22492	sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
	22493	@kbd{C-c C-c} is quick to type.)
	22494
	22495	@example
	22496	C-c C-c c @r{Insert} @samp{@@code}.
	22497	C-c C-c d @r{Insert} @samp{@@dfn}.
	22498	C-c C-c e @r{Insert} @samp{@@end}.
	22499	C-c C-c i @r{Insert} @samp{@@item}.
	22500	C-c C-c n @r{Insert} @samp{@@node}.
	22501	C-c C-c s @r{Insert} @samp{@@samp}.
	22502	C-c C-c v @r{Insert} @samp{@@var}.
	22503	C-c @{ @r{Insert braces.}
	22504	C-c ]
	22505	C-c @} @r{Move out of enclosing braces.}
	22506
	22507	@group
	22508	C-c C-c C-d @r{Insert a node's section title}
	22509	@r{in the space for the description}
	22510	@r{in a menu entry line.}
	22511	@end group
	22512	@end example
	22513
	22514	@subheading Show Structure
	22515
	22516	The @code{texinfo-show-structure} command is often used within a
	22517	narrowed region.
	22518
	22519	@example
	22520	C-c C-s @r{List all the headings.}
	22521	@end example
	22522
	22523	@subheading The Master Update Command
	22524
	22525	The @code{texinfo-master-menu} command creates a master menu; and can
	22526	be used to update every node and menu in a file as well.
	22527
	22528	@c Probably should use @tables in this section.
	22529	@example
	22530	@group
	22531	C-c C-u m
	22532	M-x texinfo-master-menu
	22533	@r{Create or update a master menu.}
	22534	@end group
	22535
	22536	@group
	22537	C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
	22538	@r{create or update all nodes and regular}
	22539	@r{menus, and then create a master menu.}
	22540	@end group
	22541	@end example
	22542
	22543	@subheading Update Pointers
	22544
	22545	The update pointer commands are invoked by typing @kbd{C-c C-u} and
	22546	then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
	22547	@code{texinfo-every-node-update}.
	22548
	22549	@example
	22550	C-c C-u C-n @r{Update a node.}
	22551	C-c C-u C-e @r{Update every node in the buffer.}
	22552	@end example
	22553
	22554	@subheading Update Menus
	22555
	22556	Invoke the update menu commands by typing @kbd{C-c C-u}
	22557	and then either @kbd{C-m} for @code{texinfo-make-menu} or
	22558	@kbd{C-a} for @code{texinfo-all-menus-update}. To update
	22559	both nodes and menus at the same time, precede @kbd{C-c C-u
	22560	C-a} with @kbd{C-u}.
	22561
	22562	@example
	22563	C-c C-u C-m @r{Make or update a menu.}
	22564
	22565	@group
	22566	C-c C-u C-a @r{Make or update all}
	22567	@r{menus in a buffer.}
	22568	@end group
	22569
	22570	@group
	22571	C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
	22572	@r{first create or update all nodes and}
	22573	@r{then create or update all menus.}
	22574	@end group
	22575	@end example
	22576
	22577	@subheading Format for Info
	22578
	22579	The Info formatting commands that are written in Emacs Lisp are
	22580	invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
	22581	or @kbd{C-b} for the whole buffer.
	22582
	22583	The Info formatting commands that are written in C and based on the
	22584	@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
	22585	either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.
	22586
	22587	@need 800
	22588	@noindent
	22589	Use the @code{texinfo-format@dots{}} commands:
	22590
	22591	@example
	22592	@group
	22593	C-c C-e C-r @r{Format the region.}
	22594	C-c C-e C-b @r{Format the buffer.}
	22595	@end group
	22596	@end example
	22597
	22598	@need 750
	22599	@noindent
	22600	Use @code{makeinfo}:
	22601
	22602	@example
	22603	C-c C-m C-r @r{Format the region.}
	22604	C-c C-m C-b @r{Format the buffer.}
	22605	C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
	22606	C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
	22607	@end example
	22608
	22609	@subheading Typeset and Print
	22610
	22611	The @TeX{} typesetting and printing commands are invoked by typing
	22612	@kbd{C-c C-t} and then another control command: @kbd{C-r} for
	22613	@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
	22614	and so on.
	22615
	22616	@example
	22617	C-c C-t C-r @r{Run @TeX{} on the region.}
	22618	C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
	22619	C-c C-t C-i @r{Run} @code{texindex}.
	22620	C-c C-t C-p @r{Print the DVI file.}
	22621	C-c C-t C-q @r{Show the print queue.}
	22622	C-c C-t C-d @r{Delete a job from the print queue.}
	22623	C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
	22624	C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
	22625	C-c C-t C-l @r{Recenter the output buffer.}
	22626	@end example
	22627
	22628	@subheading Other Updating Commands
	22629
	22630	The remaining updating commands do not have standard keybindings because
	22631	they are rarely used.
	22632
	22633	@example
	22634	@group
	22635	M-x texinfo-insert-node-lines
	22636	@r{Insert missing @code{@@node} lines in region.}
	22637	@r{With @kbd{C-u} as a prefix argument,}
	22638	@r{use section titles as node names.}
	22639	@end group
	22640
	22641	@group
	22642	M-x texinfo-multiple-files-update
	22643	@r{Update a multi-file document.}
	22644	@r{With @kbd{C-u 2} as a prefix argument,}
	22645	@r{create or update all nodes and menus}
	22646	@r{in all included files first.}
	22647	@end group
	22648
	22649	@group
	22650	M-x texinfo-indent-menu-description
	22651	@r{Indent descriptions.}
	22652	@end group
	22653
	22654	@group
	22655	M-x texinfo-sequential-node-update
	22656	@r{Insert node pointers in strict sequence.}
	22657	@end group
	22658	@end example
	22659
	22660
	22661	@node Headings
	22662	@appendix Page Headings
	22663	@cindex Headings
	22664	@cindex Footings
	22665	@cindex Page numbering
	22666	@cindex Page headings
	22667	@cindex Formatting headings and footings
	22668
	22669	Most printed manuals contain headings along the top of every page
	22670	except the title and copyright pages. Some manuals also contain
	22671	footings. @c HTML output also supports something like these, but in a
	22672	@c completely different way: @pxref{Customizing HTML Page Layout}.
	22673	Headings and footings have no meaning in Info or the other output
	22674	formats.
	22675
	22676	@menu
	22677	* Headings Introduced:: Conventions for using page headings.
	22678	* Heading Format:: Standard page heading formats.
	22679	* Heading Choice:: How to specify the type of page heading.
	22680	* Custom Headings:: How to create your own headings and footings.
	22681	@end menu
	22682
	22683	@node Headings Introduced
	22684	@section Headings Introduced
	22685
	22686	Texinfo provides standard page heading formats for manuals that are
	22687	printed on one side of each sheet of paper and for manuals that are
	22688	printed on both sides of the paper. Typically, you will use these
	22689	formats, but you can specify your own format if you wish.
	22690
	22691	In addition, you can specify whether chapters should begin on a new
	22692	page, or merely continue the same page as the previous chapter; and if
	22693	chapters begin on new pages, you can specify whether they must be
	22694	odd-numbered pages.
	22695
	22696	By convention, a book is printed on both sides of each sheet of paper.
	22697	When you open a book, the right-hand page is odd-numbered, and
	22698	chapters begin on right-hand pages---a preceding left-hand page is
	22699	left blank if necessary. Reports, however, are often printed on just
	22700	one side of paper, and chapters begin on a fresh page immediately
	22701	following the end of the preceding chapter. In short or informal
	22702	reports, chapters often do not begin on a new page at all, but are
	22703	separated from the preceding text by a small amount of whitespace.
	22704
	22705	The @code{@@setchapternewpage} command controls whether chapters begin
	22706	on new pages, and whether one of the standard heading formats is used.
	22707	In addition, Texinfo has several heading and footing commands that you
	22708	can use to generate your own heading and footing formats.
	22709
	22710	In Texinfo, headings and footings are single lines at the tops and
	22711	bottoms of pages; you cannot create multiline headings or footings.
	22712	Each header or footer line is divided into three parts: a left part, a
	22713	middle part, and a right part. Any part, or a whole line, may be left
	22714	blank. Text for the left part of a header or footer line is set
	22715	flushleft; text for the middle part is centered; and, text for the
	22716	right part is set flushright.
	22717
	22718
	22719	@node Heading Format
	22720	@section Standard Heading Formats
	22721
	22722	Texinfo provides two standard heading formats, one for manuals printed
	22723	on one side of each sheet of paper, and the other for manuals printed
	22724	on both sides of the paper.
	22725
	22726	By default, nothing is specified for the footing of a Texinfo file,
	22727	so the footing remains blank.
	22728
	22729	The standard format for single-sided printing consists of a header
	22730	line in which the left-hand part contains the name of the chapter, the
	22731	central part is blank, and the right-hand part contains the page
	22732	number.
	22733
	22734	@need 950
	22735	A single-sided page looks like this:
	22736
	22737	@example
	22738	@group
	22739	_______________________
	22740	\| \|
	22741	\| chapter page number \|
	22742	\| \|
	22743	\| Start of text ... \|
	22744	\| ... \|
	22745	\| \|
	22746	@end group
	22747	@end example
	22748
	22749	The standard format for two-sided printing depends on whether the page
	22750	number is even or odd. By convention, even-numbered pages are on the
	22751	left- and odd-numbered pages are on the right. (@TeX{} will adjust the
	22752	widths of the left- and right-hand margins. Usually, widths are
	22753	correct, but during double-sided printing, it is wise to check that
	22754	pages will bind properly---sometimes a printer will produce output in
	22755	which the even-numbered pages have a larger right-hand margin than the
	22756	odd-numbered pages.)
	22757
	22758	In the standard double-sided format, the left part of the left-hand
	22759	(even-numbered) page contains the page number, the central part is
	22760	blank, and the right part contains the title (specified by the
	22761	@code{@@settitle} command). The left part of the right-hand
	22762	(odd-numbered) page contains the name of the chapter, the central part
	22763	is blank, and the right part contains the page number.
	22764
	22765	@need 750
	22766	Two pages, side by side as in an open book, look like this:
	22767
	22768	@example
	22769	@group
	22770	_______________________ _______________________
	22771	\| \| \| \|
	22772	\| page number title \| \| chapter page number \|
	22773	\| \| \| \|
	22774	\| Start of text ... \| \| More text ... \|
	22775	\| ... \| \| ... \|
	22776	\| \| \| \|
	22777	@end group
	22778	@end example
	22779
	22780	@noindent
	22781	The chapter name is preceded by the word ``Chapter'', the chapter number
	22782	and a colon. This makes it easier to keep track of where you are in the
	22783	manual.
	22784
	22785	@node Heading Choice
	22786	@section Specifying the Type of Heading
	22787
	22788	@TeX{} does not begin to generate page headings for a standard Texinfo
	22789	file until it reaches the @code{@@end titlepage} command. Thus, the
	22790	title and copyright pages are not numbered. The @code{@@end
	22791	titlepage} command causes @TeX{} to begin to generate page headings
	22792	according to a standard format specified by the
	22793	@code{@@setchapternewpage} command that precedes the
	22794	@code{@@titlepage} section.
	22795
	22796	@need 1000
	22797	There are four possibilities:
	22798
	22799	@table @asis
	22800	@item No @code{@@setchapternewpage} command
	22801	Cause @TeX{} to specify the single-sided heading format, with chapters
	22802	on new pages. This is the same as @code{@@setchapternewpage on}.
	22803
	22804	@item @code{@@setchapternewpage on}
	22805	Specify the single-sided heading format, with chapters on new pages.
	22806
	22807	@item @code{@@setchapternewpage off}
	22808	Cause @TeX{} to start a new chapter on the same page as the last page
	22809	of the preceding chapter, after skipping some vertical whitespace.
	22810	Also cause @TeX{} to typeset for single-sided printing. (You can
	22811	override the headers format with the @code{@@headings double} command;
	22812	@pxref{@code{@@headings}}.)
	22813
	22814	@item @code{@@setchapternewpage odd}
	22815	Specify the double-sided heading format, with chapters on new pages.
	22816	@end table
	22817
	22818	@noindent
	22819	Texinfo lacks a @code{@@setchapternewpage even} command.
	22820
	22821
	22822	@node Custom Headings
	22823	@section How to Make Your Own Headings
	22824
	22825	You can use the standard headings provided with Texinfo or specify
	22826	your own. By default, Texinfo has no footers, so if you specify them,
	22827	the available page size for the main text will be slightly reduced.
	22828
	22829	Texinfo provides six commands for specifying headings and
	22830	footings:
	22831	@itemize @bullet
	22832	@item
	22833	@code{@@everyheading} and @code{@@everyfooting} generate page headers and
	22834	footers that are the same for both even- and odd-numbered pages.
	22835	@item
	22836	@code{@@evenheading} and @code{@@evenfooting} command generate headers
	22837	and footers for even-numbered (left-hand) pages.
	22838	@item
	22839	@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
	22840	for odd-numbered (right-hand) pages.
	22841	@end itemize
	22842
	22843	Write custom heading specifications in the Texinfo file immediately
	22844	after the @code{@@end titlepage} command. You must cancel the
	22845	predefined heading commands with the @code{@@headings off} command
	22846	before defining your own specifications.
	22847
	22848	@need 1000
	22849	Here is how to tell @TeX{} to place the chapter name at the left, the
	22850	page number in the center, and the date at the right of every header
	22851	for both even- and odd-numbered pages:
	22852
	22853	@example
	22854	@group
	22855	@@headings off
	22856	@@everyheading @@thischapter @@\| @@thispage @@\| @@today@{@}
	22857	@end group
	22858	@end example
	22859
	22860	@noindent
	22861	You need to divide the left part from the central part and the central
	22862	part from the right part by inserting @samp{@@\|} between parts.
	22863	Otherwise, the specification command will not be able to tell where
	22864	the text for one part ends and the next part begins.
	22865
	22866	Each part can contain text or @@-commands. The text is printed as if
	22867	the part were within an ordinary paragraph in the body of the page.
	22868	The @@-commands replace themselves with the page number, date, chapter
	22869	name, or whatever.
	22870
	22871	@need 950
	22872	Here are the six heading and footing commands:
	22873
	22874	@table @code
	22875	@item @@everyheading @var{left} @@\| @var{center} @@\| @var{right}
	22876	@itemx @@everyfooting @var{left} @@\| @var{center} @@\| @var{right}
	22877	@findex everyheading
	22878	@findex everyfooting
	22879	The `every' commands specify the format for both even- and odd-numbered
	22880	pages. These commands are for documents that are printed on one side
	22881	of each sheet of paper, or for documents in which you want symmetrical
	22882	headers or footers.
	22883
	22884	@item @@evenheading @var{left} @@\| @var{center} @@\| @var{right}
	22885	@itemx @@oddheading @var{left} @@\| @var{center} @@\| @var{right}
	22886	@itemx @@evenfooting @var{left} @@\| @var{center} @@\| @var{right}
	22887	@itemx @@oddfooting @var{left} @@\| @var{center} @@\| @var{right}
	22888	@findex evenheading
	22889	@findex evenfooting
	22890	@findex oddheading
	22891	@findex oddfooting
	22892	The `even' and `odd' commands specify the format for even-numbered
	22893	pages and odd-numbered pages. These commands are for books and
	22894	manuals that are printed on both sides of each sheet of paper.
	22895	@end table
	22896
	22897	Use the @samp{@@this@dots{}} series of @@-commands to
	22898	provide the names of chapters
	22899	and sections and the page number. You can use the
	22900	@samp{@@this@dots{}} commands in the left, center, or right portions
	22901	of headers and footers, or anywhere else in a Texinfo file so long as
	22902	they are between @code{@@iftex} and @code{@@end iftex} commands.
	22903
	22904	@need 1000
	22905	Here are the @samp{@@this@dots{}} commands:
	22906
	22907	@table @code
	22908	@item @@thispage
	22909	@findex thispage
	22910	Expands to the current page number.
	22911
	22912	@item @@thissectionname
	22913	@findex thissectionname
	22914	Expands to the name of the current section.
	22915
	22916	@item @@thissectionnum
	22917	@findex thissectionnum
	22918	Expands to the number of the current section.
	22919
	22920	@item @@thissection
	22921	@findex thissection
	22922	Expands to the number and name of the current section, in the format
	22923	`Section 1: Title'.
	22924
	22925	@item @@thischaptername
	22926	@findex thischaptername
	22927	Expands to the name of the current chapter.
	22928
	22929	@item @@thischapternum
	22930	@findex thischapternum
	22931	Expands to the number of the current chapter, or letter of the current
	22932	appendix.
	22933
	22934	@item @@thischapter
	22935	@findex thischapter
	22936	Expands to the number and name of the current
	22937	chapter, in the format `Chapter 1: Title'.
	22938
	22939	@item @@thistitle
	22940	@findex thistitle
	22941	Expands to the name of the document, as specified by the
	22942	@code{@@settitle} command.
	22943
	22944	@item @@thisfile
	22945	@findex thisfile
	22946	For @code{@@include} files only: expands to the name of the current
	22947	@code{@@include} file. If the current Texinfo source file is not an
	22948	@code{@@include} file, this command has no effect. This command does
	22949	@emph{not} provide the name of the current Texinfo source file unless
	22950	it is an @code{@@include} file. (@xref{Include Files}, for more
	22951	information about @code{@@include} files.)
	22952	@end table
	22953
	22954	@noindent
	22955	You can also use the @code{@@today@{@}} command, which expands to the
	22956	current date, in `1 Jan 1900' format.
	22957	@findex today
	22958
	22959	Other @@-commands and text are printed in a header or footer just as
	22960	if they were in the body of a page. It is useful to incorporate text,
	22961	particularly when you are writing drafts:
	22962
	22963	@example
	22964	@group
	22965	@@headings off
	22966	@@everyheading @@emph@{Draft!@} @@\| @@thispage @@\| @@thischapter
	22967	@@everyfooting @@\| @@\| Version: 0.27: @@today@{@}
	22968	@end group
	22969	@end example
	22970
	22971	Beware of overlong titles: they may overlap another part of the
	22972	header or footer and blot it out.
	22973
	22974	If you have very short chapters and/or sections, several of them can
	22975	appear on a single page. You can specify which chapters and sections
	22976	you want @code{@@thischapter}, @code{@@thissection} and other such
	22977	macros to refer to on such pages as follows:
	22978
	22979	@table @code
	22980	@item @@everyheadingmarks @var{ref}
	22981	@itemx @@everyfootingmarks @var{ref}
	22982	@findex everyheadingmarks
	22983	@findex everyfootingmarks
	22984	The @var{ref} argument can be either @code{top} (the @code{@@this...}
	22985	commands will refer to the chapter/section at the top of a page) or
	22986	@code{bottom} (the commands will reflect the situation at the bottom
	22987	of a page). These @samp{@@every...} commands specify what to do on
	22988	both even- and odd-numbered pages.
	22989
	22990	@item @@evenheadingmarks @var{ref}
	22991	@itemx @@oddheadingmarks @var{ref}
	22992	@itemx @@evenfootingmarks @var{ref}
	22993	@itemx @@oddfootingmarks @var{ref}
	22994	@findex evenheadingmarks
	22995	@findex oddheadingmarks
	22996	@findex evenfootingmarks
	22997	@findex oddfootingmarks
	22998	These @samp{@@even...} and @samp{@@odd...} commands specify what to do
	22999	on only even- or odd-numbered pages, respectively. The @var{ref}
	23000	argument is the same as with the @samp{@@every...} commands.
	23001	@end table
	23002
	23003	Write these commands immediately after the @code{@@...contents}
	23004	commands, or after the @code{@@end titlepage} command if you don't
	23005	have a table of contents or if it is printed at the end of your
	23006	manual.
	23007
	23008	By default the @code{@@this...} commands reflect the situation at the
	23009	bottom of a page both in headings and in footings.
	23010
	23011
	23012	@node Catching Mistakes
	23013	@appendix Catching Mistakes
	23014	@cindex Structure, catching mistakes in
	23015	@cindex Nodes, catching mistakes
	23016	@cindex Catching mistakes
	23017	@cindex Correcting mistakes
	23018	@cindex Mistakes, catching
	23019	@cindex Problems, catching
	23020	@cindex Debugging the Texinfo structure
	23021
	23022	Besides mistakes in the content of your documentation, there are two
	23023	kinds of mistake you can make with Texinfo: you can make mistakes with
	23024	@@-commands, and you can make mistakes with the structure of the nodes
	23025	and chapters.
	23026
	23027	Emacs has two tools for catching the @@-command mistakes and two for
	23028	catching structuring mistakes.
	23029
	23030	For finding problems with @@-commands, you can run @TeX{} or a region
	23031	formatting command on the region that has a problem; indeed, you can
	23032	run these commands on each region as you write it.
	23033
	23034	For finding problems with the structure of nodes and chapters, you can use
	23035	@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
	23036	command and you can use the @kbd{M-x Info-validate} command.
	23037
	23038	@menu
	23039	* @command{makeinfo} Preferred:: @code{makeinfo} finds errors.
	23040	* Debugging with Info:: How to catch errors with Info formatting.
	23041	* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
	23042	* Using @code{texinfo-show-structure}:: How to use @code{texinfo-show-structure}.
	23043	* Using @code{occur}:: How to list all lines containing a pattern.
	23044	* Running @code{Info-validate}:: How to find badly referenced nodes.
	23045	@end menu
	23046
	23047
	23048	@node @command{makeinfo} Preferred
	23049	@section @command{makeinfo} Preferred
	23050
	23051	@c anchor{makeinfo Preferred}@c prev name
	23052
	23053	The @code{makeinfo} program does an excellent job of catching errors
	23054	and reporting them---far better than @code{texinfo-format-region} or
	23055	@code{texinfo-format-buffer}. In addition, the various functions for
	23056	automatically creating and updating node pointers and menus remove
	23057	many opportunities for human error.
	23058
	23059	If you can, use the updating commands to create and insert pointers
	23060	and menus. These prevent many errors. Then use @code{makeinfo} (or
	23061	its Texinfo mode manifestations, @code{makeinfo-region} and
	23062	@code{makeinfo-buffer}) to format your file and check for other
	23063	errors. This is the best way to work with Texinfo. But if you
	23064	cannot use @code{makeinfo}, or your problem is very puzzling, then you
	23065	may want to use the tools described in this appendix.
	23066
	23067
	23068	@node Debugging with Info
	23069	@section Catching Errors with Info Formatting
	23070	@cindex Catching errors with Info formatting
	23071	@cindex Debugging with Info formatting
	23072
	23073	After you have written part of a Texinfo file, you can use the
	23074	@code{texinfo-format-region} or the @code{makeinfo-region} command to
	23075	see whether the region formats properly.
	23076
	23077	Most likely, however, you are reading this section because for some
	23078	reason you cannot use the @code{makeinfo-region} command; therefore, the
	23079	rest of this section presumes that you are using
	23080	@code{texinfo-format-region}.
	23081
	23082	If you have made a mistake with an @@-command,
	23083	@code{texinfo-format-region} will stop processing at or after the
	23084	error and display an error message. To see where in the buffer the
	23085	error occurred, switch to the @samp{Info Region} buffer; the cursor
	23086	will be in a position that is after the location of the error. Also,
	23087	the text will not be formatted after the place where the error
	23088	occurred (or more precisely, where it was detected).
	23089
	23090	For example, if you accidentally end a menu with the command @code{@@end
	23091	menus} with an `s' on the end, instead of with @code{@@end menu}, you
	23092	will see an error message that says:
	23093
	23094	@example
	23095	@@end menus is not handled by texinfo
	23096	@end example
	23097
	23098	@noindent
	23099	The cursor will stop at the point in the buffer where the error
	23100	occurs, or not long after it. The buffer will look like this:
	23101
	23102	@example
	23103	@group
	23104	---------- Buffer: Info Region ----------
	23105	* Menu:
	23106
	23107	* Using texinfo-show-structure:: How to use
	23108	`texinfo-show-structure'
	23109	to catch mistakes.
	23110	* Running Info-validate:: How to check for
	23111	unreferenced nodes.
	23112	@@end menus
	23113	@point{}
	23114	---------- Buffer: Info Region ----------
	23115	@end group
	23116	@end example
	23117
	23118	The @code{texinfo-format-region} command sometimes provides slightly
	23119	odd error messages. For example, the following cross-reference fails
	23120	to format:
	23121
	23122	@example
	23123	(@@xref@{Catching Mistakes, for more info.)
	23124	@end example
	23125
	23126	@noindent
	23127	In this case, @code{texinfo-format-region} detects the missing closing
	23128	brace but displays a message that says @samp{Unbalanced parentheses}
	23129	rather than @samp{Unbalanced braces}. This is because the formatting
	23130	command looks for mismatches between braces as if they were
	23131	parentheses.
	23132
	23133	Sometimes @code{texinfo-format-region} fails to detect mistakes. For
	23134	example, in the following, the closing brace is swapped with the
	23135	closing parenthesis:
	23136
	23137	@example
	23138	(@@xref@{Catching Mistakes), for more info.@}
	23139	@end example
	23140
	23141	@noindent
	23142	Formatting produces:
	23143	@example
	23144	(*Note for more info.: Catching Mistakes)
	23145	@end example
	23146
	23147	The only way for you to detect this error is to realize that the
	23148	reference should have looked like this:
	23149
	23150	@example
	23151	(*Note Catching Mistakes::, for more info.)
	23152	@end example
	23153
	23154	Incidentally, if you are reading this node in Info and type @kbd{f
	23155	@key{RET}} (@code{Info-follow-reference}), you will generate an error
	23156	message that says:
	23157
	23158	@example
	23159	No such node: "Catching Mistakes) The only way @dots{}
	23160	@end example
	23161
	23162	@noindent
	23163	This is because Info perceives the example of the error as the first
	23164	cross-reference in this node and if you type a @key{RET} immediately
	23165	after typing the Info @kbd{f} command, Info will attempt to go to the
	23166	referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
	23167	will complete the node name of the correctly written example and take
	23168	you to the `Catching Mistakes' node. (If you try this, you can return
	23169	from the `Catching Mistakes' node by typing @kbd{l}
	23170	(@code{Info-last}).)
	23171
	23172
	23173	@node Debugging with @TeX{}
	23174	@section Debugging with @TeX{}
	23175	@cindex Catching errors with @TeX{} formatting
	23176	@cindex Debugging with @TeX{} formatting
	23177
	23178	You can also catch mistakes when you format a file with @TeX{}.
	23179
	23180	Usually, you will want to do this after you have run
	23181	@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
	23182	the same file, because @code{texinfo-format-buffer} sometimes displays
	23183	error messages that make more sense than @TeX{}. (@xref{Debugging
	23184	with Info}, for more information.)
	23185
	23186	For example, @TeX{} was run on a Texinfo file, part of which is shown
	23187	here:
	23188
	23189	@example
	23190	---------- Buffer: texinfo.texi ----------
	23191	name of the Texinfo file as an extension. The
	23192	@@samp@{??@} are `wildcards' that cause the shell to
	23193	substitute all the raw index files. (@@xref@{sorting
	23194	indices, for more information about sorting
	23195	indices.)@@refill
	23196	---------- Buffer: texinfo.texi ----------
	23197	@end example
	23198
	23199	@noindent
	23200	(The cross-reference lacks a closing brace.)
	23201	@TeX{} produced the following output, after which it stopped:
	23202
	23203	@example
	23204	---------- Buffer: tex-shell ----------
	23205	Runaway argument?
	23206	@{sorting indices, for more information about sorting
	23207	indices.) @@refill @@ETC.
	23208	! Paragraph ended before @@xref was complete.
	23209	<to be read again>
	23210	@@par
	23211	l.27
	23212
	23213	?
	23214	---------- Buffer: tex-shell ----------
	23215	@end example
	23216
	23217	In this case, @TeX{} produced an accurate and
	23218	understandable error message:
	23219
	23220	@example
	23221	Paragraph ended before @@xref was complete.
	23222	@end example
	23223
	23224	@noindent
	23225	@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
	23226	@samp{l.27} means that @TeX{} detected the problem on line 27 of the
	23227	Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
	23228	circumstance.
	23229
	23230	Unfortunately, @TeX{} is not always so helpful, and sometimes you must
	23231	truly be a Sherlock Holmes to discover what went wrong.
	23232
	23233	In any case, if you run into a problem like this, you can do one of three
	23234	things.
	23235
	23236	@enumerate
	23237	@item
	23238	You can tell @TeX{} to continue running and ignore just this error by
	23239	typing @key{RET} at the @samp{?} prompt.
	23240
	23241	@item
	23242	You can tell @TeX{} to continue running and to ignore all errors as best
	23243	it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.
	23244
	23245	This is often the best thing to do. However, beware: the one error
	23246	may produce a cascade of additional error messages as its consequences
	23247	are felt through the rest of the file. To stop @TeX{} when it is
	23248	producing such an avalanche of error messages, type @kbd{C-c} (or
	23249	@kbd{C-c C-c}, if you are running a shell inside Emacs).
	23250
	23251	@item
	23252	You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
	23253	at the @samp{?} prompt.
	23254	@end enumerate
	23255
	23256	If you are running @TeX{} inside Emacs, you need to switch to the shell
	23257	buffer and line at which @TeX{} offers the @samp{?} prompt.
	23258
	23259	Sometimes @TeX{} will format a file without producing error messages even
	23260	though there is a problem. This usually occurs if a command is not ended
	23261	but @TeX{} is able to continue processing anyhow. For example, if you fail
	23262	to end an itemized list with the @code{@@end itemize} command, @TeX{} will
	23263	write a DVI file that you can print out. The only error message that
	23264	@TeX{} will give you is the somewhat mysterious comment:
	23265
	23266	@example
	23267	(@@end occurred inside a group at level 1)
	23268	@end example
	23269
	23270	@noindent
	23271	However, if you print the DVI file, you will find that the text
	23272	of the file that follows the itemized list is entirely indented as if
	23273	it were part of the last item in the itemized list. The error message
	23274	is the way @TeX{} says that it expected to find an @code{@@end}
	23275	command somewhere in the file; but that it could not determine where
	23276	it was needed.
	23277
	23278	Another source of notoriously hard-to-find errors is a missing
	23279	@code{@@end group} command. If you ever are stumped by
	23280	incomprehensible errors, look for a missing @code{@@end group} command
	23281	first.
	23282
	23283	If the Texinfo file lacks header lines,
	23284	@TeX{} may stop in the
	23285	beginning of its run and display output that looks like the following.
	23286	The @samp{*} indicates that @TeX{} is waiting for input.
	23287
	23288	@example
	23289	This is TeX, Version 3.14159 (Web2c 7.0)
	23290	(test.texinfo [1])
	23291	*
	23292	@end example
	23293
	23294	@noindent
	23295	In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
	23296	write the header lines in the Texinfo file and run the @TeX{} command
	23297	again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
	23298	instead of @samp{@@}; and in this circumstance, you are working
	23299	directly with @TeX{}, not with Texinfo.)
	23300
	23301	@node Using @code{texinfo-show-structure}
	23302	@section Using @code{texinfo-show-structure}
	23303
	23304	@cindex Showing the structure of a file
	23305	@findex texinfo-show-structure
	23306
	23307	It is not always easy to keep track of the nodes, chapters, sections, and
	23308	subsections of a Texinfo file. This is especially true if you are revising
	23309	or adding to a Texinfo file that someone else has written.
	23310
	23311	In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
	23312	command lists all the lines that begin with the @@-commands that
	23313	specify the structure: @code{@@chapter}, @code{@@section},
	23314	@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
	23315	as prefix argument, if interactive),
	23316	the command also shows the @code{@@node} lines. The
	23317	@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
	23318	Texinfo mode, by default.
	23319
	23320	The lines are displayed in a buffer called the @samp{Occur} buffer,
	23321	indented by hierarchical level. For example, here is a part of what was
	23322	produced by running @code{texinfo-show-structure} on this manual:
	23323
	23324	@example
	23325	@group
	23326	Lines matching "^@@\\(chapter \\\|sect\\\|subs\\\|subh\\\|
	23327	unnum\\\|major\\\|chapheading \\\|heading \\\|appendix\\)"
	23328	in buffer texinfo.texi.
	23329	@dots{}
	23330	4177:@@chapter Nodes
	23331	4198: @@heading Two Paths
	23332	4231: @@section Node and Menu Illustration
	23333	4337: @@section The @@code@{@@@@node@} Command
	23334	4393: @@subheading Choosing Node and Pointer Names
	23335	4417: @@subsection How to Write a @@code@{@@@@node@} Line
	23336	4469: @@subsection @@code@{@@@@node@} Line Tips
	23337	@dots{}
	23338	@end group
	23339	@end example
	23340
	23341	This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
	23342	with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
	23343	commands respectively. If you move your cursor into the @samp{Occur}
	23344	window, you can position the cursor over one of the lines and use the
	23345	@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
	23346	the corresponding spot in the Texinfo file. @xref{Other Repeating
	23347	Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
	23348	information about @code{occur-mode-goto-occurrence}.
	23349
	23350	The first line in the @samp{Occur} window describes the @dfn{regular
	23351	expression} specified by @var{texinfo-heading-pattern}. This regular
	23352	expression is the pattern that @code{texinfo-show-structure} looks for.
	23353	@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
	23354	for more information.
	23355
	23356	When you invoke the @code{texinfo-show-structure} command, Emacs will
	23357	display the structure of the whole buffer. If you want to see the
	23358	structure of just a part of the buffer, of one chapter, for example,
	23359	use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
	23360	region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
	23361	how the example used above was generated. (To see the whole buffer
	23362	again, use @kbd{C-x n w} (@code{widen}).)
	23363
	23364	If you call @code{texinfo-show-structure} with a prefix argument by
	23365	typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
	23366	@code{@@node} as well as the lines beginning with the @@-sign commands
	23367	for @code{@@chapter}, @code{@@section}, and the like.
	23368
	23369	You can remind yourself of the structure of a Texinfo file by looking at
	23370	the list in the @samp{Occur} window; and if you have mis-named a node
	23371	or left out a section, you can correct the mistake.
	23372
	23373	@node Using @code{occur}
	23374	@section Using @code{occur}
	23375
	23376	@cindex Occurrences, listing with @code{@@occur}
	23377	@findex occur
	23378
	23379	Sometimes the @code{texinfo-show-structure} command produces too much
	23380	information. Perhaps you want to remind yourself of the overall structure
	23381	of a Texinfo file, and are overwhelmed by the detailed list produced by
	23382	@code{texinfo-show-structure}. In this case, you can use the @code{occur}
	23383	command directly. To do this, type:
	23384
	23385	@example
	23386	@kbd{M-x occur}
	23387	@end example
	23388
	23389	@noindent
	23390	and then, when prompted, type a @dfn{regexp}, a regular expression for
	23391	the pattern you want to match. (@xref{Regexps, , Regular Expressions,
	23392	emacs, The GNU Emacs Manual}.) The @code{occur} command works from
	23393	the current location of the cursor in the buffer to the end of the
	23394	buffer. If you want to run @code{occur} on the whole buffer, place
	23395	the cursor at the beginning of the buffer.
	23396
	23397	For example, to see all the lines that contain the word
	23398	@samp{@@chapter} in them, just type @samp{@@chapter}. This will
	23399	produce a list of the chapters. It will also list all the sentences
	23400	with @samp{@@chapter} in the middle of the line.
	23401
	23402	If you want to see only those lines that start with the word
	23403	@samp{@@chapter}, type @samp{^@@chapter} when prompted by
	23404	@code{occur}. If you want to see all the lines that end with a word
	23405	or phrase, end the last word with a @samp{$}; for example,
	23406	@samp{catching mistakes$}. This can be helpful when you want to see
	23407	all the nodes that are part of the same chapter or section and
	23408	therefore have the same `Up' pointer.
	23409
	23410	@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
	23411	for more information.
	23412
	23413
	23414	@node Running @code{Info-validate}
	23415	@section Finding Badly Referenced Nodes
	23416
	23417	@anchor{Running Info-Validate}@c old name
	23418	@findex Info-validate
	23419	@cindex Nodes, checking for badly referenced
	23420	@cindex Checking for badly referenced nodes
	23421	@cindex Looking for badly referenced nodes
	23422	@cindex Finding badly referenced nodes
	23423	@cindex Badly referenced nodes
	23424
	23425	You can use the @code{Info-validate} command to check whether any of
	23426	the `Next', `Previous', `Up' or other node pointers fail to point to a
	23427	node. This command checks that every node pointer points to an
	23428	existing node. The @code{Info-validate} command works only on Info
	23429	files, not on Texinfo files.
	23430
	23431	The @code{makeinfo} program validates pointers automatically, so you
	23432	do not need to use the @code{Info-validate} command if you are using
	23433	@code{makeinfo}. You only may need to use @code{Info-validate} if you
	23434	are unable to run @code{makeinfo} and instead must create an Info file
	23435	using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
	23436	if you write an Info file from scratch.
	23437
	23438	@menu
	23439	* Using @code{Info-validate}:: How to run @code{Info-validate}.
	23440	* Unsplit:: How to create an unsplit file.
	23441	* Tagifying:: How to tagify a file.
	23442	* Splitting:: How to split a file manually.
	23443	@end menu
	23444
	23445
	23446	@node Using @code{Info-validate}
	23447	@subsection Using @code{Info-validate}
	23448
	23449	@cindex Using @code{Info-validate}
	23450	@cindex Info validating a large file
	23451	@cindex Validating a large file
	23452
	23453	To use @code{Info-validate}, visit the Info file you wish to check and
	23454	type:
	23455
	23456	@example
	23457	M-x Info-validate
	23458	@end example
	23459
	23460	@noindent
	23461	Note that the @code{Info-validate} command requires an uppercase
	23462	`I'@. You may also need to create a tag table before running
	23463	@code{Info-validate}. @xref{Tagifying}.
	23464
	23465	If your file is valid, you will receive a message that says ``File appears
	23466	valid''. However, if you have a pointer that does not point to a node,
	23467	error messages will be displayed in a buffer called @samp{*problems in
	23468	info file*}.
	23469
	23470	For example, @code{Info-validate} was run on a test file that contained
	23471	only the first node of this manual. One of the messages said:
	23472
	23473	@example
	23474	In node "Overview", invalid Next: Texinfo Mode
	23475	@end example
	23476
	23477	@noindent
	23478	This meant that the node called @samp{Overview} had a `Next' pointer that
	23479	did not point to anything (which was true in this case, since the test file
	23480	had only one node in it).
	23481
	23482	Now suppose we add a node named @samp{Texinfo Mode} to our test case
	23483	but we do not specify a `Previous' for this node. Then we will get
	23484	the following error message:
	23485
	23486	@example
	23487	In node "Texinfo Mode", should have Previous: Overview
	23488	@end example
	23489
	23490	@noindent
	23491	This is because every `Next' pointer should be matched by a
	23492	`Previous' (in the node where the `Next' points) which points back.
	23493
	23494	@code{Info-validate} also checks that all menu entries and cross-references
	23495	point to actual nodes.
	23496
	23497	@code{Info-validate} requires a tag table and does not work with files
	23498	that have been split. (The @code{texinfo-format-buffer} command
	23499	automatically splits large files.) In order to use @code{Info-validate}
	23500	on a large file, you must run @code{texinfo-format-buffer} with an
	23501	argument so that it does not split the Info file; and you must create a
	23502	tag table for the unsplit file.
	23503
	23504	@node Unsplit
	23505	@subsection Creating an Unsplit File
	23506	@cindex Creating an unsplit file
	23507	@cindex Unsplit file creation
	23508
	23509	You can run @code{Info-validate} only on a single Info file that has a
	23510	tag table. The command will not work on the indirect subfiles that
	23511	are generated when a master file is split. If you have a large file
	23512	(longer than 300,000 bytes or so), you need to run the
	23513	@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
	23514	a way that it does not create indirect subfiles. You will also need
	23515	to create a tag table for the Info file. After you have done this,
	23516	you can run @code{Info-validate} and look for badly referenced
	23517	nodes.
	23518
	23519	The first step is to create an unsplit Info file. To prevent
	23520	@code{texinfo-format-buffer} from splitting a Texinfo file into
	23521	smaller Info files, give a prefix to the @kbd{M-x
	23522	texinfo-format-buffer} command:
	23523
	23524	@example
	23525	C-u M-x texinfo-format-buffer
	23526	@end example
	23527
	23528	@noindent
	23529	or else
	23530
	23531	@example
	23532	C-u C-c C-e C-b
	23533	@end example
	23534
	23535	@noindent
	23536	When you do this, Texinfo will not split the file and will not create
	23537	a tag table for it.
	23538	@cindex Making a tag table manually
	23539	@cindex Tag table, making manually
	23540
	23541	@node Tagifying
	23542	@subsection Tagifying a File
	23543
	23544	After creating an unsplit Info file, you must create a tag table for
	23545	it. Visit the Info file you wish to tagify and type:
	23546
	23547	@example
	23548	M-x Info-tagify
	23549	@end example
	23550
	23551	@noindent
	23552	(Note the uppercase @samp{I} in @code{Info-tagify}.) This creates an
	23553	Info file with a tag table that you can validate.
	23554
	23555	The third step is to validate the Info file:
	23556
	23557	@example
	23558	M-x Info-validate
	23559	@end example
	23560
	23561	@noindent
	23562	(Note the uppercase @samp{I} in @code{Info-validate}.)
	23563	In brief, the steps are:
	23564
	23565	@example
	23566	@group
	23567	C-u M-x texinfo-format-buffer
	23568	M-x Info-tagify
	23569	M-x Info-validate
	23570	@end group
	23571	@end example
	23572
	23573	After you have validated the node structure, you can rerun
	23574	@code{texinfo-format-buffer} in the normal way so it will construct a
	23575	tag table and split the file automatically, or you can make the tag
	23576	table and split the file manually.
	23577
	23578	@node Splitting
	23579	@subsection Splitting a File Manually
	23580	@cindex Splitting an Info file manually
	23581	@cindex Info file, splitting manually
	23582
	23583	You should split a large file or else let the
	23584	@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
	23585	for you automatically. (Generally you will let one of the formatting
	23586	commands do this job for you. @xref{Creating an Info File}.)
	23587
	23588	The split-off files are called the indirect subfiles.
	23589
	23590	Info files are split to save memory. With smaller files, Emacs does not
	23591	have make such a large buffer to hold the information.
	23592
	23593	If an Info file has more than 30 nodes, you should also make a tag
	23594	table for it. @xref{Using @code{Info-validate}}, for information
	23595	about creating a tag table. (Again, tag tables are usually created
	23596	automatically by the formatting command; you only need to create a tag
	23597	table yourself if you are doing the job manually. Most likely, you
	23598	will do this for a large, unsplit file on which you have run
	23599	@code{Info-validate}.)
	23600
	23601	Visit the Info file you wish to tagify and split and type the two
	23602	commands:
	23603
	23604	@example
	23605	M-x Info-tagify
	23606	M-x Info-split
	23607	@end example
	23608
	23609	@noindent
	23610	(Note that the @samp{I} in @samp{Info} is uppercase.)
	23611
	23612	When you use the @code{Info-split} command, the buffer is modified into a
	23613	(small) Info file which lists the indirect subfiles. This file should be
	23614	saved in place of the original visited file. The indirect subfiles are
	23615	written in the same directory the original file is in, with names generated
	23616	by appending @samp{-} and a number to the original file name.
	23617
	23618	The primary file still functions as an Info file, but it contains just
	23619	the tag table and a directory of subfiles.
	23620
	23621
	23622	@node Info Format Specification
	23623	@appendix Info Format Specification
	23624
	23625	@cindex Info format specification
	23626	@cindex Specification of Info format
	23627	@cindex Definition of Info format
	23628
	23629	Here we describe the technical details of the Info format.
	23630
	23631	In this formal description, the characters @code{<>*()\|=#} are used
	23632	for the language of the description itself. Other characters are
	23633	literal. The formal constructs used are typical: @code{<...>}
	23634	indicates a metavariable name, @samp{=} means definition, @samp{*}
	23635	repetition, @samp{?} optional, @samp{()} grouping, @samp{\|}
	23636	alternation, @samp{#} comment. Exception: @samp{*} at the beginning
	23637	of a line is literal.
	23638
	23639	In general, programs that read Info files should try to be
	23640	case-insensitive to keywords that occur in the file (for example,
	23641	@samp{Tag Table} and @samp{Tag table} should be equivalent) in order to
	23642	support Info-generating programs that use different capitalization.
	23643
	23644	The sections in an Info file (such as nodes or tag tables) are separated
	23645	with a sequence:
	23646
	23647	@example
	23648	(^L)?^_(^L)?^J
	23649	@end example
	23650
	23651	@noindent
	23652	That is, a @samp{CTRL-_} character followed by a newline, with optional
	23653	formfeed characters. We refer to such sequences as @t{<separator>}.
	23654
	23655	We specify literal parentheses (those that are part of the Info
	23656	format) with @t{<lparen>} and @t{<rparen>}, meaning the single
	23657	characters @samp{(} and @samp{)} respectively. We specify the
	23658	@samp{CTRL-?} character (character number 127) @t{<del>}. Finally,
	23659	the two-character sequence @samp{^@var{x}} means the single
	23660	character @samp{CTRL-@var{x}}, for any @var{x}.
	23661
	23662	This format definition was written some 25 years after the Info format
	23663	was first devised. So in the event of conflicts between this
	23664	definition and actual practice, practice wins. It also assumes some
	23665	general knowledge of Texinfo; it is meant to be a guide for
	23666	implementors rather than a rigid technical standard. We often refer
	23667	back to other parts of this manual for examples and definitions,
	23668	rather than redundantly spelling out every detail.
	23669
	23670	@menu
	23671	* General: Info Format General Layout.
	23672	* Text: Info Format Text Constructs.
	23673	@end menu
	23674
	23675
	23676	@node Info Format General Layout
	23677	@section Info Format General Layout
	23678
	23679	This section describes the overall layout of Info manuals.
	23680
	23681	@menu
	23682	* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals.
	23683	* Preamble: Info Format Preamble.
	23684	* Indirect: Info Format Indirect Table.
	23685	* Tag table: Info Format Tag Table.
	23686	* Local variables: Info Format Local Variables.
	23687	* Regular nodes: Info Format Regular Nodes.
	23688	@end menu
	23689
	23690
	23691	@node Info Format Whole Manual
	23692	@subheading Info Format: A Whole Manual
	23693
	23694	@cindex Nonsplit manuals, Info format of
	23695	@cindex Split manuals, Info format of
	23696	@cindex Whole manual, in Info format
	23697
	23698	To begin, an Info manual is either @dfn{nonsplit} (contained wholly
	23699	within a single file) or @dfn{split} (across several files).
	23700
	23701	The syntax for a nonsplit manual is:
	23702
	23703	@example
	23704	<nonsplit info file> =
	23705	<preamble>
	23706	<node>*
	23707	<tag table>?
	23708	<local variables>?
	23709	@end example
	23710
	23711	When split, there is a @dfn{main file}, which contains only pointers
	23712	to the nodes given in other @dfn{subfiles}. The main file looks
	23713	like this:
	23714
	23715	@example
	23716	<split info main file> =
	23717	<preamble>
	23718	<indirect table>
	23719	<tag table>
	23720	<local variables>?
	23721	@end example
	23722
	23723	The subfiles in a split manual have the following syntax:
	23724
	23725	@example
	23726	<split info subfile> =
	23727	<preamble>
	23728	<node>*
	23729	@end example
	23730
	23731	Note that the tag table is not optional for split files, as it is used
	23732	with the indirect table to deduce which subfile a particular node is in.
	23733
	23734
	23735	@node Info Format Preamble
	23736	@subheading Info Format: Preamble
	23737
	23738	@cindex Preamble, in Info format
	23739
	23740	The @t{<preamble>} is text at the beginning of all output files.
	23741	It is not intended to be visible by default in an Info viewer, but
	23742	may be displayed upon user request.
	23743
	23744	@example
	23745	<preamble> =
	23746	<identification> # "This is FILENAME, produced by ..."
	23747	<copying text> # Expansion of @@copying text.
	23748	<dir entries> # Derived from @@dircategory and @@direntry.
	23749	@end example
	23750
	23751	@noindent
	23752	These pieces are:
	23753
	23754	@table @t
	23755	@item <identification line>
	23756	An arbitrary string beginning the output file, followed by a blank
	23757	line.
	23758
	23759	@item <copying text>
	23760	The expansion of a @code{@@copying} environment, if the manual has
	23761	one (@pxref{@code{@@copying}}).
	23762
	23763	@item <dir entries>
	23764	The result of any @code{@@dircategory} and @code{@@direntry}
	23765	commands present in the manual (@pxref{Installing Dir Entries}).
	23766
	23767	@end table
	23768
	23769
	23770	@node Info Format Indirect Table
	23771	@subheading Info Format: Indirect Table
	23772
	23773	@cindex Indirect table, in Info format
	23774
	23775	@example
	23776	<indirect table> =
	23777	<separator>
	23778	Indirect:
	23779	(<filename>: <bytepos>)*
	23780	@end example
	23781
	23782	The indirect table is written to the main file in the case of split
	23783	output only. It specifies, as a decimal integer, the starting byte
	23784	position (zero-based) that the first node of each subfile would have if
	23785	the subfiles were concatenated together in order, not including the
	23786	top-level file. The first node of actual content is pointed to by the
	23787	first entry.
	23788
	23789	As an example, suppose split output is generated for the GDB manual.
	23790	The top-level file @file{gdb.info} will contain something like this:
	23791
	23792	@example
	23793	<separator>
	23794	Indirect:
	23795	gdb.info-1: 1878
	23796	gdb.info-2: 295733
	23797	...
	23798	@end example
	23799
	23800	This tells Info viewers that the first node of the manual occurs at
	23801	byte 1878 of the file @file{gdb.info-1} (which would be after that file's
	23802	preamble.) The first node in the @file{gdb.info-2} subfile would start at
	23803	byte 295733 if @file{gdb.info-2} were appended to @file{gdb.info-1},
	23804	including any preamble sections in both files.
	23805
	23806	Unfortunately, Info-creating programs such as @code{makeinfo} have not
	23807	always implemented these rules perfectly, due to various bugs and
	23808	oversights. Therefore, robust Info viewers should fall back to
	23809	searching ``nearby'' the given position for a node, instead of
	23810	giving up immediately if the position is not exactly at a node beginning.
	23811
	23812
	23813	@node Info Format Tag Table
	23814	@subheading Info Format: Tag Table
	23815
	23816	@cindex Tag table, in Info format
	23817
	23818	@example
	23819	<tag table> =
	23820	<separator>
	23821	Tag Table:
	23822	(<lparen>Indirect<rparen>)?
	23823	(Node\|Ref): <nodeid>^?<bytepos>
	23824	<separator>
	23825	End Tag Table
	23826	@end example
	23827
	23828	The @samp{(Indirect)} line appears in the case of split output only.
	23829
	23830	The tag table specifies the starting byte position of each node and anchor
	23831	in the file. In the case of split output, it is only written in the main
	23832	output file.
	23833
	23834	Each line defines an identifier as either an anchor or a node, as
	23835	specified. For example, @samp{Node: Top^?1647} says that the node named
	23836	@samp{Top} starts at byte 1647 while @samp{Ref: Overview-Footnote-1^?30045}
	23837	says that the anchor named @samp{Overview-Footnote-1} starts at byte 30045.
	23838	It is an error to define the same identifier both ways.
	23839
	23840	In the case of nonsplit output, the byte positions simply refer to the
	23841	location in the output file. In the case of split output, the byte
	23842	positions refer to an imaginary file created by concatenating all the
	23843	split files (but not the top-level file). See the previous section.
	23844
	23845	Here is an example:
	23846
	23847	@example
	23848	^_
	23849	Tag Table:
	23850	Node: Top^?89
	23851	Node: Ch1^?292
	23852	^_
	23853	End Tag Table
	23854	@end example
	23855
	23856	@noindent
	23857	This specifies a manual with two nodes, `Top' and `Ch1', at byte
	23858	positions 89 and 292 respectively. Because the @samp{(Indirect)} line
	23859	is not present, the manual is not split.
	23860
	23861	Preamble sections or other non-node sections of files do not have a tag
	23862	table entry.
	23863
	23864
	23865	@node Info Format Local Variables
	23866	@subheading Info Format: Local Variables
	23867
	23868	@cindex Local variable section, in Info format
	23869
	23870	The local variables section is optional and is currently used to give the
	23871	encoding information. It may be augmented in the future.
	23872
	23873	@example
	23874	<local variables> =
	23875	<separator>
	23876	Local Variables:
	23877	coding: <encoding>
	23878	End:
	23879	@end example
	23880
	23881	@xref{@code{@@documentencoding}}.
	23882
	23883
	23884	@node Info Format Regular Nodes
	23885	@subheading Info Format: Regular Nodes
	23886
	23887	@cindex Info nodes, in Info format
	23888
	23889	Regular nodes look like this:
	23890
	23891	@example
	23892	<node> =
	23893	<separator>
	23894	File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4>
	23895
	23896	<general text, until the next ^_ or end-of-file>
	23897	@end example
	23898
	23899	@noindent
	23900	At least one space or tab must be present after each colon and comma,
	23901	but any number of spaces are ignored. The @t{<id>} node identifiers have
	23902	following format:
	23903
	23904	@example
	23905	<id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)?
	23906	\| <id> = (<lparen><infofile><rparen>)?(<nodename>)?
	23907	@end example
	23908
	23909	This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically
	23910	either @samp{manualname} or @samp{manualname.info}. No parenthesized
	23911	@t{<infofile>} component may appear within @t{<id1>}.
	23912
	23913	Each of the identifiers after @code{Next}, @code{Prev} and @code{Up}
	23914	refer to nodes or anchors within a file. These pointers normally
	23915	refer within the same file, but @samp{(dir)} is often used to point to
	23916	the top-level dir file. If an @t{<infofile>} component is used then
	23917	the node name may be omitted, in which case the node identifier refers
	23918	to the @samp{Top} node within the referenced file.
	23919
	23920	The @code{Next} and @code{Prev} pointers are optional. The @code{Up}
	23921	pointer is technically also optional, although most likely this
	23922	indicates a mistake in the node structuring. Conventionally, the
	23923	nodes are arranged to form a tree, but this is not a requirement of
	23924	the format.
	23925
	23926	Node names containing periods, commas, colons or parentheses
	23927	(including @@-commands which produce any of these) can confuse
	23928	Info readers.
	23929	If it is necessary to refer to a node whose name contains any of
	23930	these, the @t{<nodename>} should be surrounded by a pair of @t{<del>}
	23931	characters. There is support in @command{makeinfo} for adding these
	23932	characters (@pxref{INFO_SPECIAL_CHARS_QUOTE}); however, we don't
	23933	recommend you make use of this support until such time as Info-reading
	23934	programs that recognize this syntax are common. @xref{Node Line
	23935	Requirements}.
	23936
	23937	The use of non-ASCII characters in the names of nodes is permitted,
	23938	but can cause problems in cross-references between nodes in Info files
	23939	with different character encodings, and also when node names from many
	23940	different files are listed (for example, with the @option{--apropos}
	23941	option to the standalone Info browser), so we recommend avoiding them
	23942	whenever feasible. For example, prefer the use of the ASCII
	23943	apostrophe character (@t{'}) to Unicode directional quotes.
	23944
	23945	The @t{<general text>} of the node can include the special constructs
	23946	described next.
	23947
	23948
	23949	@node Info Format Text Constructs
	23950	@section Info Format Text Constructs
	23951
	23952	@cindex Info format text constructs
	23953	@cindex text constructs, Info format
	23954
	23955	These special Info constructs can appear within the text of a node.
	23956
	23957
	23958	@node Info Format Menu
	23959	@subsection Info Format: Menu
	23960
	23961	@cindex Menus, in Info format
	23962
	23963	Conventionally menus appear at the end of nodes, but the Info format
	23964	places no restrictions on their location.
	23965
	23966	@example
	23967	<menu> =
	23968	* Menu:
	23969	(<menu entry> \| <menu comment>)*
	23970	@end example
	23971
	23972	The parts of a @t{<menu entry>} are also described in @ref{Menu
	23973	Parts}. They have the same syntax as cross-references (@pxref{Info
	23974	Format Cross Reference}). Indices extend the menu format to specify the
	23975	destination line; @pxref{Info Format Printindex}.
	23976
	23977	A @t{<menu comment>} is any line not beginning with @samp{*} that
	23978	appears either at the beginning of the menu or is separated from a
	23979	menu entry by one or more blank lines. These comments are intended to
	23980	be displayed as part of the menu, as-is (@pxref{Writing a Menu}).
	23981
	23982
	23983	@node Info Format Image
	23984	@subsection Info Format: Image
	23985
	23986	@cindex Images, in Info format
	23987
	23988	The @code{@@image} command results in the following special directive
	23989	within the Info file (@pxref{Images}):
	23990
	23991	@example
	23992	<image> =
	23993	^@@^H[image src="<image file>"
	23994	(text="<txt file contents>")?
	23995	(alt="<alt text>")?
	23996	^@@^H]
	23997	@end example
	23998
	23999	The line breaks and indentation in this description are editorial; the
	24000	whitespace between the different parts of the directive in Info files
	24001	is arbitrary.
	24002
	24003	In the strings @t{<image file>}, @t{<txt file contents>} and @t{<alt
	24004	text>}, @samp{"} is quoted as @samp{\"} and @samp{\} is quoted as
	24005	@samp{\\}. The txt and alt specifications are optional.
	24006
	24007	The @t{alt} value serves the same purpose as in HTML: A prose
	24008	description of the image. In text-only displays or speech systems,
	24009	for example, the @t{alt} value may be used instead of displaying the
	24010	(typically graphical) @t{<image file>}.
	24011
	24012	The @t{<txt file contents>}, if present, should be taken as an ASCII
	24013	representation of the image, for possible use on a text-only display.
	24014
	24015	The format does not prescribe the choice between displaying the
	24016	@t{<image file>}, the @t{<alt text>} or the @t{<txt file contents>}.
	24017
	24018
	24019	@node Info Format Printindex
	24020	@subsection Info Format: Printindex
	24021
	24022	@cindex Indices, in Info format
	24023
	24024	Indices in Info format are generally written as a menu
	24025	(@pxref{Indices}), but with an additional directive at the beginning
	24026	marking this as an index node:
	24027
	24028	@example
	24029	<printindex> =
	24030	^@@^H[index^@@^H]
	24031	* Menu:
	24032
	24033	<index entry>*
	24034	@end example
	24035
	24036	The @t{<index entry>} items are similar to normal menu entries, but
	24037	the free-format description is replaced by the line number of where
	24038	the entries occurs in the text:
	24039
	24040	@example
	24041	<index entry> =
	24042	* <entry text>: <entry node>. <lparen>line <lineno><rparen>
	24043	@end example
	24044
	24045	@noindent
	24046	The @t{<entry text>} is the index term. The @t{<lineno>} is an
	24047	unsigned integer, given relative to the start of the @t{<entry node>}.
	24048	There may be arbitrary whitespace after the colon and period, as usual
	24049	in menus, and may be broken across lines. Here is an example:
	24050
	24051	@example
	24052	^@@^H[index^@@^H]
	24053	* Menu:
	24054
	24055	* thunder: Weather Phenomena. (line 5)
	24056	@end example
	24057
	24058	This means that an index entry for `thunder' appears at line 5 of the
	24059	node `Weather Phenomena'.
	24060
	24061
	24062	@node Info Format Cross Reference
	24063	@subsection Info Format: Cross-reference
	24064
	24065	@cindex Cross-references, in Info format
	24066
	24067	A general cross-reference in Info format has one of the following two forms:
	24068
	24069	@example
	24070	<cross-reference> =
	24071	* (N\|n)ote <id>::
	24072	@c\| * (N\|n)ote <label>:<id>(.\|,)?
	24073	\| * (N\|n)ote <label>:<id>(.\|,)
	24074
	24075	<id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)?
	24076	\| <id> = (<lparen><infofile><rparen>)?(<nodename>)?
	24077	<label> = <del>?<label text><del>?
	24078	@end example
	24079
	24080	No space should occur between the @samp{*} character and the following
	24081	@samp{N} or @samp{n}. @samp{*Note} should be used at the start of a
	24082	sentence, otherwise @samp{*note} should be used. (Some Info readers,
	24083	such as the one in Emacs, can display @samp{Note} and @samp{note} as
	24084	@samp{See} and @samp{see} respectively.) In both cases, @t{<label
	24085	text>} is descriptive text.
	24086
	24087	In both forms the @t{<id>} refers to a node or anchor, in the same way
	24088	as a reference in the node information line does (@pxref{Info Format
	24089	Regular Nodes}). The optional parenthesized @samp{<infofile>} is the
	24090	filename of the manual being referenced, and the @t{<nodename>} is the
	24091	node or anchor within that manual,
	24092
	24093	The second form has a descriptive label. A cross-reference in this form
	24094	should usually be terminated with a comma or period, to make it
	24095	feasible to find the end of the @t{<id>}.
	24096
	24097	If @t{<label>} contains a colon character (@t{:}), it should be
	24098	surrounded with a pair of @t{<del>} characters. Likewise, if
	24099	@t{<nodename>} contains problematic characters (such as commas or
	24100	periods), it should be surrounded by a pair of @t{<del>} characters;
	24101	then a terminating comma or period is not needed.
	24102
	24103	As with node names, this quoting mechanism has as of the time of
	24104	writing limited support in Info-reading programs; hence we do not
	24105	recommend using it until this changes.
	24106
	24107	The format does not prescribe how to find other manuals to resolve
	24108	such references.
	24109
	24110	Here are some examples:
	24111
	24112	@example
	24113	*note GNU Free Documentation License::
	24114	*note Tag table: Info Format Tag Table, for details.
	24115	*Note Overview: (make)Top.
	24116	*Note ^?:^?: (bash)Bourne Shell Builtins.
	24117	*Note alloca.h: (gnulib)^?alloca.h^?.
	24118	@end example
	24119
	24120	The first shows a reference to a node in the current manual using the
	24121	short form.
	24122
	24123	The second also refers to a node in the current manual, namely `Info
	24124	Format Tag Table'; the `Tag table' before the @samp{:} is only a label
	24125	on this particular reference, and the @samp{for details.} is text
	24126	belonging to the sentence, not part of the reference.
	24127
	24128	The third example refers to the node `Top' in another manual, namely
	24129	@samp{make}, with `Overview' being the label for this cross-reference.
	24130
	24131	The fourth example shows a colon character being quoted in a label,
	24132	and the fifth example shows a period being quoted in a node name.
	24133
	24134	@xref{Cross References}.
	24135
	24136
	24137	@node GNU Free Documentation License
	24138	@appendix GNU Free Documentation License
	24139
	24140	@include fdl.texi
	24141
	24142
	24143	@node Command and Variable Index
	24144	@unnumbered Command and Variable Index
	24145
	24146	This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
	24147	functions, and several variables. To make the list easier to use, the
	24148	commands are listed without their preceding @samp{@@}.
	24149
	24150	@printindex fn
	24151
	24152
	24153	@node General Index
	24154	@unnumbered General Index
	24155
	24156	@printindex cp
	24157
	24158
	24159	@bye