Mercurial > hg > xemacs-beta
changeset 5794:2d20d57d4e7b
Do not build or ship the texinfo info files.
They are available from the texinfo distribution, and break the build for
some versions of makeinfo. See xemacs-patches message with ID
<CAHCOHQ=EERhpe14cMzWjp286TzNHuw8ez-L-uy6kjoRPZE3b3A@mail.gmail.com>.
| author | Jerry James <james@xemacs.org> |
|---|---|
| date | Wed, 07 May 2014 13:33:50 -0600 |
| parents | cf0201de66df |
| children | d2c0ff38ad5c |
| files | man/ChangeLog man/Makefile.in man/texinfo/fdl.texi man/texinfo/texinfo.texi man/texinfo/version.texi |
| diffstat | 5 files changed, 9 insertions(+), 25026 deletions(-) [+] |
line wrap: on
line diff
--- a/man/ChangeLog Fri Apr 25 23:38:16 2014 +0200 +++ b/man/ChangeLog Wed May 07 13:33:50 2014 -0600 @@ -1,3 +1,11 @@ +2014-03-28 Jerry James <james@xemacs.org> + + * Makefile.in: Do not build texinfo files. + * texinfo/fdl.texi: + * texinfo/texinfo.texi: + * texinfo/version.texi: + Remove files belonging to an external project. + 2014-03-28 Jerry James <james@xemacs.org> * lispref/loading.texi:
--- a/man/Makefile.in Fri Apr 25 23:38:16 2014 +0200 +++ b/man/Makefile.in Wed May 07 13:33:50 2014 -0600 @@ -56,7 +56,6 @@ $(DIR)new-users-guide.texi \ $(DIR)standards.texi \ $(DIR)termcap.texi \ - $(DIR)texinfo.texi \ $(DIR)widget.texi \ $(DIR)xemacs.texi \ $(DIR)xemacs-faq.texi @@ -203,11 +202,6 @@ new-users-guide/search.texi \ new-users-guide/xmenu.texi -texinfo-srcs = \ - texinfo/fdl.texi \ - texinfo/texinfo.texi \ - texinfo/version.texi - $(INFODIR)/beta.info : beta.texi $(MAKEINFO) -o $(INFODIR)/beta.info beta.texi @@ -254,16 +248,12 @@ $(INFODIR)/new-users-guide.info : $(new-users-guide-srcs) $(MAKEINFO) -P new-users-guide -o $(INFODIR)/new-users-guide.info new-users-guide/new-users-guide.texi -$(INFODIR)/texinfo.info : $(texinfo-srcs) - $(MAKEINFO) -P texinfo -o $(INFODIR)/texinfo.info texinfo/texinfo.texi - xemacs : $(INFODIR)/xemacs.info lispref : $(INFODIR)/lispref.info internals : $(INFODIR)/internals.info new-users-guide.info : $(INFODIR)/new-users-guide.info -texinfo : $(INFODIR)/texinfo.info -.PHONY : xemacs lispref internals new-users-guide texinfo info dvi pdf +.PHONY : xemacs lispref internals new-users-guide info dvi pdf info : $(info_files) html : $(html_files) @@ -286,9 +276,6 @@ new-users-guide.dvi : $(new-users-guide-srcs) $(TEXI2DVI) -I new-users-guide new-users-guide/new-users-guide.texi -texinfo.dvi : $(texinfo-srcs) - $(TEXI2DVI) -I texinfo texinfo/texinfo.texi - dvi : $(dvi_files) xemacs.pdf: $(xemacs-srcs) @@ -303,9 +290,6 @@ new-users-guide.pdf: $(new-users-guide-srcs) $(TEXI2DVI) --pdf -I new-users-guide new-users-guide/new-users-guide.texi -texinfo.pdf: $(texinfo-srcs) - $(TEXI2DVI) --pdf -I texinfo texinfo/texinfo.texi - pdf: $(pdf_files) .PHONY: mostlyclean clean distclean realclean extraclean @@ -381,13 +365,9 @@ $(HTMLDIR)/new-users-guide.html : $(new-users-guide-srcs) $(TEXI2HTML_SPLIT) new-users-guide/new-users-guide.texi -$(HTMLDIR)/texinfo.html : $(texinfo-srcs) - $(TEXI2HTML_SPLIT) texinfo/texinfo.texi - xemacs : $(HTMLDIR)/xemacs.html lispref : $(HTMLDIR)/lispref.html internals : $(HTMLDIR)/internals.html new-users-guide.html : $(HTMLDIR)/new-users-guide.html -texinfo : $(HTMLDIR)/texinfo.html html : $(html_files)
--- a/man/texinfo/fdl.texi Fri Apr 25 23:38:16 2014 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,508 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@c Synced up with: GFDL v1.3 of November 2008. -@c Synced by: Jerry James, 11 Feb 2014. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, La@TeX{} input -format, SGML or XML using a publicly available -DTD, and standard-conforming simple HTML, -PostScript or PDF designed for human modification. Examples -of transparent image formats include PNG, XCF and -JPG. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, SGML or -XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML, -PostScript or PDF produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.''@: line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End:
--- a/man/texinfo/texinfo.texi Fri Apr 25 23:38:16 2014 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,24491 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.texi 5381 2013-09-26 23:03:58Z karl $ - -@c Everything between the start/end of header lines will be passed by -@c XEmacs's {texinfo,makeinfo}-format region commands. See the `start of -@c header' node for more info. -@c %**start of header -@c Synced up with: Texinfo 5.2 of 26 Sep 2013. -@c Synced by: Jerry James, 11 Feb 2014. - -@c makeinfo and texinfo.tex ignore all text before @setfilename. -@setfilename texinfo.info - -@c Automake automatically updates version.texi to @set VERSION and -@c @set UPDATED to appropriate values. -@include version.texi -@c XEmacs: @settitle Texinfo @value{edition} -@settitle GNU Texinfo @value{VERSION} - -@c Define a new index for command-line options. -@defcodeindex op - -@c Put everything except function (command, in this case) names in one -@c index (arbitrarily chosen to be the concept index). -@syncodeindex op cp -@syncodeindex vr cp -@syncodeindex pg cp - -@paragraphindent 2 -@c finalout - -@comment %**end of header - -@copying -This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), -a documentation system that can produce both online information and a -printed manual from a single source using semantic markup. - -Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, -1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010, 2011, 2012, 2013 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation -License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Update info/dir entries. -* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. -* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo. -* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. -* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. -* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. -@end direntry - -@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a -@c prefix arg). This updates the node pointers, which texinfmt.el needs. - -@c Set smallbook if printing in smallbook format so the example of the -@c smallbook font is actually written using smallbook; in bigbook, a kludge -@c is used for TeX output. Do this through the -t option to texi2dvi, -@c so this same source can be used for other paper sizes as well. -@c smallbook -@c set smallbook -@c @@clear smallbook - -@c If you like blank pages, add through texi2dvi -t. -@c setchapternewpage odd - - -@shorttitlepage GNU Texinfo - -@titlepage -@title Texinfo -@subtitle The GNU Documentation Format -@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} - -@author Robert J. Chassell -@author Richard M. Stallman - -@c Include the Distribution inside the titlepage so -@c that headings are turned off. - -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 1 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-67-1 @c for version 4.0, September 1999. -@c ISBN 1-882114-65-5 is for version 3.12, March 1998. -@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. -@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995. - -@sp 1 -Cover art by Etienne Suvasa. -@end titlepage - - -@summarycontents -@contents - - -@ifnottex -@node Top -@top Texinfo - -This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), -a documentation system that can produce both online information and a -printed manual from a single source using semantic markup. - -The first part of this master menu lists the major nodes in this Info -document, including the @@-command and concept indices. The rest of -the menu lists all the lower level nodes in the document. -@end ifnottex - -@menu -* Copying Conditions:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: Using the XEmacs Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* Chapter Structuring:: Creating chapters, sections, appendices, etc. -* Nodes:: Writing nodes, the basic unit of Texinfo. -* Menus:: Writing menus. -* Cross References:: Writing cross references. -* Marking Text:: Marking words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: Block quotations, examples, etc. -* Lists and Tables:: Itemized or numbered lists, and tables. -* Special Displays:: Floating figures and footnotes. -* Indices:: Creating indices. -* Insertions:: Inserting @@-signs, braces, etc. -* Breaks:: Forcing or preventing line and page breaks. -* Definition Commands:: Describing functions and the like uniformly. -* Internationalization:: Supporting languages other than English. -* Conditionals:: Specifying text for only some output cases. -* Defining New Texinfo Commands:: User-defined macros and aliases. -* Include Files:: How to incorporate other Texinfo files. - -* Hardcopy:: Output for paper, with @TeX{}. -* Generic Translator @t{texi2any}:: @command{texi2any}, an all-purpose converter. -* Creating and Installing Info Files:: Details on Info output. -* Generating HTML:: Details on HTML output. -@c * texi2any Output Customization:: Fine tuning with initialization files. - -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo Files:: Complete examples, including full texts. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find mistakes in formatting. -* Info Format Specification:: Technical details of the Info file format. -* GNU Free Documentation License:: Copying this manual. -* Command and Variable Index:: A menu containing commands and variables. -* General Index:: A menu covering many topics. - -@detailmenu - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* Adding Output Formats:: Man pages and implementing new formats. -* Texinfo Document Structure:: How Texinfo manuals are usually arranged. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. - -Using Texinfo Mode - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* XEmacs Editing:: Texinfo mode adds to XEmacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - -Updating Nodes and Menus - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - -Beginning a Texinfo File - -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. - -Texinfo File Header - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* @t{@@setfilename}:: Tell Info the name of the Info file. -* @t{@@settitle}:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. - -Document Permissions - -* @t{@@copying}:: Declare the document's copying permissions. -* @t{@@insertcopying}:: Where to insert the permissions. - -Title and Copyright Pages - -* @t{@@titlepage}:: Create a title for the printed document. -* @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* Heading Generation:: Turn on page headings after the title and - copyright pages. - -The `Top' Node and Master Menu - -* Top Node Example:: -* Master Menu Parts:: - -Global Document Commands - -* @t{@@documentdescription}:: Document summary for the HTML output. -* @t{@@setchapternewpage}:: Start chapters on right-hand pages. -* @t{@@headings}:: An option for turning headings on and off - and double or single sided printing. -* @t{@@paragraphindent}:: Specify paragraph indentation. -* @t{@@firstparagraphindent}:: Suppressing first paragraph indentation. -* @t{@@exampleindent}:: Specify environment indentation. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* File End:: How to mark the end of a file. - -Chapter Structuring - -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* @t{@@chapter}:: Chapter structuring. -* @t{@@unnumbered @@appendix}:: -* @t{@@majorheading @@chapheading}:: -* @t{@@section}:: -* @t{@@unnumberedsec @@appendixsec @@heading}:: -* @t{@@subsection}:: -* @t{@@unnumberedsubsec @@appendixsubsec @@subheading}:: -* @t{@@subsubsection}:: Commands for the lowest level sections. -* @t{@@part}:: Collections of chapters. -* Raise/lower sections:: How to change commands' hierarchical level. - -Nodes - -* @t{@@node}:: Creating nodes, in detail. -* @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers. -* @t{@@anchor}:: Defining arbitrary cross reference targets. -* Node Menu Illustration:: A diagram, and sample nodes and menus. - -The @code{@@node} Command - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Requirements:: Keep names unique. -* First Node:: How to write a `Top' node. -* @t{@@top} Command:: How to use the @code{@@top} command. - -Menus - -* Menu Location:: Menus go at the ends of nodes. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. - -Cross References - -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* @t{@@xref}:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* @t{@@ref}:: A reference for the last part of a sentence. -* @t{@@pxref}:: How to write a parenthetical cross reference. -* @t{@@inforef}:: How to refer to an Info-only file. -* @t{@@url}:: How to refer to a uniform resource locator. -* @t{@@cite}:: How to refer to books not in the Info system. - -@code{@@xref} - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. - -Marking Text, Words and Phrases - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - -Indicating Definitions, Commands, etc. - -* Useful Highlighting:: Highlighting provides useful information. -* @t{@@code}:: Indicating program code. -* @t{@@kbd}:: Showing keyboard input. -* @t{@@key}:: Specifying keys. -* @t{@@samp}:: Indicating a literal sequence of characters. -* @t{@@verb}:: Indicating a verbatim sequence of characters. -* @t{@@var}:: Indicating metasyntactic variables. -* @t{@@env}:: Indicating environment variables. -* @t{@@file}:: Indicating file names. -* @t{@@command}:: Indicating command names. -* @t{@@option}:: Indicating option names. -* @t{@@dfn}:: Specifying definitions. -* @t{@@abbr}:: Indicating abbreviations. -* @t{@@acronym}:: Indicating acronyms. -* @t{@@indicateurl}:: Indicating an example url. -* @t{@@email}:: Indicating an electronic mail address. - -Emphasizing Text - -* @t{@@emph @@strong}:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. - -Quotations and Examples - -* Block Enclosing Commands:: Different constructs for different purposes. -* @t{@@quotation}:: Writing a quotation. -* @t{@@indentedblock}:: Block of text indented on left. -* @t{@@example}:: Writing an example in a fixed-width font. -* @t{@@verbatim}:: Writing a verbatim example. -* @t{@@verbatiminclude}:: Including a file verbatim. -* @t{@@lisp}:: Illustrating Lisp code. -* @t{@@small@dots{}}:: Examples in a smaller font. -* @t{@@display}:: Writing an example in the current font. -* @t{@@format}:: Writing an example without narrowed margins. -* @t{@@exdent}:: Undo indentation on a line. -* @t{@@flushleft @@flushright}:: Pushing text flush left or flush right. -* @t{@@raggedright}:: Avoiding justification on the right. -* @t{@@noindent}:: Preventing paragraph indentation. -* @t{@@indent}:: Forcing paragraph indentation. -* @t{@@cartouche}:: Drawing rounded rectangles around text. - -Lists and Tables - -* Introducing Lists:: Texinfo formats lists for you. -* @t{@@itemize}:: How to construct a simple list. -* @t{@@enumerate}:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. - -Making a Two-column Table - -* @t{@@table}:: How to construct a two-column table. -* @t{@@ftable @@vtable}:: Automatic indexing for two-column tables. -* @t{@@itemx}:: How to put more entries in the first column. - -@code{@@multitable}: Multi-column Tables - -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. - -Special Displays - -* Floats:: Figures, tables, and the like. -* Images:: Including graphics and images. -* Footnotes:: Writing footnotes. - -Floats - -* @t{@@float}:: Producing floating material. -* @t{@@caption @@shortcaption}:: Specifying descriptions for floats. -* @t{@@listoffloats}:: A table of contents for floats. - -Inserting Images - -* Image Syntax:: -* Image Scaling:: - -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - -Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entries. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - -Combining Indices - -* @t{@@syncodeindex}:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* @t{@@synindex}:: How to merge two indices, using the - roman font for the merged-from index. - -Special Insertions - -* Special Characters:: Inserting @@ @{@} , \ # -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: Inserting the right amount of whitespace. -* Inserting Accents:: Inserting accents and special characters. -* Inserting Quotation Marks:: Inserting quotation marks. -* Inserting Math:: Formatting mathematical expressions. -* Glyphs for Text:: Inserting Dots, bullets, currencies, etc. -* Glyphs for Programming:: Indicating results of evaluation, - expansion of macros, errors, etc. - -Special Characters: Inserting @@ @{@} , \ # - -* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. -* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. -* Inserting a Comma:: , and @code{@@comma@{@}}. -* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. -* Inserting a Hashsign:: # and @code{@@hashchar@{@}}. - -Inserting Space - -* Multiple Spaces:: Inserting multiple spaces. -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* @t{@@frenchspacing}:: Specifying end-of-sentence spacing. -* @t{@@dmn}:: Formatting a dimension. - -Glyphs for Text - -* @t{@@TeX @@LaTeX}:: The @TeX{} logos. -* @t{@@copyright}:: The copyright symbol (c in a circle). -* @t{@@registeredsymbol}:: The registered symbol (R in a circle). -* @t{@@dots}:: How to insert ellipses: @dots{} and @enddots{} -* @t{@@bullet}:: How to insert a bullet: @bullet{} -* @t{@@euro}:: How to insert the euro currency symbol. -* @t{@@pounds}:: How to insert the pounds currency symbol. -* @t{@@textdegree}:: How to insert the degrees symbol. -* @t{@@minus}:: How to insert a minus sign. -* @t{@@geq @@leq}:: How to insert greater/less-than-or-equal signs. - -Glyphs for Programming - -* Glyphs Summary:: -* @t{@@result}:: How to show the result of expression. -* @t{@@expansion}:: How to indicate an expansion. -* @t{@@print}:: How to indicate generated output. -* @t{@@error}:: How to indicate an error message. -* @t{@@equiv}:: How to indicate equivalence. -* @t{@@point}:: How to indicate the location of point. -* Click Sequences:: Inserting GUI usage sequences. - -Forcing and Preventing Breaks - -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points. -* @t{@@allowcodebreaks}:: Controlling line breaks within @@code text. -* @t{@@w}:: Preventing unwanted line breaks in text. -* @t{@@tie}:: Inserting an unbreakable but varying space. -* @t{@@sp}:: Inserting blank lines. -* @t{@@page}:: Forcing the start of a new page. -* @t{@@group}:: Preventing unwanted page breaks. -* @t{@@need}:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: Writing descriptions using definition commands. -* Def Cmd Continuation Lines:: Continuing the heading over source lines. -* Optional Arguments:: Handling optional and repeated arguments. -* @t{@@deffnx}:: Group two or more `first' lines. -* Def Cmds in Detail:: Reference for all the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: An example. - -The Definition Commands - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Data Types:: The definition command for data types. -* Abstract Objects:: Commands for object-oriented programming. - -Object-Oriented Programming - -* Variables: Object-Oriented Variables. -* Methods: Object-Oriented Methods. - -Internationalization - -* @t{@@documentlanguage}:: Declaring the current language. -* @t{@@documentencoding}:: Declaring the input encoding. - -Conditionally Visible Text - -* Conditional Commands:: Text for a given format. -* Conditional Not Commands:: Text for any format other than a given one. -* Raw Formatter Commands:: Using raw formatter commands. -* Inline Conditionals:: Brace-delimited conditional text. -* @t{@@set @@clear @@value}:: Variable tests and substitutions. -* Testing for Texinfo Commands:: Testing if a Texinfo command is available. -* Conditional Nesting:: Using conditionals inside conditionals. - -@code{@@set}, @code{@@clear}, and @code{@@value} - -* @t{@@set @@value}:: Expand a flag variable to a string. -* @t{@@ifset @@ifclear}:: Format a region if a flag is set. -* @t{@@value} Example:: An easy way to update edition information. - -Defining New Texinfo Commands - -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* @t{@@alias}:: Command aliases. -* @t{@@definfoenclose}:: Customized highlighting. -* External Macro Processors:: @code{#line} directives. - -External Macro Processors: Line Directives - -* @t{#line} Directive:: -* TeX: @t{#line} and @TeX{}. -* Syntax: @t{#line} Syntax Details. - -Include Files - -* Using Include Files:: How to use the @code{@@include} command. -* @t{texinfo-multiple-files-update}:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. - -Formatting and Printing Hardcopy - -* Use @TeX{}:: Use @TeX{} to format for hardcopy. -* Format with @t{tex}/@t{texindex}:: How to format with explicit shell commands. -* Format with @t{texi2dvi}:: A simpler way to format. -* Print with @t{lpr}:: How to print. -* Within XEmacs:: How to format and print from an XEmacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using XEmacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for @TeX{}:: What to do before you use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* @t{@@smallbook}:: How to print small format books and manuals. -* A4 Paper:: How to print on A4 or A5 paper. -* @t{@@pagesizes}:: How to print with customized page sizes. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. -* Obtaining @TeX{}:: How to obtain @TeX{}. - -@code{texi2any}: The Generic Translator for Texinfo - -* Reference Implementation:: @command{texi2any}: the reference implementation. -* Invoking @t{texi2any}:: Running the translator from a shell. -* @t{texi2any} Printed Output:: Calling @command{texi2dvi}. -* Pointer Validation:: How to check that pointers point somewhere. -* Customization Variables:: Configuring @command{texi2any}. -* Internationalization of Document Strings:: Translating program-inserted text. -* Invoking @t{pod2texi}:: Translating Perl pod to Texinfo. -* @t{texi2html}:: An ancestor of @command{texi2any}. - -Customization Variables - -* Commands: Customization Variables for @@-Commands. -* Options: Customization Variables and Options. -* Other: Other Customization Variables. - -Creating and Installing Info Files - -* Creating an Info File:: -* Installing an Info File:: - -Creating an Info File - -* @t{makeinfo} Advantages:: @code{makeinfo} provides better error checking. -* @t{makeinfo} in XEmacs:: How to run @code{makeinfo} from XEmacs. -* @t{texinfo-format} commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in XEmacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - -Installing an Info File - -* Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new Info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking @t{install-info}:: @code{install-info} options. - -Generating HTML - -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: Influencing HTML output with Cascading Style Sheets. -* HTML Xref:: Cross references in HTML output. - -HTML Cross References - -* Link Basics: HTML Xref Link Basics. -* Node Expansion: HTML Xref Node Name Expansion. -* Command Expansion: HTML Xref Command Expansion. -* 8-bit Expansion: HTML Xref 8-bit Character Expansion. -* Mismatch: HTML Xref Mismatch. -* Configuration: HTML Xref Configuration. htmlxref.cnf. -* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. - -@@-Command List - -* Command Syntax:: General syntax for varieties of @@-commands. -* Command Contexts:: Guidelines for which commands can be used where. - -Sample Texinfo Files - -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: - -Page Headings - -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. - -Catching Mistakes - -* @t{makeinfo} Preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting. -* Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}. -* Using @t{occur}:: How to list all lines containing a pattern. -* Running @t{Info-validate}:: How to find badly referenced nodes. - -Finding Badly Referenced Nodes - -* Using @t{Info-validate}:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. - -Info Format Specification - -* General: Info Format General Layout. -* Text: Info Format Text Constructs. - -Info Format General Layout - -* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals. -* Preamble: Info Format Preamble. -* Indirect: Info Format Indirect Tag Table. -* Tag table: Info Format Tag Table. -* Local variables: Info Format Local Variables. -* Regular nodes: Info Format Regular Nodes. - -Info Format Text Constructs - -* Menu: Info Format Menu. -* Image: Info Format Image. -* Printindex: Info Format Printindex. -* Xref: Info Format Cross Reference. -@end detailmenu -@end menu - -@c Reward readers for getting to the end of the menu :). -@c Contributed by Arnold Robbins. -@quotation -Documentation is like sex: when it is good, it is very, very good; and -when it is bad, it is better than nothing. ----Dick Brandon -@end quotation - - -@node Copying Conditions -@unnumbered Texinfo Copying Conditions -@cindex Copying conditions -@cindex Conditions for copying Texinfo -@cindex Free software -@cindex Libre software - -GNU Texinfo is @dfn{free software}; this means that everyone is free -to use it and free to redistribute it on certain conditions. Texinfo -is not in the public domain; it is copyrighted and there are -restrictions on its distribution, but these restrictions are designed -to permit everything that a good cooperating citizen would want to do. -What is not allowed is to try to prevent others from further sharing -any version of Texinfo that they might get from you. - -Specifically, we want to make sure that you have the right to give away -copies of the programs that relate to Texinfo, that you receive source -code or else can get it if you want it, that you can change these -programs or use pieces of them in new free programs, and that you know -you can do these things. - -To make sure that everyone has such rights, we have to forbid you to -deprive anyone else of these rights. For example, if you distribute -copies of the Texinfo related programs, you must give the recipients all -the rights that you have. You must make sure that they, too, receive or -can get the source code. And you must tell them their rights. - -Also, for our own protection, we must make certain that everyone finds -out that there is no warranty for the programs that relate to Texinfo. -If these programs are modified by someone else and passed on, we want -their recipients to know that what they have is not what we distributed, -so that any problems introduced by others will not reflect on our -reputation. - -The precise conditions of the licenses for the programs currently -being distributed that relate to Texinfo are found in the General -Public Licenses that accompany them. This manual is covered by the -GNU Free Documentation License (@pxref{GNU Free Documentation -License}). - - -@node Overview -@chapter Overview of Texinfo -@cindex Overview of Texinfo -@cindex Texinfo overview - -@dfn{Texinfo} is a documentation system that uses a single source file -to produce both online information and printed output. This means -that instead of writing two different documents, one for the online -information and the other for a printed work, you need write only one -document. Therefore, when the work is revised, you need revise only -that one document. - -@cindex Semantic markup -Texinfo's markup commands are almost entirely @dfn{semantic}; that is, -they specify the intended meaning of text in the document, rather than -physical formatting instructions. - -@cindex Limited scope of Texinfo -Texinfo was devised for the purpose of writing software documentation -and manuals. It is not, and was never intended to be, a -general-purpose formatting program. If you need to lay out a -newspaper, devise a glossy magazine ad, or follow the exact formatting -requirements of a publishing house, Texinfo is not the simplest tool. -On the other hand, if you want to write a good manual for your -program, Texinfo has many features that will make your job easier. -Overall, it's intended to let you concentrate on the content, and thus -provides almost no commands for controlling the final formatting. - -@cindex Pronounciation of Texinfo -@cindex Spelling of Texinfo -The first syllable of ``Texinfo'' is pronounced like ``speck'', not -``hex''. This odd pronunciation is derived from, but is not the same -as, the pronunciation of @TeX{}. In the word @TeX{}, the @samp{X} is -actually the Greek letter ``chi'' rather than the English letter -``ex''. Pronounce @TeX{} as if the @samp{X} were the last sound in -the name `Bach'; but pronounce Texinfo as if the @samp{x} were a `k'. -Spell ``Texinfo'' with a capital ``T'' and the other letters in -lowercase. - -Manuals for most GNU packages are written in Texinfo, and available -online at @url{http://www.gnu.org/doc}. The Texinfo - -@menu -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* Adding Output Formats:: Man pages and implementing new formats. -* Texinfo Document Structure:: How Texinfo manuals are usually arranged. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. -@end menu - - -@node Reporting Bugs -@section Reporting Bugs - -@cindex Bugs, reporting -@cindex Suggestions for Texinfo, making -@cindex Reporting bugs -We welcome bug reports and suggestions for any aspect of the Texinfo -system: programs, documentation, installation, etc. Please email them -to @email{bug-texinfo@@gnu.org}. You can get the latest version of -Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}. - -@cindex Checklist for bug reports -For bug reports, please include enough information for the maintainers -to reproduce the problem. Generally speaking, that means: - -@itemize @bullet -@item The version number of Texinfo and the program(s) or manual(s) involved. -@item The contents of any input files necessary to reproduce the bug. -@item Precisely how you ran any program(s) involved. -@item A description of the problem and samples of any erroneous output. -@item Hardware and operating system names and versions. -@item Anything else that you think would be helpful. -@end itemize - -When in doubt whether something is needed or not, include it. It's -better to include too much than to leave out something important. - -It is critical to send an actual input file that reproduces the -problem. What's not critical is to ``narrow down'' the example to the -smallest possible input---the actual input with which you discovered -the bug will suffice. (Of course, if you do do experiments, the -smaller the input file, the better.) - -@cindex Patches, contributing -Patches are most welcome; if possible, please make them with -@samp{@w{diff -c}} (@pxref{Top,,, diff, Comparing and Merging Files}) -and include @file{ChangeLog} entries (@pxref{Change Log,,, xemacs, -XEmacs User's Manual}), and follow the existing coding style. - - -@node Using Texinfo -@section Using Texinfo - -@cindex Using Texinfo in general -@cindex Texinfo, introduction to -@cindex Introduction to Texinfo - -Using Texinfo, you can create a printed document (via the @TeX{} -typesetting system) with the normal features of a book, including -chapters, sections, cross references, and indices. From the same -Texinfo source file, you can create an Info file with special features -to make documentation browsing easy. You can also create from that -same source file an HTML output file suitable for use with a web -browser, a Docbook file, or a transliteration in XML format. See the -next section (@pxref{Output Formats}) for details and sample commands -to generate output from the source. - -@TeX{} works with virtually all printers; Info works with virtually -all computer terminals; the HTML output works with virtually all web -browsers. Thus Texinfo and its output can be used by almost any -computer user. - -@cindex Source file format -A Texinfo source file is a plain ASCII file containing text -interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) -that tell the Texinfo processors what to do. You can edit a Texinfo -file with any text editor, but it is especially convenient to use -XEmacs since that editor has a special mode, called Texinfo mode, that -provides various Texinfo-related features. (@xref{Texinfo Mode}.) - -Texinfo is the official documentation format of the GNU project. More -information is available at the @uref{http://www.gnu.org/doc/, GNU -documentation web page}. - - -@node Output Formats -@section Output Formats -@cindex Output formats -@cindex Back-end output formats - -Here is a brief overview of the output formats currently supported by -Texinfo. - -@table @asis -@item Info -@cindex Info output, overview -(Generated via @command{makeinfo}.) Info format is mostly a plain -text transliteration of the Texinfo source. It adds a few control -characters to separate nodes and provide navigational information for -menus, cross references, indices, and so on. The XEmacs Info subsystem -(@pxref{Top,,Getting Started,info, Info}), and the standalone @command{info} -program (@pxref{Top,,, info-stnd, GNU Info}), among others, can read these -files. @xref{Info Files}, and @ref{Creating and Installing Info -Files}. - -@item Plain text -@cindex Plain text output, overview -(Generated via @command{makeinfo --plaintext}.) This is almost the -same as Info output with the navigational control characters are -omitted. - -@item HTML -@cindex HTML output, overview -@cindex W3 consortium -@cindex Mozilla -@cindex Lynx -@cindex XEmacs-W3 -(Generated via @command{makeinfo --html}.) HTML, standing for Hyper -Text Markup Language, has become the most commonly used language for -writing documents on the World Wide Web. Web browsers, such as -Mozilla, Lynx, and XEmacs-W3, can render this language online. There -are many versions of HTML; @command{makeinfo} tries to use a subset of -the language that can be interpreted by any common browser. For -details of the HTML language and much related information, see -@uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. - -@item DVI -@cindex DVI output, overview -@pindex dvips -@pindex xdvi -(Generated via @command{texi2dvi}.) The DeVIce Independent binary -format is output by the @TeX{} typesetting program -(@uref{http://tug.org}). This is then read by a DVI `driver', which -knows the actual device-specific commands that can be viewed or -printed, notably Dvips for translation to PostScript (@pxref{Top,,, -dvips, Dvips}) and Xdvi for viewing on an X display -(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. -(Be aware that the Texinfo language is very different from and much -stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{}, -Con@TeX{}t, etc.) - -@item PostScript -@cindex PostScript output, overview -(Generated via @command{texi2dvi --ps}.) PostScript is a page -description language that became widely used around 1985 and is still -used today. @uref{http://en.wikipedia.org/wiki/PostScript} gives a -basic description and more preferences. By default, Texinfo uses the -@command{dvips} program to convert @TeX{}'s DVI output to PostScript. -@xref{Top,,, dvips, Dvips}. - -@item PDF -@cindex PDF output, overview -@cindex Beebe, Nelson -(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This -format was developed by Adobe Systems for portable document -interchange, based on their previous PostScript language. It can -represent the exact appearance of a document, including fonts and -graphics, and supporting arbitrary scaling. It is intended to be -platform-independent and easily viewable, among other design goals; -@uref{http://en.wikipedia.org/wiki/Portable_Document_Format} and -@uref{http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some -background. By default, Texinfo uses the @command{pdftex} program, an -extension of @TeX{}, to output PDF; see -@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. - -@item Docbook -@cindex Docbook output, overview -@cindex XML Docbook output, overview -(Generated via @command{makeinfo --docbook}.) This is an XML-based -format developed some years ago, primarily for technical -documentation. It therefore bears some resemblance, in broad -outline, to Texinfo. See @uref{http://www.docbook.org}. Various -converters from Docbook @emph{to} Texinfo have also been developed; -see the Texinfo web pages. - -@item XML -@cindex XML Texinfo output, overview -@cindex Texinfo XML output, overview -@cindex DTD, for Texinfo XML -@pindex texinfo.dtd -@pindex txixml2texi -(Generated via @command{makeinfo --xml}.) XML is a generic syntax -specification usable for any sort of content (a reference is at -@uref{http://www.w3.org/XML}). The @command{makeinfo} XML output, -unlike all the other output formats, is a transliteration of the -Texinfo source rather than processed output. That is, it translates -the Texinfo markup commands into XML syntax, for further processing by -XML tools. The details of the output are defined in an XML DTD as -usual, which is contained in a file @file{texinfo.dtd} included in the -Texinfo source distribution and available via the Texinfo web pages. -The XML contains enough information to recreate the original content, -except for syntactic constructs such as Texinfo macros and -conditionals. The Texinfo source distribution includes a utility script -@file{txixml2texi} to do that backward transformation. -@end table - - -@node Adding Output Formats -@section Adding Output Formats -@cindex Additional output formats - -The output formats in the previous section handle a wide variety of -usage, but of course there is always room for more. - -@cindex Man page output, not supported -From time to time, proposals are made to generate traditional Unix man -pages from Texinfo source. However, because man pages have a strict -conventional format, creating a good man page requires a completely -different source than the typical Texinfo applications of writing a -good user tutorial and/or a good reference manual. This makes -generating man pages incompatible with the Texinfo design goal of not -having to document the same information in different ways for -different output formats. You might as well write the man page -directly. - -@pindex help2man -@cindex O'Dea, Brendan -As an alternative way to support man pages, you may find the program -@command{help2man} to be useful. It generates a traditional man page -from the @samp{--help} output of a program. In fact, the man pages -for the programs in the Texinfo distribution are generated with this. -It is GNU software written by Brendan O'Dea, available from -@uref{http://www.gnu.org/software/help2man}. - -@cindex Output formats, supporting more -@cindex SGML-tools output format -If you are a programmer and would like to contribute to the GNU -project by implementing additional output formats for Texinfo, that -would be excellent. The way to do this that would be most useful is -to write a new back-end for @command{texi2any}, our reference -implementation of a Texinfo parser; it creates a tree representation -of the Texinfo input that you can use for the conversion. The -documentation in the source file -@file{tp/Texinfo/Convert/Converter.pm} is a good place to start. -@xref{Generic Translator @t{texi2any}}. - -Another viable approach is use the Texinfo XML output from -@command{texi2any} as your input. This XML is an essentially complete -representation of the input, but without the Texinfo syntax and option -peculiarities, as described above. - -@cindex Texinfo parsers, discouraging more -If you still cannot resist the temptation of writing a new program -that reads Texinfo source directly, let us give some more caveats: -please do not underestimate the amount of work required. Texinfo is -by no means a simple language to parse correctly, and remains under -development, so you would be committing to an ongoing task. At a -minimum, please check that the extensive tests of the language that -come with @command{texi2any} give correct results with your new -program. - - -@node Texinfo Document Structure -@section Texinfo Document Structure -@cindex Texinfo document structure -@cindex Document structure, of Texinfo -@cindex Structure, of Texinfo documents -@cindex Double structure, of Texinfo documents - -@anchor{Two Paths}@c node name -Texinfo documents most usefully have a double structure, reflecting -the double purposes of printed and online output. For printed output -(DVI, PDF, @dots{}), with physical pages, there are chapters, -sections, subsections, etc. For online output (Info, HTML, @dots{}), -with interactive navigation and no physical pages, there are so-called -``nodes''. - -Typically, the sectioning structure and the node structure are -completely parallel, with one node for each chapter, section, etc., -and with the nodes following the same hierarchical arrangement as the -sectioning. Thus, if a node is at the logical level of a chapter, its -child nodes are at the level of sections; similarly, the child nodes -of sections are at the level of subsections. - -Each @dfn{node} has a name, and contains the discussion of one topic. -Along with the text for the user to read, each node also has pointers -to other nodes, identified in turn by their own names. Info readers -display one node at a time, and provide commands for the user to move -to related nodes. The HTML output can be similarly navigated. - -The names of child nodes are listed in a @dfn{menu} within the parent -node; for example, a node corresponding to a chapter would have a menu -of the sections in that chapter. The menus allow the user to move to -the child nodes in a natural way in the online output. - -In addition, nodes at the same level are formed into a chain with -`Next' and `Previous' pointers. As you might imagine, the `Next' -pointer links to the next node (section), and the `Previous' pointer -links to the previous node (section). Thus, for example, all the -nodes that are at the level of sections within a chapter are linked -together, and the order in this chain is the same as the order of the -children in the menu of parent chapter. Each child node records the -parent node name as its `Up' pointer. The last child has no `Next' -pointer, and the first child has the parent both as its `Previous' and -as its `Up' pointer. - -In addition to menus and `Next', `Previous', and `Up' pointers, -Texinfo provides pointers of another kind for cross references, that -can be sprinkled throughout the text. This is usually the best way to -represent links that do not fit a hierarchical structure. - -Although it is technically possible to create Texinfo documents with -only one structure or the other, or for the two structures not to be -parallel, or for either the sectioning or node structure to be -abnormally formed, etc., this is @emph{not at all recommended}. To -the best of our knowledge, all the Texinfo manuals currently in -general use do follow the conventional parallel structure. - - -@node Info Files -@section Info Files -@cindex Info files - -As mentioned above, Info format is mostly a plain text transliteration -of the Texinfo source, with the addition of a few control characters -to separate nodes and provide navigational information, so that -Info-reading programs can operate on it. - -Info files are nearly always created by processing a Texinfo source -document. @command{makeinfo}, also known as @command{texi2any}, is -the principal command that converts a Texinfo file into an Info file; -@pxref{Generic Translator @t{texi2any}}. - -Generally, you enter an Info file through a node that by convention is -named `Top'. This node normally contains just a brief summary of the -file's purpose, and a large menu through which the rest of the file is -reached. From this node, you can either traverse the file -systematically by going from node to node, or you can go to a specific -node listed in the main menu, or you can search the index menus and then -go directly to the node that has the information you want. Alternatively, -with the standalone Info program, you can specify specific menu items on -the command line (@pxref{Top,,, info, Info}). - -If you want to read through an Info file in sequence, as if it were a -printed manual, you can hit @key{SPC} repeatedly, or you get the whole -file with the advanced Info command @kbd{g *}. (@xref{Advanced,, -Advanced Info commands, info, Info}.) - -The @file{dir} file in the @file{info} directory serves as the -departure point for the whole Info system. From it, you can reach the -`Top' nodes of each of the documents in a complete Info system. - -@cindex URI syntax for Info -If you wish to refer to an Info file via a URI, you can use the -(unofficial) syntax exemplified by the following. This works with -XEmacs/W3, for example: -@example -info:xemacs#Dissociated%20Press -info:///usr/info/xemacs#Dissociated%20Press -info://localhost/usr/info/xemacs#Dissociated%20Press -@end example - -The @command{info} program itself does not follow URIs of any kind. - - -@node Printed Books -@section Printed Books -@cindex Printed book and manual characteristics -@cindex Manual characteristics, printed -@cindex Book characteristics, printed -@cindex Texinfo printed book characteristics -@cindex Characteristics, printed books or manuals - -@cindex Knuth, Donald -A Texinfo file can be formatted and typeset as a printed book or -manual. To do this, you need @TeX{}, a sophisticated typesetting -program written by Donald Knuth of Stanford University. - -A Texinfo-based book is similar to any other typeset, printed work: it -can have a title page, copyright page, table of contents, and preface, -as well as chapters, numbered or unnumbered sections and subsections, -page headers, cross references, footnotes, and indices. - -@TeX{} is a general purpose typesetting program. Texinfo provides a -file @file{texinfo.tex} that contains information (definitions or -@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. -(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands -to @TeX{} commands, which @TeX{} can then process to create the typeset -document.) @file{texinfo.tex} contains the specifications for printing -a document. You can get the latest version of @file{texinfo.tex} from -the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. - -In the United States, documents are most often printed on 8.5 inch by -11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. -But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by -235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper -(@code{@@afourpaper}, @code{@@afivepaper}). -@xref{@t{@@smallbook}}, and @ref{A4 Paper}. - -@cindex Literate programming -@TeX{} is freely distributable. It is written in a superset of Pascal -for literate programming called WEB and can be compiled either in -Pascal or (by using a conversion program that comes with the @TeX{} -distribution) in C. - -@TeX{} is very powerful and has a great many features. Because a -Texinfo file must be able to present information both on a -character-only terminal in Info form and in a typeset book, the -formatting commands that Texinfo supports are necessarily limited. - -@xref{Obtaining @TeX{}}, for information on acquiring @TeX{}. It is -not part of the Texinfo distribution. - - -@node Formatting Commands -@section @@-commands -@cindex @@-commands -@cindex Formatting commands - -In a Texinfo file, the commands you write to describe the contents of -the manual are preceded by an @samp{@@} character; they are called -@dfn{@@-commands}. For example, @code{@@node} is the command to -indicate a node and @code{@@chapter} is the command to indicate the -start of a chapter. Almost all @@ command names are entirely -lowercase. - -Texinfo's @@-commands are a strictly limited set of constructs. The -strict limits are primarily intended to ``force'' you, the author, to -concentrate on the writing and the content of your manual, rather than -the details of the formatting. - -Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does not -refer to a dispute between two people; it refers to the information -presented to the command. According to the @cite{Oxford English -Dictionary}, the word derives from the Latin for @dfn{to make clear, -prove}; thus it came to mean `the evidence offered as proof', which is -to say, `the information offered', which led to its mathematical -meaning. In its other thread of derivation, the word came to mean `to -assert in a manner against which others may make counter assertions', -which led to the meaning of `argument' as a dispute.} they take, you -need to write @@-commands on lines of their own or as part of -sentences: - -@itemize @bullet -@item -Some commands are written at the start of a line and the rest of the -line comprises the argument text, such as @code{@@chapter} (which -creates chapter titles). - -@item -Some commands can appear anywhere, generally within a sentence, and -are followed by empty braces, such as @code{@@dots@{@}} (which creates -an ellipsis @dots{}). - -@item -Some commands can appear anywhere, generally within a sentence, and -are followed by the argument text in braces, such as -@code{@@code@{a+1@}} (which marks text as being code, @code{a+1} being -the argument in this case). - -@item -Some commands are written at the start of a line, with general text on -following lines, terminated by a matching @code{@@end} command on a -line of its own. For example, @code{@@example}, then the lines of a -coding example, then @code{@@end example}. -@end itemize - -@noindent -@cindex Braces, when to use -As a general rule, a command requires braces if it mingles among other -text; but it does not need braces if it is on a line of its own. The -non-alphabetic commands, such as @code{@@:}, are exceptions to the -rule; they do not need braces. - -As you gain experience with Texinfo, you will rapidly learn how to -write the different commands: the different ways to write commands -actually make it easier to write and read Texinfo files than if all -commands followed exactly the same syntax. @xref{Command Syntax, , -@@-Command Syntax}, for all the details. - - -@node Conventions -@section General Syntactic Conventions -@cindex General syntactic conventions -@cindex Syntactic conventions -@cindex Conventions, syntactic -@cindex Characters, basic input - -This section describes the general conventions used in all Texinfo documents. - -@itemize @bullet -@item -@cindex Source files, characters used -All printable ASCII characters except @samp{@@}, @samp{@{} and -@samp{@}} can appear in a Texinfo file and stand for themselves. -@samp{@@} is the escape character which introduces commands, while -@samp{@{} and @samp{@}} are used to surround arguments to certain -commands. To put one of these special characters into the document, put -an @samp{@@} character in front of it, like this: @samp{@@@@}, -@samp{@@@{}, and @samp{@@@}}. - -@item -Texinfo supports the usual quotation marks used in English and in -other languages; see @ref{Inserting Quotation Marks}. - -@item -@cindex Multiple dashes in source -@cindex Dashes in source -@cindex Hyphens in source, two or three in a row -@cindex Em dash, producing -@cindex En dash, producing -Use three hyphens in a row, @samp{---}, to produce a long dash---like -this (called an @dfn{em dash}), used for punctuation in sentences. -Use two hyphens, @samp{--}, to produce a medium dash (called an -@dfn{en dash}), used primarily for numeric ranges, as in ``June -25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen -used in compound words. For display on the screen, Info reduces three -hyphens to two and two hyphens to one (not transitively!). Of course, -any number of hyphens in the source remain as they are in literal -contexts, such as @code{@@code} and @code{@@example}. - -@item -@cindex Form feed characters -@cindex @kbd{CTRL-l} -Form feed (@kbd{CTRL-l}) characters in the input are handled as -follows: - -@table @asis -@item PDF/DVI -In normal text, treated as ending any open paragraph; essentially -ignored between paragraphs. - -@item Info -Output as-is between paragraphs (their most common use); in other -contexts, they may be treated as regular spaces (and thus consolidated -with surrounding whitespace). - -@item HTML -Written as a numeric entity except contexts where spaces are ignored; -for example, in @samp{@@footnote@{ ^L foo@}}, the form feed is -ignored. - -@item XML -Keep them everywhere; in attributes, escaped as @samp{\f}; also, -@samp{\} is escaped as @samp{\\} and newline as @samp{\n}. - -@item Docbook -Completely removed, as they are not allowed. -@end table - -As you can see, because of these differing requirements of the output -formats, it's not possible to use form feeds completely portably. - -@item -@cindex Tabs; don't use! -@strong{Caution:} Last, do not use tab characters in a Texinfo file! -(Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts, -which means that it is impractical at best to define a tab to work in -all circumstances. Consequently, @TeX{} treats tabs like single -spaces, and that is not what they look like in the source. -Furthermore, @code{makeinfo} does nothing special with tabs, and thus -a tab character in your input file will usually have a different -appearance in the output. - -@noindent -To avoid this problem, Texinfo mode in XEmacs inserts -multiple spaces when you press the @key{TAB} key. Also, you can run -@code{untabify} in XEmacs to convert tabs in a region to multiple -spaces, or use the @code{unexpand} command from the shell. -@end itemize - - -@node Comments -@section Comments - -@cindex Comments -@findex comment -@findex c @r{(comment)} - -You can write comments in a Texinfo file by using the @code{@@comment} -command, which may be abbreviated to @code{@@c}. Such comments are -for a person looking at the Texinfo source file. All the text on a -line that follows either @code{@@comment} or @code{@@c} is a comment; -the rest of the line does not appear in the visible output. - -Often, you can write the @code{@@comment} or @code{@@c} in the middle -of a line, and only the text that follows after the @code{@@comment} -or @code{@@c} command does not appear; but some commands, such as -@code{@@settitle} and @code{@@setfilename}, work on a whole line. You -cannot use @code{@@comment} or @code{@@c} within a line beginning with -such a command. - -@findex DEL @r{(comment character)} -@cindex Catcode for comments in @TeX{} -In cases of nested command invocations, complicated macro definitions, -etc., @code{@@c} and @code{@@comment} may provoke an error when -processing with @TeX{}. Therefore, you can also use the @kbd{DEL} -character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{} -comment character (catcode 14, in @TeX{} internals). Everything on -the line after the @kbd{DEL} will be ignored. - -@cindex Ignored text -@cindex Unprocessed text -@findex ignore -You can also have long stretches of text to be ignored by the Texinfo -processors with the @code{@@ignore} and @code{@@end ignore} commands. -Write each of these commands on a line of its own, starting each -command at the beginning of the line. Text between these two commands -does not appear in the processed output. You can use @code{@@ignore} -and @code{@@end ignore} for writing comments. (For some technical -caveats regarding nesting of such commands, @pxref{Conditional -Nesting}.) - - -@node Minimum -@section What a Texinfo File Must Have -@cindex Minimal Texinfo file (requirements) -@cindex Must have in Texinfo file -@cindex Required in Texinfo file -@cindex Texinfo file minimum - -By convention, the name of a Texinfo file ends with (in order of -preference) one of the extensions @file{.texinfo}, @file{.texi}, -@file{.txi}, or @file{.tex}. The longer extensions are preferred -since they describe more clearly to a human reader the nature of the -file. The shorter extensions are for operating systems that cannot -handle long file names. - -In order to be made into a good printed manual and other output -formats, a Texinfo file @emph{must} begin with lines like this: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -@noindent -The contents of the file follow this beginning, and then you -@emph{must} end the Texinfo source with a line like this: - -@example -@@bye -@end example - -@findex \input @r{(raw @TeX{} startup)} -@noindent -Here's an explanation: - -@itemize @bullet -@item -The @samp{\input texinfo} line tells @TeX{} to use the -@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo -@@-commands into @TeX{} typesetting commands. (Note the use of the -backslash, @samp{\}; this is correct for @TeX{}.) - -@item -The @code{@@setfilename} line provides a name for the Info file and -tells @TeX{} to open auxiliary files. @strong{All text before -@code{@@setfilename} is ignored!} - -@item -The @code{@@settitle} line specifies a title for the page headers (or -footers) of the printed manual, and the default title and document -description for the @samp{<head>} in HTML@. Strictly speaking, -@code{@@settitle} is optional---if you don't mind your document being -titled `Untitled'. - -@item -The @code{@@bye} line at the end of the file on a line of its own tells -the formatters that the file is ended and to stop formatting. -@end itemize - -If you use XEmacs, it is also useful to include mode setting and -start-of-header and end-of-header lines at the beginning of a Texinfo -file, like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@@c %**end of header -@end group -@end example - -@noindent -In the first line, @samp{-*-texinfo-*-} causes XEmacs to switch into -Texinfo mode when you edit the file. - -The @code{@@c ...header} lines above which surround the -@code{@@setfilename} and @code{@@settitle} lines allow you to process, -within XEmacs, just part of the Texinfo source. (@xref{Start of -Header}.) - -Furthermore, you will usually provide a Texinfo file with a title page, -indices, and the like, all of which are explained in this manual. But -the minimum, which can be useful for short documents, is just the three -lines at the beginning and the one line at the end. - - -@node Six Parts -@section Six Parts of a Texinfo File - -Generally, a Texinfo file contains more than the minimal beginning and -end described in the previous section---it usually contains the six -parts listed below. These are described fully in the following sections. - -@table @r -@item 1. Header -The @dfn{Header} names the file, tells @TeX{} which definitions file to -use, and other such housekeeping tasks. - -@item 2. Summary and Copyright -The @dfn{Summary and Copyright} segment describes the document and -contains the copyright notice and copying permissions. This is done -with the @code{@@copying} command. - -@item 3. Title and Copyright -The @dfn{Title and Copyright} segment contains the title and copyright -pages for the printed manual. The segment must be enclosed between -@code{@@titlepage} and @code{@@end titlepage} commands. The title and -copyright page appear only in the printed manual. - -@item 4. `Top' Node and Master Menu -The `Top' node starts off the online output; it does not appear in the -printed manual. We recommend including the copying permissions here as -well as the segments above. And it contains at least a top-level menu -listing the chapters, and possibly a @dfn{Master Menu} listing all the -nodes in the entire document. - -@item 5. Body -The @dfn{Body} of the document is typically structured like a -traditional book or encyclopedia, but it may be free form. - -@item 6. End -The @dfn{End} segment may contain commands for printing indices, and -closes with the @code{@@bye} command on a line of its own. -@end table - - -@node Short Sample -@section A Short Sample Texinfo File -@cindex Sample Texinfo file, with comments - -Here is a very short but complete Texinfo file, in the six conventional -parts enumerated in the previous section, so you can see how Texinfo -source appears in practice. The first three parts of the file, from -@samp{\input texinfo} through to @samp{@@end titlepage}, look more -intimidating than they are: most of the material is standard -boilerplate; when writing a manual, you simply change the names as -appropriate. - -@xref{Beginning a File}, for full documentation on the commands listed -here. @xref{GNU Sample Texts}, for the full texts to be used in GNU -manuals. - -In the following, the sample text is @emph{indented}; comments on it are -not. The complete file, without interspersed comments, is shown in -@ref{Short Sample Texinfo File}. - -@subheading Part 1: Header - -@noindent -The header does not appear in either the Info file or the -printed output. It sets various parameters, including the -name of the Info file and the title used in the header. - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Manual 1.0 -@@c %**end of header -@end group -@end example - -@subheading Part 2: Summary Description and Copyright - -@noindent -A real manual includes more text here, according to the license under -which it is distributed. @xref{GNU Sample Texts}. - -@example -@group -@@copying -This is a short example of a complete Texinfo file, version 1.0. - -Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. -@@end copying -@end group -@end example - -@subheading Part 3: Titlepage, Contents, Copyright - -@noindent -The titlepage segment does not appear in the online output, only in the -printed manual. We use the @code{@@insertcopying} command to -include the permission text from the previous section, instead of -writing it out again; it is output on the back of the title page. The -@code{@@contents} command generates a table of contents. - -@example -@group -@@titlepage -@@title Sample Title -@end group - -@group -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -@@insertcopying -@@end titlepage -@end group - -@@c Output the table of contents at the beginning. -@@contents -@end example - -@subheading Part 4: `Top' Node and Master Menu - -@noindent -The `Top' node contains the master menu for the Info file. Since the -printed manual uses a table of contents rather than a menu, it -excludes the `Top' node. We repeat the short description from the -beginning of the @samp{@@copying} text, but there's no need to repeat -the copyright information, so we don't use @samp{@@insertcopying} here. -The @samp{@@top} command itself helps @command{makeinfo} determine the -relationships between nodes. - -@example -@@ifnottex -@@node Top -@@top Short Sample - -This is a short sample Texinfo file. -@@end ifnottex - -@group -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Index:: Complete index. -@@end menu -@end group -@end example - - -@subheading Part 5: The Body of the Document - -@noindent -The body segment contains all the text of the document, but not the -indices or table of contents. This example illustrates a node and a -chapter containing an enumerated list. - -@example -@group -@@node First Chapter -@@chapter First Chapter - -@@cindex chapter, first -@end group - -@group -This is the first chapter. -@@cindex index entry, another -@end group - -@group -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate -@end group -@end example - - -@subheading Part 6: The End of the Document - -@noindent -The end segment contains commands for generating an index in a node and -unnumbered chapter of its own, and the @code{@@bye} command that marks -the end of the document. - -@example -@group -@@node Index -@@unnumbered Index -@end group - -@group -@@printindex cp - -@@bye -@end group -@end example - - -@subheading Some Results - -Here is what the contents of the first chapter of the sample look like: - -@sp 1 -@need 700 -@quotation -This is the first chapter. - -Here is a numbered list. - -@enumerate -@item -This is the first item. - -@item -This is the second item. -@end enumerate -@end quotation - - -@node History -@section History - -@cindex Stallman, Richard M. -@cindex Chassell, Robert J. -@cindex Fox, Brian -@cindex Berry, Karl -Richard M. Stallman invented the Texinfo format, wrote the initial -processors, and created Edition 1.0 of this manual. Robert@tie{}J. -Chassell greatly revised and extended the manual, starting with -Edition 1.1. Brian Fox was responsible for the standalone Texinfo -distribution until version 3.8, and originally wrote the standalone -@command{makeinfo} and @command{info} programs. Karl Berry has -continued maintenance since Texinfo 3.8 (manual edition 2.22). - -@cindex Pinard, Fran@,{c}ois -@cindex Schwab, Andreas -@cindex Weinberg, Zack -@cindex Weisshaus, Melissa -@cindex Zaretskii, Eli -@cindex Zuhn, David D. -Our thanks go out to all who helped improve this work, particularly -the indefatigable Eli Zaretskii and Andreas Schwab, who have provided -patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn, -tirelessly recorded and reported mistakes and obscurities. Zack -Weinberg did the impossible by implementing the macro syntax in -@file{texinfo.tex}. Thanks to Melissa Weisshaus for her frequent -reviews of nearly similar editions. Dozens of others have contributed -patches and suggestions, they are gratefully acknowledged in the -@file{ChangeLog} file. Our mistakes are our own. - -@cindex History of Texinfo -@cindex Texinfo history -@subheading Beginnings - -@cindex Scribe -@cindex Reid, Brian -In the 1970's at CMU, Brian Reid developed a program and format named -Scribe to mark up documents for printing. It used the @code{@@} -character to introduce commands, as Texinfo does. Much more -consequentially, it strove to describe document contents rather than -formatting, an idea wholeheartedly adopted by Texinfo. - -@cindex Bolio -@cindex Bo@TeX{} -Meanwhile, people at MIT developed another, not too dissimilar format -called Bolio. This then was converted to using @TeX{} as its typesetting -language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been -0.02 on October 31, 1984. - -Bo@TeX{} could only be used as a markup language for documents to be -printed, not for online documents. Richard Stallman (RMS) worked on -both Bolio and Bo@TeX{}. He also developed a nifty on-line help format -called Info, and then combined Bo@TeX{} and Info to create Texinfo, a -mark up language for text that is intended to be read both online and -as printed hard copy. - -Moving forward, the original translator to create Info was written -(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the -@code{texinfo-format-buffer} and other functions. In the early 1990s, -Brian Fox reimplemented the conversion program in C, now called -@command{makeinfo}. - -@subheading Reimplementing in Perl - -@cindex Cons, Lionel -@cindex Dumas, Patrice -In 2012, the C @command{makeinfo} was itself replaced by a Perl -implementation generically called @command{texi2any}. This version -supports the same level of output customization as -@command{texi2html}, an independent program originally written by -Lionel Cons, later with substantial work by many others. The many -additional features needed to make @command{texi2html} a replacement -for @command{makeinfo} were implemented by Patrice Dumas. The first -never-released version of @command{texi2any} was based on the -@command{texi2html} code. That implementation, however, was abandoned -in favor of the current program, which parses the Texinfo input into a -tree for processing. It still supports nearly all the features of -@command{texi2html}. - -The new Perl program is much slower than the old C program. We hope -the speed gap will close in the future, but it may not ever be -entirely comparable. So why did we switch? In short, we intend and -hope that the present program will be much easier than the previous C -implementation of @command{makeinfo} to extend to different output -styles, back-end output formats, and all other customizations. -In more detail: - -@itemize @bullet -@item HTML customization. Many GNU and other free software packages -had been happily using the HTML customization features in -@command{texi2html} for years. Thus, in effect two independent -implementations of the Texinfo language had developed, and keeping -them in sync was not simple. Adding the HTML customization possible -in @command{texi2html} to a C program would have been an -enormous effort. - -@item Unicode, and multilingual support generally, especially of east -Asian languages. Although of course it's perfectly plausible to write -such support in C, in the particular case of @command{makeinfo}, it -would have been tantamount to rewriting the entire program. In Perl, -much of that comes essentially for free. - -@item Additional back-ends. The @command{makeinfo} code had become -convoluted to the point where adding a new back-end was quite complex, -requiring complex interactions with existing back-ends. In contrast, -our Perl implementation provides a clean tree-based representation for -all back-ends to work from. People have requested numerous different -back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now -be much more feasible to implement. Which leads to the last item: - -@item Making contributions easier. In general, due to the cleaner -structure, the Perl program should be considerably easier than the C -for anyone to read and contribute to, with the resulting obvious -benefits. -@end itemize - -@xref{Reference Implementation}, for more on the rationale for and -role of @command{texi2any}. - - -@node Texinfo Mode -@chapter Using Texinfo Mode -@cindex Texinfo mode -@cindex Mode, using Texinfo -@cindex XEmacs -@cindex Emacs - -You may edit a Texinfo file with any text editor you choose. A Texinfo -file is no different from any other ASCII file. However, XEmacs -comes with a special mode, called Texinfo mode, that provides XEmacs -commands and tools to help ease your work. - -This chapter describes features of XEmacs' Texinfo mode but not any -features of the Texinfo formatting language. So if you are reading this -manual straight through from the beginning, you may want to skim through -this chapter briefly and come back to it after reading succeeding -chapters which describe the Texinfo formatting language in detail. - -@menu -* Texinfo Mode Overview:: How Texinfo mode can help you. -* XEmacs Editing:: Texinfo mode adds to XEmacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. -@end menu - -@node Texinfo Mode Overview -@section Texinfo Mode Overview - -Texinfo mode provides special features for working with Texinfo files. -You can: - -@itemize @bullet -@item -Insert frequently used @@-commands. - -@item -Automatically create @code{@@node} lines. - -@item -Show the structure of a Texinfo source file. - -@item -Automatically create or update the `Next', -`Previous', and `Up' pointers of a node. - -@item -Automatically create or update menus. - -@item -Automatically create a master menu. - -@item -Format a part or all of a file for Info. - -@item -Typeset and print part or all of a file. -@end itemize - -Perhaps the two most helpful features are those for inserting frequently -used @@-commands and for creating node pointers and menus. - -@node XEmacs Editing -@section The Usual XEmacs Editing Commands - -In most cases, the usual Text mode commands work the same in Texinfo -mode as they do in Text mode. Texinfo mode adds new editing commands -and tools to XEmacs' general purpose editing features. The major -difference concerns filling. In Texinfo mode, the paragraph -separation variable and syntax table are redefined so that Texinfo -commands that should be on lines of their own are not inadvertently -included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) -command will refill a paragraph but not mix an indexing command on a -line adjacent to it into the paragraph. - -In addition, Texinfo mode sets the @code{page-delimiter} variable to -the value of @code{texinfo-chapter-level-regexp}; by default, this is -a regular expression matching the commands for chapters and their -equivalents, such as appendices. With this value for the page -delimiter, you can jump from chapter title to chapter title with the -@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} -(@code{backward-page}) commands and narrow to a chapter with the -@kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,xemacs, -XEmacs User's Manual}, for details about the page commands.) - -You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the extensions -@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer -extension is preferred, since it is explicit, but a shorter extension -may be necessary for operating systems that limit the length of file -names. XEmacs automatically enters Texinfo mode when you visit a -file with a @file{.texinfo}, @file{.texi} or @file{.txi} -extension. Also, XEmacs switches to Texinfo mode -when you visit a -file that has @samp{-*-texinfo-*-} in its first line. If ever you are -in another mode and wish to switch to Texinfo mode, type @code{M-x -texinfo-mode}. - -Like all other XEmacs features, you can customize or enhance Texinfo -mode as you wish. In particular, the keybindings are very easy to -change. The keybindings described here are the default or standard -ones. - -@node Inserting -@section Inserting Frequently Used Commands -@cindex Inserting frequently used commands -@cindex Frequently used commands, inserting -@cindex Commands, inserting them - -Texinfo mode provides commands to insert various frequently used -@@-commands into the buffer. You can use these commands to save -keystrokes. - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command: - -@table @kbd -@item C-c C-c c -@itemx M-x texinfo-insert-@@code -@findex texinfo-insert-@@code -Insert @code{@@code@{@}} and put the -cursor between the braces. - -@item C-c C-c d -@itemx M-x texinfo-insert-@@dfn -@findex texinfo-insert-@@dfn -Insert @code{@@dfn@{@}} and put the -cursor between the braces. - -@item C-c C-c e -@itemx M-x texinfo-insert-@@end -@findex texinfo-insert-@@end -Insert @code{@@end} and attempt to insert the correct following word, -such as @samp{example} or @samp{table}. (This command does not handle -nested lists correctly, but inserts the word appropriate to the -immediately preceding list.) - -@item C-c C-c i -@itemx M-x texinfo-insert-@@item -@findex texinfo-insert-@@item -Insert @code{@@item} and put the -cursor at the beginning of the next line. - -@item C-c C-c k -@itemx M-x texinfo-insert-@@kbd -@findex texinfo-insert-@@kbd -Insert @code{@@kbd@{@}} and put the -cursor between the braces. - -@item C-c C-c n -@itemx M-x texinfo-insert-@@node -@findex texinfo-insert-@@node -Insert @code{@@node} and a comment line -listing the sequence for the `Next', -`Previous', and `Up' nodes. -Leave point after the @code{@@node}. - -@item C-c C-c o -@itemx M-x texinfo-insert-@@noindent -@findex texinfo-insert-@@noindent -Insert @code{@@noindent} and put the -cursor at the beginning of the next line. - -@item C-c C-c s -@itemx M-x texinfo-insert-@@samp -@findex texinfo-insert-@@samp -Insert @code{@@samp@{@}} and put the -cursor between the braces. - -@item C-c C-c t -@itemx M-x texinfo-insert-@@table -@findex texinfo-insert-@@table -Insert @code{@@table} followed by a @key{SPC} -and leave the cursor after the @key{SPC}. - -@item C-c C-c v -@itemx M-x texinfo-insert-@@var -@findex texinfo-insert-@@var -Insert @code{@@var@{@}} and put the -cursor between the braces. - -@item C-c C-c x -@itemx M-x texinfo-insert-@@example -@findex texinfo-insert-@@example -Insert @code{@@example} and put the -cursor at the beginning of the next line. - -@c M-@{ was the binding for texinfo-insert-braces; -@c in Emacs 19, backward-paragraph will take this binding. -@item C-c C-c @{ -@itemx M-x texinfo-insert-braces -@findex texinfo-insert-braces -Insert @code{@{@}} and put the cursor between the braces. - -@item C-c @} -@itemx C-c ] -@itemx M-x up-list -@findex up-list -Move from between a pair of braces forward past the closing brace. -Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which -is, however, more mnemonic; hence the two keybindings. (Also, you can -move out from between braces by typing @kbd{C-f}.) -@end table - -To put a command such as @w{@code{@@code@{@dots{}@}}} around an -@emph{existing} word, position the cursor in front of the word and type -@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. -The value of the prefix argument tells XEmacs how many words following -point to include between braces---@samp{1} for one word, @samp{2} for -two words, and so on. Use a negative argument to enclose the previous -word or words. If you do not specify a prefix argument, XEmacs inserts -the @@-command string and positions the cursor between the braces. This -feature works only for those @@-commands that operate on a word or words -within one line, such as @code{@@kbd} and @code{@@var}. - -This set of insert commands was created after analyzing the frequency -with which different @@-commands are used in the @cite{XEmacs User's -Manual} and the @cite{GDB Manual}. If you wish to add your own insert -commands, you can bind a keyboard macro to a key, use abbreviations, -or extend the code in @file{texinfo.el}. - -@findex texinfo-start-menu-description -@cindex Menu description, start -@cindex Description for menu, start -@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert -command that works differently from the other insert commands. It -inserts a node's section or chapter title in the space for the -description in a menu entry line. (A menu entry has three parts, the -entry name, the node name, and the description. Only the node name is -required, but a description helps explain what the node is about. -@xref{Menu Parts, , The Parts of a Menu}.) - -To use @code{texinfo-start-menu-description}, position point in a menu -entry line and type @kbd{C-c C-c C-d}. The command looks for and copies -the title that goes with the node name, and inserts the title as a -description; it positions point at beginning of the inserted text so you -can edit it. The function does not insert the title if the menu entry -line already contains a description. - -This command is only an aid to writing descriptions; it does not do the -whole job. You must edit the inserted text since a title tends to use -the same words as a node name but a useful description uses different -words. - -@node Showing the Structure -@section Showing the Sectioning Structure of a File -@cindex Showing the sectioning structure of a file -@cindex Sectioning structure of a file, showing -@cindex Structure of a file, showing -@cindex Outline of file structure, showing -@cindex Contents-like outline of file structure -@cindex File sectioning structure, showing -@cindex Texinfo file sectioning structure, showing - -You can show the sectioning structure of a Texinfo file by using the -@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command -lists the lines that begin with the @@-commands for @code{@@chapter}, -@code{@@section}, and the like. It constructs what amounts to a table -of contents. These lines are displayed in another buffer called the -@samp{*Occur*} buffer. In that buffer, you can position the cursor -over one of the lines and use the @kbd{C-c C-c} command -(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot -in the Texinfo file. - -@table @kbd -@item C-c C-s -@itemx M-x texinfo-show-structure -@findex texinfo-show-structure -Show the @code{@@chapter}, @code{@@section}, and such lines of a -Texinfo file. - -@item C-c C-c -@itemx M-x occur-mode-goto-occurrence -@findex occur-mode-goto-occurrence -Go to the line in the Texinfo file corresponding to the line under the -cursor in the @file{*Occur*} buffer. -@end table - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the -@@-commands for @code{@@chapter}, @code{@@section}, and the like, but -also the @code{@@node} lines. You can use @code{texinfo-show-structure} -with a prefix argument to check whether the `Next', `Previous', and `Up' -pointers of an @code{@@node} line are correct. - -Often, when you are working on a manual, you will be interested only -in the structure of the current chapter. In this case, you can mark -off the region of the buffer that you are interested in by using the -@kbd{C-x n n} (@code{narrow-to-region}) command and -@code{texinfo-show-structure} will work on only that region. To see -the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). -(@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more -information about the narrowing commands.) - -@vindex page-delimiter -@cindex Page delimiter in Texinfo mode -In addition to providing the @code{texinfo-show-structure} command, -Texinfo mode sets the value of the page delimiter variable to match -the chapter-level @@-commands. This enables you to use the @kbd{C-x -]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) -commands to move forward and backward by chapter, and to use the -@kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter. -@xref{Pages, , , xemacs, XEmacs User's Manual}, for more information -about the page commands. - - -@node Updating Nodes and Menus -@section Updating Nodes and Menus - -@cindex Updating nodes and menus -@cindex Create nodes, menus automatically -@cindex Insert nodes, menus automatically -@cindex Automatically insert nodes, menus - -Texinfo mode provides commands for automatically creating or updating -menus and node pointers. The commands are called ``update'' commands -because their most frequent use is for updating a Texinfo file after you -have worked on it; but you can use them to insert the `Next', -`Previous', and `Up' pointers into an @code{@@node} line that has none -and to create menus in a file that has none. - -If you do not use any updating commands, you need to write menus and -node pointers by hand, which is a tedious task. - -@menu -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. -@end menu - -@node Updating Commands -@subsection The Updating Commands - -You can use the updating commands to: - -@itemize @bullet -@item -insert or update the `Next', `Previous', and `Up' pointers of a node, - -@item -insert or update the menu for a section, and - -@item -create a master menu for a Texinfo source file. -@end itemize - -You can also use the commands to update all the nodes and menus in a -region or in a whole Texinfo file. - -The updating commands work only with conventional Texinfo files, which -are structured hierarchically like books. In such files, a structuring -command line must follow closely after each @code{@@node} line, except -for the `Top' @code{@@node} line. (A @dfn{structuring command line} is -a line beginning with @code{@@chapter}, @code{@@section}, or other -similar command.) - -You can write the structuring command line on the line that follows -immediately after an @code{@@node} line or else on the line that -follows after a single @code{@@comment} line or a single -@code{@@ifinfo} line. You cannot interpose more than one line between -the @code{@@node} line and the structuring command line; and you may -interpose only an @code{@@comment} line or an @code{@@ifinfo} line. - -Commands which work on a whole buffer require that the `Top' node be -followed by a node with an @code{@@chapter} or equivalent-level command. -The menu updating commands will not create a main or master menu for a -Texinfo file that has only @code{@@chapter}-level nodes! The menu -updating commands only create menus @emph{within} nodes for lower level -nodes. To create a menu of chapters, you must provide a `Top' -node. - -The menu updating commands remove menu entries that refer to other Info -files since they do not refer to nodes within the current buffer. This -is a deficiency. Rather than use menu entries, you can use cross -references to refer to other Info files. None of the updating commands -affect cross references. - -Texinfo mode has five updating commands that are used most often: two -are for updating the node pointers or menu of a single node (or a -region); two are for updating every node pointer and menu in a file; -and one, the @code{texinfo-master-menu} command, is for creating a -master menu for a complete file, and optionally, for updating every -node and menu in the whole Texinfo file. - -The @code{texinfo-master-menu} command is the primary command: - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -@findex texinfo-master-menu -Create or update a master menu that includes all the other menus -(incorporating the descriptions from pre-existing menus, if -any). - -With an argument (prefix argument, @kbd{C-u,} if interactive), first create or -update all the nodes and all the regular menus in the buffer before -constructing the master menu. (@xref{The Top Node, , The Top Node and -Master Menu}, for more about a master menu.) - -For @code{texinfo-master-menu} to work, the Texinfo file must have a -`Top' node and at least one subsequent node. - -After extensively editing a Texinfo file, you can type the following: - -@example -C-u M-x texinfo-master-menu -@exdent or -C-u C-c C-u m -@end example - -@noindent -This updates all the nodes and menus completely and all at once. -@end table - -The other major updating commands do smaller jobs and are designed for -the person who updates nodes and menus as he or she writes a Texinfo -file. - -@need 1000 -The commands are: - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -@findex texinfo-update-node -Insert the `Next', `Previous', and `Up' pointers for the node that point is -within (i.e., for the @code{@@node} line preceding point). If the -@code{@@node} line has pre-existing `Next', `Previous', or `Up' -pointers in it, the old pointers are removed and new ones inserted. -With an argument (prefix argument, @kbd{C-u}, if interactive), this command -updates all @code{@@node} lines in the region (which is the text -between point and mark). - -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -@findex texinfo-make-menu -Create or update the menu in the node that point is within. -With an argument (@kbd{C-u} as prefix argument, if -interactive), the command makes or updates menus for the -nodes which are either within or a part of the -region. - -Whenever @code{texinfo-make-menu} updates an existing menu, the -descriptions from that menu are incorporated into the new menu. This -is done by copying descriptions from the existing menu to the entries -in the new menu that have the same node names. If the node names are -different, the descriptions are not copied to the new menu. - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -@findex texinfo-every-node-update -Insert or update the `Next', `Previous', and `Up' pointers for every -node in the buffer. - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -@findex texinfo-all-menus-update -Create or update all the menus in the buffer. With an argument -(@kbd{C-u} as prefix argument, if interactive), first insert -or update all the node -pointers before working on the menus. - -If a master menu exists, the @code{texinfo-all-menus-update} command -updates it; but the command does not create a new master menu if none -already exists. (Use the @code{texinfo-master-menu} command for -that.) - -When working on a document that does not merit a master menu, you can -type the following: - -@example -C-u C-c C-u C-a -@exdent or -C-u M-x texinfo-all-menus-update -@end example - -@noindent -This updates all the nodes and menus. -@end table - -The @code{texinfo-column-for-description} variable specifies the -column to which menu descriptions are indented. By default, the value -is 32 although it can be useful to reduce it to as low as 24. You -can set the variable via customization (@pxref{Changing an Option,,, -xemacs, XEmacs User's Manual}) or with the @kbd{M-x set-variable} -command (@pxref{Examining, , Examining and Setting Variables, xemacs, -XEmacs User's Manual}). - -Also, the @code{texinfo-indent-menu-description} command may be used to -indent existing menu descriptions to a specified column. Finally, if -you wish, you can use the @code{texinfo-insert-node-lines} command to -insert missing @code{@@node} lines into a file. (@xref{Other Updating -Commands}, for more information.) - -@node Updating Requirements -@subsection Updating Requirements -@cindex Updating requirements -@cindex Requirements for updating commands - -To use the updating commands, you must organize the Texinfo file -hierarchically with chapters, sections, subsections, and the like. -When you construct the hierarchy of the manual, do not `jump down' -more than one level at a time: you can follow the `Top' node with a -chapter, but not with a section; you can follow a chapter with a -section, but not with a subsection. However, you may `jump up' any -number of levels at one time---for example, from a subsection to a -chapter. - -Each @code{@@node} line, with the exception of the line for the `Top' -node, must be followed by a line with a structuring command such as -@code{@@chapter}, @code{@@section}, or -@code{@@unnumberedsubsec}. - -Each @code{@@node} line/structuring-command line combination -must look either like this: - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@comment node-name, next, previous, up -@@section Comments -@end group -@end example - -or like this (without the @code{@@comment} line): - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@section Comments -@end group -@end example - -or like this (without the explicit node pointers): - -@example -@group -@@node Comments -@@section Comments -@end group -@end example - -@noindent -In this example, `Comments' is the name of both the node and the -section. The next node is called `Minimum' and the previous node is -called `Conventions'. The `Comments' section is within the `Overview' -node, which is specified by the `Up' pointer. (Instead of an -@code{@@comment} line, you may also write an @code{@@ifinfo} line.) - -If a file has a `Top' node, it must be called @samp{top} or @samp{Top} -and be the first node in the file. - -The menu updating commands create a menu of sections within a chapter, -a menu of subsections within a section, and so on. This means that -you must have a `Top' node if you want a menu of chapters. - -Incidentally, the @code{makeinfo} command will create an Info file for a -hierarchically organized Texinfo file that lacks `Next', `Previous' and -`Up' pointers. Thus, if you can be sure that your Texinfo file will be -formatted with @code{makeinfo}, you have no need for the update node -commands. (@xref{Creating an Info File}, for more information about -@code{makeinfo}.) However, both @code{makeinfo} and the -@code{texinfo-format-@dots{}} commands require that you insert menus in -the file. - - -@node Other Updating Commands -@subsection Other Updating Commands - -In addition to the five major updating commands, Texinfo mode -possesses several less frequently used updating commands: - -@table @kbd -@item M-x texinfo-insert-node-lines -@findex texinfo-insert-node-lines -Insert @code{@@node} lines before the @code{@@chapter}, -@code{@@section}, and other sectioning commands wherever they are -missing throughout a region in a Texinfo file. - -With an argument (@kbd{C-u} as prefix argument, if interactive), the -command @code{texinfo-insert-node-lines} not only inserts -@code{@@node} lines but also inserts the chapter or section titles as -the names of the corresponding nodes. In addition, it inserts the -titles as node names in pre-existing @code{@@node} lines that lack -names. Since node names should be more concise than section or -chapter titles, you must manually edit node names so inserted. - -For example, the following marks a whole buffer as a region and inserts -@code{@@node} lines and titles throughout: - -@example -C-x h C-u M-x texinfo-insert-node-lines -@end example - -This command inserts titles as node names in @code{@@node} lines; the -@code{texinfo-start-menu-description} command (@pxref{Inserting, -Inserting Frequently Used Commands}) inserts titles as descriptions in -menu entries, a different action. However, in both cases, you need to -edit the inserted text. - -@item M-x texinfo-multiple-files-update -@findex texinfo-multiple-files-update @r{(in brief)} -Update nodes and menus in a document built from several separate files. -With @kbd{C-u} as a prefix argument, create and insert a master menu in -the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first -update all the menus and all the `Next', `Previous', and `Up' pointers -of all the included files before creating and inserting a master menu in -the outer file. The @code{texinfo-multiple-files-update} command is -described in the appendix on @code{@@include} files. -@xref{@t{texinfo-multiple-files-update}}. - -@item M-x texinfo-indent-menu-description -@findex texinfo-indent-menu-description -Indent every description in the menu following point to the specified -column. You can use this command to give yourself more space for -descriptions. With an argument (@kbd{C-u} as prefix argument, if -interactive), the @code{texinfo-indent-menu-description} command indents -every description in every menu in the region. However, this command -does not indent the second and subsequent lines of a multi-line -description. - -@item M-x texinfo-sequential-node-update -@findex texinfo-sequential-node-update -Insert the names of the nodes immediately following and preceding the -current node as the `Next' or `Previous' pointers regardless of those -nodes' hierarchical level. This means that the `Next' node of a -subsection may well be the next chapter. Sequentially ordered nodes are -useful for novels and other documents that you read through -sequentially. (However, in Info, the @kbd{g *} command lets -you look through the file sequentially, so sequentially ordered nodes -are not strictly necessary.) With an argument (prefix argument, if -interactive), the @code{texinfo-sequential-node-update} command -sequentially updates all the nodes in the region. -@end table - -@node Info Formatting -@section Formatting for Info -@cindex Formatting for Info -@cindex Running an Info formatter -@cindex Info formatting - -Texinfo mode provides several commands for formatting part or all of a -Texinfo file for Info. Often, when you are writing a document, you -want to format only part of a file---that is, a region. - -You can use either the @code{texinfo-format-region} or the -@code{makeinfo-region} command to format a region: - -@table @kbd -@findex texinfo-format-region -@item C-c C-e C-r -@itemx M-x texinfo-format-region -@itemx C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info. -@end table - -You can use either the @code{texinfo-format-buffer} or the -@code{makeinfo-buffer} command to format a whole buffer: - -@table @kbd -@findex texinfo-format-buffer -@item C-c C-e C-b -@itemx M-x texinfo-format-buffer -@itemx C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info. -@end table - -@need 1000 -For example, after writing a Texinfo file, you can type the following: - -@example -C-u C-c C-u m -@exdent or -C-u M-x texinfo-master-menu -@end example - -@noindent -This updates all the nodes and menus. Then type the following to create -an Info file: - -@example -C-c C-m C-b -@exdent or -M-x makeinfo-buffer -@end example - -For @TeX{} or the Info formatting commands to work, the file @emph{must} -include a line that has @code{@@setfilename} in its header. - -@xref{Creating an Info File}, for details about Info formatting. - -@node Printing -@comment node-name, next, previous, up -@section Printing -@cindex Formatting for printing -@cindex Printing a region or buffer -@cindex Region formatting and printing -@cindex Buffer formatting and printing -@cindex Part of file formatting and printing - -Typesetting and printing a Texinfo file is a multi-step process in -which you first create a file for printing (called a DVI file), and -then print the file. Optionally, you may also create indices. To do -this, you must run the @code{texindex} command after first running the -@code{tex} typesetting command; and then you must run the @code{tex} -command again. Or else run the @code{texi2dvi} command which -automatically creates indices as needed (@pxref{Format with -@t{texi2dvi}}). - -Often, when you are writing a document, you want to typeset and print -only part of a file to see what it will look like. You can use the -@code{texinfo-tex-region} and related commands for this purpose. Use -the @code{texinfo-tex-buffer} command to format all of a -buffer. - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -@findex texinfo-tex-buffer -Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the -buffer, this command automatically creates or updates indices as -needed. - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -@findex texinfo-tex-region -Run @TeX{} on the region. - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Run @code{texindex} to sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does -not run @code{texindex} automatically; it only runs the @code{tex} -typesetting command. You must run the @code{texinfo-tex-region} command -a second time after sorting the raw index files with the @code{texindex} -command. (Usually, you do not format an index when you format a region, -only when you format a buffer. Now that the @code{texi2dvi} command -exists, there is little or no need for this command.) - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -@findex texinfo-tex-print -Print the file (or the part of the file) previously formatted with -@code{texinfo-tex-buffer} or @code{texinfo-tex-region}. -@end table - -For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the -file @emph{must} start with a @samp{\input texinfo} line and must -include an @code{@@settitle} line. The file must end with @code{@@bye} -on a line by itself. (When you use @code{texinfo-tex-region}, you must -surround the @code{@@settitle} line with start-of-header and -end-of-header lines.) - -@xref{Hardcopy}, for a description of the other @TeX{} related -commands, such as @code{tex-show-print-queue}. - -@node Texinfo Mode Summary -@section Texinfo Mode Summary - -In Texinfo mode, each set of commands has default keybindings that -begin with the same keys. All the commands that are custom-created -for Texinfo mode begin with @kbd{C-c}. The keys are somewhat -mnemonic. - -@subheading Insert Commands - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command to be inserted. (It might make more -sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but -@kbd{C-c C-c} is quick to type.) - -@example -C-c C-c c @r{Insert} @samp{@@code}. -C-c C-c d @r{Insert} @samp{@@dfn}. -C-c C-c e @r{Insert} @samp{@@end}. -C-c C-c i @r{Insert} @samp{@@item}. -C-c C-c n @r{Insert} @samp{@@node}. -C-c C-c s @r{Insert} @samp{@@samp}. -C-c C-c v @r{Insert} @samp{@@var}. -C-c @{ @r{Insert braces.} -C-c ] -C-c @} @r{Move out of enclosing braces.} - -@group -C-c C-c C-d @r{Insert a node's section title} - @r{in the space for the description} - @r{in a menu entry line.} -@end group -@end example - -@subheading Show Structure - -The @code{texinfo-show-structure} command is often used within a -narrowed region. - -@example -C-c C-s @r{List all the headings.} -@end example - -@subheading The Master Update Command - -The @code{texinfo-master-menu} command creates a master menu; and can -be used to update every node and menu in a file as well. - -@c Probably should use @tables in this section. -@example -@group -C-c C-u m -M-x texinfo-master-menu - @r{Create or update a master menu.} -@end group - -@group -C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} - @r{create or update all nodes and regular} - @r{menus, and then create a master menu.} -@end group -@end example - -@subheading Update Pointers - -The update pointer commands are invoked by typing @kbd{C-c C-u} and -then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for -@code{texinfo-every-node-update}. - -@example -C-c C-u C-n @r{Update a node.} -C-c C-u C-e @r{Update every node in the buffer.} -@end example - -@subheading Update Menus - -Invoke the update menu commands by typing @kbd{C-c C-u} -and then either @kbd{C-m} for @code{texinfo-make-menu} or -@kbd{C-a} for @code{texinfo-all-menus-update}. To update -both nodes and menus at the same time, precede @kbd{C-c C-u -C-a} with @kbd{C-u}. - -@example -C-c C-u C-m @r{Make or update a menu.} - -@group -C-c C-u C-a @r{Make or update all} - @r{menus in a buffer.} -@end group - -@group -C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} - @r{first create or update all nodes and} - @r{then create or update all menus.} -@end group -@end example - -@subheading Format for Info - -The Info formatting commands that are written in Emacs Lisp are -invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region -or @kbd{C-b} for the whole buffer. - -The Info formatting commands that are written in C and based on the -@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then -either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer. - -@need 800 -@noindent -Use the @code{texinfo-format@dots{}} commands: - -@example -@group -C-c C-e C-r @r{Format the region.} -C-c C-e C-b @r{Format the buffer.} -@end group -@end example - -@need 750 -@noindent -Use @code{makeinfo}: - -@example -C-c C-m C-r @r{Format the region.} -C-c C-m C-b @r{Format the buffer.} -C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} -C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} -@end example - -@subheading Typeset and Print - -The @TeX{} typesetting and printing commands are invoked by typing -@kbd{C-c C-t} and then another control command: @kbd{C-r} for -@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, -and so on. - -@example -C-c C-t C-r @r{Run @TeX{} on the region.} -C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} -C-c C-t C-i @r{Run} @code{texindex}. -C-c C-t C-p @r{Print the DVI file.} -C-c C-t C-q @r{Show the print queue.} -C-c C-t C-d @r{Delete a job from the print queue.} -C-c C-t C-k @r{Kill the current @TeX{} formatting job.} -C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} -C-c C-t C-l @r{Recenter the output buffer.} -@end example - -@subheading Other Updating Commands - -The remaining updating commands do not have standard keybindings because -they are rarely used. - -@example -@group -M-x texinfo-insert-node-lines - @r{Insert missing @code{@@node} lines in region.} - @r{With @kbd{C-u} as a prefix argument,} - @r{use section titles as node names.} -@end group - -@group -M-x texinfo-multiple-files-update - @r{Update a multi-file document.} - @r{With @kbd{C-u 2} as a prefix argument,} - @r{create or update all nodes and menus} - @r{in all included files first.} -@end group - -@group -M-x texinfo-indent-menu-description - @r{Indent descriptions.} -@end group - -@group -M-x texinfo-sequential-node-update - @r{Insert node pointers in strict sequence.} -@end group -@end example - - -@node Beginning a File -@chapter Beginning a Texinfo File -@cindex Beginning a Texinfo file -@cindex Texinfo file beginning -@cindex File beginning - -Certain pieces of information must be provided at the beginning of a -Texinfo file, such as the name for the output file(s), the title of the -document, and the Top node. A table of contents is also generally -produced here. - -This chapter expands on the minimal complete Texinfo source file -previously given (@pxref{Six Parts}). It describes the numerous -commands for handling the traditional frontmatter items in Texinfo. - -@cindex Frontmatter, text in -Straight text outside of any command before the Top node should be -avoided. Such text is treated differently in the different output -formats: at the time of writing, it is visible in @TeX{} and HTML, by -default not shown in Info readers, and so on. - -@menu -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. -@end menu - - -@node Sample Beginning -@section Sample Texinfo File Beginning - -@cindex Example beginning of Texinfo file - -The following sample shows what is needed. The elements given here are -explained in more detail in the following sections. Other commands are -often included at the beginning of Texinfo files, but the ones here are -the most critical. - -@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. - -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{infoname}.info -@@settitle @var{name-of-manual} @var{version} -@@c %**end of header - -@@copying -This manual is for @var{program}, version @var{version}. - -Copyright @@copyright@{@} @var{years} @var{copyright-owner}. - -@group -@@quotation -Permission is granted to @dots{} -@@end quotation -@@end copying -@end group - -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@end group - -@group -@@c The following two commands -@@c start the copyright page. -@@page -@@vskip 0pt plus 1filll -@@insertcopying -@end group - -Published by @dots{} -@@end titlepage - -@@c So the toc is printed at the start. -@@contents - -@@ifnottex -@@node Top -@@top @var{title} - -This manual is for @var{program}, version @var{version}. -@@end ifnottex - -@group -@@menu -* First Chapter:: Getting started @dots{} -* Second Chapter:: @dots{} - @dots{} -* Copying:: Your rights and freedoms. -@@end menu -@end group - -@group -@@node First Chapter -@@chapter First Chapter - -@@cindex first chapter -@@cindex chapter, first -@dots{} -@end group -@end example - - -@node Texinfo File Header -@section Texinfo File Header -@cindex Header for Texinfo files -@cindex Texinfo file header - -Texinfo files start with at least three lines that provide Texinfo -translators with necessary information. These are the @code{\input -texinfo} line, the @code{@@settitle} line, and the -@code{@@setfilename} line. - -Also, if you want to format just part of the Texinfo file in XEmacs, -you must write the @code{@@settitle} and @code{@@setfilename} lines -between start-of-header and end-of-header lines. These start- and -end-of-header lines are optional, but they do no harm, so you might as -well always include them. - -Any command that affects document formatting as a whole makes sense to -include in the header. @code{@@synindex} (@pxref{@t{@@synindex}}), -for instance, is another command often included in the header. - -Thus, the beginning of a Texinfo file generally looks approximately -like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Manual 1.0 -@@c %**end of header -@end group -@end example - -(@xref{GNU Sample Texts}, for complete sample texts.) - -@menu -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* @t{@@setfilename}:: Tell Info the name of the Info file. -* @t{@@settitle}:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. -@end menu - - -@node First Line -@subsection The First Line of a Texinfo File -@cindex First line of a Texinfo file -@cindex Beginning line of a Texinfo file -@cindex Header of a Texinfo file - -Every Texinfo file that is to be the top-level input to @TeX{} must begin -with a line that looks like this: - -@example -\input texinfo @@c -*-texinfo-*- -@end example - -@noindent -This line serves two functions: - -@enumerate -@item -When the file is processed by @TeX{}, the @samp{\input texinfo} command -tells @TeX{} to load the macros needed for processing a Texinfo file. -These are in a file called @file{texinfo.tex}, which should have been -installed on your system along with either the @TeX{} or Texinfo -software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of -a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex} -file causes the switch from @samp{\} to @samp{@@}; before the switch -occurs, @TeX{} requires @samp{\}, which is why it appears at the -beginning of the file. - -@item -When the file is edited in XEmacs, the @samp{-*-texinfo-*-} mode -specification tells XEmacs to use Texinfo mode. -@end enumerate - - -@node Start of Header -@subsection Start of Header -@cindex Start of header line - -A start-of-header line is a Texinfo comment that looks like this: - -@example -@@c %**start of header -@end example - -Write the start-of-header line on the second line of a Texinfo file. -Follow the start-of-header line with @code{@@setfilename} and -@code{@@settitle} lines and, optionally, with other commands that -globally affect the document formatting, such as @code{@@synindex} or -@code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of -Header}). - -The start- and end-of-header lines allow you to format only part of a -Texinfo file for Info or printing. @xref{@t{texinfo-format} commands}. - -The odd string of characters, @samp{%**}, is to ensure that no other -comment is accidentally taken for a start-of-header line. You can -change it if you wish by setting the @code{tex-start-of-header} and/or -@code{tex-end-of-header} XEmacs variables. @xref{Texinfo Mode Printing}. - - -@node @t{@@setfilename} -@subsection @code{@@setfilename}: Set the Output File Name - -@anchor{setfilename}@c old name -@findex setfilename -@cindex Texinfo requires @code{@@setfilename} -@cindex Output file name, required - -The first Texinfo command (that is, after the @code{\input texinfo}) -in a document is generally @code{@@setfilename}: - -@example -@@setfilename @var{info-file-name} -@end example - -This command is required for @TeX{}, and very strongly recommended for -@code{makeinfo}. - -Write the @code{@@setfilename} command at the beginning of a line and -follow it on the same line by the Info file name. Do not write -anything else on the line. - -@cindex Ignored before @code{@@setfilename} -@cindex @samp{\input} source line ignored -When an @code{@@setfilename} line is present, the Texinfo processors -ignore everything written before the @code{@@setfilename} line. This -is why the very first line of the file (the @code{\input} line) does -not show up in the output. - -The @code{@@setfilename} line specifies the name of the output file to -be generated. This name must be different from the name of the -Texinfo file. There are two conventions for choosing the name: you -can either remove the extension (such as @samp{.texi}) entirely from -the input file name, or (recommended) replace it with the @samp{.info} -extension. - -@cindex Length of file names -@cindex File name collision -@cindex Info file name, choosing -Although an explicit @samp{.info} extension is preferable, some -operating systems cannot handle long file names. You can run into a -problem even when the file name you specify is itself short enough. -This occurs because the Info formatters split a long Info file into -short indirect subfiles, and name them by appending @samp{-1}, -@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original -file name. (@xref{Tag and Split Files}.) The subfile name -@file{texinfo.info-10}, for example, is too long for old systems with -a 14-character limit on filenames; so the Info file name for this -document is @file{texinfo} rather than @file{texinfo.info}. When -@code{makeinfo} is running on operating systems such as MS-DOS which -impose severe limits on file names, it may remove some characters from -the original file name to leave enough space for the subfile suffix, -thus producing files named @file{texin-10}, @file{gcc.i12}, etc. - -When producing another output format, @code{makeinfo} will replace any -final extension with the output format-specific extension (@samp{html} -when generating HTML, for example), or add a dot followed by the -extension (@samp{.html} for HTML) if the given name has no extension. - -@pindex texinfo.cnf -The @code{@@setfilename} line produces no output when you typeset a -manual with @TeX{}, but it is nevertheless essential: it opens the -index and other auxiliary files used by Texinfo, and also reads -@file{texinfo.cnf} if that file is present on your system -(@pxref{Preparing for @TeX{}}). - -If there is no @code{@@setfilename} line, @code{makeinfo} uses the -input file name to determine the output name: first, any of the -extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo} -is removed from the input file name; then, the output format specific -extension is added---@code{.html} when generating HTML, @code{.info} -when generating Info, etc. The @code{\input} line is still ignored in -this processing, as well as leading blank lines. - -See also the @option{--output} option in @ref{Invoking @t{texi2any}}. - - -@node @t{@@settitle} -@subsection @code{@@settitle}: Set the Document Title - -@anchor{settitle}@c old name -@findex settitle -@cindex Document title, specifying - -A Texinfo file should contain a line that looks like this: - -@example -@@settitle @var{title} -@end example - -Write the @code{@@settitle} command at the beginning of a line and -follow it on the same line by the title. Do not write anything else -on the line. The @code{@@settitle} command should precede everything -that generates actual output. The best place for it is right after -the @code{@@setfilename} command (described in the previous section). - -This command tells @TeX{} the title to use in a header or footer -for double-sided output, in case such headings are output. For -more on headings for @TeX{}, see @ref{Heading Generation}. - -@cindex @code{<title>} HTML tag -In the HTML file produced by @command{makeinfo}, @var{title} serves as -the document @samp{<title>}. It also becomes the default document -description in the @samp{<head>} part -(@pxref{@t{@@documentdescription}}). - -When the title page is used in the output, the title in the -@code{@@settitle} command does not affect the title as it appears on -the title page. Thus, the two do not need not to match exactly. A -practice we recommend is to include the version or edition number of -the manual in the @code{@@settitle} title; on the title page, the -version number generally appears as an @code{@@subtitle} so it would -be omitted from the @code{@@title}. @xref{@t{@@titlepage}}. - - -@node End of Header -@subsection End of Header -@cindex End of header line - -Follow the header lines with an @w{end-of-header} line, which is a -Texinfo comment that looks like this: - -@example -@@c %**end of header -@end example - -@xref{Start of Header}. - - -@node Document Permissions -@section Document Permissions -@cindex Document Permissions -@cindex Copying Permissions - -The copyright notice and copying permissions for a document need to -appear in several places in the various Texinfo output formats. -Therefore, Texinfo provides a command (@code{@@copying}) to declare -this text once, and another command (@code{@@insertcopying}) to -insert the text at appropriate points. - -@anchor{Software Copying Permissions}@c old node name -This section is about the license of the Texinfo document. If the -document is a software manual, the software is typically under a -different license---for GNU and many other free software packages, -software is usually released under the GNU GPL, and manuals are -released under the GNU FDL@. It is helpful to state the license of -the software of the manual, but giving the complete text of the -software license is not necessarily required. - -@menu -* @t{@@copying}:: Declare the document's copying permissions. -* @t{@@insertcopying}:: Where to insert the permissions. -@end menu - - -@node @t{@@copying} -@subsection @code{@@copying}: Declare Copying Permissions - -@anchor{copying}@c old name -@findex copying - -The @code{@@copying} command should be given very early in the document; -the recommended location is right after the header material -(@pxref{Texinfo File Header}). It conventionally consists of a sentence -or two about what the program is, identification of the documentation -itself, the legal copyright line, and the copying permissions. Here is -a skeletal example: - -@example -@@copying -This manual is for @var{program} (version @var{version}, updated -@var{date}), which @dots{} - -Copyright @@copyright@{@} @var{years} @var{copyright-owner}. - -@@quotation -Permission is granted to @dots{} -@@end quotation -@@end copying -@end example - -The @code{@@quotation} has no legal significance; it's there to improve -readability in some contexts. - -The text of @code{@@copying} is output as a comment at the beginning of -Info, HTML, and XML output files. It is @emph{not} output implicitly in -plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to -emit the copying information. See the next section for details. - -@findex copyright -The @code{@@copyright@{@}} command generates a @samp{c} inside a -circle when the output format supports this glyph (print and HTML -always do, for instance). When the glyph is not supported in the -output, it generates the three-character sequence @samp{(C)}. - -The copyright notice itself has the following legally-prescribed -form: - -@example -Copyright @copyright{} @var{years} @var{copyright-owner}. -@end example - -@cindex Copyright word, always in English -The word `Copyright' must always be written in English, even if the -document is otherwise written in another language. This is due to -international law. - -@cindex Years, in copyright line -The list of years should include all years in which a version was -completed (even if it was released in a subsequent year). It is -simplest for each year to be written out individually and in full, -separated by commas. - -@cindex Copyright holder for FSF works -@cindex Holder of copyright for FSF works -@cindex Owner of copyright for FSF works -The copyright owner (or owners) is whoever holds legal copyright on the -work. In the case of works assigned to the FSF, the owner is `Free -Software Foundation, Inc.'. - -The copyright `line' may actually be split across multiple lines, both -in the source document and in the output. This often happens for -documents with a long history, having many different years of -publication. If you do use several lines, do not indent any of them -(or anything else in the @code{@@copying} block) in the source file. - -@xref{Copyright Notices,,, maintain, GNU Maintainer Information}, for -additional information. @xref{GNU Sample Texts}, for the full text to -be used in GNU manuals. @xref{GNU Free Documentation License}, for -the license itself under which GNU and other free manuals are -distributed. - - -@node @t{@@insertcopying} -@subsection @code{@@insertcopying}: Include Permissions Text - -@anchor{insertcopying}@c old name -@findex insertcopying -@cindex Copying text, including -@cindex Permissions text, including -@cindex Including permissions text - -The @code{@@insertcopying} command is simply written on a line by -itself, like this: - -@example -@@insertcopying -@end example - -This inserts the text previously defined by @code{@@copying}. To meet -legal requirements, it must be used on the copyright page in the printed -manual (@pxref{Copyright}). - -The @code{@@copying} command itself causes the permissions text to -appear in an Info file @emph{before} the first node. The text is also -copied into the beginning of each split Info output file, as is legally -necessary. This location implies a human reading the manual using Info -does @emph{not} see this text (except when using the advanced Info -command @kbd{g *}), but this does not matter for legal purposes, -because the text is present. - -Similarly, the @code{@@copying} text is automatically included at the -beginning of each HTML output file, as an HTML comment. Again, this -text is not visible (unless the reader views the HTML source). - -The permissions text defined by @code{@@copying} also appears -automatically at the beginning of the XML and Docbook output files. - - -@node Titlepage & Copyright Page -@section Title and Copyright Pages - -In hard copy output, the manual's name and author are usually printed on -a title page. Copyright information is usually printed on the back of -the title page. - -The title and copyright pages appear in printed manuals, but not in -most other output formats. Because of this, it is possible to use -several slightly obscure typesetting commands that are not to be used -in the main text. In addition, this part of the beginning of a -Texinfo file contains the text of the copying permissions that appears -in the printed manual. - -@menu -* @t{@@titlepage}:: Create a title for the printed document. -* @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* Heading Generation:: Turn on page headings after the title and - copyright pages. -@end menu - - -@node @t{@@titlepage} -@subsection @code{@@titlepage} - -@anchor{titlepage}@c old name -@cindex Title page -@findex titlepage - -Start the material for the title page and following copyright page -with @code{@@titlepage} on a line by itself and end it with -@code{@@end titlepage} on a line by itself. - -The @code{@@end titlepage} command starts a new page and turns on page -numbering (@pxref{Heading Generation}). All the -material that you want to appear on unnumbered pages should be put -between the @code{@@titlepage} and @code{@@end titlepage} commands. -You can force the table of contents to appear there with the -@code{@@setcontentsaftertitlepage} command (@pxref{Contents}). - -@findex page@r{, within @code{@@titlepage}} -By using the @code{@@page} command you can force a page break within the -region delineated by the @code{@@titlepage} and @code{@@end titlepage} -commands and thereby create more than one unnumbered page. This is how -the copyright page is produced. (The @code{@@titlepage} command might -perhaps have been better named the @code{@@titleandadditionalpages} -command, but that would have been rather long!) - -When you write a manual about a computer program, you should write the -version of the program to which the manual applies on the title page. -If the manual changes more frequently than the program or is independent -of it, you should also include an edition number@footnote{We have found -that it is helpful to refer to versions of independent manuals as -`editions' and versions of programs as `versions'; otherwise, we find we -are liable to confuse each other in conversation by referring to both -the documentation and the software with the same words.} for the manual. -This helps readers keep track of which manual is for which version of -the program. (The `Top' node should also contain this information; see -@ref{The Top Node}.) - -Texinfo provides two main methods for creating a title page. One method -uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands -to generate a title page in which the words on the page are -centered. - -The second method uses the @code{@@title}, @code{@@subtitle}, and -@code{@@author} commands to create a title page with black rules under -the title and author lines and the subtitle text set flush to the -right hand side of the page. With this method, you do not specify any -of the actual formatting of the title page. You specify the text -you want, and Texinfo does the formatting. - -You may use either method, or you may combine them; see the examples in -the sections below. - -@findex shorttitlepage -@cindex Bastard title page -@cindex Title page, bastard -For sufficiently simple documents, and for the bastard title page in -traditional book frontmatter, Texinfo also provides a command -@code{@@shorttitlepage} which takes the rest of the line as the title. -The argument is typeset on a page by itself and followed by a blank -page. - - -@node @t{@@titlefont @@center @@sp} -@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} - -@anchor{titlefont center sp}@c old name -@findex titlefont -@findex center -@findex sp @r{(titlepage line spacing)} - -You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} -commands to create a title page for a printed document. (This is the -first of the two methods for creating a title page in Texinfo.) - -Use the @code{@@titlefont} command to select a large font suitable for -the title itself. You can use @code{@@titlefont} more than once if you -have an especially long title. - -For HTML output, each @code{@@titlefont} command produces an -@code{<h1>} heading, but the HTML document @code{<title>} is not -affected. For that, you must put an @code{@@settitle} command before -the @code{@@titlefont} command (@pxref{@t{@@settitle}}). - -@need 700 -For example: - -@example -@@titlefont@{Texinfo@} -@end example - -Use the @code{@@center} command at the beginning of a line to center -the remaining text on that line. Thus, - -@example -@@center @@titlefont@{Texinfo@} -@end example - -@noindent -centers the title, which in this example is ``Texinfo'' printed -in the title font. - -Use the @code{@@sp} command to insert vertical space. For example: - -@example -@@sp 2 -@end example - -@noindent -This inserts two blank lines on the printed page. -(@xref{@t{@@sp}}, for more information about the @code{@@sp} -command.) - -A template for this method looks like this: - -@example -@group -@@titlepage -@@sp 10 -@@center @@titlefont@{@var{name-of-manual-when-printed}@} -@@sp 2 -@@center @var{subtitle-if-any} -@@sp 2 -@@center @var{author} -@dots{} -@@end titlepage -@end group -@end example - -The spacing of the example fits an 8.5 by 11 inch manual. - -You can in fact use these commands anywhere, not just on a title page, -but since they are not logical markup commands, we don't recommend -them. - -@node @t{@@title @@subtitle @@author} -@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} - -@anchor{title subtitle author}@c old name -@findex title -@findex subtitle -@findex author - -You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} -commands to create a title page in which the vertical and horizontal -spacing is done for you automatically. This contrasts with the method -described in the previous section, in which the @code{@@sp} command is -needed to adjust vertical spacing. - -Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} -commands at the beginning of a line followed by the title, subtitle, -or author. The @code{@@author} command may be used for a quotation in -an @code{@@quotation} block (@pxref{@t{@@quotation}}); -except for that, it is an error to use any of these commands outside -of @code{@@titlepage}. - -The @code{@@title} command produces a line in which the title is set -flush to the left-hand side of the page in a larger than normal font. -The title is underlined with a black rule. The title must be given on -a single line in the source file; it will be broken into multiple -lines of output is needed. - -For long titles, the @code{@@*} command may be used to specify the -line breaks in long titles if the automatic breaks do not suit. Such -explicit line breaks are generally reflected in all output formats; if -you only want to specify them for the printed output, use a -conditional (@pxref{Conditionals}). For example: - -@example -@@title This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} -@end example - -The @code{@@subtitle} command sets subtitles in a normal-sized font -flush to the right-hand side of the page. - -The @code{@@author} command sets the names of the author or authors in -a middle-sized font flush to the left-hand side of the page on a line -near the bottom of the title page. The names are followed by a black -rule that is thinner than the rule that underlines the title. - -There are two ways to use the @code{@@author} command: you can write -the name or names on the remaining part of the line that starts with -an @code{@@author} command: - -@example -@@author by Jane Smith and John Doe -@end example - -@noindent -or you can write the names one above each other by using multiple -@code{@@author} commands: - -@example -@group -@@author Jane Smith -@@author John Doe -@end group -@end example - -@need 950 -A template for this method looks like this: - -@example -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@@page -@dots{} -@@end titlepage -@end group -@end example - - -@node Copyright -@subsection Copyright Page -@cindex Copyright page -@cindex Printed permissions -@cindex Permissions, printed - -By international treaty, the copyright notice for a book must be either -on the title page or on the back of the title page. When the copyright -notice is on the back of the title page, that page is customarily not -numbered. Therefore, in Texinfo, the information on the copyright page -should be within @code{@@titlepage} and @code{@@end titlepage} -commands. - -@findex vskip @r{@TeX{} vertical skip} -@findex filll @r{@TeX{} dimension} -Use the @code{@@page} command to cause a page break. To push the -copyright notice and the other text on the copyright page towards the -bottom of the page, use the following incantation after @code{@@page}: - -@example -@@vskip 0pt plus 1filll -@end example - -@noindent -The @code{@@vskip} command inserts whitespace in the @TeX{} output; it -is ignored in all other output formats. The @samp{0pt plus 1filll} -means to put in zero points of mandatory whitespace, and as much -optional whitespace as needed to push the following text to the bottom -of the page. Note the use of three @samp{l}s in the word -@samp{filll}; this is correct. - -To insert the copyright text itself, write @code{@@insertcopying} -next (@pxref{Document Permissions}): - -@example -@@insertcopying -@end example - -Follow the copying text by the publisher, ISBN numbers, cover art -credits, and other such information. - -Here is an example putting all this together: - -@example -@@titlepage -@dots{} -@@page -@@vskip 0pt plus 1filll -@@insertcopying - -Published by @dots{} - -Cover art by @dots{} -@@end titlepage -@end example - -We have one more special case to consider: for plain text output, you -must insert the copyright information explicitly if you want it to -appear. For instance, you could have the following after the copyright -page: - -@example -@@ifplaintext -@@insertcopying -@@end ifplaintext -@end example - -You could include other title-like information for the plain text -output in the same place. - - - -@node Heading Generation -@subsection Heading Generation - -@anchor{end titlepage}@c old name -@cindex Headings, page, begin to appear -@cindex Titlepage end starts headings -@cindex End titlepage starts headings -@cindex Generating page headings - -Like all @code{@@end} commands (@pxref{Quotations and Examples}), the -@code{@@end titlepage} command must be written at the beginning of a -line by itself, with only one space between the @code{@@end} and the -@code{titlepage}. It not only marks the end of the title and -copyright pages, but also causes @TeX{} to start generating page -headings and page numbers. - -Texinfo has two standard page heading formats, one for documents -printed on one side of each sheet of paper (single-sided printing), -and the other for documents printed on both sides of each sheet -(double-sided printing). - -In full generality, you can control the headings in different ways: - -@itemize @bullet -@item -The conventional way is to write an @code{@@setchapternewpage} command -before the title page commands, if required, and then have the -@code{@@end titlepage} command start generating page headings in the -manner desired. - -Most documents are formatted with the standard single-sided or -double-sided headings, (sometimes) using @code{@@setchapternewpage -odd} for double-sided printing and (almost always) no -@code{@@setchapternewpage} command for single-sided printing -(@pxref{@t{@@setchapternewpage}}). - -@item -Alternatively, you can use the @code{@@headings} command to prevent -page headings from being generated or to start them for either single -or double-sided printing. Write an @code{@@headings} command -immediately after the @code{@@end titlepage} command. To turn off -headings, write @code{@@headings off}. @xref{@t{@@headings}}. - -@item -Or, you may specify your own page heading and footing format. -@xref{Headings}. -@end itemize - - -@node Contents -@section Generating a Table of Contents -@cindex Table of contents -@cindex Contents, table of -@cindex Short table of contents -@findex contents -@findex summarycontents -@findex shortcontents - -The @code{@@chapter}, @code{@@section}, and other structuring commands -(@pxref{Chapter Structuring}) supply the information to make up a -table of contents, but they do not cause an actual table to appear in -the manual. To do this, you must use the @code{@@contents} and/or -@code{@@summarycontents} command(s). - -@table @code -@item @@contents -Generates a table of contents in a printed manual, including all -chapters, sections, subsections, etc., as well as appendices and -unnumbered chapters. Headings generated by @code{@@majorheading}, -@code{@@chapheading}, and the other @code{@@@dots{}heading} commands -do not appear in the table of contents (@pxref{Structuring Command -Types}). - -@item @@shortcontents -@itemx @@summarycontents -(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.) - -Generates a short or summary table of contents that lists only the -chapters, appendices, and unnumbered chapters. Sections, subsections -and subsubsections are omitted. Only a long manual needs a short -table of contents in addition to the full table of contents. -@end table - -Both contents commands should be written on a line by themselves, and -placed near the beginning of the file, after the @code{@@end -titlepage} (@pxref{@t{@@titlepage}}), before any sectioning -command. The contents commands automatically generate a chapter-like -heading at the top of the first table of contents page, so don't -include any sectioning command such as @code{@@unnumbered} before -them. - -Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the contents commands. But the contents -are included in plain text output (generated by @code{makeinfo ---plaintext}) and in other output formats, such as HTML. - -When @code{makeinfo} writes a short table of contents while producing -HTML output, the links in the short table of contents point to -corresponding entries in the full table of contents rather than the text -of the document. The links in the full table of contents point to the -main text of the document. - -In the past, the contents commands were sometimes placed at the end of -the file, after any indices and just before the @code{@@bye}, but we -no longer recommend this. - -@findex setcontentsaftertitlepage -@findex setshortcontentsaftertitlepage -@cindex Contents, after title page -@cindex Table of contents, after title page -However, since many existing Texinfo documents still do have the -@code{@@contents} at the end of the manual, if you are a user printing -a manual, you may wish to force the contents to be printed after the -title page. You can do this by specifying -@code{@@setcontentsaftertitlepage} and/or -@code{@@setshortcontentsaftertitlepage}. The first prints only the -main contents after the @code{@@end titlepage}; the second prints both -the short contents and the main contents. In either case, any -subsequent @code{@@contents} or @code{@@shortcontents} is ignored. - -You need to include the @code{@@set@dots{}contentsaftertitlepage} -commands early in the document (just after @code{@@setfilename}, for -example). We recommend using @command{texi2dvi} (@pxref{Format with -@t{texi2dvi}}) to specify this without altering the source file at -all. For example: - -@example -texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi -@end example - -An alternative invocation, using @command{texi2any}: - -@example -texi2any --dvi --Xopt --texinfo=@@setcontentsaftertitlepage foo.texi -@end example - - - -@node The Top Node -@section The `Top' Node and Master Menu -@cindex Top node -@cindex Node, `Top' - -The `Top' node is the node in which a reader enters an Info manual. -As such, it should begin with a brief description of the manual -(including the version number), and end with a master menu for the -whole manual. Of course you should include any other general -information you feel a reader would find helpful. - -@findex top -It is conventional and desirable to write an @code{@@top} sectioning -command line containing the title of the document immediately after -the @code{@@node Top} line (@pxref{@t{@@top} Command}). - -The contents of the `Top' node should appear only in the online output; -none of it should appear in printed output, so enclose it between -@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not -print either an @code{@@node} line or a menu; they appear only in Info; -strictly speaking, you are not required to enclose these parts between -@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do -so. @xref{Conditionals, , Conditionally Visible Text}.) - -@menu -* Top Node Example:: -* Master Menu Parts:: -@end menu - - -@node Top Node Example -@subsection Top Node Example - -@cindex Top node example - -Here is an example of a Top node. - -@example -@group -@@ifnottex -@@node Top -@@top Sample Title - -@@insertcopying -@@end ifnottex -@end group - -Additional general information. - -@group -@@menu -* First Chapter:: -* Second Chapter:: -@dots{} -* Index:: -@end group -@@end menu -@end example - - -@node Master Menu Parts -@subsection Parts of a Master Menu -@cindex Master menu -@cindex Menu, master -@cindex Parts of a master menu - -A @dfn{master menu} is the main menu. It is customary to include a -detailed menu listing all the nodes in the document in this menu. - -Like any other menu, a master menu is enclosed in @code{@@menu} and -@code{@@end menu} and does not appear in the printed output. - -Generally, a master menu is divided into parts. - -@itemize @bullet -@item -The first part contains the major nodes in the Texinfo file: the nodes -for the chapters, chapter-like sections, and the appendices. - -@item -The second part contains nodes for the indices. - -@item -@findex detailmenu -@cindex Detailed menu -The third and subsequent parts contain a listing of the other, -lower-level nodes, often ordered by chapter. This way, rather than go -through an intermediary menu, an inquirer can go directly to a -particular node when searching for specific information. These menu -items are not required; add them if you think they are a convenience. -If you do use them, put @code{@@detailmenu} before the first one, and -@code{@@end detailmenu} after the last; otherwise, @code{makeinfo} -will get confused. -@end itemize - -Each section in the menu can be introduced by a descriptive line. So -long as the line does not begin with an asterisk, it will not be -treated as a menu entry. (@xref{Writing a Menu}, for more -information.) - -For example, the master menu for this manual looks like the following -(but has many more entries): - -@example -@group -@@menu -* Copying Conditions:: Your rights. -* Overview:: Texinfo in brief. -@dots{} -@end group -@group -* Command and Variable Index:: -* General Index:: -@end group - -@group -@@detailmenu ---- The Detailed Node Listing --- - -Overview of Texinfo - -* Reporting Bugs:: @dots{} -@dots{} -@end group - -@group -Beginning a Texinfo File - -* Sample Beginning:: @dots{} -@dots{} -@@end detailmenu -@@end menu -@end group -@end example - - -@node Global Document Commands -@section Global Document Commands -@cindex Global Document Commands - -Besides the basic commands mentioned in the previous sections, here are -additional commands which affect the document as a whole. They are -generally all given before the Top node, if they are given at all. - -@menu -* @t{@@documentdescription}:: Document summary for the HTML output. -* @t{@@setchapternewpage}:: Start chapters on right-hand pages. -* @t{@@headings}:: An option for turning headings on and off - and double or single sided printing. -* @t{@@paragraphindent}:: Specify paragraph indentation. -* @t{@@firstparagraphindent}:: Suppressing first paragraph indentation. -* @t{@@exampleindent}:: Specify environment indentation. -@end menu - - -@node @t{@@documentdescription} -@subsection @code{@@documentdescription}: Summary Text -@anchor{documentdescription}@c old name - -@cindex Document description -@cindex Description of document -@cindex Summary of document -@cindex Abstract of document -@cindex <meta> HTML tag, and document description -@findex documentdescription - -When producing HTML output for a document, @command{makeinfo} writes a -@samp{<meta>} element in the @samp{<head>} to give some idea of the -content of the document. By default, this @dfn{description} is the -title of the document, taken from the @code{@@settitle} command -(@pxref{@t{@@settitle}}). To change this, use the -@code{@@documentdescription} environment, as in: - -@example -@@documentdescription -descriptive text. -@@end documentdescription -@end example - -@noindent -This will produce the following output in the @samp{<head>} of the HTML: - -@example -<meta name=description content="descriptive text."> -@end example - -@code{@@documentdescription} must be specified before the first node of -the document. - - -@node @t{@@setchapternewpage} -@subsection @code{@@setchapternewpage}: Blank Pages Before Chapters - -@anchor{setchapternewpage}@c old name -@findex setchapternewpage -@cindex Starting chapters -@cindex Pages, starting odd - -In an officially bound book, text is usually printed on both sides of -the paper, chapters start on right-hand pages, and right-hand pages have -odd numbers. But in short reports, text often is printed only on one -side of the paper. Also in short reports, chapters sometimes do not -start on new pages, but are printed on the same page as the end of the -preceding chapter, after a small amount of vertical whitespace. - -You can use the @code{@@setchapternewpage} command with various -arguments to specify how @TeX{} should start chapters and whether it -should format headers for printing on one or both sides of the paper -(single-sided or double-sided printing). - -Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument. - -For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page: - -@example -@@setchapternewpage odd -@end example - -You can specify one of three alternatives with the -@code{@@setchapternewpage} command: - -@table @asis - -@item @code{@@setchapternewpage off} -Cause @TeX{} to typeset a new chapter on the same page as the last -chapter, after skipping some vertical whitespace. Also, cause @TeX{} to -format page headers for single-sided printing. - -@item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to format page -headers for single-sided printing. This is the form most often used for -short reports or personal printing. This is the default. - -@item @code{@@setchapternewpage odd} -Cause @TeX{} to start new chapters on new, odd-numbered pages -(right-handed pages) and to typeset for double-sided printing. This is -the form most often used for books and manuals. -@end table - -Texinfo does not have an @code{@@setchapternewpage even} command, -because there is no printing tradition of starting chapters or books on -an even-numbered page. - -If you don't like the default headers that @code{@@setchapternewpage} -sets, you can explicit control them with the @code{@@headings} command. -@xref{@t{@@headings}}. - -At the beginning of a manual or book, pages are not numbered---for -example, the title and copyright pages of a book are not numbered. By -convention, table of contents and frontmatter pages are numbered with -roman numerals and not in sequence with the rest of the document. - -The @code{@@setchapternewpage} has no effect in output formats that do -not have pages, such as Info and HTML. - -We recommend not including any @code{@@setchapternewpage} command in -your document source at all, since such desired pagination is not -intrinsic to the document. For a particular hard copy run, if you -don't want the default output (no blank pages, same headers on all -pages) use the @option{--texinfo} option to @command{texi2dvi} to -specify the output you want. - - -@node @t{@@headings} -@subsection The @code{@@headings} Command - -@anchor{headings on off}@c old name -@findex headings - -The @code{@@headings} command is rarely used. It specifies what kind of -page headings and footings to print on each page. Usually, this is -controlled by the @code{@@setchapternewpage} command. You need the -@code{@@headings} command only if the @code{@@setchapternewpage} command -does not do what you want, or if you want to turn off predefined page -headings prior to defining your own. Write an @code{@@headings} command -immediately after the @code{@@end titlepage} command. - -You can use @code{@@headings} as follows: - -@table @code -@item @@headings off -Turn off printing of page headings. - -@item @@headings single -Turn on page headings appropriate for single-sided printing. - -@item @@headings double -Turn on page headings appropriate for double-sided printing. - -@item @@headings singleafter -@itemx @@headings doubleafter -Turn on @code{single} or @code{double} headings, respectively, after the -current page is output. - -@item @@headings on -Turn on page headings: @code{single} if @samp{@@setchapternewpage -on}, @code{double} otherwise. -@end table - -For example, suppose you write @code{@@setchapternewpage off} before the -@code{@@titlepage} command to tell @TeX{} to start a new chapter on the -same page as the end of the last chapter. This command also causes -@TeX{} to typeset page headers for single-sided printing. To cause -@TeX{} to typeset for double sided printing, write @code{@@headings -double} after the @code{@@end titlepage} command. - -You can stop @TeX{} from generating any page headings at all by -writing @code{@@headings off} on a line of its own immediately after the -line containing the @code{@@end titlepage} command, like this: - -@example -@@end titlepage -@@headings off -@end example - -@noindent -The @code{@@headings off} command overrides the @code{@@end titlepage} -command, which would otherwise cause @TeX{} to print page headings. - -You can also specify your own style of page heading and footing. -@xref{Headings, , Page Headings}, for more information. - - -@node @t{@@paragraphindent} -@subsection @code{@@paragraphindent}: Controlling Paragraph Indentation - -@anchor{paragraphindent}@c old name -@findex paragraphindent -@cindex Indenting paragraphs, control of -@cindex Paragraph indentation control - -The Texinfo processors may insert whitespace at the beginning of the -first line of each paragraph, thereby indenting that paragraph. You can -use the @code{@@paragraphindent} command to specify this indentation. -Write an @code{@@paragraphindent} command at the beginning of a line -followed by either @samp{asis} or a number: - -@example -@@paragraphindent @var{indent} -@end example - -The indentation is according to the value of @var{indent}: - -@table @asis -@item @code{asis} -Do not change the existing indentation (not implemented in @TeX{}). - -@item @code{none} -@itemx 0 -Omit all indentation. - -@item @var{n} -Indent by @var{n} space characters in Info output, by @var{n} ems in -@TeX{}. - -@end table - -The default value of @var{indent} is 3. @code{@@paragraphindent} is -ignored for HTML output. - -It is best to write the @code{@@paragraphindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - -A peculiarity of the @code{texinfo-format-buffer} and -@code{texinfo-format-region} commands is that they do not indent (nor -fill) paragraphs that contain @code{@@w} or @code{@@*} commands. - - -@node @t{@@firstparagraphindent} -@subsection @code{@@firstparagraphindent}: Indenting After Headings - -@anchor{firstparagraphindent}@c old name -@findex firstparagraphindent -@cindex First paragraph, suppressing indentation of -@cindex Suppressing first paragraph indentation -@cindex Preventing first paragraph indentation -@cindex Indenting, suppressing of first paragraph -@cindex Headings, indentation after - -As you can see in the present manual, the first paragraph in any -section is not indented by default. Typographically, indentation is a -paragraph separator, which means that it is unnecessary when a new -section begins. This indentation is controlled with the -@code{@@firstparagraphindent} command: - -@example -@@firstparagraphindent @var{word} -@end example - -The first paragraph after a heading is indented according to the value -of @var{word}: - -@table @asis -@item @code{none} -Prevents the first paragraph from being indented (default). -This option is ignored by @command{makeinfo} if -@code{@@paragraphindent asis} is in effect. - -@item @code{insert} -Include normal paragraph indentation. This respects the paragraph -indentation set by an @code{@@paragraphindent} command -(@pxref{@t{@@paragraphindent}}). -@end table - -@code{@@firstparagraphindent} is ignored for HTML and Docbook output. - -It is best to write the @code{@@firstparagraphindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - - -@node @t{@@exampleindent} -@subsection @code{@@exampleindent}: Environment Indenting - -@anchor{exampleindent}@c old name -@findex exampleindent -@cindex Indenting environments -@cindex Environment indentation -@cindex Example indentation - -The Texinfo processors indent each line of @code{@@example} and similar -environments. You can use the @code{@@exampleindent} command to specify -this indentation. Write an @code{@@exampleindent} command at the -beginning of a line followed by either @samp{asis} or a number: - -@example -@@exampleindent @var{indent} -@end example - -The indentation is according to the value of @var{indent}: - -@table @asis -@item @code{asis} -Do not change the existing indentation (not implemented in @TeX{}). - -@item 0 -Omit all indentation. - -@item @var{n} -Indent environments by @var{n} space characters in Info output, by -@var{n} ems in @TeX{}. - -@end table - -The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in} -in @TeX{}, which is somewhat less. (The reduction is to help @TeX{} -fit more characters onto physical lines.) - -It is best to write the @code{@@exampleindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - - -@node Ending a File -@chapter Ending a Texinfo File -@cindex Ending a Texinfo file -@cindex Texinfo file ending -@cindex File ending -@findex bye - -The end of a Texinfo file should include commands to create indices, -and the @code{@@bye} command to mark the last line to be processed. -For example: - -@example -@@node Index -@@unnumbered Index - -@@printindex cp - -@@bye -@end example - -@menu -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* File End:: How to mark the end of a file. -@end menu - - -@node Printing Indices & Menus -@section Printing Indices and Menus -@cindex Printing an index -@cindex Indices, printing and menus -@cindex Generating menus with indices -@cindex Menus generated with indices - -To print an index means to include it as part of a manual or Info file. -This does not happen automatically just because you use @code{@@cindex} -or other index-entry generating commands in the Texinfo file; those just -cause the raw data for the index to be accumulated. To generate an -index, you must include the @code{@@printindex} command at the place in -the document where you want the index to appear. Also, as part of the -process of creating a printed manual, you must run a program called -@code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a -sorted index file. The sorted index file is what is actually used to -print the index. - -Texinfo offers six separate types of predefined index, which suffice -in most cases. @xref{Indices}, for information on this, as well -defining your own new indices, combining indices, and, most -importantly advice on writing the actual index entries. This section -focuses on printing indices, which is done with the -@code{@@printindex} command. - -@findex printindex -@code{@@printindex} takes one argument, a two-letter index -abbreviation. It reads the corresponding sorted index file (for -printed output), and formats it appropriately into an index. - -The @code{@@printindex} command does not generate a chapter heading -for the index, since different manuals have different needs. -Consequently, you should precede the @code{@@printindex} command with -a suitable section or chapter command (usually @code{@@appendix} or -@code{@@unnumbered}) to supply the chapter heading and put the index -into the table of contents. Precede the chapter heading with an -@code{@@node} line as usual. - -For example: - -@smallexample -@group -@@node Variable Index -@@unnumbered Variable Index - -@@printindex vr -@end group - -@group -@@node Concept Index -@@unnumbered Concept Index - -@@printindex cp -@end group -@end smallexample - -If you have more than one index, we recommend placing the concept index last. - -@itemize -@item -In printed output, @code{@@printindex} produces a traditional -two-column index, with dot leaders between the index terms and page -numbers. - -@item -In Info output, @code{@@printindex} produces a special menu containing -the line number of the entry, relative to the start of the node. Info -readers can use this to go to the exact line of an entry, not just the -containing node. (Older Info readers will just go to the node.) -Here's an example: - -@smallexample -* First index entry: Top. (line 7) -@end smallexample - -@noindent The actual number of spaces is variable, to right-justify -the line number; it's been reduced here to make the line fit in the -printed manual. - -@item -In plain text output, @code{@@printindex} produces the same menu, but -the line numbers are relative to the start of the file, since that's -more convenient for that format. - -@item -In HTML output, @code{@@printindex} produces links to the index -entries. - -@item -In XML and Docbook output, it simply records the index to be printed. -@end itemize - - -@node File End -@section @code{@@bye} File Ending -@findex bye - -An @code{@@bye} command terminates Texinfo processing. None of the -formatters process anything following @code{@@bye}; any such text is -completely ignored. The @code{@@bye} command should be on a line by -itself. - -Thus, if you wish, you may follow the @code{@@bye} line with arbitrary -notes. Also, you may follow the @code{@@bye} line with a local -variables list for XEmacs, most typically a @samp{compile-command} -(@pxref{Compile-Command,, Using the Local Variables List}). - - -@node Chapter Structuring -@chapter Chapter Structuring -@anchor{Structuring}@c old name -@cindex Chapter structuring -@cindex Structuring of chapters -@cindex Sectioning - -Texinfo's @dfn{chapter structuring} commands (could more generally be -called @dfn{sectioning structuring}, but that is awkward) divide a -document into a hierarchy of chapters, sections, subsections, and -subsubsections. These commands generate large headings in the text, -like the one above. They also provide information for generating the -table of contents (@pxref{Contents,, Generating a Table of Contents}), -and for implicitly determining node pointers, as is recommended -(@pxref{@t{makeinfo} Pointer Creation}). - -The chapter structuring commands do not create a node structure, so -normally you put an @code{@@node} command immediately before each -chapter structuring command (@pxref{Nodes}). The only time you are -likely to use the chapter structuring commands without also using -nodes is if you are writing a document that contains no cross -references and will only be printed, not transformed into Info, HTML, -or other formats. - -@menu -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* @t{@@chapter}:: Chapter structuring. -* @t{@@unnumbered @@appendix}:: -* @t{@@majorheading @@chapheading}:: -* @t{@@section}:: -* @t{@@unnumberedsec @@appendixsec @@heading}:: -* @t{@@subsection}:: -* @t{@@unnumberedsubsec @@appendixsubsec @@subheading}:: -* @t{@@subsubsection}:: Commands for the lowest level sections. -* @t{@@part}:: Collections of chapters. -* Raise/lower sections:: How to change commands' hierarchical level. -@end menu - - -@node Tree Structuring -@section Tree Structure of Sections -@cindex Tree structuring - -A Texinfo file is usually structured like a book with chapters, -sections, subsections, and the like. This structure can be visualized -as a tree (or rather as an upside-down tree) with the root at the top -and the levels corresponding to chapters, sections, subsection, and -subsubsections. - -Here is a diagram that shows a Texinfo file with three chapters, each -with two sections. - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | -Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - -@end group -@end example - -In a Texinfo file that has this structure, the beginning of Chapter 2 -would normally (with implicitly-determined node pointers) be written -like this: - -@example -@group -@@node Chapter 2 -@@chapter Chapter 2 -@end group -@end example - -@noindent -But for purposes of example, here is how it would be written with -explicit node pointers: - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, Top -@@chapter Chapter 2 -@end group -@end example - -The chapter structuring commands are described in the sections that -follow; the @code{@@node} command is described in -the following chapter (@pxref{Nodes}). - - -@node Structuring Command Types -@section Structuring Command Types - -The chapter structuring commands fall into four groups or series, each -of which contains structuring commands corresponding to the -hierarchical levels of chapters, sections, subsections, and -subsubsections. - -The four groups of commands are the @code{@@chapter} series, the -@code{@@unnumbered} series, the @code{@@appendix} series, and the -@code{@@heading} series. Each command produces a title with a -different appearance in the body of the document. Some of the -commands list their titles in the tables of contents, while others do -not. Here are the details: - -@itemize @bullet -@item -The @code{@@chapter} and @code{@@appendix} series of commands produce -numbered or lettered entries both in the body of a document and in its -table of contents. - -@item -The @code{@@unnumbered} series of commands produce unnumbered entries -both in the body of a document and in its table of contents. The -@code{@@top} command, which has a special use, is a member of this -series (@pxref{@t{@@top} Command}). An @code{@@unnumbered} section -is a normal part of the document structure. - -@item -The @code{@@heading} series of commands produce simple unnumbered -headings that do not appear in a table of contents, are not associated -with nodes, and cannot be cross-referenced. These heading commands -never start a new page. -@end itemize - -When an @code{@@setchapternewpage} command says to do so, the -@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands -start new pages in the printed manual; the @code{@@heading} commands -do not. @xref{@t{@@setchapternewpage}}. - -Here is a summary: - -@tex -{\globaldefs=1 \smallfonts \rm} -@end tex - -@multitable @columnfractions .19 .30 .29 .22 -@item @tab @tab @tab No new page -@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} -@item In contents @tab In contents @tab In contents @tab Not in contents -@item @tab @code{@@top} @tab @tab @code{@@majorheading} -@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading} -@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} -@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} -@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} -@end multitable -@tex -{\globaldefs=1 \textfonts \rm} -@end tex - - -@node @t{@@chapter} -@section @code{@@chapter}: Chapter Structuring - -@anchor{chapter}@c old name -@findex chapter - -@code{@@chapter} identifies a chapter in the document--the highest -level of the normal document structuring hierarchy. Write the command -at the beginning of a line and follow it on the same line by the title -of the chapter. The chapter is numbered automatically, starting -from@tie{}1. - -For example, the present chapter in this manual is entitled -``@code{@@chapter}: Chapter Structuring''; the @code{@@chapter} line -looks like this: - -@example -@@chapter @@code@{@@@@chapter@}: Chapter Structuring -@end example - -In @TeX{}, the @code{@@chapter} command produces a chapter heading in -the document. - -In Info and plain text output, the @code{@@chapter} command causes the -title to appear on a line by itself, with a line of asterisks inserted -underneath. So, the above example produces the following output: - -@example -@group -5 Chapter Structuring -********************* -@end group -@end example - -In HTML, the @code{@@chapter} command produces an @code{<h2>}-level -header by default (controlled by the @code{CHAPTER_HEADER_LEVEL} -customization variable, @pxref{Other Customization Variables}). - -In the XML and Docbook output, a @code{<chapter>} element is produced -that includes all the following sections, up to the next chapter. - - -@node @t{@@unnumbered @@appendix} -@section @code{@@unnumbered}, @code{@@appendix}: Chapters with Other Labeling - -@anchor{unnumbered & appendix}@c old name -@findex unnumbered -@findex appendix - -Use the @code{@@unnumbered} command to start a chapter-level element -that appears without chapter numbers of any kind. Use the -@code{@@appendix} command to start an appendix that is labeled by -letter (`A', `B', @dots{}) instead of by number; appendices are also -at the chapter level of structuring. - -Write an @code{@@appendix} or @code{@@unnumbered} command at the -beginning of a line and follow it on the same line by the title, -just as with @code{@@chapter}. - -@findex centerchap -Texinfo also provides a command @code{@@centerchap}, which is analogous -to @code{@@unnumbered}, but centers its argument in the printed and HTML -outputs. This kind of stylistic choice is not usually offered by -Texinfo. It may be suitable for short documents. -@c but the Hacker's Dictionary wanted it, before they quit Texinfo. - -@cindex Docbook and prefatory sections -@cindex Preface, etc., and Docbook -With @code{@@unnumbered}, if the name of the associated node is one of -these English words (case-insensitive): - -@example -Acknowledgements Colophon Dedication Preface -@end example - -@cindex @code{<acknowledgements>} Docbook tag -@cindex @code{<colophon>} Docbook tag -@cindex @code{<dedication>} Docbook tag -@cindex @code{<preface>} Docbook tag -@cindex @code{<chapter>} Docbook tag -@cindex @code{<title>} Docbook tag -@noindent then the Docbook output uses corresponding special tags -(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}. -The argument to @code{@@unnumbered} itself can be anything, and is -output as the following @code{<title>} text as usual. - - -@node @t{@@majorheading @@chapheading} -@section @code{@@majorheading}, @code{@@chapheading}: Chapter-level Headings - -@anchor{majorheading & chapheading}@c old name -@findex majorheading -@findex chapheading - -The @code{@@majorheading} and @code{@@chapheading} commands produce -chapter-like headings in the body of a document. - -However, neither command produces an entry in the table of contents, -and neither command causes @TeX{} to start a new page in a printed -manual. - -In @TeX{}, an @code{@@majorheading} command generates a larger vertical -whitespace before the heading than an @code{@@chapheading} command but -is otherwise the same. - -In Info and plain text, the @code{@@majorheading} and -@code{@@chapheading} commands produce the same output as -@code{@@chapter}: the title is printed on a line by itself with a line -of asterisks underneath. Similarly for HTML@. The only difference is -the lack of numbering and the lack of any association with nodes. -@xref{@t{@@chapter}}. - - -@node @t{@@section} -@section @code{@@section}: Sections Below Chapters - -@anchor{section}@c old name -@findex section - -An @code{@@section} command identifies a section within a chapter -unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or -@code{@@appendix}, following the numbering scheme of the chapter-level -command. Thus, within an @code{@@chapter} chapter numbered `1', the -sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix} -``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.; -within an @code{@@unnumbered} chapter, the section gets no number. -The output is underlined with @samp{=} in Info and plain text. - -To make a section, write the @code{@@section} command at the -beginning of a line and follow it on the same line by the section -title. For example, - -@example -@@section This is a section -@end example - -@noindent -might produce the following in Info: - -@example -@group -5.7 This is a section -===================== -@end group -@end example - -Section titles are listed in the table of contents. - -The @TeX{}, HTML, Docbook, and XML output is all analogous to the -chapter-level output, just ``one level down''; @pxref{@t{@@chapter}}. - - -@node @t{@@unnumberedsec @@appendixsec @@heading} -@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} - -@anchor{unnumberedsec appendixsec heading}@c old name -@findex unnumberedsec -@findex appendixsec -@findex heading - -The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} -commands are, respectively, the unnumbered, appendix-like, and -heading-like equivalents of the @code{@@section} command (see the -previous section). - -@code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used -in ordinary circumstances, because @code{@@section} may also be used -within @code{@@unnumbered} and @code{@@appendix} chapters; again, see -the previous section. - -@table @code -@item @@unnumberedsec -The @code{@@unnumberedsec} command may be used within an unnumbered -chapter or within a regular chapter or appendix to produce an -unnumbered section. - -@item @@appendixsec -@itemx @@appendixsection -@findex appendixsection -@findex appendixsec -@code{@@appendixsection} is a longer spelling of the -@code{@@appendixsec} command; the two are synonymous. - -Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} -command is used only within appendices. - -@item @@heading -You may use the @code{@@heading} command anywhere you wish for a -section-style heading that will not appear in the table of contents. -@end table - - -@node @t{@@subsection} -@section @code{@@subsection}: Subsections Below Sections - -@anchor{subsection}@c old name -@findex subsection - -Subsections are to sections as sections are to chapters; -@pxref{@t{@@section}}. In Info and plain text, subsection titles -are underlined with @samp{-}. For example, - -@example -@@subsection This is a subsection -@end example - -@noindent -might produce - -@example -@group -1.2.3 This is a subsection --------------------------- -@end group -@end example - -Subsection titles are listed in the table of contents. - -The @TeX{}, HTML, Docbook, and XML output is all analogous to the -chapter-level output, just ``two levels down''; -@pxref{@t{@@chapter}}. - - -@node @t{@@unnumberedsubsec @@appendixsubsec @@subheading} -@section The @code{@@subsection}-like Commands - -@anchor{unnumberedsubsec appendixsubsec subheading}@c old name -@findex unnumberedsubsec -@findex appendixsubsec -@findex subheading -@cindex Subsection-like commands - -The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and -@code{@@subheading} commands are, respectively, the unnumbered, -appendix-like, and heading-like equivalents of the @code{@@subsection} -command. (@xref{@t{@@subsection}}.) - -@code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to -be used in ordinary circumstances, because @code{@@subsection} may -also be used within sections of @code{@@unnumbered} and -@code{@@appendix} chapters (@pxref{@t{@@section}}). - -An @code{@@subheading} command produces a heading like that of a -subsection except that it is not numbered and does not appear in the -table of contents. Similarly, an @code{@@unnumberedsubsec} command -produces an unnumbered heading like that of a subsection and an -@code{@@appendixsubsec} command produces a subsection-like heading -labeled with a letter and numbers; both of these commands produce -headings that appear in the table of contents. In Info and plain -text, the @code{@@subsection}-like commands generate a title -underlined with hyphens. - - -@node @t{@@subsubsection} -@section @code{@@subsection} and Other Subsub Commands - -@anchor{subsubsection}@c old name -@findex subsubsection -@findex unnumberedsubsubsec -@findex appendixsubsubsec -@findex subsubheading -@cindex Subsub sectioning commands - -The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are: - -@table @code -@item @@subsubsection -Subsubsections are to subsections as subsections are to sections. -(@xref{@t{@@subsection}}.) Subsubsection titles appear in the -table of contents. - -@item @@unnumberedsubsubsec -Unnumbered subsubsection titles appear in the table of contents, -but lack numbers. Otherwise, unnumbered subsubsections are the same -as subsubsections. - -@item @@appendixsubsubsec -Conventionally, appendix commands are used only for appendices and are -lettered and numbered appropriately. They also appear in the table -of contents. - -@item @@subsubheading -The @code{@@subsubheading} command may be used anywhere that you want -a small heading that will not appear in the table of contents. -@end table - -As with subsections, @code{@@unnumberedsubsubsec} and -@code{@@appendixsubsubsec} do not need to be used in ordinary -circumstances, because @code{@@subsubsection} may also be used within -subsections of @code{@@unnumbered} and @code{@@appendix} chapters -(@pxref{@t{@@section}}). - -In Info, `subsub' titles are underlined with periods. For example, - -@example -@@subsubsection This is a subsubsection -@end example - -@noindent -might produce - -@example -@group -1.2.3.4 This is a subsubsection -............................... -@end group -@end example - -The @TeX{}, HTML, Docbook, and XML output is all analogous to the -chapter-level output, just ``three levels down''; @pxref{@t{@@chapter}}. - - -@node @t{@@part} -@section @code{@@part}: Groups of Chapters -@findex part -@cindex Part pages - -The final sectioning command is @code{@@part}, to mark a @dfn{part} of -a manual, that is, a group of chapters or (rarely) appendices. This -behaves quite differently from the other sectioning commands, to fit -with the way such ``parts'' are conventionally used in books. - -No @code{@@node} command is associated with @code{@@part}. Just write -the command on a line by itself, including the part title, at the -place in the document you want to mark off as starting that part. For -example: - -@example -@@part Part I:@@* The beginning -@end example - -As can be inferred from this example, no automatic numbering or -labeling of the @code{@@part} text is done. The text is taken as-is. - -Because parts are not associated with nodes, no general text can -follow the @code{@@part} line. To produce the intended output, it -must be followed by a chapter-level command (including its node). -Thus, to continue the example: - -@example -@@part Part I:@@* The beginning - -@@node Introduction -@@chapter Introduction -... -@end example - -In the @TeX{} output, the @code{@@part} text is included in both the -normal and short tables of contents (@pxref{Contents}), without a page -number (since that is the normal convention). In addition, a ``part -page'' is output in the body of the document, with just the -@code{@@part} text. In the example above, the @code{@@*} causes a -line break on the part page (but is replaced with a space in the -tables of contents). This part page is always forced to be on an odd -(right-hand) page, regardless of the chapter pagination -(@pxref{@t{@@setchapternewpage}}). - -In the HTML output, the @code{@@part} text is similarly included in -the tables of contents, and a heading is included in the main document -text, as part of the following chapter or appendix node. - -In the XML and Docbook output, the @code{<part>} element includes all -the following chapters, up to the next @code{<part>}. A @code{<part>} -containing chapters is also closed at an appendix. - -In the Info and plain text output, @code{@@part} has no effect. - -@code{@@part} is ignored when raising or lowering sections (see next -section). That is, it is never lowered and nothing can be raised to it. - - -@node Raise/lower sections -@section Raise/lower Sections: @code{@@raisesections} and @code{@@lowersections} -@findex raisesections -@findex lowersections -@cindex Raising and lowering sections -@cindex Lowering and raising sections -@cindex Sections, raising and lowering - -The @code{@@raisesections} and @code{@@lowersections} commands -implicitly raise and lower the hierarchical level of following -chapters, sections and the other sectioning commands (excluding parts). - -That is, the @code{@@raisesections} command changes sections to -chapters, subsections to sections, and so on. Conversely, the -@code{@@lowersections} command changes chapters to sections, sections -to subsections, and so on. Thus, an @code{@@lowersections} command -cancels an @code{@@raisesections} command, and vice versa. - -@cindex Include files, and section levels -You can use @code{@@lowersections} to include text written as an outer -or standalone Texinfo file in another Texinfo file as an inner, -included file (@pxref{Include Files}). Typical usage looks like this: - -@example -@@lowersections -@@include somefile.texi -@@raisesections -@end example - -@noindent (Without the @code{@@raisesections}, all the subsequent -sections in the main file would also be lowered.) - -If the included file being lowered has an @code{@@top} node, you'll -need to conditionalize its inclusion with a flag (@pxref{@t{@@set -@@value}}). - -Another difficulty can arise with documents that use the (recommended) -feature of @command{makeinfo} for implicitly determining node -pointers. Since @command{makeinfo} must assume a hierarchically -organized document to determine the pointers, you cannot just -arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections} -commands throughout the document. The final result has to have menus -that take the raising and lowering into account. So, as a practical -matter, you generally only want to raise or lower large chunks, -usually in external files as shown above. - -Repeated use of the commands continues to raise or lower the -hierarchical level a step at a time. An attempt to raise above -`chapter' reproduces chapter commands; an attempt to lower below -`subsubsection' reproduces subsubsection commands. Also, lowered -subsubsections and raised chapters will not work with -@command{makeinfo}'s feature of implicitly determining node pointers, -since the menu structure cannot be represented correctly. - -Write each @code{@@raisesections} and @code{@@lowersections} command -on a line of its own. - - -@node Nodes -@chapter Nodes - -@dfn{Nodes} are the primary segments of a Texinfo file. They do not -in and of themselves impose a hierarchical or any other kind of -structure on a file. Nodes contain @dfn{node pointers} that name -other nodes, and can contain @dfn{menus} which are lists of nodes. In -Info, the movement commands can carry you to a pointed-to node or to a -node listed in a menu. - -Node pointers and menus provide structure for Info files just as -chapters, sections, subsections, and the like provide structure for -printed books. The two structures are theoretically distinct. In -practice, however, the tree structure of printed books is essentially -always used for the node and menu structure also, as this leads to a -document which is easiest to follow. @xref{Texinfo Document -Structure}. - -Because node names are used in cross references, it is not desirable -to casually change them once published. Such name changes invalidate -references from other manuals, from mail archives, and so on. -@xref{HTML Xref Link Preservation}. - -@menu -* @t{@@node}:: Creating nodes, in detail. -* @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers. -* @t{@@anchor}:: Defining arbitrary cross reference targets. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -@end menu - - -@node @t{@@node} -@section The @code{@@node} Command - -@anchor{node}@c node -@findex node -@cindex Node, defined - -A @dfn{node} is a stretch of text that begins at an @code{@@node} -command and continues until the next @code{@@node} command. The -definition of node is different from that for chapter or section. A -chapter may contain sections and a section may contain subsections, -but a node cannot contain subnodes: the text of a node continues only -until the next @code{@@node} command in the file. A node usually -contains only one chapter structuring command, immediately following -the @code{@@node} line. - -To specify a node, write an @code{@@node} command at the beginning of -a line, and follow it with up to four arguments, separated by commas, -on the rest of the same line. The first argument is required; it is -the name of this node (for details of node names, @pxref{Node Line -Requirements}). The subsequent arguments are optional---they are the -names of the `Next', `Previous', and `Up' pointers, in that order. We -strongly recommend omitting them if your Texinfo document is -hierarchically organized, as virtually all are (@pxref{@t{makeinfo} -Pointer Creation}). You may insert spaces before or after each name -on the @code{@@node} line if you wish; such spaces are ignored. - -@opindex accesskey@r{, in HTML output of nodes} -Whether the node pointers are specified implicitly or explicitly, the -Info and HTML output from @command{makeinfo} for each node includes -links to the `Next', `Previous', and `Up' nodes. The HTML also uses -the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and -@samp{u} respectively. This allows people using web browsers to -follow the navigation using (typically) @kbd{M-@var{letter}}, e.g., -@kbd{M-n} for the `Next' node, from anywhere within the node. - -Usually, you write one of the chapter-structuring command lines -immediately after an @code{@@node} line---for example, an -@code{@@section} or @code{@@subsection} line. @xref{Structuring -Command Types}. - -@TeX{} uses both @code{@@node} names and chapter-structuring names in -the output for cross references. For this reason, you must write -@code{@@node} lines in a Texinfo file that you intend to format for -printing, even if you do not intend to format it for Info; and you -must include a chapter-structuring command after a node for it to be a -valid cross reference target (to @TeX{}). You can use @code{@@anchor} -(@pxref{@t{@@anchor}}) to make cross references to an arbitrary -position in a document. - -Cross references, such as the one at the end of this sentence, are -made with @code{@@xref} and related commands; see @ref{Cross -References}. - -@menu -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Requirements:: Keep names unique. -* First Node:: How to write a `Top' node. -* @t{@@top} Command:: How to use the @code{@@top} command. -@end menu - - -@node Node Names -@subsection Choosing Node and Pointer Names - -@cindex Node names, choosing -The name of a node identifies the node. For all the details of node -names, @pxref{Node Line Requirements}). - -@anchor{Node Line Tips}@c previous node name -Here are some suggestions for node names: - -@itemize @bullet -@item -Try to pick node names that are informative but short. - -In the Info file, the file name, node name, and pointer names are all -inserted on one line, which may run into the right edge of the window. -(This does not cause a problem with Info, but is ugly.) - -@item -Try to pick node names that differ from each other near the beginnings -of their names. This way, it is easy to use automatic name completion in -Info. - -@item -Conventionally, node names are capitalized in the same way as section -and chapter titles. In this manual, initial and significant words are -capitalized; others are not. In other manuals, just initial words and -proper nouns are capitalized. Either way is fine; we recommend just -being consistent. -@end itemize - -The pointers from a given node enable you to reach other nodes and -consist simply of the names of those nodes. The pointers are usually -not specified explicitly, as @command{makeinfo} can determine them -(@pxref{@t{makeinfo} Pointer Creation}). - -Normally, a node's `Up' pointer contains the name of the node whose -menu mentions that node. The node's `Next' pointer contains the name -of the node that follows the present node in that menu and its -`Previous' pointer contains the name of the node that precedes it in -that menu. When a node's `Previous' node is the same as its `Up' -node, both pointers name the same node. - -Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' pointer points to the @file{dir} file, which contains the main menu -for all of Info. - - -@node Writing a Node -@subsection Writing an @code{@@node} Line -@cindex Writing an @code{@@node} line -@cindex @code{@@node} line writing -@cindex Node line writing - -The easiest and preferred way to write an @code{@@node} line is to -write @code{@@node} at the beginning of a line and then the name of -the node, like this: - -@example -@@node @var{node-name} -@end example - -If you are using XEmacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or -(recommended), you can leave the pointers out of the Texinfo file and -let @code{makeinfo} insert node pointers into the Info file it -creates. (@xref{Texinfo Mode}, and @ref{@t{makeinfo} Pointer -Creation}.) - -Alternatively, you can insert the `Next', `Previous', and `Up' -pointers yourself. If you do this, you may find it helpful to use the -Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts -@samp{@@node} and a comment line listing the names of the pointers in -their proper order. The comment line helps you keep track of which -arguments are for which pointers. This comment line is especially useful -if you are not familiar with Texinfo. - -The template for a fully-written-out node line with `Next', `Previous', -and `Up' pointers looks like this: - -@example -@@node @var{node-name}, @var{next}, @var{previous}, @var{up} -@end example - -The @var{node-name} argument must be present, but the others are -optional. If you wish to specify some but not others, just insert -commas as needed, as in: @samp{@@node mynode,,,uppernode}. However, -we recommend leaving off all the pointers and letting @code{makeinfo} -determine them, as described above. - -It's, you can ignore @code{@@node} lines altogether in your -first draft and then use the @code{texinfo-insert-node-lines} command -to create @code{@@node} lines for you. However, we do not recommend -this practice. It is better to name the node itself at the same time -that you write a segment so you can easily make cross references. -Useful cross references are an especially important feature of a good -Texinfo manual. - -After you have inserted an @code{@@node} line, you should immediately -write an @@-command for the chapter or section and insert its name. -Next (and this is important!), put in several index entries. Usually, -you will find at least two and often as many as four or five ways of -referring to the node in the index. Use them all. This will make it -much easier for people to find the node. - -Even when you explicitly specify all pointers, you cannot write the -nodes in the Texinfo source file in an arbitrary order! Because -formatters must process the file sequentially, irrespective of node -pointers, you must write the nodes in the order you wish them to -appear in the output. For Info format one can imagine that the order -may not matter, but it matters for the other formats. - - -@node Node Line Requirements -@subsection @code{@@node} Line Requirements - -@cindex Node line requirements -@cindex Restrictions on node names - -Names used with @code{@@node} have several requirements: - -@itemize @bullet -@item -@cindex Unique node names requirement -@cindex Node names must be unique -All the node names in a single Texinfo file must be unique. - -This means, for example, that if you end every chapter with a summary, -you must name each summary node differently. You cannot just call -them all ``Summary''. You may, however, duplicate the titles of -chapters, sections, and the like. Thus you can end each chapter with -a section called ``Summary'', so long as the node names for those -sections are all different. - -@item -The next/previous/up pointers on @code{@@node} lines must be the names -of nodes. (It's recommended to leave out these explicit node pointer -names, which automatically avoids any problem here; @pxref{@t{makeinfo} -Pointer Creation}.) - -@item -@cindex Commands in node names -@cindex @@-commands in node names -Node names can contain @@-commands. The output is generally the -natural result of the command; for example, using @code{@@TeX@{@}} in a -node name results in the @TeX{} logo being output, as it would be in -normal text. Cross references should use @code{@@TeX@{@}} just as the -node name does. - -For Info and HTML output, especially, it is necessary to expand -commands to some sequence of plain characters; for instance, -@code{@@TeX@{@}} expands to the three letters @samp{TeX} in the Info -node name. However, cross references to the node should not take the -``shortcut'' of using @samp{TeX}; stick to the actual node name, -commands and all. - -Some commands do not make sense in node names; for instance, -environments (e.g., @code{@@quotation}), commands that read a whole -line as their argument (e.g., @code{@@sp}), and plenty of others. - -For the complete list of commands that are allowed, and their -expansion for HTML identifiers and file names, @pxref{HTML Xref -Command Expansion}. The expansions for Info are generally given with -main the description of the command. - -Prior to the Texinfo 5 release in 2013, this feature was supported in -an ad hoc way (the @option{--commands-in-node-names} option to -@command{makeinfo}). Now it is part of the language. - -@item -@cindex Colon in node name -@cindex Comma in node name -@cindex Parentheses in node name -@cindex Period in node name -@cindex Characters, invalid in node name -@cindex Invalid characters in node names -@cindex Node names, invalid characters in -Unfortunately, you cannot reliably use periods, commas, or colons -within a node name; these can confuse the Info reader. Also, a node -name may not start with a left parenthesis preceding a right -parenthesis, as in @code{(not)allowed}, since this syntax is used to -specify an external manual. (Perhaps these limitations will be -removed some day.) - -@command{makeinfo} warns about such problematic usage in node names, -menu items, and cross references. If you don't want to see the -warnings, you can set the customization variable -@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other -Customization Variables}). - -Also, if you insist on using these characters in node names (accepting -the resulting substandard Info output), in order not to confuse the -Texinfo processors you must still escape those characters, by using -either special insertions (@pxref{Inserting a Comma}) or @code{@@asis} -(@pxref{@t{@@asis}}). For example: - -@example -@@node foo@@asis@{::@}bar -@end example - -As an example of avoiding the special characters, the following is a -section title in this manual: - -@smallexample -@@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: ... -@end smallexample - -@noindent -But the corresponding node name lacks the commas and the subtitle: - -@smallexample -@@node @t{@@unnumbered @@appendix} -@end smallexample - -@cindex Case in node name -@item -Case is significant in node names. - -@cindex White space in node name -@cindex Spaces in node name -Spaces before and after names on the @samp{@@node} line are ignored. -Multiple whitespace characters ``inside'' a name are collapsed to a -single space. For example: - -@example -@@node foo bar, -@@node foo bar , -@@node foo bar, -@@node foo bar , -@end example - -@noindent all define the same node, namely @samp{foo bar}. References -to the node should all use that name, with no leading or trailing -spaces, and a single internal space. -@end itemize - - -@node First Node -@subsection The First Node -@cindex Top node is first -@cindex First node - -The first node of a Texinfo file is the @dfn{Top} node, except in an -included file (@pxref{Include Files}). The Top node should contain a -short summary, copying permissions, and a master menu. @xref{The Top -Node}, for more information on the Top node contents and examples. - -Here is a description of the node pointers to be used in the Top node: - -@itemize @bullet -@item -@cindex Up node of Top node -@cindex (dir) as Up node of Top node -The Top node (which must be named @samp{top} or @samp{Top}) should have -as its `Up' node the name of a node in another file, where there is a -menu that leads to this file. Specify the file name in parentheses. - -Usually, all Info files are installed in one system-wide Info tree -(often constructed from multiple directories). In this case, use -@samp{(dir)} as the parent of the Top node; this specifies the -top-level node in the @file{dir} file, which contains the main menu -for the Info system as a whole. - -@item -@cindex Next node of Top node -The `Next' node of the Top node should be the first chapter in your -document. - -@end itemize - -@xref{Installing an Info File}, for more information about installing -an Info file in the @file{info} directory. - -It is usually best to leave the pointers off entirely and let the -tools implicitly define them, with this simple result: - -@example -@@node Top -@end example - - -@node @t{@@top} Command -@subsection The @code{@@top} Sectioning Command - -@anchor{top command}@c old name -@anchor{makeinfo top}@c another old name -@anchor{makeinfo top command}@c yet another name -@findex top - -The @code{@@top} command is a special sectioning command that you -should only use after an @samp{@@node Top} line at the beginning of a -Texinfo file. The @code{@@top} command tells the @code{makeinfo} -formatter which node is to be used as the root of the node tree -(needed if your manual uses implicit node pointers). - -It produces the same sort of output as @code{@@unnumbered} -(@pxref{@t{@@unnumbered @@appendix}}). - -The @code{@@top} node is conventionally wrapped in an -@code{@@ifnottex} conditional so that it will not appear in @TeX{} -output (@pxref{Conditionals}). -Thus, in practice, a Top node usually looks like this: - -@example -@@ifnottex -@@node Top -@@top @var{your-manual-title} - -@var{very-high-level-summary} -@@end ifnottex -@end example - -@code{@@top} is ignored when raising or lowering sections. That is, -it is never lowered and nothing can be raised to it -(@pxref{Raise/lower sections}). - - -@node @t{makeinfo} Pointer Creation -@section @code{makeinfo} Pointer Creation - -@cindex Creating pointers with @code{makeinfo} -@cindex Pointer creation with @code{makeinfo} -@cindex Automatic pointer creation with @code{makeinfo} -@cindex Implicit pointer creation with @code{makeinfo} - -The @code{makeinfo} program can automatically determine node pointers -for a hierarchically organized document. This implicit node pointer -creation feature in @code{makeinfo} relieves you from the need to -update menus and pointers manually or with Texinfo mode commands. -(@xref{Updating Nodes and Menus}.) We highly recommend taking -advantage of this. - -To do so, write your @code{@@node} lines with just the name of the -node: - -@example -@@node My Node -@end example - -@noindent -You do not need to write out the `Next', `Previous', and `Up' -pointers. - -Then, you must write a sectioning command, such as @code{@@chapter} -or @code{@@section}, on the line immediately following each truncated -@code{@@node} line (except that comment lines may intervene). This is -where it normally goes. - -Also, you must write the name of each node (except for the `Top' node) -in a menu that is one or more hierarchical levels above the node's -level. - -Finally, you must follow the `Top' @code{@@node} line with a line -beginning with @code{@@top} to mark the top-level node in the file. -@xref{@t{@@top} Command}. - -@cindex Detail menu -@findex detailmenu -If you use a detailed menu in your master menu (@pxref{Master Menu -Parts}), mark it with the @code{@@detailmenu @dots{} @@end -detailmenu} environment, or @command{makeinfo} will get confused, -typically about the last and/or first node in the document. - -In most cases, you will want to take advantage of this feature and not -redundantly specify node pointers that the programs can determine. -However, Texinfo documents are not required to be organized -hierarchically or in fact to contain sectioning commands at all (for -example, if you never intend the document to be printed), so node -pointers may still be specified explicitly, in full generality. - - -@node @t{@@anchor} -@section @code{@@anchor}: Defining Arbitrary Cross Reference Targets - -@anchor{anchor}@c old name -@findex anchor -@cindex Anchors -@cindex Cross reference targets, arbitrary -@cindex Targets for cross references, arbitrary - -An @dfn{anchor} is a position in your document, labeled so that cross -references can refer to it, just as they can to nodes. You create an -anchor with the @code{@@anchor} command, and give the label as a -normal brace-delimited argument. For example: - -@example -This marks the @@anchor@{x-spot@}spot. -@dots{} -@@xref@{x-spot,,the spot@}. -@end example - -@noindent produces: - -@example -This marks the spot. -@dots{} -See [the spot], page 1. -@end example - -As you can see, the @code{@@anchor} command itself produces no output. -This example defines an anchor `x-spot' just before the word `spot'. -You can refer to it later with an @code{@@xref} or other cross -reference command, as shown (@pxref{Cross References}). - -It is best to put @code{@@anchor} commands just before the position you -wish to refer to; that way, the reader's eye is led on to the correct -text when they jump to the anchor. You can put the @code{@@anchor} -command on a line by itself if that helps readability of the source. -Whitespace (including newlines) is ignored after @code{@@anchor}. - -Anchor names and node names may not conflict. Anchors and nodes are -given similar treatment in some ways; for example, the -@code{goto-node} command takes either an anchor name or a node name as -an argument. (@xref{Go to node,,, info, Info}.) - -Also like node names, anchor names cannot include some characters -(@pxref{Node Line Requirements}). - -@cindex Nodes, deleting or renaming -Because of this duality, when you delete or rename a node, it is -usually a good idea to define an @code{@@anchor} with the old name. -That way, any links to the old node, whether from other Texinfo -manuals or general web pages, keep working. You can also do this with -the @file{RENAMED_NODES_FILE} feature of @command{makeinfo} -(@pxref{HTML Xref Link Preservation}). Both methods keep links -on the web working; the only substantive difference is that defining -anchors also makes the old node names available when reading the -document in Info. - - -@node Node Menu Illustration -@section Node and Menu Illustration - -Here is a copy of the diagram shown earlier that illustrates a Texinfo -file with three chapters, each of which contains two sections. - -The ``root'' is at the top of the diagram and the ``leaves'' are at -the bottom. This is how such a diagram is drawn conventionally; it -illustrates an upside-down tree. For this reason, the root node is -called the `Top' node, and `Up' node pointers carry you closer to the -root. - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | -Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 -@end group -@end example - -Using explicit pointers (not recommended, but for shown for purposes -of the example), the fully-written command to start Chapter@tie{}2 -would be this: - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, Top -@@comment node-name, next, previous, up -@end group -@end example - -@noindent -This @code{@@node} line says that the name of this node is -``Chapter@tie{}2'', the name of the `Next' node is ``Chapter 3'', the -name of the `Previous' node is ``Chapter@tie{}1'', and the name of the -`Up' node is ``Top''. You can (and should) omit writing out these -node names if your document is hierarchically organized -(@pxref{@t{makeinfo} Pointer Creation}), but the pointer -relationships still obtain. - -@quotation Note -`Next' and `Previous' refer to nodes at the @emph{same hierarchical -level} in the manual, not necessarily to the next node within the -Texinfo file. In the Texinfo file, the subsequent node may be at a -lower level---a section-level node most often follows a chapter-level -node, for example. (The `Top' node contains the exception to this -rule. Since the `Top' node is the only node at that level, `Next' -refers to the first following node, which is almost always a chapter -or chapter-level node.) -@end quotation - -To go to Sections 2.1 and 2.2 using Info, you need a menu inside -Chapter 2. (@xref{Menus}.) You would write the menu just before the -beginning of Section 2.1, like this: - -@example -@group - @@menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: Description. - @@end menu -@end group -@end example - -Using explicit pointers, the node for Sect.@: 2.1 is written like this: - -@example -@group -@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 -@@comment node-name, next, previous, up -@end group -@end example - -In Info format, the `Next' and `Previous' pointers of a node usually -lead to other nodes at the same level---from chapter to chapter or -from section to section (sometimes, as shown, the `Previous' pointer -points up); an `Up' pointer usually leads to a node at the level above -(closer to the `Top' node); and a `Menu' leads to nodes at a level -below (closer to `leaves'). (A cross reference can point to a node at -any level; see @ref{Cross References}.) - -Usually, an @code{@@node} command and a chapter structuring command -are conventionally used together, in that order, often followed by -indexing commands. (As shown in the example above, you may follow the -@code{@@node} line with a comment line, e.g., to show which pointer is -which if explicit pointers are used.) The Texinfo processors use this -construct to determine the relationships between nodes and sectioning -commands. - -Here is the beginning of the chapter in this manual called ``Ending a -Texinfo File''. This shows an @code{@@node} line followed by an -@code{@@chapter} line, and then by indexing lines. The manual uses -implictly determined node pointers; therefore, nothing else is needed -on the @code{@@node} line. - -@example -@group -@@node Ending a File -@@chapter Ending a Texinfo File -@@cindex Ending a Texinfo file -@@cindex Texinfo file ending -@@cindex File ending -@end group -@end example - -An earlier version of the manual used explicit node pointers. Here is -the beginning of the same chapter for that case. This shows an -@code{@@node} line followed by a comment line, an @code{@@chapter} -line, and then by indexing lines. - -@example -@group -@@node Ending a File, Structuring, Beginning a File, Top -@@comment node-name, next, previous, up -@@chapter Ending a Texinfo File -@@cindex Ending a Texinfo file -@dots{} -@end group -@end example - - -@node Menus -@chapter Menus -@cindex Menus -@findex menu - -@dfn{Menus} contain pointers to subordinate nodes. In online output, -you use menus to go to such nodes. Menus have no effect in printed -manuals and do not appear in them. - -It's usually best if a node with a menu does not contain much text. -If you find yourself with a lot of text before a menu, we generally -recommend moving all but a couple of paragraphs into a new subnode. -Otherwise, it is easy for readers to miss the menu. - -@menu -* Menu Location:: Menus go at the ends of nodes. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. -@end menu - - -@node Menu Location -@section Menu Location -@cindex Menu location -@cindex Location of menus - -There may be at most one menu in a node. A menu is conventionally -located at the end of a node, without any regular text or additional -commands between the @code{@@end menu} and the beginning of the next -node. - -@cindex Info format, and menus -This convention is useful, since a reader who uses the menu could -easily miss any such text. Also, any such post-menu text will be -considered part of the menu in Info output (which has no marker for -the end of a menu). Thus, a line beginning with @samp{* } will likely -be incorrectly handled. - -@cindex Hierarchical documents, and menus -Technically, menus can carry you to any node, regardless of the -structure of the document; even to nodes in a different Info file. -However, we do not recommend making use of this, because it is hard -for readers to follow. Also, the @command{makeinfo} implicit pointer -creation feature (@pxref{@t{makeinfo} Pointer Creation}) and -XEmacs Texinfo mode updating commands work only to create menus of -subordinate nodes in a hierarchically structured document. It is much -better to use cross references to refer to arbitrary nodes. - -Years ago, we recommended using an @samp{@@heading} command within an -@code{@@ifinfo} conditional instead of the normal sectioning commands -after a very short node with a menu. This had the advantage of making -the printed output look better, because there was no very short text -between two headings on the page. But it does not work with -@command{makeinfo}'s implicit pointer creation, and it also makes the -XML output incorrect, since it does not reflect the true document -structure. So, we no longer recommend this. - - -@node Writing a Menu -@section Writing a Menu -@cindex Writing a menu -@cindex Menu writing - -A menu consists of an @code{@@menu} command on a line by itself -followed by menu entry lines or menu comment lines and then by an -@code{@@end menu} command on a line by itself. - -A menu looks like this: - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -@cindex Spaces, in menus -In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu -entry}. (Note the space after the asterisk.) A line that does not -start with an @w{@samp{* }} may also appear in a menu. Such a line is -not a menu entry but rather a @dfn{menu comment} line that appears in -the Info file. In the example above, the line @samp{Larger Units of -Text} is such a menu comment line; the two lines starting with -@w{@samp{* }} are menu entries. Space characters in a menu are -preserved as-is in the Info output; this allows you to format the menu -as you wish. - -@opindex accesskey@r{, in HTML output of menus} -In the HTML output from @command{makeinfo}, the @code{accesskey} -attribute is used with the values @samp{1}@dots{}@samp{9} for the -first nine entries. This allows people using web browsers to follow -the first menu entries using (typically) @kbd{M-@var{digit}}, e.g., -@kbd{M-1} for the first entry. - - -@node Menu Parts -@section The Parts of a Menu -@cindex Parts of a menu -@cindex Menu parts -@cindex @code{@@menu} parts - -A menu entry has three parts, only the second of which is required: - -@enumerate -@item -The menu entry name (optional). - -@item -The name of the node (required). - -@item -A description of the item (optional). -@end enumerate - -The template for a generic menu entry looks like this (but see the -next section for one more possibility): - -@example -* @var{menu-entry-name}: @var{node-name}. @var{description} -@end example - -Follow the menu entry name with a single colon and follow the node -name with tab, comma, newline, or the two characters period and space -(@samp{. }). - -@command{makeinfo} warns when the text of a menu item (and node names -and cross references) contains a problematic construct that will -interfere with its parsing in Info. If you don't want to see the -warnings, you can set the customization variable -@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other -Customization Variables}). - -In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) -command. The menu entry name is what the user types after the @kbd{m} -command. - -The third part of a menu entry is a descriptive phrase or sentence. -Menu entry names and node names are often short; the description -explains to the reader what the node is about. A useful description -complements the node name rather than repeats it. The description, -which is optional, can spread over multiple lines; if it does, some -authors prefer to indent the second line while others prefer to align -it with the first (and all others). It's up to you. An empty line, -or the next menu entry, ends a description. - - -@node Less Cluttered Menu Entry -@section Less Cluttered Menu Entry -@cindex Two part menu entry -@cindex Double-colon menu entries -@cindex Menu entries with two colons -@cindex Less cluttered menu entry -@cindex Uncluttered menu entry - -When the menu entry name and node name are the same, you can write -the name immediately after the asterisk and space at the beginning of -the line and follow the name with two colons. - -@need 800 -For example, write - -@example -* Name:: @var{description} -@end example - -@need 800 -@noindent -instead of - -@example -* Name: Name. @var{description} -@end example - -We recommend using the node name for the menu entry name whenever -possible, since it reduces visual clutter in the menu. - - -@node Menu Example -@section A Menu Example -@cindex Menu example -@cindex Example menu - -A menu looks like this in Texinfo: - -@example -@group -@@menu -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: - -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@end group -@end example - -@need 700 -Here is an example as you might see it in a Texinfo file: - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@end group -@end example - -In this example, the menu has two entries. @samp{Files} is both a menu -entry name and the name of the node referred to by that name. -@samp{Multiples} is the menu entry name; it refers to the node named -@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it -appears in the menu, but is not an entry. - -Since no file name is specified with either @samp{Files} or -@samp{Buffers}, they must be the names of nodes in the same Info file -(@pxref{Other Info Files, , Referring to Other Info Files}). - -@node Other Info Files -@section Referring to Other Info Files -@cindex Referring to other Info files -@cindex Nodes in other Info files -@cindex Other Info files' nodes -@cindex Going to other Info files' nodes -@cindex Info; other files' nodes - -You can create a menu entry that enables a reader in Info to go to a -node in another Info file by writing the file name in parentheses just -before the node name. Some examples: - -@example -@group -@@menu -* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} -* (@var{filename})@var{second-node}:: @var{description} -@@end menu -@end group -@end example - -For example, to refer directly to the @samp{Outlining} and -@samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you could write a -menu like this: - -@example -@group -@@menu -* Outlining: (xemacs)Outline Mode. The major mode for - editing outlines. -* (xemacs)Rebinding:: How to redefine the - meaning of a key. -@@end menu -@end group -@end example - -If you do not list the node name, but only name the file, then Info -presumes that you are referring to the `Top' node. Examples: - -@example -@group -* Info: (info). Documentation browsing system. -* (xemacs):: The extensible, self-documenting - text editor. -@end group -@end example - -The XEmacs Texinfo mode menu updating commands only work with nodes -within the current buffer, so you cannot use them to create menus that -refer to other files. You must write such menus by hand. - - -@node Cross References -@chapter Cross References -@cindex Making cross references -@cindex Cross references -@cindex References - -@dfn{Cross references} are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes and anchors are the -places to which cross references can refer. - -@menu -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* @t{@@xref}:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* @t{@@ref}:: A reference for the last part of a sentence. -* @t{@@pxref}:: How to write a parenthetical cross reference. -* @t{@@inforef}:: How to refer to an Info-only file. -* @t{@@url}:: How to refer to a uniform resource locator. -* @t{@@cite}:: How to refer to books not in the Info system. -@end menu - - -@node References -@section What References Are For - -Often, but not always, a printed document should be designed so that -it can be read sequentially. People tire of flipping back and forth -to find information that should be presented to them as they need -it. - -However, in any document, some information will be too detailed for -the current context, or incidental to it; use cross references to -provide access to such information. Also, an online help system or a -reference manual is not like a novel; few read such documents in -sequence from beginning to end. Instead, people look up what they -need. For this reason, such creations should contain many cross -references to help readers find other information that they may not -have read. - -In a printed manual, a cross reference results in a page reference, -unless it is to another manual altogether, in which case the cross -reference names that manual. - -In Info, a cross reference results in an entry that you can follow -using the Info @samp{f} command. (@xref{Help-Xref,, Following -cross-references, info, Info}.) - -In HTML, a cross reference results in an hyperlink. - -The various cross reference commands use nodes (or anchors, -@pxref{@t{@@anchor}}) to define cross reference locations. This is -evident in Info and HTML, in which a cross reference takes you to the -specified location. - -@TeX{} also needs nodes to define cross reference locations, but the -action is less obvious. When @TeX{} generates a DVI file, it records -each node's page number and uses the page numbers in making -references. Thus, even if you are writing a manual that will only be -printed, and not used online, you must nonetheless write @code{@@node} -lines in order to name the places to which you make cross references. - -@need 800 -@node Cross Reference Commands -@section Different Cross Reference Commands -@cindex Different cross reference commands - -There are four different cross reference commands: - -@table @code -@item @@xref -Used to start a sentence in the printed manual and in HTML with -@w{`See @dots{}'} or an Info cross reference saying @samp{*Note -@var{name}: @var{node}.}. - -@item @@ref -Used within or, more often, at the end of a sentence; produces just -the reference in the printed manual and in HTML without the preceding -`See' (same as @code{@@xref} for Info). - -@item @@pxref -Used within parentheses, at the end of a sentence, or otherwise before -punctuation, to make a reference. Its output starts with a lowercase -`see' in the printed manual and in HTML, and a lowercase @samp{*note} -in Info. (@samp{p} is for `parenthesis'.) - -@item @@inforef -Used to make a reference to an Info file for which there is no printed -manual. -@end table - -@noindent -The @code{@@cite} command is used to make references to books and -manuals for which there is no corresponding Info file and, therefore, -no node to which to point. @xref{@t{@@cite}}. - - -@node Cross Reference Parts -@section Parts of a Cross Reference -@cindex Cross reference parts -@cindex Parts of a cross reference - -A cross reference command to a node requires only one argument, which -is the name of the node to which it refers. But a cross reference -command may contain up to four additional arguments. By using these -arguments, you can provide a cross reference name, a topic description -or section title for the printed output, the name of a different -manual file, and the name of a different printed manual. To refer -to another manual as a whole, the manual file and/or the name of the -printed manual are the only required arguments (@pxref{Top Node -Naming}). - -Here is a simple cross reference example: - -@example -@@xref@{Node name@}. -@end example - -@noindent -which produces - -@example -*Note Node name::. -@end example - -@noindent -in Info and - -@quotation -See Section @var{nnn} [Node name], page @var{ppp}. -@end quotation - -@noindent -in a printed manual. - -@need 700 -Here is an example of a full five-part cross reference: - -@example -@group -@@xref@{Node name, Cross Reference Name, Particular Topic, -info-file-name, A Printed Manual@}, for details. -@end group -@end example - -@noindent -which produces - -@example -*Note Cross Reference Name: (info-file-name)Node name, -for details. -@end example - -@noindent -in Info and - -@quotation -See section ``Particular Topic'' in @i{A Printed Manual}, for details. -@end quotation - -@noindent -in a printed book. - -The five possible arguments for a cross reference are: - -@enumerate -@item -The node or anchor name (required, except for reference to whole -manuals). This is the location to which the cross reference takes -you. In a printed document, the location of the node provides the -page reference only for references within the same document. - -@item -The cross reference name. If you include this argument, it becomes -the first part of the cross reference. It is usually omitted; then -the topic description (third argument) is used if it was specified; -if that was omitted as well, the node name is used. - -@item -A topic description or section name. Often, this is the title of the -section. This is used as the name of the reference in the printed -manual. If omitted, the node name is used. - -@item -The name of the manual file in which the reference is located, if it is -different from the current file. This name is used both for Info and -HTML. - -@item -The name of a printed manual from a different Texinfo file. -@end enumerate - -The template for a full five argument cross reference looks like -this: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -Cross references with one, two, three, four, and five arguments are -described separately following the description of @code{@@xref}. - -Write a node name in a cross reference in exactly the same way as in -the @code{@@node} line, including the same capitalization; otherwise, the -formatters may not find the reference. - -@command{makeinfo} warns when the text of a cross reference (and node -names and menu items) contains a problematic construct that will -interfere with its parsing in Info. If you don't want to see the -warnings, you can set the customization variable -@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other -Customization Variables}). - - -@node @t{@@xref} -@section @code{@@xref} - -@anchor{xref}@c old name -@findex xref -@cindex Cross references using @code{@@xref} -@cindex References using @code{@@xref} - -The @code{@@xref} command generates a cross reference for the -beginning of a sentence. The Info formatting commands convert it into -an Info cross reference, which the Info @samp{f} command can use to -bring you directly to another node. The @TeX{} typesetting commands -convert it into a page reference, or a reference to another book or -manual. In the HTML output format the cross reference is output -as a hyperlink. - -@menu -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. -@end menu - -@node Reference Syntax -@subsection What a Reference Looks Like and Requires - -Most often, an Info cross reference looks like this: - -@example -*Note @var{node-name}::. -@end example - -@noindent -or like this - -@example -*Note @var{cross-reference-name}: @var{node-name}. -@end example - -@noindent -In @TeX{}, a cross reference looks like this: - -@quotation -See Section @var{section-number} [@var{node-name}], page @var{page}. -@end quotation - -@noindent -or like this - -@quotation -See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end quotation - -The @code{@@xref} command does not generate a period or comma to end -the cross reference automatically. You must write that period or -comma yourself; otherwise, Info will not recognize the end of the -reference. (The @code{@@pxref} command works differently; -@pxref{@t{@@pxref}}.) - -@quotation Caution -A period or comma @emph{must} follow the closing brace of an -@code{@@xref}. It is required to terminate the cross reference. This -period or comma will appear in the output. -@end quotation - -@code{@@xref} must refer to a node by name. Use @code{@@node} to -define the node (@pxref{Writing a Node}), or @code{@@anchor} -(@pxref{@t{@@anchor}}). - -@code{@@xref} is followed by several arguments inside braces, -separated by commas. Whitespace before and after these commas is -ignored. - -A cross reference to a node within the current file requires only the -name of a node; but it may contain up to four additional arguments. -Each of these variations produces a cross reference that looks -somewhat different. A cross reference to another manual as a whole -only requires the fourth or fifth argument. - -@quotation Note -Commas separate arguments in a cross reference, so you must not -include a comma in the title or any other part lest the formatters -mistake them for separators. @code{@@comma@{@}} may be used to -protect such commas (@pxref{Inserting a Comma}). -@end quotation - - -@node One Argument -@subsection @code{@@xref} with One Argument -@cindex One-argument form of cross references - -The simplest form of @code{@@xref} takes one argument, the name of -another node in the same Texinfo file. The Info formatters produce -output that the Info readers can use to jump to the reference; @TeX{} -produces output that specifies the page and section number for you; -the HTML output is a normal hyperlink. - -@need 700 -@noindent -For example, - -@example -@@xref@{Tropical Storms@}. -@end example - -@noindent -produces - -@example -*Note Tropical Storms::. -@end example - -@noindent -in Info and - -@quotation -See Section 3.1 [Tropical Storms], page 24. -@end quotation - -@noindent -in a printed manual. -(Note that in the preceding example the closing brace to -@code{@@xref}'s argument is followed by a period.) - -You can write a clause after the cross reference, like this: - -@example -@@xref@{Tropical Storms@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Tropical Storms::, for more info. -@end example - -@noindent -in Info and - -@quotation -See Section 3.1 [Tropical Storms], page 24, for more info. -@end quotation - - -@noindent -in a printed manual. Note that in the preceding example the closing -brace to @code{@@xref} is followed by a comma, then the additional -text. It's a common mistake to follow an @code{@@xref} command with a -space, but this is never correct. - - -@node Two Arguments -@subsection @code{@@xref} with Two Arguments -@cindex Two-argument form of cross references - -With two arguments, the second is used as the name of the cross -reference, while the first is still the name of the node to which the -cross reference points. - -@need 750 -@noindent -The template is like this: - -@example -@@xref@{@var{node-name}, @var{cross-reference-name}@}. -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning@}. -@end example - -@noindent -produces: - -@example -*Note Lightning: Electrical Effects. -@end example - -@noindent -in Info and - -@quotation -See Section 5.2 [Electrical Effects], page 57. -@end quotation - -@noindent -in a printed manual. -(Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.) - -You can write a clause after the cross reference, like this: - -@example -@@xref@{Electrical Effects, Lightning@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Lightning: Electrical Effects, for more info. -@end example - -@noindent -in Info and - -@quotation -See Section 5.2 [Electrical Effects], page 57, for more info. -@end quotation - -@noindent -in a printed manual. (Note that in the preceding example the closing -brace is followed by a comma, and then by the clause, which is -followed by a period.) - -The second argument to cross references must observe some of the -restrictions for node names (@pxref{Node Line Requirements}). The -most common issue is that colons cannot be used, since that interferes -with the parsing of the Info file. - - -@node Three Arguments -@subsection @code{@@xref} with Three Arguments -@cindex Three-argument form of cross references - -A third argument replaces the node name in the @TeX{} output. The third -argument should be the name of the section in the printed output, or -else state the topic discussed by that section. Often, you will want to -use initial uppercase letters so it will be easier to read when the -reference is printed. Use a third argument when the node name is -unsuitable because of syntax or meaning. - -Remember to write a comma or period after the closing brace of an -@code{@@xref} to terminate the cross reference. In the following -examples, a clause follows a terminating comma. - -@need 750 -@noindent -The template is like this: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Lightning: Electrical Effects, for details. -@end example - -@noindent -in Info and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -@noindent -in a printed manual. - -If a third argument is given and the second one is empty, then the -third argument serves for both. (Note how two commas, side by side, mark -the empty second argument.) - -@example -@group -@@xref@{Electrical Effects, , Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Thunder and Lightning: Electrical Effects, for details. -@end example - -@noindent -in Info and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -@noindent -in a printed manual. - -The third argument to cross references must observe some of the -restrictions for node names (@pxref{Node Line Requirements}). The -most common issue is that colons cannot be used, since that interferes -with the parsing of the Info file. - -As a practical matter, it is often best to write cross references with -just the first argument if the node name and the section title are the -same (or nearly so), and with the first and third arguments only if the -node name and title are different. - -@findex xrefautomaticsectiontitle -Texinfo offers a setting to use the section title instead of node -names by default in cross references (an explicitly specified third -argument still takes precedence): - -@example -@@xrefautomaticsectiontitle on -@end example - -Typically this line would be given near the beginning of the document -and used for the whole manual. But you can turn it off if you want -(@code{@@xrefautomaticsectiontitle off}), for example, if you're -including some other sub-document that doesn't have suitable section -names. - - -@node Four and Five Arguments -@subsection @code{@@xref} with Four and Five Arguments -@cindex Four- and five argument forms of cross references - -In a cross reference, a fourth argument specifies the name of another -Info file, different from the file in which the reference appears, and -a fifth argument specifies its title as a printed manual. - -Remember that a comma or period must follow the closing brace of an -@code{@@xref} command to terminate the cross reference. - -@need 800 -@noindent -The full template is: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning, Thunder and Lightning, -weather, An Introduction to Meteorology@}. -@end example - -@noindent -produces this output in Info: - -@example -*Note Lightning: (weather)Electrical Effects. -@end example - -@noindent -As you can see, the name of the Info file is enclosed in parentheses -and precedes the name of the node. - -@noindent -In a printed manual, the reference looks like this: - -@quotation -See section ``Thunder and Lightning'' in @cite{An Introduction to -Meteorology}. -@end quotation - -@noindent -The title of the printed manual is typeset like @code{@@cite}; and the -reference lacks a page number since @TeX{} cannot know to which page a -reference refers when that reference is to another manual. - -Next case: often, you will leave out the second argument when you use -the long version of @code{@@xref}. In this case, the third argument, -the topic description, will be used as the cross reference name in -Info. For example, - -@example -@@xref@{Electrical Effects, , Thunder and Lightning, -weather, An Introduction to Meteorology@}. -@end example - -@noindent -produces - -@example -@group -*Note Thunder and Lightning: (weather)Electrical Effects. -@end group -@end example - -@noindent -in Info and - -@quotation -See section ``Thunder and Lightning'' in @cite{An Introduction to -Meteorology}. -@end quotation - -@noindent -in a printed manual. - -Next case: If the node name and the section title are the same in the -other manual, you may also leave out the section title. In this case, -the node name is used in both instances. For example, - -@example -@@xref@{Electrical Effects,,, -weather, An Introduction to Meteorology@}. -@end example - -@noindent -produces - -@example -@group -*Note (weather)Electrical Effects::. -@end group -@end example - -@noindent -in Info and - -@quotation -See section ``Electrical Effects'' in @cite{An Introduction to -Meteorology}. -@end quotation - -@noindent -in a printed manual. - -A very unusual case: you may want to refer to another manual file that -is within a single printed manual---when multiple Texinfo files are -incorporated into the same @TeX{} run but can create separate Info or -HTML output files. In this case, you need to specify only the fourth -argument, and not the fifth. - -Finally, it's also allowed to leave out all the arguments -@emph{except} the fourth and fifth, to refer to another manual as a -whole. See the next section. - - -@node Top Node Naming -@section Naming a `Top' Node -@cindex Naming a `Top' Node in references -@cindex `Top' node naming for references - -@cindex Manual, referring to as a whole -@cindex Referring to an entire manual - -Ordinarily, you must always name a node in a cross reference. -However, it's not unusual to want to refer to another manual as a -whole, rather than a particular section within it. In this case, -giving any section name is an unnecessary distraction. - -So, with cross references to other manuals (@pxref{Four and Five -Arguments}), if the first argument is either @samp{Top} (capitalized -just that way) or omitted entirely, and the third argument is omitted, -the printed output includes no node or section name. (The Info output -includes @samp{Top} if it was given.) For example, - -@example -@@xref@{Top,,, make, The GNU Make Manual@}. -@end example - -@noindent produces - -@example -@group -*Note (make)::Top. -@end group -@end example - -@noindent and - -@quotation -See @cite{The GNU Make Manual}. -@end quotation - -@noindent -Info readers will go to the Top node of the manual whether -or not the `Top' node is explicitly specified. - -It's also possible (and is historical practice) to refer to a whole -manual by specifying the `Top' node and an appropriate entry for the -third argument to the @code{@@xref} command. Using this idiom, to -make a cross reference to @cite{The GNU Make Manual}, you would write: - -@example -@@xref@{Top,, Overview, make, The GNU Make Manual@}. -@end example - -@noindent -which produces - -@example -*Note Overview: (make)Top. -@end example - -@noindent -in Info and - -@quotation -See section ``Overview'' in @cite{The GNU Make Manual}. -@end quotation - -@noindent -in a printed manual. - -In this example, @samp{Top} is the name of the first node, and -@samp{Overview} is the name of the first section of the manual. There -is no widely-used convention for naming the first section in a printed -manual, this is just what the Make manual happens to use. This -arbitrariness of the first name is a principal reason why omitting the -third argument in whole-manual cross references is preferable. - - -@node @t{@@ref} -@section @code{@@ref} - -@anchor{ref}@c old name -@findex ref -@cindex Cross references using @code{@@ref} -@cindex References using @code{@@ref} - -@code{@@ref} is nearly the same as @code{@@xref} except that it does -not generate a `See' in the printed output, just the reference itself. -This makes it useful as the last part of a sentence. - -@noindent For example, - -@cindex Hurricanes -@example -For more information, @@pxref@{This@}, and @@ref@{That@}. -@end example - -@noindent -produces in Info: - -@example -For more information, *note This::, and *note That::. -@end example - -@noindent -and in printed output: - -@quotation -For more information, see Section 1.1 [This], page 1, -and Section 1.2 [That], page 2. -@end quotation - -The @code{@@ref} command can tempt writers to express themselves in a -manner that is suitable for a printed manual but looks awkward in the -Info format. Bear in mind that your audience could be using both the -printed and the Info format. For example: - -@cindex Sea surges -@example -Sea surges are described in @@ref@{Hurricanes@}. -@end example - -@noindent -looks ok in the printed output: - -@quotation -Sea surges are described in Section 6.7 [Hurricanes], page 72. -@end quotation - -@noindent -but is awkward to read in Info, ``note'' being a verb: - -@example -Sea surges are described in *note Hurricanes::. -@end example - -You should write a period or comma immediately after an @code{@@ref} -command with two or more arguments. If there is no such following -punctuation, @command{makeinfo} will generate a (grammatically -incorrect) period in the Info output; otherwise, the cross reference -would fail completely, due to the current syntax of Info format. - -In general, it is best to use @code{@@ref} only when you need some -word other than ``see'' to precede the reference. When ``see'' (or -``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable. - - -@node @t{@@pxref} -@section @code{@@pxref} - -@anchor{pxref}@c old name -@findex pxref -@cindex Cross references using @code{@@pxref} -@cindex References using @code{@@pxref} - -The parenthetical reference command, @code{@@pxref}, is nearly the -same as @code{@@xref}, but it is best used at the end of a sentence or -before a closing parenthesis. The command differs from @code{@@xref} -in two ways: - -@enumerate -@item -@TeX{} typesets the reference for the printed manual with a lowercase -`see' rather than an uppercase `See'. - -@item -The Info formatting commands automatically end the reference with a -closing colon or period, if necessary. -@end enumerate - -@code{@@pxref} is designed so that the output looks right and works -right at the end of a sentence or parenthetical phrase, both in -printed output and in an Info file. In a printed manual, a closing -comma or period should not follow a cross reference within -parentheses; such punctuation is wrong. But in an Info file, suitable -closing punctuation must follow the cross reference so Info can -recognize its end. @code{@@pxref} spares you the need to use -complicated methods to put a terminator into one form of the output -and not the other. - -@noindent -With one argument, a parenthetical cross reference looks like this: - -@cindex Flooding -@example -@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} -@end example - -@need 800 -@noindent -which produces - -@example -@group -@dots{} storms cause flooding (*note Hurricanes::) @dots{} -@end group -@end example - -@noindent -in Info and - -@quotation -@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} -@end quotation - -@noindent -in a printed manual. - -With two arguments, a parenthetical cross reference has this template: - -@example -@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} -@end example - -@noindent -which produces - -@example -@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{} -@end example - -@noindent -in Info and - -@quotation -@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} -@end quotation - -@noindent -in a printed manual. - -@code{@@pxref} can be used with up to five arguments, just like -@code{@@xref} (@pxref{@t{@@xref}}). - -In past versions of Texinfo, it was not allowed to write punctuation -after an @code{@@pxref}, so it could be used @emph{only} before a -right parenthesis. This is no longer the case, so now it can be used -(for example) at the end of a sentence, where a lowercase ``see'' -works best. For instance: - -@example -@dots{} For more information, @@pxref@{More@}. -@end example - -@noindent -which outputs (in Info): - -@example -@dots{} For more information, *note More::. -@end example - -@noindent -In general, @code{@@pxref} should only be followed by a comma, period, -or right parenthesis; in other cases, @command{makeinfo} has to insert -a period to make the cross reference work correctly in Info, and that -period looks wrong. - -As a matter of style, @code{@@pxref} is best used at the ends of -sentences. Although it technically works in the middle of a sentence, -that location breaks up the flow of reading. - - -@node @t{@@inforef} -@section @code{@@inforef}: Cross References to Info-only Material - -@anchor{inforef}@c old name -@findex inforef -@cindex Cross references using @code{@@inforef} -@cindex References using @code{@@inforef} - -@code{@@inforef} is used for making cross references to Info -documents---even from a printed manual. This might be because you -want to refer to conditional @code{@@ifinfo} text -(@pxref{Conditionals}), or because printed output is not available -(perhaps because there is no Texinfo source), among other -possibilities. - -The command takes either two or three arguments, in the following -order: - -@enumerate -@item -The node name. - -@item -The cross reference name (optional). - -@item -The Info file name. -@end enumerate - -@noindent -Separate the arguments with commas, as with @code{@@xref}. Also, you -must terminate the reference with a comma or period after the -@samp{@}}, as you do with @code{@@xref}. - -@noindent -The template is: - -@example -@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, -@end example - -@need 800 -@noindent -For example, - -@example -@group -@@inforef@{Advanced, Advanced Info commands, info@}, -for more information. -@end group -@end example - -@need 800 -@noindent -produces (in Info): - -@example -@group -*Note Advanced Info commands: (info)Advanced, -for more information. -@end group -@end example - -@need 800 -@noindent -and (in the printed output): - -@quotation -See Info file @file{info}, node @samp{Advanced}, for more information. -@end quotation - -(This particular example is not realistic, since the Info manual is -written in Texinfo, so all formats are available. In fact, we don't -know of any extant Info-only manuals.) - -The converse of @code{@@inforef} is @code{@@cite}, which is used to -refer to printed works for which no Info form exists. -@xref{@t{@@cite}}. - - -@node @t{@@url} -@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} - -@anchor{uref}@c old name -@findex uref -@cindex Uniform resource locator, referring to -@cindex URL, referring to - -@cindex @code{href}, producing HTML -@code{@@uref} produces a reference to a uniform resource locator (url). -It takes one mandatory argument, the url, and two optional arguments -which control the text that is displayed. In HTML output, @code{@@uref} -produces a link you can follow. - -@anchor{url} @code{@@url} is a synonym for @code{@@uref}. -(Originally, @code{@@url} had the meaning of @code{@@indicateurl} -(@pxref{@t{@@indicateurl}}), but in practice it was almost always -misused. So we've changed the meaning.) - -The second argument, if specified, is the text to display (the default -is the url itself); in Info and DVI output, but not in HTML output, the -url is output in addition to this text. - -@cindex Man page, reference to -The third argument, if specified, is the text to display, but in this -case the url is not output in any format. This is useful when the -text is already sufficiently referential, as in a man page. If the -third argument is given, the second argument is ignored. - -@cindex Line breaking, and urls -@cindex Breakpoints within urls -@TeX{} allows line breaking within urls at only a few characters -(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?}, -and @samp{/} (but not between @samp{/} characters). A tiny amount of -stretchable space is also inserted around these characters to help -with line breaking. For HTML output, modern browsers will also do -line breaking within displayed urls. If you need to allow breaks at -other characters you can insert @code{@@/} as needed (@pxref{Line -Breaks}). - -@findex urefbreakstyle -By default, any such breaks at special characters will occur after the -character. Some people prefer such breaks to happen after the special -character. This can be controlled with the @code{@@urefbreakstyle} -command (this command has effect only in @TeX{}): - -Write this command at the -beginning of a line with a single word as an argument, one of the -following: - -@vindex after@r{, value for @code{@@urefbreakstyle}} -@vindex before@r{, value for @code{@@urefbreakstyle}} -@vindex none@r{, value for @code{@@urefbreakstyle}} -@table @samp -@item after -(the default) Potentially break after the special characters. -@item before -Potentially break before the special characters. -@item none -Do not consider breaking at the special characters; any potential -breaks must be manually inserted. -@end table - -Here is an example of the simple one argument form, where the url is -both the target and the text of the link: - -@example -The official GNU ftp site is @@uref@{http://ftp.gnu.org/gnu@}. -@end example - -@noindent produces: -@display -The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}. -@end display - - -An example of the two-argument form: -@example -The official @@uref@{http://ftp.gnu.org/gnu, GNU ftp site@} -holds programs and texts. -@end example - -@noindent produces: -@display -The official @uref{http://ftp.gnu.org/gnu, GNU ftp site} -holds programs and texts. -@end display - -@noindent that is, the Info output is this: -@example -The official GNU ftp site (http://ftp.gnu.org/gnu) -holds programs and texts. -@end example - -@noindent and the HTML output is this: -@example -The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a> -holds programs and texts. -@end example - - -An example of the three-argument form: -@example -The @@uref@{/man.cgi/1/ls,,ls@} program @dots{} -@end example - -@noindent produces: -@display -The @uref{/man.cgi/1/ls,,ls} program @dots{} -@end display - -@noindent but with HTML: -@example -The <a href="/man.cgi/1/ls">ls</a> program @dots{} -@end example - -Some people prefer to display urls in the unambiguous format: - -@display -<URL:http://@var{host}/@var{path}> -@end display - -@noindent -@cindex @code{<URL...>} convention, not used -You can use this form in the input file if you wish. We feel it's not -necessary to include the @samp{<URL:} and @samp{>} in the output, -since any software that tries to detect urls in text already has to -detect them without the @samp{<URL:} to be useful. - -To merely indicate a url without creating a link people can follow, -use @code{@@indicateurl} (@pxref{@t{@@indicateurl}}). - - -@node @t{@@cite} -@section @code{@@cite}@{@var{reference}@} - -@anchor{cite}@c old name -@findex cite - -Use the @code{@@cite} command for the name of a book that lacks a -companion Info file. The command produces italics in the printed -manual, and quotation marks in the Info file. - -If a book is written in Texinfo, it is better to use a cross reference -command since a reader can easily follow such a reference in Info. -@xref{@t{@@xref}}. - - -@node Marking Text -@chapter Marking Text, Words and Phrases -@cindex Paragraph, marking text within -@cindex Marking words and phrases -@cindex Words and phrases, marking them -@cindex Marking text within a paragraph -@cindex Text, marking up - -In Texinfo, you can mark words and phrases in a variety of ways. -The Texinfo formatters use this information to determine how to -highlight the text. -You can specify, for example, whether a word or phrase is a -defining occurrence, a metasyntactic variable, or a symbol used in a -program. Also, you can emphasize text, in several different ways. - -@menu -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. -@end menu - - -@node Indicating -@section Indicating Definitions, Commands, etc. - -@cindex Highlighting text -@cindex Indicating commands, definitions, etc. - -Texinfo has commands for indicating just what kind of object a piece -of text refers to. For example, email addresses are marked by -@code{@@email}; that way, the result can be a live link to send email -when the output format supports it. If the email address was simply -marked as ``print in a typewriter font'', that would not be possible. - -@menu -* Useful Highlighting:: Highlighting provides useful information. -* @t{@@code}:: Indicating program code. -* @t{@@kbd}:: Showing keyboard input. -* @t{@@key}:: Specifying keys. -* @t{@@samp}:: Indicating a literal sequence of characters. -* @t{@@verb}:: Indicating a verbatim sequence of characters. -* @t{@@var}:: Indicating metasyntactic variables. -* @t{@@env}:: Indicating environment variables. -* @t{@@file}:: Indicating file names. -* @t{@@command}:: Indicating command names. -* @t{@@option}:: Indicating option names. -* @t{@@dfn}:: Specifying definitions. -* @t{@@abbr}:: Indicating abbreviations. -* @t{@@acronym}:: Indicating acronyms. -* @t{@@indicateurl}:: Indicating an example url. -* @t{@@email}:: Indicating an electronic mail address. -@end menu - - -@node Useful Highlighting -@subsection Highlighting Commands are Useful - -The commands serve a variety of purposes: - -@table @code -@item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program. -@xref{@t{@@code}}. - -@item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input. @xref{@t{@@kbd}}. - -@item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard. -@xref{@t{@@key}}. - -@item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters. -@xref{@t{@@samp}}. - -@item @@verb@{@var{text}@} -Write a verbatim sequence of characters. -@xref{@t{@@verb}}. - -@item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable. @xref{@t{@@var}}. - -@item @@env@{@var{environment-variable}@} -Indicate an environment variable. @xref{@t{@@env}}. - -@item @@file@{@var{file-name}@} -Indicate the name of a file. @xref{@t{@@file}}. - -@item @@command@{@var{command-name}@} -Indicate the name of a command. -@xref{@t{@@command}}. - -@item @@option@{@var{option}@} -Indicate a command-line option. -@xref{@t{@@option}}. - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term. -@xref{@t{@@dfn}}. - -@item @@cite@{@var{reference}@} -Indicate the name of a book. @xref{@t{@@cite}}. - -@item @@abbr@{@var{abbreviation}@} -Indicate an abbreviation, such as `Comput.'. - -@item @@acronym@{@var{acronym}@} -Indicate an acronym. @xref{@t{@@acronym}}. - -@item @@indicateurl@{@var{uniform-resource-locator}@} -Indicate an example (that is, nonfunctional) uniform resource locator. -@xref{@t{@@indicateurl}}. (Use @code{@@url} (@pxref{@t{@@url}}) for -live urls.) - -@item @@email@{@var{email-address}[, @var{displayed-text}]@} -Indicate an electronic mail address. @xref{@t{@@email}}. - -@end table - - -@node @t{@@code} -@subsection @code{@@code}@{@var{sample-code}@} - -@anchor{code}@c old name -@findex code - -@cindex Syntactic tokens, indicating -Use the @code{@@code} command to indicate text that is a piece of a -program and which consists of entire syntactic tokens. Enclose the -text in braces. - -@cindex Expressions in a program, indicating -@cindex Keywords, indicating -@cindex Reserved words, indicating -Thus, you should use @code{@@code} for an expression in a program, for -the name of a variable or function used in a program, or for a -keyword in a programming language. - -Use @code{@@code} for command names in languages that resemble -programming languages, such as Texinfo. For example, @code{@@code} and -@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and -@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively. - -@cindex Case, not altering in @code{@@code} -It is incorrect to alter the case of a word inside an @code{@@code} -command when it appears at the beginning of a sentence. Most computer -languages are case sensitive. In C, for example, @code{Printf} is -different from the identifier @code{printf}, and most likely is a -misspelling of it. Even in languages which are not case sensitive, it -is confusing to a human reader to see identifiers spelled in different -ways. Pick one spelling and always use that. If you do not want to -start a sentence with a command name written all in lowercase, you -should rearrange the sentence. - -In the Info output, @code{@@code} results in single quotation marks -around the text. In other formats, @code{@@code} argument is typeset -in a typewriter (monospace) font. For example, - -@example -The function returns @@code@{nil@}. -@end example - -@noindent -produces this: - -@quotation -The function returns @code{nil}. -@end quotation - -Here are some cases for which it is preferable @emph{not} to use @code{@@code}: - -@itemize @bullet -@item -For shell command names such as @command{ls} (use @code{@@command}). - -@item -For environment variable such as @env{TEXINPUTS} (use @code{@@env}). - -@item -For shell options such as @samp{-c} when such options stand alone (use -@code{@@option}). - -@item -An entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format. - -@item -For a string of characters shorter than a syntactic token. For example, -if you are writing about @samp{goto-ch}, which is just a part of the -name for the @code{goto-char} Emacs Lisp function, you should use -@code{@@samp}. - -@item -In general, when writing about the characters used in a token; for -example, do not use @code{@@code} when you are explaining what letters -or printable symbols can be used in the names of functions. (Use -@code{@@samp}.) Also, you should not use @code{@@code} to mark text -that is considered input to programs unless the input is written in a -language that is like a programming language. For example, you should -not use @code{@@code} for the keystroke commands of XEmacs (use -@code{@@kbd} instead) although you may use @code{@@code} for the names -of the Emacs Lisp functions that the keystroke commands invoke. - -@end itemize - -By default, @TeX{} will consider breaking lines at @samp{-} and -@samp{_} characters within @code{@@code} and related commands. This -can be controlled with @code{@@allowcodebreaks} -(@pxref{@t{@@allowcodebreaks}}). The HTML output attempts to -respect this for @samp{-}, but ultimately it is up to the browser's -behavior. For Info, it seems better never to make such breaks. - -For Info, the quotes are omitted in the output of the @code{@@code} -command and related commands (e.g., @code{@@kbd}, @code{@@command}), -in typewriter-like contexts such as the @code{@@example} environment -(@pxref{@t{@@example}}) and @code{@@code} itself, etc. - -To control which quoting characters are implicitly inserted by Texinfo -processors in the output of @samp{@@code}, etc., see the -@code{OPEN_QUOTE_SYMBOL} and @code{CLOSE_QUOTE_SYMBOL} customization -variables (@pxref{Other Customization Variables}). This is separate -from how actual quotation characters in the input document are handled -(@pxref{Inserting Quote Characters}). - - -@node @t{@@kbd} -@subsection @code{@@kbd}@{@var{keyboard-characters}@} - -@anchor{kbd}@c old name -@findex kbd -@cindex Keyboard input - -Use the @code{@@kbd} command for characters of input to be typed by -users. For example, to refer to the characters @kbd{M-a}, write: - -@example -@@kbd@{M-a@} -@end example - -@noindent -and to refer to the characters @kbd{M-x shell}, write: - -@example -@@kbd@{M-x shell@} -@end example - -@cindex User input -@cindex Slanted typewriter font, for @code{@@kbd} -By default, the @code{@@kbd} command produces a different font -(slanted typewriter instead of normal typewriter), -so users can distinguish the characters that they are supposed -to type from those that the computer outputs. - -@findex kbdinputstyle -Since the usage of @code{@@kbd} varies from manual to manual, you can -control the font switching with the @code{@@kbdinputstyle} command. -This command has no effect on Info output. Write this command at the -beginning of a line with a single word as an argument, one of the -following: - -@vindex distinct@r{, value for @code{@@kbdinputstyle}} -@vindex example@r{, value for @code{@@kbdinputstyle}} -@vindex code@r{, value for @code{@@kbdinputstyle}} -@table @samp -@item code -Always use the same font for @code{@@kbd} as @code{@@code}. -@item example -Use the distinguishing font for @code{@@kbd} only in @code{@@example} -and similar environments. -@item distinct -(the default) Always use the distinguishing font for @code{@@kbd}. -@end table - -You can embed another @@-command inside the braces of an @code{@@kbd} -command. Here, for example, is the way to describe a command that -would be described more verbosely as ``press the @samp{r} key and then -press the @key{RETURN} key'': - -@example -@@kbd@{r @@key@{RET@}@} -@end example - -@noindent -This produces: @kbd{r @key{RET}}. (The present manual uses the -default for @code{@@kbdinputstyle}.) - -You also use the @code{@@kbd} command if you are spelling out the letters -you type; for example: - -@example -To give the @@code@{logout@} command, -type the characters @@kbd@{l o g o u t @@key@{RET@}@}. -@end example - -@noindent -This produces: - -@quotation -To give the @code{logout} command, -type the characters @kbd{l o g o u t @key{RET}}. -@end quotation - -(Also, this example shows that you can add spaces for clarity. If you -explicitly want to mention a space character as one of the characters of -input, write @kbd{@@key@{SPC@}} for it.) - - -@node @t{@@key} -@subsection @code{@@key}@{@var{key-name}@} - -@anchor{key}@c old name -@findex key - -Use the @code{@@key} command for the conventional name for a key on a -keyboard, as in: - -@example -@@key@{RET@} -@end example - -You can use the @code{@@key} command within the argument of an -@code{@@kbd} command when the sequence of characters to be typed -includes one or more keys that are described by name. - -For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you -would type: - -@example -@@kbd@{C-x @@key@{ESC@}@} -@@kbd@{M-@@key@{TAB@}@} -@end example - -Here is a list of the recommended names for keys: -@cindex Recommended names for keys -@cindex Keys, recommended names -@cindex Names recommended for keys -@cindex Abbreviations for keys -@cindex Control keys, specifying -@cindex Meta keys, specifying - -@quotation -@table @t -@item SPC -Space -@item RET -Return -@item LFD -Linefeed (however, since most keyboards nowadays do not have a Linefeed key, -it might be better to call this character @kbd{C-j}) -@item TAB -Tab -@item BS -Backspace -@item ESC -Escape -@item DELETE -Delete -@item SHIFT -Shift -@item CTRL -Control -@item META -Meta -@end table -@end quotation - -@cindex META key -There are subtleties to handling words like `meta' or `ctrl' that are -names of modifier keys. When mentioning a character in which the -modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command -alone; do not use the @code{@@key} command; but when you are referring -to the modifier key in isolation, use the @code{@@key} command. For -example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and -@samp{@@key@{META@}} to produce @key{META}. - -As a convention in GNU manuals, @code{@@key} should not be used in -index entries. - - -@node @t{@@samp} -@subsection @code{@@samp}@{@var{text}@} - -@anchor{samp}@c old name -@findex samp - -Use the @code{@@samp} command to indicate text that is a literal example -or `sample' of a sequence of characters in a file, string, pattern, etc. -Enclose the text in braces. The argument appears within single -quotation marks in both the Info file and the printed manual; in -addition, it is printed in a fixed-width font. - -@example -To match @@samp@{foo@} at the end of the line, -use the regexp @@samp@{foo$@}. -@end example - -@noindent -produces - -@quotation -To match @samp{foo} at the end of the line, use the regexp -@samp{foo$}. -@end quotation - -Any time you are referring to single characters, you should use -@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. -Also, you may use @code{@@samp} for entire statements in C and for entire -shell commands---in this case, @code{@@samp} often looks better than -@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is -not covered by @code{@@code}, @code{@@kbd}, @code{@@key}, -@code{@@command}, etc. - -Only include punctuation marks within braces if they are part of the -string you are specifying. Write punctuation marks outside the braces -if those punctuation marks are part of the English text that surrounds -the string. In the following sentence, for example, the commas and -period are outside of the braces: - -@example -@group -In English, the vowels are @@samp@{a@}, @@samp@{e@}, -@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes -@@samp@{y@}. -@end group -@end example - -@noindent -This produces: - -@quotation -In English, the vowels are @samp{a}, @samp{e}, -@samp{i}, @samp{o}, @samp{u}, and sometimes -@samp{y}. -@end quotation - - -@node @t{@@verb} -@subsection @code{@@verb}@{@var{char}@var{text}@var{char}@} - -@anchor{verb}@c old name -@findex verb -@cindex Verbatim in-line text - -@cindex Delimiter character, for verbatim -Use the @code{@@verb} command to print a verbatim sequence of -characters. - -Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using -any unique delimiter character. Enclose the verbatim text, including the -delimiters, in braces. Text is printed in a fixed-width font: - -@example -How many @@verb@{|@@|@}-escapes does one need to print this -@@verb@{.@@a @@b.@@c.@} string or @@verb@{+@@'e?`@{@}!`\+@} this? -@end example - -@noindent -produces - -@example -How many @verb{|@|}-escapes does one need to print this -@verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this? -@end example - -This is in contrast to @code{@@samp} (see the previous section), -@code{@@code}, and similar commands; in those cases, the argument is -normal Texinfo text, where the three characters @code{@@@{@}} are -special, as usual. With @code{@@verb}, nothing is special except the -delimiter character you choose. - -The delimiter character itself may appear inside the verbatim text, as -shown above. As another example, @samp{@@verb@{...@}} prints a single -(fixed-width) period. - -It is not reliable to use @code{@@verb} inside other Texinfo -constructs. In particular, it does not work to use @code{@@verb} in -anything related to cross referencing, such as section titles or -figure captions. - - -@node @t{@@var} -@subsection @code{@@var}@{@var{metasyntactic-variable}@} - -@anchor{var}@c old name -@findex var - -Use the @code{@@var} command to indicate metasyntactic variables. A -@dfn{metasyntactic variable} is something that stands for another -piece of text. For example, you should use a metasyntactic variable -in the documentation of a function to describe the arguments that are -passed to that function. - -Do not use @code{@@var} for the names of normal variables in computer -programs. These are specific names, so @code{@@code} is correct for -them (@t{@@code}). For example, the Emacs Lisp variable -@code{texinfo-tex-command} is not a metasyntactic variable; it is -properly formatted using @code{@@code}. - -Do not use @code{@@var} for environment variables either; @code{@@env} -is correct for them (see the next section). - -The effect of @code{@@var} in the Info file is to change the case of -the argument to all uppercase. In the printed manual and HTML -output, the argument is output in slanted type. - -@need 700 -For example, - -@example -To delete file @@var@{filename@}, -type @@samp@{rm @@var@{filename@}@}. -@end example - -@noindent -produces - -@quotation -To delete file @var{filename}, type @samp{rm @var{filename}}. -@end quotation - -@noindent -(Note that @code{@@var} may appear inside @code{@@code}, -@code{@@samp}, @code{@@file}, etc.) - -Write a metasyntactic variable all in lowercase without spaces, and -use hyphens to make it more readable. Thus, the Texinfo source for -the illustration of how to begin a Texinfo manual looks like -this: - -@example -@group -\input texinfo -@@@@setfilename @@var@{info-file-name@} -@@@@settitle @@var@{name-of-manual@} -@end group -@end example - -@noindent -This produces: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -In some documentation styles, metasyntactic variables are shown with -angle brackets, for example: - -@example -@dots{}, type rm <filename> -@end example - -@noindent -However, that is not the style that Texinfo uses. - -@c FIXME add a customization variable? Add an example on how to do that -@c for HTML? -@c (You can, of course, modify the sources to @file{texinfo.tex} -@c and the Info formatting commands -@c to output the @code{<@dots{}>} format if you wish.) - - -@node @t{@@env} -@subsection @code{@@env}@{@var{environment-variable}@} - -@anchor{env}@c old name -@findex env - -Use the @code{@@env} command to indicate environment variables, as -used by many operating systems, including GNU@. Do not use it for -@emph{meta}syntactic variables; use @code{@@var} for those (see the -previous section). - -@code{@@env} is equivalent to @code{@@code} in its effects. -For example: - -@example -The @@env@{PATH@} environment variable @dots{} -@end example -@noindent produces -@quotation -The @env{PATH} environment variable @dots{} -@end quotation - - -@node @t{@@file} -@subsection @code{@@file}@{@var{file-name}@} - -@anchor{file}@c old name -@findex file - -Use the @code{@@file} command to indicate text that is the name of a -file, buffer, or directory, or is the name of a node in Info. You can -also use the command for file name suffixes. Do not use @code{@@file} -for symbols in a programming language; use @code{@@code}. - -@code{@@file} is equivalent to @code{code} in its effects. For -example, - -@example -The @@file@{.el@} files are in -the @@file@{/usr/local/xemacs/lisp@} directory. -@end example - -@noindent -produces - -@quotation -The @file{.el} files are in -the @file{/usr/local/xemacs/lisp} directory. -@end quotation - - -@node @t{@@command} -@subsection @code{@@command}@{@var{command-name}@} - -@anchor{command}@c old name -@findex command -@cindex Command names, indicating -@cindex Program names, indicating - -Use the @code{@@command} command to indicate command names, such as -@command{ls} or @command{cc}. - -@code{@@command} is equivalent to @code{@@code} in its effects. -For example: - -@example -The command @@command@{ls@} lists directory contents. -@end example -@noindent produces -@quotation -The command @command{ls} lists directory contents. -@end quotation - -You should write the name of a program in the ordinary text font, rather -than using @code{@@command}, if you regard it as a new English word, -such as `Emacs' or `Bison'. - -When writing an entire shell command invocation, as in @samp{ls -l}, -you should use either @code{@@samp} or @code{@@code} at your discretion. - - -@node @t{@@option} -@subsection @code{@@option}@{@var{option-name}@} - -@anchor{option}@c old name -@findex option - -Use the @code{@@option} command to indicate a command-line option; for -example, @option{-l} or @option{--version} or -@option{--output=@var{filename}}. - -@code{@@option} is equivalent to @code{@@code} in its effects. -For example: - -@example -The option @@option@{-l@} produces a long listing. -@end example -@noindent produces -@quotation -The option @option{-l} produces a long listing. -@end quotation - - -@node @t{@@dfn} -@subsection @code{@@dfn}@{@var{term}@} - -@anchor{dfn}@c old name -@findex dfn - -Use the @code{@@dfn} command to identify the introductory or defining -use of a technical term. Use the command only in passages whose -purpose is to introduce a term which will be used again or which the -reader ought to know. Mere passing mention of a term for the first -time does not deserve @code{@@dfn}. The command generates italics in -the printed manual, and double quotation marks in the Info file. For -example: - -@example -Getting rid of a file is called @@dfn@{deleting@} it. -@end example - -@noindent -produces - -@quotation -Getting rid of a file is called @dfn{deleting} it. -@end quotation - -As a general rule, a sentence containing the defining occurrence of a -term should be a definition of the term. The sentence does not need -to say explicitly that it is a definition, but it should contain the -information of a definition---it should make the meaning clear. - - -@node @t{@@abbr} -@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} - -@anchor{abbr}@c old name -@findex abbr - -@cindex Abbreviations, tagging -You can use the @code{@@abbr} command for general abbreviations. The -abbreviation is given as the single argument in braces, as in -@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular -abbreviations, you may prefer to omit periods, as in -@samp{@@abbr@{Mr@} Stallman}. - -@code{@@abbr} accepts an optional second argument, intended to be used -for the meaning of the abbreviation. - -If the abbreviation ends with a lowercase letter and a period, and is -not at the end of a sentence, and has no second argument, remember to -use the @code{@@.} command (@pxref{Ending a Sentence}) to get the -correct spacing. However, you do not have to use @code{@@.} within -the abbreviation itself; Texinfo automatically assumes periods within -the abbreviation do not end a sentence. - -@cindex @code{<abbr>} and @code{<abbrev>} tags -In @TeX{} and in the Info output, the first argument is printed as-is; -if the second argument is present, it is printed in parentheses after -the abbreviation. In HTML the @code{<abbr>} tag is used; in Docbook, -the @code{<abbrev>} tag is used. For instance: - -@example -@@abbr@{Comput. J., Computer Journal@} -@end example - -@noindent produces: - -@display -@abbr{Comput. J., Computer Journal} -@end display - -For abbreviations consisting of all capital letters, you may prefer to -use the @code{@@acronym} command instead. See the next section for -more on the usage of these two commands. - - -@node @t{@@acronym} -@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} - -@anchor{acronym}@c old name -@findex acronym - -@cindex NASA, as acronym -@cindex Acronyms, tagging -You can use the @code{@@acronym} command for abbreviations written in -all capital letters, such as `@acronym{NASA}'. The abbreviation is -given as the single argument in braces, as in -@samp{@@acronym@{NASA@}}. As a matter of style, or for particular -acronyms, you may prefer to use periods, as in -@samp{@@acronym@{N.A.S.A.@}}. - -@code{@@acronym} accepts an optional second argument, intended to be -used for the meaning of the acronym. - -If the acronym is at the end of a sentence, and if there is no second -argument, remember to use the @code{@@.} or similar command -(@pxref{Ending a Sentence}) to get the correct spacing. - -@cindex @code{<acronym>} tag -In @TeX{}, the acronym is printed in slightly smaller font. In the -Info output, the argument is printed as-is. In either format, if the -second argument is present, it is printed in parentheses after the -acronym. In HTML and Docbook the @code{<acronym>} tag is used. - -For instance (since GNU is a recursive acronym, we use -@code{@@acronym} recursively): - -@example -@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@} -@end example - -@noindent produces: - -@display -@acronym{GNU, @acronym{GNU}'s Not Unix} -@end display - -@cindex Family names, in all capitals -In some circumstances, it is conventional to print family names in all -capitals. Don't use @code{@@acronym} for this, since a name is not an -acronym. Use @code{@@sc} instead (@pxref{Smallcaps}). - -@code{@@abbr} and @code{@@acronym} are closely related commands: they -both signal to the reader that a shortened form is being used, and -possibly give a meaning. When choosing whether to use these two -commands, please bear the following in mind. - -@itemize @minus -@item -In common English usage, acronyms are a subset of abbreviations: they -include pronounceable words like `@acronym{NATO}', `radar', and -`snafu'; some sources also include syllable acronyms like -`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable -initialisms like `@acronym{FBI}'. - -@item -In Texinfo, an acronym (but not an abbreviation) should consist only -of capital letters and periods, no lowercase. - -@item -In @TeX{}, an acronym (but not an abbreviation) is printed in a -slightly smaller font. - -@item -Some browsers place a dotted bottom border under abbreviations but not -acronyms. - -@item -It usually turns out to be quite difficult and/or time-consuming to -consistently use @code{@@acronym} for all sequences of uppercase -letters. Furthermore, it looks strange for some acronyms to be in the -normal font size and others to be smaller. Thus, a simpler approach -you may wish to consider is to avoid @code{@@acronym} and just typeset -everything as normal text in all capitals: @samp{GNU}, producing the -output `GNU'. - -@item -In general, it's not essential to use either of these commands for all -abbreviations; use your judgment. Text is perfectly readable without -them. -@end itemize - - -@node @t{@@indicateurl} -@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} - -@anchor{indicateurl}@c old name -@findex indicateurl -@cindex Uniform resource locator, indicating -@cindex URL, indicating - -Use the @code{@@indicateurl} command to indicate a uniform resource -locator on the World Wide Web. This is purely for markup purposes and -does not produce a link you can follow (use the @code{@@url} or -@code{@@uref} command for that, @pxref{@t{@@url}}). -@code{@@indicateurl} is useful for urls which do not actually exist. -For example: - -@example -For example, the url might be @@indicateurl@{http://example.org/path@}. -@end example - -@noindent which produces: - -@display -For example, the url might be @indicateurl{http://example.org/path}. -@end display - -The output from @code{@@indicateurl} is more or less like that of -@code{@@samp} (@pxref{@t{@@samp}}). - - -@node @t{@@email} -@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} - -@anchor{email}@c old name -@findex email - -Use the @code{@@email} command to indicate an electronic mail address. -It takes one mandatory argument, the address, and one optional argument, the -text to display (the default is the address itself). - -@cindex Mailto link -In Info, the address is shown in angle brackets, preceded by the text -to display if any. In @TeX{}, the angle brackets are omitted. In -HTML output, @code{@@email} produces a @samp{mailto} link that usually -brings up a mail composition window. For example: - -@example -Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, -suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. -@end example - -@noindent produces - -@display -Send bug reports to @email{bug-texinfo@@gnu.org}, -suggestions to the @email{bug-texinfo@@gnu.org, same place}. -@end display - - -@node Emphasis -@section Emphasizing Text -@cindex Emphasizing text - -Usually, Texinfo changes the font to mark words in the text according -to the category the words belong to; an example is the @code{@@code} -command. Most often, this is the best way to mark words. However, -sometimes you will want to emphasize text without indicating a -category. Texinfo has two commands to do this. Also, Texinfo has -several commands that specify the font in which text will be output. -These commands have no effect in Info and only one of them, the -@code{@@r} command, has any regular use. - -@menu -* @t{@@emph @@strong}:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -@end menu - - -@node @t{@@emph @@strong} -@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} - -@anchor{emph & strong}@c oldname -@findex emph -@findex strong -@cindex Emphasizing text, font for - -The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} produces -@emph{italics} and @code{@@strong} produces @strong{bold}. -In the Info output, @code{@@emph} surrounds the text with underscores -(@samp{_}), and @code{@@strong} puts asterisks around the text. - -For example, - -@example -@group -@@strong@{Caution:@} @@samp@{rm *@} -removes @@emph@{all@} normal files. -@end group -@end example - -@noindent -produces the following: - -@quotation -@strong{Caution}: @samp{rm * .[^.]*} -removes @emph{all} normal files. -@end quotation - -The @code{@@strong} command is seldom used except to mark what is, in -effect, a typographical element, such as the word `Caution' in the -preceding example. - -@quotation Caution -Do not use @code{@@strong} with the word @samp{Note} followed by a -space; Info will mistake the combination for a cross reference. Use a -phrase such as @strong{Please notice} or @strong{Caution} instead, or -the optional argument to @code{@@quotation}---@samp{Note} is allowable -there. -@end quotation - - -@node Smallcaps -@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font -@cindex Small caps font -@findex sc @r{(small caps font)} - -Use the @samp{@@sc} command to set text in @sc{a small caps font} -(where possible). Write the text you want to be in small caps between -braces in lowercase, like this: - -@example -Richard @@sc@{Stallman@} commenc@'{e} GNU. -@end example - -@noindent -This produces: - -@display -Richard @sc{Stallman} commenc@'{e} GNU. -@end display - -As shown here, we recommend reserving @code{@@sc} for special cases -where you want typographic small caps; family names are one such, -especially in languages other than English, though there are no -hard-and-fast rules about such things. - -@cindex @code{<small>} tag -@TeX{} typesets any uppercase letters between the braces of an -@code{@@sc} command in full-size capitals; only lowercase letters are -printed in the small caps font. In the Info output, the argument to -@code{@@sc} is printed in all uppercase. In HTML, the argument is -uppercased and the output marked with the @code{<small>} tag to reduce -the font size, since HTML cannot easily represent true small caps. - -Overall, we recommend using standard upper- and lowercase letters -wherever possible. - - -@node Fonts -@subsection Fonts for Printing -@cindex Fonts for printing - -@findex fonttextsize -@cindex Font size, reducing -@cindex Reducing font size -@cindex Smaller fonts -Texinfo provides one command to change the size of the main body font -in the @TeX{} output for a document: @code{@@fonttextsize}. It has no -effect in other output. It takes a single argument on the remainder -of the line, which must be either @samp{10} or @samp{11}. For -example: - -@example -@@fonttextsize 10 -@end example - -@cindex Printing cost, reducing -The effect is to reduce the body font to a 10@dmn{pt} size (the -default is 11@dmn{pt}). Fonts for other elements, such as sections -and chapters, are reduced accordingly. This should only be used in -conjunction with @code{@@smallbook} (@pxref{@t{@@smallbook}}) or -similar, since 10@dmn{pt} fonts on standard paper (8.5x11 or A4) are -too small. One reason to use this command is to save pages, and hence -printing cost, for physical books. - -Texinfo does not at present have commands to switch the font family -to use, or more general size-changing commands. - -Texinfo also provides a number of font commands that specify font -changes in the printed manual and (where possible) in the HTML output. -They have no effect in Info. All the commands apply to a following -argument surrounded by braces. - -@table @code -@item @@b -@findex b @r{(bold font)} -@cindex Bold font -selects @b{bold} face; - -@item @@i -@findex i @r{(italic font)} -@cindex Italic font -selects an @i{italic} font; - -@item @@r -@findex r @r{(roman font)} -@cindex Roman font -@cindex Default font -selects a @r{roman} font, which is the usual font in which text is -printed. It may or may not be seriffed. - -@item @@sansserif -@findex sansserif @r{(sans serif font)} -@cindex Sans serif font -selects a @sansserif{sans serif} font; - -@item @@slanted -@findex slanted @r{(slanted font)} -@cindex Slanted font -@cindex Oblique font -selects a @slanted{slanted} font; - -@item @@t -@findex t @r{(typewriter font)} -@cindex Monospace font -@cindex Fixed-width font -@cindex Typewriter font -selects the @t{fixed-width}, typewriter-style font used by @code{@@code}; - -@end table - -(The commands with longer names were invented much later than the -others, at which time it did not seem desirable to use very short -names for such infrequently needed features.) - -@cindex <lineannotation> Docbook tag -The @code{@@r} command can be useful in example-like environments, to -write comments in the standard roman font instead of the fixed-width -font. This looks better in printed output, and produces a -@code{<lineannotation>} tag in Docbook output. - -For example, - -@example -@group -@@lisp -(+ 2 2) ; @@r@{Add two plus two.@} -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -(+ 2 2) ; @r{Add two plus two.} -@end lisp - -The @code{@@t} command can occasionally be useful to produce output in -a typewriter font where that is supported (e.g., HTML and PDF), but no -distinction is needed in Info or plain text: @code{@@t@{foo@}} -produces @t{foo}, cf. @code{@@code@{foo@}} producing @code{foo}. - -For example, we use @code{@@t} in the @code{@@node} commands for this -manual to specify the Texinfo command names, because the quotes which -@code{@@code} outputs look extraneous in that particular context. - -In general, the other font commands are unlikely to be useful; they -exist primarily to make it possible to document the functionality of -specific font effects, such as in @TeX{} and related packages. - - -@node Quotations and Examples -@chapter Quotations and Examples - -Quotations and examples are blocks of text consisting of one or more -whole paragraphs that are set off from the bulk of the text and -treated differently. They are usually indented in the output. - -@findex end -In Texinfo, you always begin a quotation or example by writing an -@@-command at the beginning of a line by itself, and end it by writing -an @code{@@end} command that is also at the beginning of a line by -itself. For instance, you begin an example by writing -@code{@@example} by itself at the beginning of a line and end the -example by writing @code{@@end example} on a line by itself, at the -beginning of that line, and with only one space between the -@code{@@end} and the @code{example}. - -@menu -* Block Enclosing Commands:: Different constructs for different purposes. -* @t{@@quotation}:: Writing a quotation. -* @t{@@indentedblock}:: Block of text indented on left. -* @t{@@example}:: Writing an example in a fixed-width font. -* @t{@@verbatim}:: Writing a verbatim example. -* @t{@@verbatiminclude}:: Including a file verbatim. -* @t{@@lisp}:: Illustrating Lisp code. -* @t{@@small@dots{}}:: Examples in a smaller font. -* @t{@@display}:: Writing an example in the current font. -* @t{@@format}:: Writing an example without narrowed margins. -* @t{@@exdent}:: Undo indentation on a line. -* @t{@@flushleft @@flushright}:: Pushing text flush left or flush right. -* @t{@@raggedright}:: Avoiding justification on the right. -* @t{@@noindent}:: Preventing paragraph indentation. -* @t{@@indent}:: Forcing paragraph indentation. -* @t{@@cartouche}:: Drawing rounded rectangles around text. -@end menu - - -@node Block Enclosing Commands -@section Block Enclosing Commands - -Here is a summary of commands that enclose blocks of text, also known -as @dfn{environments}. They're explained further in the following -sections. - -@table @code -@item @@quotation -Indicate text that is quoted. The text is filled, indented (from both -margins), and printed in a roman font by default. - -@item @@indentedblock -Like @code{@@quotation}, but the text is indented only on the left. - -@item @@example -Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled. - -@item @@lisp -Like @code{@@example}, but specifically for illustrating Lisp code. The -text is printed in a fixed-width font, and indented but not filled. - -@item @@verbatim -Mark a piece of text that is to be printed verbatim; no character -substitutions are made and all commands are ignored, until the next -@code{@@end verbatim}. The text is printed in a fixed-width font, -and not indented or filled. Extra spaces and blank lines are -significant, and tabs are expanded. - -@item @@display -Display illustrative text. The text is indented but not filled, and -no font is selected (so, by default, the font is roman). - -@item @@format -Like @code{@@display} (the text is not filled and no font is -selected), but the text is not indented. - -@item @@smallquotation -@itemx @@smallindentedblock -@itemx @@smallexample -@itemx @@smalllisp -@itemx @@smalldisplay -@itemx @@smallformat -These @code{@@small...} commands are just like their non-small -counterparts, except that they output text in a smaller font size, -where possible. - -@item @@flushleft -@itemx @@flushright -Text is not filled, but is set flush with the left or right margin, -respectively. - -@item @@raggedright -Text is filled, but only justified on the left, leaving the right -margin ragged. - -@item @@cartouche -Highlight text, often an example or quotation, by drawing a box with -rounded corners around it. -@end table - -The @code{@@exdent} command is used within the above constructs to -undo the indentation of a line. - -The @code{@@noindent} command may be used after one of the above -constructs (or anywhere) to prevent the following text from being -indented as a new paragraph. - - -@node @t{@@quotation} -@section @code{@@quotation}: Block Quotations -@anchor{quotation}@c old name - -@cindex Quotations -@findex quotation - -The text of a quotation is processed like normal text (regular font, -text is filled) except that: - -@itemize @bullet -@item -both the left and right margins are closer to the center of the page, -so the whole of the quotation is indented; - -@item -the first lines of paragraphs are indented no more than other lines; and - -@item -an @code{@@author} command may be given to specify the author of the -quotation. -@end itemize - -@quotation -This is an example of text written between an @code{@@quotation} -command and an @code{@@end quotation} command. An @code{@@quotation} -command is most often used to indicate text that is excerpted from -another (real or hypothetical) printed work. -@end quotation - -Write an @code{@@quotation} command as text on a line by itself. This -line will disappear from the output. Mark the end of the quotation -with a line beginning with and containing only @code{@@end quotation}. -The @code{@@end quotation} line will likewise disappear from the -output. - -@code{@@quotation} takes one optional argument, given on the remainder -of the line. This text, if present, is included at the beginning of -the quotation in bold or otherwise emphasized, and followed with a -@samp{:}. For example: - -@example -@@quotation Note -This is -a foo. -@@end quotation -@end example - -@noindent -produces - -@quotation Note -This is -a foo. -@end quotation - -If the @code{@@quotation} argument is one of these English words -(case-insensitive): - -@example -Caution Important Note Tip Warning -@end example - -@cindex @code{<caution>} Docbook tag -@cindex @code{<important>} Docbook tag -@cindex @code{<note>} Docbook tag -@cindex @code{<tip>} Docbook tag -@cindex @code{<warning>} Docbook tag -@cindex @code{<blockquote>} HTML tag -@noindent then the Docbook output uses corresponding special tags -(@code{<note>}, etc.)@: instead of the default @code{<blockquote>}. -HTML output always uses @code{<blockquote>}. - -If the author of the quotation is specified in the @code{@@quotation} -block with the @code{@@author} command, a line with the author name is -displayed after the quotation: - -@example -@@quotation -People sometimes ask me if it is a sin in the Church of Emacs to use -vi. Using a free version of vi is not a sin; it is a penance. So happy -hacking. - -@@author Richard Stallman -@@end quotation -@end example - -@noindent -produces - -@quotation -People sometimes ask me if it is a sin in the Church of Emacs to use -vi. Using a free version of vi is not a sin; it is a penance. So happy -hacking. - -@author Richard Stallman -@end quotation - -@findex smallquotation -Texinfo also provides a command @code{@@smallquotation}, which is just -like @code{@@quotation} but uses a smaller font size where possible. -@xref{@t{@@small@dots{}}}. - - -@node @t{@@indentedblock} -@section @code{@@indentedblock}: Indented text blocks -@cindex Indented text block -@findex indentedblock - -The @code{@@indentedblock} environment is similar to -@code{@@quotation}, except that text is only indented on the left (and -there is no optional argument for an author). Thus, the text font -remains unchanged, and text is gathered and filled as usual, but the -left margin is increased. For example: - -@indentedblock -This is an example of text written between an @code{@@indentedblock} -command and an @code{@@end indentedblock} command. The -@code{@@indentedblock} environment can contain any text or other -commands desired. -@end indentedblock - -This is written in the Texinfo source as: - -@example -@@indentedblock -This is an example ... -@@end indentedblock -@end example - -@findex smallindentedblock -Texinfo also provides a command @code{@@smallindentedblock}, which is -just like @code{@@indentedblock} but uses a smaller font size where -possible. @xref{@t{@@small@dots{}}}. - - -@node @t{@@example} -@section @code{@@example}: Example Text - -@anchor{example}@c old name -@findex example -@cindex Examples, formatting them -@cindex Formatting examples - -The @code{@@example} environment is used to indicate an example that -is not part of the running text, such as computer input or output. -Write an @code{@@example} command at the beginning of a line by -itself. Mark the end of the example with an @code{@@end example} -command, also written at the beginning of a line by itself. - -An @code{@@example} environment has the following characteristics: - -@itemize -@item Each line in the input file is a line in the output; that is, -the source text is not filled as it normally is. -@item Extra spaces and blank lines are significant. -@item The output is indented. -@item The output uses a fixed-width font. -@item Texinfo commands @emph{are} expanded; if you want the output to -be the input verbatim, use the @code{@@verbatim} environment instead -(@pxref{@t{@@verbatim}}). -@end itemize - -For example, - -@example -@@example -cp foo @@var@{dest1@}; \ - cp foo @@var@{dest2@} -@@end example -@end example - -@noindent -produces - -@example -cp foo @var{dest1}; \ - cp foo @var{dest2} -@end example - -The lines containing @code{@@example} and @code{@@end example} will -disappear from the output. To make the output look good, you should -put a blank line before the @code{@@example} and another blank line -after the @code{@@end example}. Blank lines inside the beginning -@code{@@example} and the ending @code{@@end example}, on the other -hand, do appear in the output. - -@quotation Caution -Do not use tabs in the lines of an example! (Or anywhere else in -Texinfo, except in verbatim environments.) @TeX{} treats tabs as -single spaces, and that is not what they look like. In XEmacs, you can -use @kbd{M-x untabify} to convert tabs in a region to multiple spaces. -@end quotation - -Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text that continues afterwards should not be -indented, as in the example above. The @code{@@noindent} command -prevents a piece of text from being indented as if it were a new -paragraph (@pxref{@t{@@noindent}}. - -If you want to embed code fragments within sentences, instead of -displaying them, use the @code{@@code} command or its relatives -(@pxref{@t{@@code}}). - -If you wish to write a ``comment'' on a line of an example in the -normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). - - -@node @t{@@verbatim} -@section @code{@@verbatim}: Literal Text - -@anchor{verbatim}@c old name -@findex verbatim -@cindex Verbatim environment - -Use the @code{@@verbatim} environment for printing of text that may -contain special characters or commands that should not be interpreted, -such as computer input or output (@code{@@example} interprets its text -as regular Texinfo commands). This is especially useful for including automatically -generated files in a Texinfo manual. - -In general, the output will be just the same as the input. No -character substitutions are made, e.g., all spaces and blank lines are -significant, including tabs. In the printed manual, the text is -typeset in a fixed-width font, and not indented or filled. - -Write an @code{@@verbatim} command at the beginning of a line by -itself. This line will disappear from the output. Mark the end of -the verbatim block with an @code{@@end verbatim} command, also written -at the beginning of a line by itself. The @code{@@end verbatim} will -also disappear from the output. - -For example: -@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim - -@example -@exdent @t{@@verbatim} -@exdent @t{@{} -@exdent @key{TAB}@t{@@command with strange characters: @@'e} -@exdent @t{expand@key{TAB}me} -@exdent @t{@}} -@exdent @t{@@end verbatim} -@end example - -@noindent -This produces: - -@verbatim -{ - @command with strange characters: @'e -expand me -} -@end verbatim - -Since the lines containing @code{@@verbatim} and @code{@@end verbatim} -produce no output, typically you should put a blank line before the -@code{@@verbatim} and another blank line after the @code{@@end -verbatim}. Blank lines between the beginning @code{@@verbatim} and -the ending @code{@@end verbatim} will appear in the output. - -@cindex Verbatim, small -@cindex Small verbatim -You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in -an @code{@@smallformat} environment, as shown here: - -@c more cheating ... -@smallexample -@exdent @t{@@smallformat} -@exdent @t{@@verbatim} -@exdent @t{... still verbatim, but in a smaller font ...} -@exdent @t{@@end verbatim} -@exdent @t{@@end smallformat} -@end smallexample - -Finally, a word of warning: it is not reliable to use -@code{@@verbatim} inside other Texinfo constructs. - - -@node @t{@@verbatiminclude} -@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim - -@anchor{verbatiminclude}@c old name -@findex verbatiminclude -@cindex Verbatim, include file -@cindex Including a file verbatim - -You can include the exact contents of a file in the document with the -@code{@@verbatiminclude} command: - -@example -@@verbatiminclude @var{filename} -@end example - -The contents of @var{filename} is printed in a verbatim environment -(@pxref{@t{@@verbatim}}). Generally, the file is printed exactly -as it is, with all special characters and white space retained. No -indentation is added; if you want indentation, enclose the -@code{@@verbatiminclude} within @code{@@example} -(@pxref{@t{@@example}}). - -The name of the file is taken literally, with a single exception: -@code{@@value@{@var{var}@}} references are expanded. This makes it -possible to include files in other directories within a distribution, -for instance: - -@example -@@verbatiminclude @@value@{top_srcdir@}/NEWS -@end example - -@noindent (You still have to get @code{top_srcdir} defined in the -first place.) - -For a method on printing the file contents in a smaller font size, see -the end of the previous section on @code{@@verbatim}. - - -@node @t{@@lisp} -@section @code{@@lisp}: Marking a Lisp Example - -@anchor{lisp}@c old name -@findex lisp -@cindex Lisp example - -The @code{@@lisp} command is used for Lisp code. It is synonymous -with the @code{@@example} command. - -@lisp -This is an example of text written between an -@code{@@lisp} command and an @code{@@end lisp} command. -@end lisp - -Use @code{@@lisp} instead of @code{@@example} to preserve information -regarding the nature of the example. This is useful, for example, if -you write a function that evaluates only and all the Lisp code in a -Texinfo file. Then you can use the Texinfo file as a Lisp -library.@footnote{It would be straightforward to extend Texinfo to work -in a similar fashion for C, Fortran, or other languages.} - -Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by -itself. - - -@node @t{@@small@dots{}} -@section @code{@@small@dots{}} Block Commands - -@anchor{small}@c old name -@findex smallexample -@findex smallformat -@findex smalllisp -@findex smallquotation -@cindex Small examples -@cindex Examples in smaller fonts -@cindex Quotations in smaller fonts -@cindex Lisp examples in smaller fonts - -In addition to the regular @code{@@example} and similar commands, -Texinfo has ``small'' example-style commands. These are -@code{@@smallquotation}, @code{@@smallindentedblock}, -@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, -and @code{@@smalllisp}. - -In Info output, the @code{@@small@dots{}} commands are equivalent to -their non-small companion commands. - -In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in -a smaller font than the non-small example commands. Thus, for -instance, code examples can contain longer lines and still fit on a -page without needing to be rewritten. - -A smaller font size is also requested in HTML output, and (as usual) -retained in the Texinfo@tie{}XML transliteration. - -Mark the end of an @code{@@small@dots{}} block with a corresponding -@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with -@code{@@end smallexample}. - -Here is an example of the font used by the @code{@@smallexample} -command (in Info, the output will be the same as usual): - -@smallexample -@dots{} to make sure that you have the freedom to -distribute copies of free software (and charge for -this service if you wish), that you receive source -code or can get it if you want it, that you can -change the software or use pieces of it in new free -programs; and that you know you can do these things. -@end smallexample - -The @code{@@small@dots{}} commands use the same font style as their -normal counterparts: @code{@@smallexample} and @code{@@smalllisp} use -a fixed-width font, and everything else uses the regular font. -They also have the same behavior in other respects---whether filling -is done and whether margins are narrowed. - -As a general rule, a printed document looks better if you use only one -of (for instance) @code{@@example} or @code{@@smallexample} -consistently within a chapter. - - -@node @t{@@display} -@section @code{@@display}: Examples Using the Text Font - -@anchor{display}@c old name -@findex display -@cindex Display formatting - -The @code{@@display} command begins another kind of environment, where -the font is left unchanged, not switched to typewriter as with -@code{@@example}. Each line of input still produces a line of output, -and the output is still indented. - -@display -This is an example of text written between an @code{@@display} command -and an @code{@@end display} command. The @code{@@display} command -indents the text, but does not fill it. -@end display - -@findex smalldisplay -Texinfo also provides the environment @code{@@smalldisplay}, which is -like @code{@@display} but uses a smaller font size. -@xref{@t{@@small@dots{}}}. - -The @code{@@table} command (@pxref{@t{@@table}}) is not supported -inside @code{@@display}. Since @code{@@display} is line-oriented, it -doesn't make sense to use them together. If you want to indent a -table, try @code{@@quotation} (@pxref{@t{@@quotation}}) or -@code{@@indentedblock} (@pxref{@t{@@indentedblock}}). - - -@node @t{@@format} -@section @code{@@format}: Examples Using the Full Line Width - -@anchor{format}@c old name -@findex format - -The @code{@@format} command is similar to @code{@@display}, except it -leaves the text unindented. Like @code{@@display}, it does not select -the fixed-width font. - -@format -This is an example of text written between an @code{@@format} command -and an @code{@@end format} command. As you can see -from this example, -the @code{@@format} command does not fill the text. -@end format - -@findex smallformat -Texinfo also provides the environment @code{@@smallformat}, which is -like @code{@@format} but uses a smaller font size. -@xref{@t{@@small@dots{}}}. - - -@node @t{@@exdent} -@section @code{@@exdent}: Undoing a Line's Indentation - -@anchor{exdent}@c old name -@findex exdent -@cindex Indentation undoing - -The @code{@@exdent} command removes any indentation a line might have. -The command is written at the beginning of a line and applies only to -the text that follows the command that is on the same line. Do not use -braces around the text. In a printed manual, the text on an -@code{@@exdent} line is printed in the roman font. - -@code{@@exdent} is usually used within examples. Thus, - -@example -@group -@@example -This line follows an @@@@example command. -@@exdent This line is exdented. -This line follows the exdented line. -The @@@@end example comes on the next line. -@@end example -@end group -@end example - -@noindent -produces - -@example -@group -This line follows an @@example command. -@exdent This line is exdented. -This line follows the exdented line. -The @@end example comes on the next line. -@end group -@end example - -In practice, the @code{@@exdent} command is rarely used. Usually, you -un-indent text by ending the example and returning the page to its -normal width. - -@code{@@exdent} has no effect in HTML output. - - -@node @t{@@flushleft @@flushright} -@section @code{@@flushleft} and @code{@@flushright} - -@anchor{flushleft & flushright}@c old name -@findex flushleft -@findex flushright -@cindex Ragged right, without filling -@cindex Ragged left, without filling - -The @code{@@flushleft} and @code{@@flushright} commands line up the -ends of lines on the left and right margins of a page, -but do not fill the text. The commands are written on lines of their -own, without braces. The @code{@@flushleft} and @code{@@flushright} -commands are ended by @code{@@end flushleft} and @code{@@end -flushright} commands on lines of their own. - -@need 1500 -For example, - -@example -@group -@@flushleft -This text is -written flushleft. -@@end flushleft -@end group -@end example - -@noindent -produces - -@quotation -@flushleft -This text is -written flushleft. -@end flushleft -@end quotation - - -@code{@@flushright} produces the type of indentation often used in the -return address of letters. For example, - -@example -@group -@@flushright -Here is an example of text written -flushright. The @@code@{@@flushright@} command -right justifies every line but leaves the -left end ragged. -@@end flushright -@end group -@end example - -@noindent -produces - -@flushright -Here is an example of text written -flushright. The @code{@@flushright} command -right justifies every line but leaves the -left end ragged. -@end flushright - - -@node @t{@@raggedright} -@section @code{@@raggedright}: Ragged Right Text - -@anchor{raggedright}@c old name -@findex raggedright -@cindex Ragged right, with filling - -The @code{@@raggedright} fills text as usual, but the text is only -justified on the left; the right margin is ragged. The command is -written on a line of its own, without braces. The -@code{@@raggedright} command is ended by @code{@@end raggedright} on a -line of its own. This command has no effect in Info and HTML output, -where text is always set ragged right. - -The @code{@@raggedright} command can be useful with paragraphs -containing lists of commands with long names, when it is known in -advance that justifying the text on both margins will make the -paragraph look bad. - -For example, - -@example -@group -@@raggedright -Commands for double and single angle quotation marks: -@@code@{@@@@guillemetleft@@@{@@@}@}, @@code@{@@@@guillemetright@@@{@@@}@}, -@@code@{@@@@guillemotleft@@@{@@@}@}, @@code@{@@@@guillemotright@@@{@@@}@}, -@@code@{@@@@guilsinglleft@@@{@@@}@}, @@code@{@@@@guilsinglright@@@{@@@}@}. -@@end raggedright -@end group -@end example - -@noindent -produces - -@raggedright -Commands for double and single angle quotation marks: -@code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}}, -@code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}}, -@code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}. -@end raggedright - - -@node @t{@@noindent} -@section @code{@@noindent}: Omitting Indentation - -@anchor{noindent}@c old name -@findex noindent -@cindex Omitting indentation -@cindex Suppressing indentation -@cindex Indentation, omitting - -An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. You can prevent this on a case-by-case basis by writing -@code{@@noindent} at the beginning of a line, preceding the continuation -text. You can also disable indentation for all paragraphs globally with -@code{@@paragraphindent} (@pxref{@t{@@paragraphindent}}). - -It is best to write @code{@@noindent} on a line by itself, since in most -environments, spaces following the command will not be ignored. It's ok -to use it at the beginning of a line, with text following, outside of -any environment. - -@need 1500 -For example: - -@example -@group -@@example -This is an example -@@end example - -@@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@@code@{@@@@display@} and @@code@{@@@@end display@}.) -@end group -@end example - -@noindent produces: - -@display - -@example -This is an example -@end example - -@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@code{@@display} and @code{@@end display}.) - -@end display - -To adjust the number of blank lines properly in the Info file output, -remember that the line containing @code{@@noindent} does not generate a -blank line, and neither does the @code{@@end example} line. - -In the Texinfo source file for this manual, each line that says -`produces' is preceded by @code{@@noindent}. - -Do not put braces after an @code{@@noindent} command; they are not -necessary, since @code{@@noindent} is a command used outside of -paragraphs (@pxref{Command Syntax}). - - -@node @t{@@indent} -@section @code{@@indent}: Forcing Indentation - -@anchor{indent}@c old name -@findex indent -@cindex Forcing indentation -@cindex Inserting indentation -@cindex Indentation, forcing - -@indent -To complement the @code{@@noindent} command (see the previous -section), Texinfo provides the @code{@@indent} command that forces a -paragraph to be indented. This paragraph, for instance, is indented -using an @code{@@indent} command. The first paragraph of a section is -the most likely place to use @code{@@indent}, to override the normal -behavior of no indentation there (@pxref{@t{@@paragraphindent}}). - -It is best to write @code{@@indent} on a line by itself, since in most -environments, spaces following the command will not be ignored. The -@code{@@indent} line will not generate a blank line in the Info output -within an environment. - -However, it is ok to use it at the beginning of a line, with text -following, outside of any environment. - -Do not put braces after an @code{@@indent} command; they are not -necessary, since @code{@@indent} is a command used outside of -paragraphs (@pxref{Command Syntax}). - - -@node @t{@@cartouche} -@section @code{@@cartouche}: Rounded Rectangles - -@anchor{cartouche}@c old name -@findex cartouche -@cindex Box with rounded corners -@cindex Rounded rectangles, around text - -In a printed manual, the @code{@@cartouche} command draws a box with -rounded corners around its contents. In HTML, a normal rectangle is -drawn. @code{@@cartouche} has no effect in Info output. - -You can use this command to further highlight an example or quotation. -For instance, you could write a manual in which one type of example is -surrounded by a cartouche for emphasis. - -For example, - -@example -@@cartouche -@@example -% pwd -/usr/local/share/xemacs -@@end example -@@end cartouche -@end example - -@noindent -surrounds the two-line example with a box with rounded corners, in the -printed manual. - -The output from the example looks like this (if you're reading this in -Info, you'll see the @code{@@cartouche} had no effect): - -@cartouche -@example -% pwd -/usr/local/info -@end example -@end cartouche - -@code{@@cartouche} also implies @code{@@group} (@pxref{@t{@@group}}). - - -@node Lists and Tables -@chapter Lists and Tables -@cindex Making lists and tables -@cindex Lists and tables, making -@cindex Tables and lists, making - -Texinfo has several ways of making lists and tables. Lists can be -bulleted or numbered; two-column tables can highlight the items in -the first column; multi-column tables are also supported. - -@menu -* Introducing Lists:: Texinfo formats lists for you. -* @t{@@itemize}:: How to construct a simple list. -* @t{@@enumerate}:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. -@end menu - -@node Introducing Lists -@section Introducing Lists - -Texinfo automatically indents the text in lists or tables, and numbers -an enumerated list. This last feature is useful if you modify the -list, since you do not need to renumber it yourself. - -Numbered lists and tables begin with the appropriate @@-command at the -beginning of a line, and end with the corresponding @code{@@end} -command on a line by itself. The table and itemized-list commands -also require that you write formatting information on the same line as -the beginning @@-command. - -Begin an enumerated list, for example, with an @code{@@enumerate} -command and end the list with an @code{@@end enumerate} command. -Begin an itemized list with an @code{@@itemize} command, followed on -the same line by a formatting command such as @code{@@bullet}, and end -the list with an @code{@@end itemize} command. -@findex end - -Precede each element of a list with an @code{@@item} or @code{@@itemx} -command. - -@sp 1 -@noindent -Here is an itemized list of the different kinds of table and lists: - -@itemize @bullet -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end itemize - -@sp 1 -@noindent -Here is an enumerated list with the same items: - -@enumerate -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end enumerate - -@sp 1 -@noindent -And here is a two-column table with the same items and their -@w{@@-commands}: - -@table @code -@item @@itemize -Itemized lists with and without bullets. - -@item @@enumerate -Enumerated lists, using numbers or letters. - -@item @@table -@itemx @@ftable -@itemx @@vtable -Two-column tables, optionally with indexing. -@end table - - -@node @t{@@itemize} -@section @code{@@itemize}: Making an Itemized List - -@anchor{itemize}@c old name -@findex itemize -@cindex Itemization - -The @code{@@itemize} command produces a sequence of ``items'', each -starting with a bullet or other mark inside the left margin, and -generally indented. - -@cindex @code{@@w}, for blank items -Begin an itemized list by writing @code{@@itemize} at the beginning of -a line. Follow the command, on the same line, with a character or a -Texinfo command that generates a mark. Usually, you will use -@code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any command or character that results in a single -character in the Info file. (When you write the mark command such as -@code{@@bullet} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.) If you don't specify a mark command, the default is -@code{@@bullet}. If you don't want any mark at all, but still want -logical items, use @code{@@w@{@}} (in this case the braces are -required). - -@findex item -After the @code{@@itemize}, write your items, each starting with -@code{@@item}. Text can follow on the same line as the @code{@@item}. -The text of an item can continue for more than one paragraph. - -There should be at least one @code{@@item} inside the @code{@@itemize} -environment. If none are present, @code{makeinfo} gives a warning. -If you just want indented text and not a list of items, use -@code{@@indentedblock}; @pxref{@t{@@indentedblock}}. - -Index entries and comments that are given before an @code{@@item} -including the first, are automatically moved (internally) to after the -@code{@@item}, so the output is as expected. Historically this has -been a common practice. - -Usually, you should put a blank line between items. This puts a blank -line in the Info file. (@TeX{} inserts the proper vertical space in -any case.) Except when the entries are very brief, these blank lines -make the list look better. - -Here is an example of the use of @code{@@itemize}, followed by the -output it produces. @code{@@bullet} produces an @samp{*} in Info and -a round dot in other output formats. - -@example -@group -@@itemize @@bullet -@@item -Some text for foo. - -@@item -Some text -for bar. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -Some text for foo. - -@item -Some text -for bar. -@end itemize -@end quotation - -Itemized lists may be embedded within other itemized lists. Here is a -list marked with dashes embedded in a list marked with bullets: - -@example -@group -@@itemize @@bullet -@@item -First item. - -@@itemize @@minus -@@item -Inner item. - -@@item -Second inner item. -@@end itemize - -@@item -Second outer item. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -First item. - -@itemize @minus -@item -Inner item. - -@item -Second inner item. -@end itemize - -@item -Second outer item. -@end itemize -@end quotation - - -@node @t{@@enumerate} -@section @code{@@enumerate}: Making a Numbered or Lettered List - -@anchor{enumerate}@c old name -@findex enumerate -@cindex Enumeration - -@code{@@enumerate} is like @code{@@itemize} (@pxref{@t{@@itemize}}), -except that the labels on the items are successive integers or letters -instead of bullets. - -Write the @code{@@enumerate} command at the beginning of a line. The -command does not require an argument, but accepts either a number or a -letter as an option. Without an argument, @code{@@enumerate} starts the -list with the number @samp{1}. With a numeric argument, such as -@samp{3}, the command starts the list with that number. With an upper- -or lowercase letter, such as @samp{a} or @samp{A}, the command starts -the list with that letter. - -Write the text of the enumerated list in the same way as an itemized -list: write a line starting with @code{@@item} at the beginning of -each item in the enumeration. It is ok to have text following the -@code{@@item}, and the text for an item can continue for several -paragraphs. - -You should put a blank line between entries in the list. -This generally makes it easier to read the Info file. - -@need 1500 -Here is an example of @code{@@enumerate} without an argument: - -@example -@group -@@enumerate -@@item -Underlying causes. - -@@item -Proximate causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate -@item -Underlying causes. - -@item -Proximate causes. -@end enumerate -@sp 1 -Here is an example with an argument of @kbd{3}: -@sp 1 -@example -@group -@@enumerate 3 -@@item -Predisposing causes. - -@@item -Precipitating causes. - -@@item -Perpetuating causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate 3 -@item -Predisposing causes. - -@item -Precipitating causes. - -@item -Perpetuating causes. -@end enumerate -@sp 1 -Here is a brief summary of the alternatives. The summary is constructed -using @code{@@enumerate} with an argument of @kbd{a}. -@sp 1 -@enumerate a -@item -@code{@@enumerate} - -Without an argument, produce a numbered list, starting with the -number@tie{}1. - -@item -@code{@@enumerate @var{positive-integer}} - -With a (positive) numeric argument, start a numbered list with that -number. You can use this to continue a list that you interrupted with -other text. - -@item -@code{@@enumerate @var{upper-case-letter}} - -With an uppercase letter as argument, start a list -in which each item is marked -by a letter, beginning with that uppercase letter. - -@item -@code{@@enumerate @var{lower-case-letter}} - -With a lowercase letter as argument, start a list -in which each item is marked by -a letter, beginning with that lowercase letter. -@end enumerate - -You can also nest enumerated lists, as in an outline. - - -@node Two-column Tables -@section Making a Two-column Table - -@cindex Tables, making two-column -@findex table - -@code{@@table} is similar to @code{@@itemize} -(@pxref{@t{@@itemize}}), but allows you to specify a name or -heading line for each item. The @code{@@table} command is used to -produce two-column tables, and is especially useful for glossaries, -explanatory exhibits, and command-line option summaries. - -@menu -* @t{@@table}:: How to construct a two-column table. -* @t{@@ftable @@vtable}:: Automatic indexing for two-column tables. -* @t{@@itemx}:: How to put more entries in the first column. -@end menu - -@node @t{@@table} -@subsection Using the @code{@@table} Command - -@anchor{table}@c old name - -@cindex Definition lists, typesetting -Use the @code{@@table} command to produce two-column tables. It is -typically used when you have a list of items and a brief text with -each one, such as ``definition lists''. - -Write the @code{@@table} command at the beginning of a line, after a -blank line, and follow it on the same line with an argument that is a -Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp}, -@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}). - -This command will be applied to the text that goes into the first -column of each item and thus determines how it will be highlighted. -For example, @code{@@table @@code} will cause the text in the first -column to be output as if it had been the argument to an @code{@@code} -command. - -@anchor{@t{@@asis}}@c command name with @, for consistency -@findex asis -You may also use the @code{@@asis} command as an argument to -@code{@@table}. @code{@@asis} is a command that does nothing; if you -use this command after @code{@@table}, the first column entries are -output without added highlighting (``as is''). - -The @code{@@table} command works with other commands besides those -explicitly mentioned here. However, you can only use predefined -Texinfo commands that normally take an argument in braces. You cannot -reliably use a new command defined with @code{@@macro}, but an -@code{@@alias} (for a suitable predefined command) is acceptable. -@xref{Defining New Texinfo Commands}. - -@findex item -Begin each table entry with an @code{@@item} command at the beginning -of a line. Write the first column text on the same line as the -@code{@@item} command. Write the second column text on the line -following the @code{@@item} line and on subsequent lines. (You do not -need to type anything for an empty second column entry.) You may -write as many lines of supporting text as you wish, even several -paragraphs. But only the text on the same line as the @code{@@item} -will be placed in the first column (including any footnotes). - -Normally, you should put a blank line before an @code{@@item} line -(except the first one). This puts a blank line in the Info file. -Except when the entries are very brief, a blank line looks better. - -End the table with a line consisting of @code{@@end table}, followed -by a blank line. @TeX{} will always start a new paragraph after the -table, so the blank line is needed for the Info output to be analogous. - -@need 1500 -The following table, for example, highlights the text in the first -column with an @code{@@samp} command: - -@example -@group -@@table @@samp -@@item foo -This is the text for -@@samp@{foo@}. - -@@item bar -Text for @@samp@{bar@}. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @samp -@item foo -This is the text for -@samp{foo}. -@item bar -Text for @samp{bar}. -@end table - -If you want to list two or more named items with a single block of -text, use the @code{@@itemx} command. (@xref{@t{@@itemx}}.) - - -@node @t{@@ftable @@vtable} -@subsection @code{@@ftable} and @code{@@vtable} - -@anchor{ftable vtable}@c old name -@findex ftable -@findex vtable -@cindex Tables with indexing -@cindex Indexing table entries automatically - -The @code{@@ftable} and @code{@@vtable} commands are the same as the -@code{@@table} command except that @code{@@ftable} automatically enters -each of the items in the first column of the table into the index of -functions and @code{@@vtable} automatically enters each of the items in -the first column of the table into the index of variables. This -simplifies the task of creating indices. Only the items on the same -line as the @code{@@item} commands are indexed, and they are indexed in -exactly the form that they appear on that line. @xref{Indices}, -for more information about indices. - -Begin a two-column table using @code{@@ftable} or @code{@@vtable} by -writing the @@-command at the beginning of a line, followed on the same -line by an argument that is a Texinfo command such as @code{@@code}, -exactly as you would for an @code{@@table} command; and end the table -with an @code{@@end ftable} or @code{@@end vtable} command on a line by -itself. - -See the example for @code{@@table} in the previous section. - - -@node @t{@@itemx} -@subsection @code{@@itemx}: Second and Subsequent Items - -@anchor{itemx}@c old name -@cindex Two named items for @code{@@table} -@findex itemx - -Use the @code{@@itemx} command inside a table when you have two or more -first column entries for the same item, each of which should appear on a -line of its own. - -Use @code{@@item} for the first entry, and @code{@@itemx} for all -subsequent entries; @code{@@itemx} must always follow an @code{@@item} -command, with no blank line intervening. - -The @code{@@itemx} command works exactly like @code{@@item} except -that it does not generate extra vertical space above the first column -text. If you have multiple consecutive @code{@@itemx} commands, do -not insert any blank lines between them. - -For example, - -@example -@group -@@table @@code -@@item upcase -@@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding uppercase (lowercase) -character or string. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @code -@item upcase -@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding uppercase (lowercase) -character or string. -@end table - -@noindent -(Note also that this example illustrates multi-line supporting text in -a two-column table.) - - -@node Multi-column Tables -@section @code{@@multitable}: Multi-column Tables - -@findex multitable -@cindex Tables, making multi-column - -@code{@@multitable} allows you to construct tables with any number of -columns, with each column having any width you like. - -You define the column widths on the @code{@@multitable} line itself, and -write each row of the actual table following an @code{@@item} command, -with columns separated by an @code{@@tab} command. Finally, @code{@@end -multitable} completes the table. Details in the sections below. - -@menu -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. -@end menu - -@node Multitable Column Widths -@subsection Multitable Column Widths -@cindex Multitable column widths -@cindex Column widths, defining for multitables -@cindex Widths, defining multitable column - -You can define the column widths for a multitable in two ways: as -fractions of the line length; or with a prototype row. Mixing the two -methods is not supported. In either case, the widths are defined -entirely on the same line as the @code{@@multitable} command. - -@enumerate -@item -@findex columnfractions -@cindex Line length, column widths as fraction of -To specify column widths as fractions of the line length, write -@code{@@columnfractions} and the decimal numbers (presumably less than -1; a leading zero is allowed and ignored) after the -@code{@@multitable} command, as in: - -@example -@@multitable @@columnfractions .33 .33 .33 -@end example - -The fractions need not add up exactly to 1.0, as these do not. This -allows you to produce tables that do not need the full line length. - -@item -@cindex Prototype row, column widths defined by -To specify a prototype row, write the longest entry for each column -enclosed in braces after the @code{@@multitable} command. For example: - -@example -@@multitable @{some text for column one@} @{for column two@} -@end example - -@noindent -The first column will then have the width of the typeset `some text for -column one', and the second column the width of `for column two'. - -The prototype entries need not appear in the table itself. - -Although we used simple text in this example, the prototype entries can -contain Texinfo commands; markup commands such as @code{@@code} are -particularly likely to be useful. - -@end enumerate - - -@node Multitable Rows -@subsection Multitable Rows - -@cindex Multitable rows -@cindex Rows, of a multitable - -@findex item -@findex tab -After the @code{@@multitable} command defining the column widths (see -the previous section), you begin each row in the body of a multitable -with @code{@@item}, and separate the column entries with @code{@@tab}. -Line breaks are not special within the table body, and you may break -input lines in your source file as necessary. - -@findex headitem -@cindex Heading row, in table -@cindex @code{<thead>} HTML/XML tag -You can also use @code{@@headitem} instead of @code{@@item} to produce -a @dfn{heading row}. The @TeX{} output for such a row is in bold, and -the HTML and Docbook output uses the @code{<thead>} tag. In Info, the -heading row is followed by a separator line made of dashes (@samp{-} -characters). - -@findex headitemfont -@cindex Font for multitable heading rows -The command @code{@@headitemfont} can be used in templates when the -entries in an @code{@@headitem} row need to be used in a template. It -is a synonym for @code{@@b}, but using @code{@@headitemfont} avoids -any dependency on that particular font style, in case we provide a way -to change it in the future. - -Here is a complete example of a multi-column table (the text is from -@cite{XEmacs User's Manual}, @pxref{Split Window,, Splitting Windows, -emacs, XEmacs User's Manual}): - -@example -@@multitable @@columnfractions .15 .45 .4 -@@headitem Key @@tab Command @@tab Description -@@item C-x 2 -@@tab @@code@{split-window-vertically@} -@@tab Split the selected window into two windows, -with one above the other. -@@item C-x 3 -@@tab @@code@{split-window-horizontally@} -@@tab Split the selected window into two windows -positioned side by side. -@@item C-Mouse-2 -@@tab -@@tab In the mode line or scroll bar of a window, -split that window. -@@end multitable -@end example - -@noindent produces: - -@multitable @columnfractions .15 .45 .4 -@headitem Key @tab Command @tab Description -@item C-x 2 -@tab @code{split-window-vertically} -@tab Split the selected window into two windows, -with one above the other. -@item C-x 3 -@tab @code{split-window-horizontally} -@tab Split the selected window into two windows -positioned side by side. -@item C-Mouse-2 -@tab -@tab In the mode line or scroll bar of a window, -split that window. -@end multitable - - -@node Special Displays -@chapter Special Displays -@cindex Special displays - -The commands in this chapter allow you to write text that is specially -displayed (output format permitting), outside of the normal document -flow. - -One set of such commands is for creating ``floats'', that is, figures, -tables, and the like, set off from the main text, possibly numbered, -captioned, and/or referred to from elsewhere in the document. Images -are often included in these displays. - -Another group of commands is for creating footnotes in Texinfo. - -@menu -* Floats:: Figures, tables, and the like. -* Images:: Including graphics and images. -* Footnotes:: Writing footnotes. -@end menu - - -@node Floats -@section Floats -@cindex Floats, in general - -A @dfn{float} is a display which is set off from the main text. It is -typically labeled as being a ``Figure'', ``Table'', ``Example'', or -some similar type. - -@cindex Floating, not yet implemented -A float is so-named because, in principle, it can be moved to the -bottom or top of the current page, or to a following page, in the -printed output. (Floating does not make sense in other output -formats.) In the present version of Texinfo, however, this floating -is unfortunately not yet implemented. Instead, the floating material -is simply output at the current location, more or less as if it were -an @code{@@group} (@pxref{@t{@@group}}). - -@menu -* @t{@@float}:: Producing floating material. -* @t{@@caption @@shortcaption}:: Specifying descriptions for floats. -* @t{@@listoffloats}:: A table of contents for floats. -@end menu - - -@node @t{@@float} -@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material - -@anchor{float}@c old name -@findex float -@cindex Float environment - -To produce floating material, enclose the material you want to be -displayed separate between @code{@@float} and @code{@@end float} -commands, on lines by themselves. - -Floating material often uses @code{@@image} to display an -already-existing graphic (@pxref{Images}), or @code{@@multitable} to -display a table (@pxref{Multi-column Tables}). However, the contents -of the float can be anything. Here's an example with simple text: - -@example -@@float Figure,fig:ex1 -This is an example float. -@@end float -@end example - -@noindent And the output: - -@float Figure,fig:ex1 -This is an example float. -@end float - -As shown in the example, @code{@@float} takes two arguments (separated -by a comma), @var{type} and @var{label}. Both are optional. - -@table @var -@item type -Specifies the sort of float this is; typically a word such as -``Figure'', ``Table'', etc. If this is not given, and @var{label} is, -any cross referencing will simply use a bare number. - -@item label -Specifies a cross reference label for this float. If given, this -float is automatically given a number, and will appear in any -@code{@@listoffloats} output (@pxref{@t{@@listoffloats}}). Cross -references to @var{label} are allowed. - -@cindex Floats, making unnumbered -@cindex Unnumbered float, creating -On the other hand, if @var{label} is not given, then the float will -not be numbered and consequently will not appear in the -@code{@@listoffloats} output or be cross-referenceable. -@end table - -@noindent Ordinarily, you specify both @var{type} and @var{label}, to get a -labeled and numbered float. - -@cindex Floats, numbering of -@cindex Numbering of floats -In Texinfo, all floats are numbered in the same way: with the chapter -number (or appendix letter), a period, and the float number, which -simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each -float type is counted independently. - -Floats within an @code{@@unnumbered}, or outside of any chapter, are -simply numbered consecutively from 1. - -These numbering conventions are not, at present, changeable. - - -@node @t{@@caption @@shortcaption} -@subsection @code{@@caption} & @code{@@shortcaption} - -@anchor{caption shortcaption}@c old name -@findex caption -@findex shortcaption -@cindex Captions, for floats -@cindex Short captions, for lists of floats - -You may write an @code{@@caption} anywhere within an @code{@@float} -environment, to define a caption for the float. It is not allowed in -any other context. @code{@@caption} takes a single argument, enclosed -in braces. Here's an example: - -@example -@@float -An example float, with caption. -@@caption@{Caption for example float.@} -@@end float -@end example - -@noindent The output is: - -@float -An example float, with caption. -@caption{Caption for example float.} -@end float - -@code{@@caption} can appear anywhere within the float; it is not -processed until the @code{@@end float}. The caption text is usually a -sentence or two, but may consist of several paragraphs if necessary. - -In the output, the caption always appears below the float; this is not -currently changeable. It is preceded by the float type and/or number, -as specified to the @code{@@float} command (see the previous section). - -The @code{@@shortcaption} command likewise may be used only within -@code{@@float}, and takes a single argument in braces. The short -caption text is used instead of the caption text in a list of floats -(see the next section). Thus, you can write a long caption for the -main document, and a short title to appear in the list of floats. For -example: - -@example -@@float -... as above ... -@@shortcaption@{Text for list of floats.@} -@@end float -@end example - -The text for @code{@@shortcaption} may not contain comments -(@code{@@c}), verbatim text (@code{@@verb}), environments such as -@code{@@example}, footnotes (@code{@@footnote}) or other complex -constructs. The same constraints apply to @code{@@caption} unless -there is an @code{@@shortcaption}. - - -@node @t{@@listoffloats} -@subsection @code{@@listoffloats}: Tables of Contents for Floats - -@anchor{listoffloats}@c old name -@findex listoffloats -@cindex List of floats -@cindex Floats, list of -@cindex Table of contents, for floats - -You can write an @code{@@listoffloats} command to generate a list of -floats for a given float type (@pxref{@t{@@float}}), analogous to -the document's overall table of contents. Typically, it is written in -its own @code{@@unnumbered} node to provide a heading and structure, -rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). - -@code{@@listoffloats} takes one optional argument, the float type. -Here's an example: - -@example -@@node List of Figures -@@unnumbered List of Figures -@@listoffloats Figure -@end example - -@noindent And the output from @code{@@listoffloats}: - -@display -@listoffloats Figure -@end display - -Without any argument, @code{@@listoffloats} generates a list of floats -for which no float type was specified, i.e., no first argument to the -@code{@@float} command (@pxref{@t{@@float}}). - -Each line in the list of floats contains the float type (if any), -the float number, and the caption, if any---the @code{@@shortcaption} -argument, if it was specified, else the @code{@@caption} argument. -In Info, the result is a menu where each float can be selected. In -HTML, each line is a link to the float. In printed output, the page -number is included. - -Unnumbered floats (those without cross reference labels) are omitted -from the list of floats. - - -@node Images -@section Inserting Images - -@cindex Images, inserting -@cindex Pictures, inserting -@findex image - -You can insert an image given in an external file with the -@code{@@image} command. Although images can be used anywhere, -including the middle of a paragraph, we describe them in this chapter -since they are most often part of a displayed figure or example. - -@menu -* Image Syntax:: -* Image Scaling:: -@end menu - - -@node Image Syntax -@subsection Image Syntax - -Here is the synopsis of the @code{@@image} command: - -@example -@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@} -@end example - -@cindex Formats for images -@cindex Image formats -The @var{filename} argument is mandatory, and must not have an -extension, because the different processors support different formats: - -@itemize @bullet -@item -@pindex eps image format -@TeX{} (DVI output) reads the file @file{@var{filename}.eps} -(Encapsulated PostScript format). - -@item -@pindex pdftex@r{, and images} -@pindex png image format -@pindex jpeg image format -@pindex pdf image inclusions -pdf@TeX{} reads @file{@var{filename}.pdf}, @file{@var{filename}.png}, -@file{@var{filename}.jpg}, or @file{@var{filename}.jpeg} (in that -order). It also tries uppercase versions of the extensions. The PDF -format does not support EPS images, so such must be converted first. - -@item -For Info, @code{makeinfo} includes @file{@var{filename}.txt} verbatim -(more or less as if it were in @code{@@verbatim}). The Info output -may also include a reference to @file{@var{filename}.png} or -@file{@var{filename}.jpg}. (See below.) - -@item -For HTML, @code{makeinfo} outputs a reference to -@file{@var{filename}.png}, @file{@var{filename}.jpg}, -@file{@var{filename}.jpeg} or @file{@var{filename}.gif} (in that -order). If none of those exist, it gives an error, and outputs a -reference to @file{@var{filename}.jpg} anyway. - -@item -@cindex SVG images, used in Docbook -For Docbook, @code{makeinfo} outputs references to -@file{@var{filename}.eps}, @file{@var{filename}.gif} -@file{@var{filename}.jpeg}, @file{@var{filename}.jpg}, -@file{@var{filename}.pdf}, @file{@var{filename}.png} and -@file{@var{filename}.svg}, for every file found. Also, -@file{@var{filename}.txt} is included verbatim, if present. (The -subsequent Docbook processor is supposed to choose the appropriate one.) - -@item -For Info and HTML output, @code{makeinfo} uses the optional fifth -argument @var{extension} to @code{@@image} for the filename extension, -if it is specified and the file is found. Any leading period should -be included in @var{extension}. For example: - -@pindex XPM image format -@example -@@image@{foo,,,,.xpm@} -@end example - -@end itemize - -If you want to install image files for use by Info readers too, we -recommend putting them in a subdirectory like @samp{@var{foo}-figures} -for a package @var{foo}. Copying the files into -@code{$(infodir)/@var{foo}-figures/} should be done in your -@code{Makefile}. - -The @var{width} and @var{height} arguments are described in the next -section. - -For @TeX{} output, if an image is the only thing in a paragraph it -will ordinarily be displayed on a line by itself, respecting the -current environment indentation, but without the normal paragraph -indentation. If you want it centered, use @code{@@center} -(@pxref{@t{@@titlefont @@center @@sp}}). - -@cindex Alt attribute for images -@cindex Images, alternate text for -@findex - (in image alt string) -For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for -inline images to the optional @var{alttext} (fourth) argument to -@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses -the full file name of the image being displayed. The @var{alttext} is -processed as Texinfo text, so special characters such as @samp{"} and -@samp{<} and @samp{&} are escaped in the HTML output; also, you can -get an empty @code{alt} string with @code{@@-} (a command that -produces no output; @pxref{@t{@@- @@hyphenation}}). - -For Info output, the @code{alt} string is also processed as Texinfo -text and output. In this case, @samp{\} is escaped as @samp{\\} and -@samp{"} as @samp{\"}; no other escapes are done. - -In Info output, @code{makeinfo} writes a reference to the binary image -file (trying @var{filename} suffixed with @file{@var{extension}}, -@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) -if one exists. It also literally includes the @file{.txt} file if one -exists. This way, Info readers which can display images (such as the -XEmacs Info browser, running under X) can do so, whereas Info readers -which can only use text (such as the standalone Info reader) can -display the textual version. - -@cindex @samp{^@@^H} for images in Info -The implementation of this is to put the following construct into the -Info output: - -@example -^@@^H[image src="@var{binaryfile}" text="@var{txtfile}" - alt="@var{alttext} ... ^@@^H] -@end example - -@noindent where @samp{^@@} and @samp{^H} stand for the actual null and -backspace control characters. If one of the files is not present, the -corresponding argument is omitted. - -The reason for mentioning this here is that older Info browsers (this -feature was introduced in Texinfo version 4.6) will display the above -literally, which, although not pretty, should not be harmful. - - -@node Image Scaling -@subsection Image Scaling - -@cindex Images, scaling -@cindex Scaling images -@cindex Width of images -@cindex Height of images -@cindex Aspect ratio of images -@cindex Distorting images -The optional @var{width} and @var{height} arguments to the -@code{@@image} command (see the previous section) specify the size to -which to scale the image. They are only taken into account in @TeX{}. -If neither is specified, the image is presented in its natural size -(given in the file); if only one is specified, the other is scaled -proportionately; and if both are specified, both are respected, thus -likely distorting the original image by changing its aspect ratio. - -@cindex Dimensions and image sizes -The @var{width} and @var{height} may be specified using any valid @TeX{} -dimension, namely: - -@table @asis -@item pt -@cindex Points (dimension) -point (72.27pt = 1in) -@item pc -@cindex Picas -pica (1pc = 12pt) -@item bp -@cindex Big points -big point (72bp = 1in) -@item in -@cindex Inches -inch -@item cm -@cindex Centimeters -centimeter (2.54cm = 1in) -@item mm -@cindex Millimeters -millimeter (10mm = 1cm) -@item dd -@cindex Did@^ot points -did@^ot point (1157dd = 1238pt) -@item cc -@cindex Ciceros -cicero (1cc = 12dd) -@item sp -@cindex Scaled points -scaled point (65536sp = 1pt) -@end table - -@pindex ridt.eps -For example, the following will scale a file @file{ridt.eps} to one -inch vertically, with the width scaled proportionately: - -@example -@@image@{ridt,,1in@} -@end example - -@pindex epsf.tex -For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be -installed somewhere that @TeX{} can find it. (The standard location is -@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a -root of your @TeX{} directory tree.) This file is included in the -Texinfo distribution and is also available from -@uref{ftp://tug.org/tex/epsf.tex}, among other places. - -@code{@@image} can be used within a line as well as for displayed -figures. Therefore, if you intend it to be displayed, be sure to leave -a blank line before the command, or the output will run into the -preceding text. - -Image scaling is presently implemented only in @TeX{}, not in HTML or -any other sort of output. - - -@node Footnotes -@section Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon the -primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.} Footnotes are distracting; use them -sparingly at most, and it is best to avoid them completely. Standard -bibliographical references are better placed in a bibliography at the -end of a document instead of in footnotes throughout. - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu - - -@node Footnote Commands -@subsection Footnote Commands - -In Texinfo, footnotes are created with the @code{@@footnote} command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. Footnotes may -be of any length (they will be broken across pages if necessary), but -are usually short. The template is: - -@example -ordinary text@@footnote@{@var{text of footnote}@} -@end example - -As shown here, the @code{@@footnote} command should come right after the -text being footnoted, with no intervening space; otherwise, the footnote -marker might end up starting a line. - -For example, this clause is followed by a sample footnote@footnote{Here -is the sample footnote.}; in the Texinfo source, it looks like -this: - -@example -@dots{}a sample footnote@@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -As you can see, the source includes two punctuation marks next to each -other; in this case, @samp{.@};} is the sequence. This is normal (the -first ends the footnote and the second belongs to the sentence being -footnoted), so don't worry that it looks odd. - -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line. - -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}. The -reference mark is followed by a cross reference link to the footnote -text if footnotes are put in separate nodes (@pxref{Footnote Styles}). - -In the HTML output, footnote references are generally marked with a -small, superscripted number which is rendered as a hypertext link to -the footnote text. - -By the way, footnotes in the argument of an @code{@@item} command for -an @code{@@table} must be on the same line as the @code{@@item} (as -usual). @xref{Two-column Tables}. - - -@node Footnote Styles -@subsection Footnote Styles - -Info has two footnote styles, which determine where the text of the -footnote is located: - -@itemize @bullet -@cindex @samp{@r{End}} node footnote style -@item -In the `End' node style, all the footnotes for a single node are -placed at the end of that node. The footnotes are separated from the -rest of the node by a line of dashes with the word @samp{Footnotes} -within it. Each footnote begins with an @samp{(@var{n})} reference -mark. - -@need 700 -@noindent -Here is an example of the Info output for a single footnote in the -end-of-node style: - -@example -@group ---------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node. - -The name of the node with the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node. - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style: - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) The first syllable of "Texinfo" is pronounced like "speck", not -"hex". @dots{} -@end group -@end smallexample -@end itemize - -Unless your document has long and important footnotes (as in, say, -Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end} -style, as it is simpler for readers to follow. - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (You should -include any @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, so the region formatting commands will format -footnotes as specified.) - -In HTML, when the footnote style is @samp{end}, or if the output is -not split, footnotes are put at the end of the output. If set to -@samp{separate}, and the output is split, they are placed in a -separate file. - - -@node Indices -@chapter Indices -@cindex Indices - -Using Texinfo, you can generate indices without having to sort and -collate entries manually. In an index, the entries are listed in -alphabetical order, together with information on how to find the -discussion of each entry. In a printed manual, this information -consists of page numbers. In an Info file, this information is a menu -entry leading to the first node referenced. - -Texinfo provides several predefined kinds of index: an index for -functions, an index for variables, an index for concepts, and so on. -You can combine indices or use them for other than their canonical -purpose. Lastly, you can define your own new indices. - -@xref{Printing Indices & Menus}, for information on how to print -indices. - -@menu -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entries. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. -@end menu - - -@node Index Entries -@section Making Index Entries -@cindex Index entries, making -@cindex Entries, making index - -When you are making index entries, it is good practice to think of the -different ways people may look for something. Different people -@emph{do not} think of the same words when they look something up. A -helpful index will have items indexed under all the different words -that people may use. For example, one reader may think it obvious -that the two-letter names for indices should be listed under -``Indices, two-letter names, since ``Indices'' are the general -concept. But another reader may remember the specific concept of -two-letter names and search for the entry listed as ``Two letter names -for indices''. A good index will have both entries and will help both -readers. - -Like typesetting, the construction of an index is a skilled art, the -subtleties of which may not be appreciated until you need to do it -yourself. - -@xref{Printing Indices & Menus}, for information about printing an -index at the end of a book or creating an index menu in an Info file. - - -@node Predefined Indices -@section Predefined Indices - -Texinfo provides six predefined indices. Here are their nominal -meanings, abbreviations, and the corresponding index entry commands: - -@table @samp -@item cp -@cindex @code{cp} (concept) index -@findex cindex -(@code{@@cindex}) concept index, for general concepts. -@item fn -@cindex @code{fn} (function) index -@findex findex -(@code{@@findex}) function index, for function and function-like -names (such as entry points of libraries). -@item ky -@cindex @code{ky} (keystroke) index -@findex kindex -(@code{@@kindex}) keystroke index, for keyboard commands. -@item pg -@cindex @code{pg} (program) index -@findex pindex -(@code{@@pindex}) program index, for names of programs. -@item tp -@cindex @code{tp} (data type) index -@findex tindex -(@code{@@tindex}) data type index, for type names (such as structures -defined in header files). -@item vr -@cindex @code{vr} (variable) index -@findex vindex -(@code{@@vindex}) variable index, for variable names (such as global -variables of libraries). -@end table - -@noindent -Not every manual needs all of these, and most manuals use only two or -three at most. The present manual, for example, has two indices: a -concept index and an @@-command index (that is actually the function -index but is called a command index in the chapter heading). - -You are not required to use the predefined indices strictly for their -canonical purposes. For example, suppose you wish to index some C -preprocessor macros. You could put them in the function index along -with actual functions, just by writing @code{@@findex} commands for -them; then, when you print the ``Function Index'' as an unnumbered -chapter, you could give it the title `Function and Macro Index' and -all will be consistent for the reader. - -On the other hand, it is best not to stray too far from the meaning of -the predefined indices. Otherwise, in the event that your text is -combined with other text from other manuals, the index entries will -not match up. Instead, define your own new index (@pxref{New -Indices}). - -We recommend having a single index in the final document whenever -possible, however many source indices you use, since then readers have -only one place to look. Two or more source indices can be combined -into one output index using the @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Combining Indices}). - - -@node Indexing Commands -@section Defining the Entries of an Index - -@cindex Defining indexing entries -@cindex Index entries -@cindex Entries for an index -@cindex Specifying index entries -@cindex Creating index entries - -The data to make an index come from many individual indexing commands -scattered throughout the Texinfo source file. Each command says to add -one entry to a particular index; after formatting, the index will give -the current page number or node name as the reference. - -An index entry consists of an indexing command at the beginning of a -line followed, on the rest of the line, by the entry. - -For example, this section begins with the following five entries for -the concept index: - -@example -@@cindex Defining indexing entries -@@cindex Index entries, defining -@@cindex Entries for an index -@@cindex Specifying index entries -@@cindex Creating index entries -@end example - -Each predefined index has its own indexing command---@code{@@cindex} -for the concept index, @code{@@findex} for the function index, and so -on, as listed in the previous section. - -@cindex Writing index entries -@cindex Index entries, advice on writing -@cindex Advice on writing entries -@cindex Capitalization of index entries -Concept index entries consist of text. The best way to write an index -is to devise entries which are terse yet clear. If you can do this, -the index usually looks better if the entries are written just as they -would appear in the middle of a sentence, that is, capitalizing only -proper names and acronyms that always call for uppercase letters. -This is the case convention we use in most GNU manuals' indices. - -If you don't see how to make an entry terse yet clear, make it longer -and clear---not terse and confusing. If many of the entries are -several words long, the index may look better if you use a different -convention: to capitalize the first word of each entry. Whichever -case convention you use, use it consistently. - -In any event, do not ever capitalize a case-sensitive name such as a C -or Lisp function name or a shell command; that would be a spelling -error. Entries in indices other than the concept index are symbol -names in programming languages, or program names; these names are -usually case-sensitive, so likewise use upper- and lowercase as -required. - -@cindex Unique index entries -It is a good idea to make index entries unique wherever feasible. -That way, people using the printed output or online completion of -index entries don't see undifferentiated lists. Consider this an -opportunity to make otherwise-identical index entries be more -specific, so readers can more easily find the exact place they are -looking for. - -Index entries should precede the visible material that is being -indexed. For instance: - -@example -@@cindex hello -Hello, there! -@end example - -@noindent Among other reasons, that way following indexing links (in -whatever context) ends up before the material, where readers want to -be, instead of after. - -@cindex Index font types -By default, entries for a concept index are printed in a small roman -font and entries for the other indices are printed in a small -@code{@@code} font. You may change the way part of an entry is -printed with the usual Texinfo commands, such as @code{@@file} for -file names (@pxref{Marking Text}), and @code{@@r} for the normal roman -font (@pxref{Fonts}). - -@quotation Caution -Do not use a colon in an index entry. In Info, a colon separates the -menu entry name from the node name, so a colon in the entry itself -confuses Info. @xref{Menu Parts}, for more information about the -structure of a menu entry. -@end quotation - - -@node Combining Indices -@section Combining Indices -@cindex Combining indices -@cindex Indices, combining them - -Sometimes you will want to combine two disparate indices such as -functions and concepts, perhaps because you have few enough entries -that a separate index would look silly. - -You could put functions into the concept index by writing -@code{@@cindex} commands for them instead of @code{@@findex} commands, -and produce a consistent manual by printing the concept index with the -title `Function and Concept Index' and not printing the `Function -Index' at all; but this is not a robust procedure. It works only if -your document is never included as part of another document that is -designed to have a separate function index; if your document were to -be included with such a document, the functions from your document and -those from the other would not end up together. Also, to make your -function names appear in the right font in the concept index, you -would need to enclose every one of them between the braces of -@code{@@code}. - -@menu -* @t{@@syncodeindex}:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* @t{@@synindex}:: How to merge two indices, using the - roman font for the merged-from index. -@end menu - - -@node @t{@@syncodeindex} -@subsection @code{@@syncodeindex}: Combining indices using @code{@@code} - -@anchor{syncodeindex}@c old name -@findex syncodeindex - -When you want to combine functions and concepts into one index, you -should index the functions with @code{@@findex} and index the concepts -with @code{@@cindex}, and use the @code{@@syncodeindex} command to -redirect the function index entries into the concept index. - -The @code{@@syncodeindex} command takes two arguments; they are the name -of the index to redirect, and the name of the index to redirect it to. -The template looks like this: - -@example -@@syncodeindex @var{from} @var{to} -@end example - -@cindex Predefined names for indices -@cindex Two letter names for indices -@cindex Indices, two letter names -@cindex Names for indices -For this purpose, the indices are given two-letter names: - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table - -Write an @code{@@syncodeindex} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. For example, -to merge a function index with a concept index, write the -following: - -@example -@@syncodeindex fn cp -@end example - -@noindent -This will cause all entries designated for the function index to merge -in with the concept index instead. - -To merge both a variables index and a function index into a concept -index, write the following: - -@example -@group -@@syncodeindex vr cp -@@syncodeindex fn cp -@end group -@end example - -@cindex Fonts for indices -The @code{@@syncodeindex} command puts all the entries from the `from' -index (the redirected index) into the @code{@@code} font, overriding -whatever default font is used by the index to which the entries are -now directed. This way, if you direct function names from a function -index into a concept index, all the function names are printed in the -@code{@@code} font as you would expect. - - -@node @t{@@synindex} -@subsection @code{@@synindex}: Combining indices - -@anchor{synindex}@c old name -@findex synindex - -The @code{@@synindex} command is nearly the same as the -@code{@@syncodeindex} command, except that it does not put the `from' -index entries into the @code{@@code} font; rather it puts them in the -roman font. Thus, you use @code{@@synindex} when you merge a concept -index into a function index. - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file. - - -@node New Indices -@section Defining New Indices - -@cindex Defining new indices -@cindex Indices, defining new -@cindex New index defining -@findex defindex -@findex defcodeindex - -In addition to the predefined indices (@pxref{Predefined Indices}), -you may use the @code{@@defindex} and @code{@@defcodeindex} commands -to define new indices. These commands create new indexing @@-commands -with which you mark index entries. The @code{@@defindex} command is -used like this: - -@example -@@defindex @var{name} -@end example - -New index names are usually two-letter words, such as @samp{au}. -For example: - -@example -@@defindex au -@end example - -This defines a new index, called the @samp{au} index. At the same -time, it creates a new indexing command, @code{@@auindex}, that you -can use to make index entries. Use this new indexing command just as -you would use a predefined indexing command. - -For example, here is a section heading followed by a concept index -entry and two @samp{au} index entries. - -@example -@@section Cognitive Semantics -@@cindex kinesthetic image schemas -@@auindex Johnson, Mark -@@auindex Lakoff, George -@end example - -@noindent -(Evidently, @samp{au} serves here as an abbreviation for ``author''.) - -Texinfo constructs the new indexing command by concatenating the name -of the index with @samp{index}; thus, defining an @samp{xy} index -leads to the automatic creation of an @code{@@xyindex} command. - -Use the @code{@@printindex} command to print the index, as you do with -the predefined indices. For example: - -@example -@group -@@node Author Index -@@unnumbered Author Index - -@@printindex au -@end group -@end example - -The @code{@@defcodeindex} is like the @code{@@defindex} command, -except that, in the printed output, it prints entries in an -@code{@@code} font by default instead of a roman font. - -You should define new indices before the end-of-header line of a -Texinfo file, and (of course) before any @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). - -As mentioned earlier (@pxref{Predefined Indices}), we recommend having -a single index in the final document whenever possible, however many -source indices you use, since then readers have only one place to -look. - -When creating an index, @TeX{} creates a file whose extension is the -name of the index (@pxref{Names of index files}). Therefore you -should avoid using index names that collide with extensions used for -other purposes, such as @samp{.aux} or @samp{.xml}. -@command{makeinfo} already reports an error if a new index conflicts -well-known extension name. - - -@node Insertions -@chapter Special Insertions -@cindex Inserting special characters and symbols -@cindex Special insertions - -Texinfo provides several commands for inserting characters that have -special meaning in Texinfo, such as braces, and for other graphic -elements that do not correspond to simple characters you can type. - -@iftex -These are: - -@itemize @bullet -@item The Texinfo special characters: @samp{@@ @{@} , \ #}. -@item Whitespace within and around a sentence. -@item Accents. -@item Dots and bullets. -@item The @TeX{} logo and the copyright symbol. -@item The euro and pounds currency symbols. -@item The degrees symbol. -@item The minus sign. -@item Mathematical expressions. -@item Glyphs for examples of programming: evaluation, macros, errors, etc. -@item Footnotes. -@end itemize -@end iftex - -@menu -* Special Characters:: Inserting @@ @{@} , \ # -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: Inserting the right amount of whitespace. -* Inserting Accents:: Inserting accents and special characters. -* Inserting Quotation Marks:: Inserting quotation marks. -* Inserting Math:: Formatting mathematical expressions. -* Glyphs for Text:: Inserting Dots, bullets, currencies, etc. -* Glyphs for Programming:: Indicating results of evaluation, - expansion of macros, errors, etc. -@end menu - - -@node Special Characters -@section Special Characters: Inserting @@ @{@} , \ # -@anchor{Braces Atsign}@c previous names for this node -@anchor{Atsign Braces Comma} -@cindex Special characters, inserting -@cindex Commands to insert special characters - -@samp{@@} and curly braces are the basic special characters in -Texinfo. To insert these characters so they appear in text, you must -put an @samp{@@} in front of these characters to prevent Texinfo from -misinterpreting them. Alphabetic commands are also provided. - -The other characters (comma, backslash, hash) are special only in -restricted contexts, as explained in the respective sections. - -@menu -* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. -* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. -* Inserting a Comma:: , and @code{@@comma@{@}}. -* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. -* Inserting a Hashsign:: # and @code{@@hashchar@{@}}. -@end menu - - -@node Inserting an Atsign -@subsection Inserting `@@' with @code{@@@@} and @code{@@atchar@{@}} -@cindex At sign, inserting -@cindex Inserting @@ @r{(literal @samp{@@})} -@findex @@ @r{(literal @samp{@@})} -@findex @@atchar@{@} @r{(literal @samp{@@})} - -@code{@@@@} produces a single @samp{@@} character in the output. Do -not put braces after an @code{@@@@} command. - -@code{@@atchar@{@}} also produces a single @samp{@@} character in the -output. It does need following braces, as usual for alphabetic -commands. In inline conditionals (@pxref{Inline Conditionals}), it -can be necessary to avoid using the literal @samp{@@} character in the -source (and may be clearer in other contexts). - - -@node Inserting Braces -@subsection Inserting `@{ `@}' with @code{@@@{ @@@}} and @code{@@l rbracechar@{@}} - -@findex @{ @r{(literal @samp{@{})} -@findex @} @r{(literal @samp{@}})} -@findex @@lbracechar@{@} @r{(literal @samp{@{})} -@findex @@rbracechar@{@} @r{(literal @samp{@}})} -@cindex Braces, inserting - -@code{@@@{} produces a single @samp{@{} in the output, and @code{@@@}} -produces a single @samp{@}}. Do not put braces after either an -@code{@@@{} or an @code{@@@}} command. - -@code{@@lbracechar@{@}} and @code{@@rbracechar@{@}} also produce -single @samp{@{} and @samp{@}} characters in the output. They do need -following braces, as usual for alphabetic commands. In inline -conditionals (@pxref{Inline Conditionals}), it can be -necessary to avoid using literal brace characters in the source (and -may be clearer in other contexts). - - -@node Inserting a Comma -@subsection Inserting `,' with @code{@@comma@{@}} - -@findex comma -@cindex Comma, inserting - -Ordinarily, a comma `,' is a normal character that can be simply typed -in your input where you need it. - -However, Texinfo uses the comma as a special character only in one -context: to separate arguments to those Texinfo commands, such as -@code{@@acronym} (@pxref{@t{@@acronym}}) and @code{@@xref} -(@pxref{Cross References}), as well as user-defined macros -(@pxref{Defining Macros}), which take more than one argument. - -Since a comma character would confuse Texinfo's parsing for these -commands, you must use the command @samp{@@comma@{@}} instead if you want -to pass an actual comma. Here are some examples: - -@example -@@acronym@{ABC, A Bizarre @@comma@{@}@} -@@xref@{Comma,, The @@comma@{@} symbol@} -@@mymac@{One argument@@comma@{@} containing a comma@} -@end example - -Although @samp{@@comma@{@}} can be used nearly anywhere, there is no -need for it anywhere except in this unusual case. - -(Incidentally, the name @samp{@@comma} lacks the @samp{char} suffix used -in its companion commands only for historical reasons. It didn't seem -important enough to define a synonym.) - - -@node Inserting a Backslash -@subsection Inserting `\' with @code{@@backslashchar@{@}} - -@findex backslash -@cindex Backslash, inserting - -Ordinarily, a backslash `\' is a normal character in Texinfo that can -be simply typed in your input where you need it. The result is to -typeset the backslash from the typewriter font. - -However, Texinfo uses the backslash as a special character in one -restricted context: to delimit formal arguments in the bodies of -user-defined macros (@pxref{Defining Macros}). - -Due to the vagaries of macro argument parsing, it is more reliable to -pass an alphabetic command that produces a backslash instead of using -a literal \. Hence @code{@@backslashchar@{@}}. Here is an example -macro call: - -@example -@@mymac@{One argument@@backslashchar@{@} with a backslash@} -@end example - -Texinfo documents may also use \ as a command character inside -@code{@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or -@code{\backslash} produces a ``math'' backslash (from the math symbol -font), while @code{@@backslashchar@{@}} produces a typewriter -backslash as usual. - -Although @samp{@@backslashchar@{@}} can be used nearly anywhere, there -is no need for it except in these unusual cases. - - -@node Inserting a Hashsign -@subsection Inserting `#' with @code{@@hashchar@{@}} - -@findex @@hashchar@{@} @r{(literal @samp{#})} -@cindex Inserting # -@cindex Hash sign, inserting - -Ordinarily, a hash `#' is a normal character in Texinfo that can be -simply typed in your input where you need it. The result is to -typeset the hash character from the current font. - -@cindex Number sign, inserting -@cindex Octotherp, inserting -@cindex Sharp sign (not), inserting -This character has many other names, varying by locale, such as -``number sign'', ``pound'', and ``octothorp''. It is also sometimes -called ``sharp'' or ``sharp sign'' since it vaguely resembles the -musical symbol by that name. In situations where Texinfo is used, -``hash'' is the most common in our experience. - -However, Texinfo uses the hash character as a special character in one -restricted context: to introduce the so-called @code{#line} directive -and variants (@pxref{External Macro Processors}). - -So, in order to typeset an actual hash character in such a place (for -example, in a program that needs documentation about @code{#line}), -it's necessary to use @code{@@hashchar@{@}} or some other construct. -Here's an example: - -@example -@@hashchar@{@} 10 "example.c" -@end example - -Although @samp{@@hashchar@{@}} can be used nearly anywhere, there -is no need for it anywhere except this unusual case. - - -@node Inserting Quote Characters -@section Inserting Quote Characters - -@cindex Inserting quote characters -@cindex Quote characters, inserting - -As explained in the early section on general Texinfo input conventions -(@pxref{Conventions}), Texinfo source files use the ASCII character -@code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'} -(39 decimal) to produce a right quote ('). Doubling these input -characters (@code{``} and @code{''}) produces double quotes (`` and -''). These are the conventions used by @TeX{}. - -This works all right for text. However, in examples of computer code, -readers are especially likely to cut and paste the text -verbatim---and, unfortunately, some document viewers will mangle these -characters. (The free PDF reader @command{xpdf} works fine, but other -PDF readers, both free and nonfree, have problems.) - -If this is a concern for you, Texinfo provides these two commands: - -@ftable @code -@item @@codequoteundirected @var{on-off} -@cindex undirected single quote -causes the output for the @code{'} character in code environments to -be the undirected single quote, like this: -@set txicodequoteundirected on -@code{'}. -@set txicodequoteundirected off - -@item @@codequotebacktick @var{on-off} -@cindex backtick -@cindex grave accent, standalone -causes the output for the @code{`} character in code environments to -be the backtick character (standalone grave accent), like this: -@set txicodequotebacktick on -@code{`}. -@set txicodequotebacktick off -@end ftable - -If you want these settings for only part of the document, -@code{@@codequote... off} will restore the normal behavior, as in -@code{@@codequoteundirected off}. - -These settings affect @code{@@code}, @code{@@example}, @code{@@kbd}, -@code{@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful -Highlighting}. - -This feature used to be controlled by @code{@@set} variable names; -they are still supported, but the command interface is preferred. - - -@node Inserting Space -@section Inserting Space - -@cindex Inserting space -@cindex Spacing, inserting -The following sections describe commands that control spacing of various -kinds within and after sentences. - -@menu -* Multiple Spaces:: Inserting multiple spaces. -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* @t{@@frenchspacing}:: Specifying end-of-sentence spacing. -* @t{@@dmn}:: Formatting a dimension. -@end menu - - -@node Multiple Spaces -@subsection Multiple Spaces - -@cindex Multiple spaces -@cindex Whitespace, inserting -@cindex Space, inserting horizontal -@findex <space> -@findex <tab> -@findex <newline> - -Ordinarily, multiple whitespace characters (space, tab, and newline) -are collapsed into a single space. - -Occasionally, you may want to produce several consecutive spaces, -either for purposes of example (e.g., what your program does with -multiple spaces as input), or merely for purposes of appearance in -headings or lists. Texinfo supports three commands: -@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all -of which insert a single space into the output. (Here, -@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a -space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character, -and @kbd{NL} represent the tab character and end-of-line, i.e., when -@samp{@@} is the last character on a line.) - -For example, -@example -Spacey@@ @@ @@ @@ -example. -@end example - -@noindent produces - -@example -Spacey@ @ @ @ -example. -@end example - -Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by -@code{@@multitable} (@pxref{Multi-column Tables}). - -Do not follow any of these commands with braces. - -To produce a non-breakable space, see @ref{@t{@@tie}}. - - -@node Not Ending a Sentence -@subsection Not Ending a Sentence - -@cindex Not ending a sentence -@cindex Sentence non-ending punctuation -@cindex Periods, inserting -@cindex Spacing, in the middle of sentences -Depending on whether a period or exclamation point or question mark is -inside or at the end of a sentence, slightly less or more space is -inserted after a period in a typeset manual. Since it is not always -possible to determine automatically when a period ends a sentence, -special commands are needed in some circumstances. Usually, Texinfo -can guess how to handle periods, so you do not need to use the special -commands; you just enter a period as you would if you were using a -typewriter: put two spaces after the period, question mark, or -exclamation mark that ends a sentence. - -@findex <colon> @r{(suppress end-of-sentence space)} -Use the @code{@@:}@: command after a period, question mark, -exclamation mark, or colon that should not be followed by extra space. -For example, use @code{@@:}@: after periods that end (lowercase) -abbreviations which are not at the ends of sentences. - -Also, when a parenthetical remark in the middle of a sentence (like -this one!)@: ends with a period, exclamation point, or question mark, -@code{@@:} should be used after the right parenthesis. Similarly for -right brackets and right quotes (both single and double). - -For example, - -@example -foo vs.@@: bar (or?)@@: baz -foo vs. bar (or?) baz -@end example - -@noindent -@ifnottex -produces -@end ifnottex -@iftex -produces the following. If you look carefully at this printed output, -you will see a bit of extraneous space after the @samp{vs.}@: and -@samp{(or?)}@: in the second line. -@end iftex - -@quotation -foo vs.@: bar (or?)@: baz@* -foo vs. bar (or?) baz -@end quotation - -@noindent -@code{@@:} has no effect on the HTML or Docbook output. - -Do not put braces after @code{@@:} (or any non-alphabetic command). - -A few Texinfo commands force normal interword spacing, so that you -don't have to insert @code{@@:} where you otherwise would. These are -the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and -@code{@@acronym} (@pxref{Useful Highlighting}). For example, in -@samp{@@code@{foo. bar@}} the period is not considered the end of a -sentence, and no extra space is inserted. - - -@node Ending a Sentence -@subsection Ending a Sentence - -@cindex Ending a Sentence -@cindex Sentence ending punctuation - -@findex . @r{(end of sentence)} -@findex ! @r{(end of sentence)} -@findex ? @r{(end of sentence)} -@cindex Spacing, at ends of sentences -As mentioned above, Texinfo normally inserts additional space after -the end of a sentence. It uses a simple heuristic for this: a -sentence ends with a period, exclamation point, or question mark -followed by optional closing punctuation and then whitespace, and -@emph{not} preceded by a capital letter. - -Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an -exclamation point, and @code{@@?}@: instead of a question mark at the -end of a sentence that does end with a capital letter. For example: - -@example -Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end example - -@noindent -The output follows. In printed output and Info, you can see the -desired extra whitespace after the @samp{W} in the first line. - -@quotation -Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end quotation - -In the HTML output, @code{@@.}@: is equivalent to a simple @samp{.}; -likewise for @code{@@!}@: and @code{@@?}@:. - -The meanings of @code{@@:} and @code{@@.}, etc.@: in Texinfo are -designed to work well with the XEmacs sentence motion commands -(@pxref{Sentences,,, xemacs, XEmacs User's Manual}). - -Do not put braces after any of these commands. - -A few Texinfo commands are not considered as being an abbreviation, -even though they may end with a capital letter when expanded, so that -you don't have to insert @code{@@.} and companions. This is the case -for code-like highlighting commands, @code{@@var} arguments ending -with a capital letter, and @code{@@TeX}. For example, that sentence -ended with @samp{@@code@{@@@@TeX@}.}; @code{@@.} was not needed. Also -in @code{... @@var@{VARNAME@}. Text} the period after @var{VARNAME} -ends the sentence; there is no need to use @code{@@.}. - - -@node @t{@@frenchspacing} -@subsection @code{@@frenchspacing} @var{val}: Control Sentence Spacing - -@anchor{frenchspacing}@c old name -@findex frenchspacing -@cindex French spacing -@cindex Sentences, spacing after -@cindex Space, after sentences - -In American typography, it is traditional and correct to put extra -space at the end of a sentence. This is the default in Texinfo -(implemented in Info and printed output; for HTML, we don't try to -override the browser). In French typography (and others), this extra -space is wrong; all spaces are uniform. - -Therefore Texinfo provides the @code{@@frenchspacing} command to -control the spacing after punctuation. It reads the rest of the line -as its argument, which must be the single word @samp{on} or @samp{off} -(always these words, regardless of the language of the document). -Here is an example: - -@example -@@frenchspacing on -This is text. Two sentences. Three sentences. French spacing. - -@@frenchspacing off -This is text. Two sentences. Three sentences. Non-French spacing. -@end example - -@noindent produces: - -@frenchspacing on -This is text. Two sentences. Three sentences. French spacing. - -@frenchspacing off -This is text. Two sentences. Three sentences. Non-French spacing. - -@code{@@frenchspacing} also affects the output after @code{@@.}, -@code{@@!}, and @code{@@?} (@pxref{Ending a Sentence}). - -@code{@@frenchspacing} has no effect on the HTML or Docbook output; -for XML, it outputs a transliteration of itself (@pxref{Output -Formats}). - - -@node @t{@@dmn} -@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension - -@anchor{dmn}@c old name -@cindex Thin space between number, dimension -@cindex Dimension formatting -@cindex Format a dimension -@findex dmn - -You can use the @code{@@dmn} command to format a dimension with a -little extra space in the printed output. That is, on seeing -@code{@@dmn}, @TeX{} inserts just enough space for proper typesetting; -in other output formats, the formatting commands insert no space at -all. - -To use the @code{@@dmn} command, write the number and then follow it -immediately, with no intervening space, by @code{@@dmn}, and then by -the dimension within braces. For example, - -@example -A4 paper is 8.27@@dmn@{in@} wide. -@end example - -@noindent -produces - -@quotation -A4 paper is 8.27@dmn{in} wide. -@end quotation - -Not everyone uses this style. Some people prefer `8.27@tie{}in.'@: or -`8.27@tie{}inches'. In these cases, however, you need to use -@code{@@tie} (@pxref{@t{@@tie}}) or @code{@@w} (@pxref{@t{@@w}}) -so that no line break can occur between the number and the dimension. -Also, if you write a period after an abbreviation within a sentence -(as with the `in.'@: above), you should write @samp{@@:} after the -period to prevent @TeX{} from inserting extra whitespace, as shown -here. @xref{Not Ending a Sentence}. - - -@node Inserting Accents -@section Inserting Accents - -@cindex Inserting accents -@cindex Accents, inserting -@cindex Floating accents, inserting - -Here is a table with the commands Texinfo provides for inserting -floating accents. They all need an argument, the character to accent, -which can either be given in braces as usual (@code{@@'@{e@}}), or, as -a special case, the braces can be omitted, in which case the argument -is the next character (@code{@@'e}). This is to make the source as -convenient as possible to type and read, since accented characters are -very common in some languages. - -If the command is alphabetic, such as @code{@@dotaccent}, then there -must be a space between the command name and argument if braces are -not used. If the command is non-alphabetic, such as @code{@@'}, then -there must @emph{not} be a space; the argument is the very next -character. - -Exception: the argument to @code{@@tieaccent} must be enclosed in -braces (since it is two characters instead of one). - -@findex documentencoding -To get the true accented characters output in Info, not just the ASCII -transliterations, it is necessary to specify @code{@@documentencoding} -with an encoding which supports the required characters -(@pxref{@t{@@documentencoding}}). In this case, you can also use -non-ASCII (e.g., pre-accented) characters in the source file. - -@findex " @r{(umlaut accent)} -@cindex Umlaut accent -@findex ' @r{(umlaut accent)} -@cindex Acute accent -@findex = @r{(macron accent)} -@cindex Macron accent -@findex ^ @r{(circumflex accent)} -@cindex Circumflex accent -@findex ` @r{(grave accent)} -@cindex Grave accent -@findex ~ @r{(tilde accent)} -@cindex Tilde accent -@findex , @r{(cedilla accent)} -@cindex Cedilla accent -@findex dotaccent -@cindex Dot accent -@findex H @r{(Hungarian umlaut accent)} -@cindex Hungarian umlaut accent -@findex ogonek -@cindex Ogonek diacritic -@findex ringaccent -@cindex Ring accent -@findex tieaccent -@cindex Tie-after accent -@findex u @r{(breve accent)} -@cindex Breve accent -@findex ubaraccent -@cindex Underbar accent -@findex udotaccent -@cindex Underdot accent -@findex v @r{(check accent)} -@cindex Hacek accent -@cindex Check accent -@cindex Caron accent -@multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent} -@headitem Command @tab Output @tab What -@item @t{@@"o} @tab @"o @tab umlaut accent -@item @t{@@'o} @tab @'o @tab acute accent -@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent -@item @t{@@=o} @tab @=o @tab macron/overbar accent -@item @t{@@^o} @tab @^o @tab circumflex accent -@item @t{@@`o} @tab @`o @tab grave accent -@item @t{@@~o} @tab @~o @tab tilde accent -@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent -@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut -@item @t{@@ogonek@{a@}} @tab @ogonek{a} @tab ogonek -@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent -@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent -@item @t{@@u@{o@}} @tab @u{o} @tab breve accent -@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent -@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent -@item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent -@end multitable - -This table lists the Texinfo commands for inserting other characters -commonly used in languages other than English. - -@findex questiondown -@cindex @questiondown{} -@findex exclamdown -@cindex @exclamdown{} -@findex aa -@cindex @aa{} -@findex AA -@cindex @AA{} -@findex ae -@cindex @ae{} -@findex AE -@cindex @AE{} -@cindex Icelandic -@cindex Eth -@findex dh -@cindex @dh{} -@findex DH -@cindex @DH{} -@findex dotless -@cindex @dotless{i} (dotless i) -@cindex @dotless{j} (dotless j) -@cindex Dotless i, j -@findex l -@cindex @l{} -@findex L -@cindex @L{} -@findex o -@cindex @o{} -@findex O -@cindex @O{} -@findex oe -@cindex @oe{} -@findex OE -@cindex @OE{} -@cindex Romance ordinals -@cindex Ordinals, Romance -@cindex Feminine ordinal -@findex ordf -@cindex @ordf{} -@cindex Masculine ordinal -@findex ordm -@cindex @ordm{} -@findex ss -@cindex @ss{} -@cindex Es-zet -@cindex Sharp S -@cindex German S -@cindex Thorn -@findex th -@cindex @th{} -@findex TH -@cindex @TH{} -@multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S} -@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! -@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? -@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle -@item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures -@item @t{@@dh@{@} @@DH@{@}} @tab @dh{} @DH{} @tab Icelandic eth -@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i -@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j -@item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l -@item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash -@item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures -@item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals -@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S -@item @t{@@th@{@} @@TH@{@}} @tab @th{} @TH{} @tab Icelandic thorn -@end multitable - - -@node Inserting Quotation Marks -@section Inserting Quotation Marks -@cindex Inserting quotation marks -@cindex Quotation marks, inserting - -@cindex Quotation characters (`'), in source -Use doubled single-quote characters to begin and end quotations: -@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to -left- and right-hand doubled quotation marks, -@c this comes out as "like this" in Info, which is just confusing. -@iftex -``like this'', -@end iftex -and Info converts doubled single-quote characters to ASCII -double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. - -You may occasionally need to produce two consecutive single quotes; -for example, in documenting a computer language such as Maxima where -@t{'@w{}'} is a valid command. You can do this with the input -@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into -the double-quote characters. - -@cindex Unicode quotation characters -@cindex Grave accent, vs. left quote -The left quote character (@t{`}, ASCII code 96) used in Texinfo is a -grave accent in ANSI and ISO character set standards. We use it as a -quote character because that is how @TeX{} is set up, by default. - -Texinfo supports several other quotation marks used in languages other -than English. Below is a table with the commands Texinfo provides for -inserting quotation marks. - -@findex documentencoding -@cindex UTF-8 -@cindex ISO 8859-15 -@cindex Latin 9 -@cindex ISO 8859-1 -@cindex Latin 1 -In order to get the symbols for the quotation marks in encoded Info -output, it is necessary to specify @code{@@documentencoding UTF-8}. -(@xref{@t{@@documentencoding}}.) Double guillemets are also -present in ISO 8859-1 (aka Latin@tie{}1) and ISO 8859-15 (aka -Latin@tie{}9). - -@cindex European Computer Modern fonts -@cindex EC fonts -The standard @TeX{} fonts support the usual quotation marks used in -English (the ones produced with single and doubled ASCII -single-quotes). For the other quotation marks, @TeX{} uses European -Computer Modern (EC) fonts (@file{ecrm1000} and other variants). -These fonts are freely available, of course; you can download them -from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other -places. - -@cindex CM-Super fonts -The free EC fonts are bitmap fonts created with Metafont. Especially -for on-line viewing, Type@tie{}1 (vector) versions of the fonts are -preferable; these are available in the CM-Super font package -(@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}). - -Both distributions include installation instructions. - -@cindex Single quotation marks -@cindex Double quotation marks -@cindex Left quotation marks -@cindex Right quotation marks -@findex quotedblleft -@cindex `@w{}` -@findex quoteleft -@cindex ` -@cindex " (undirected double quote character) -@findex quotedblright -@cindex '@w{}' -@findex quoteright -@cindex ' -@cindex Double low-9 quotation mark -@cindex Single low-9 quotation mark -@findex quotedblbase -@cindex @quotedblbase{} (double low-9 quotation mark) -@findex quotesinglbase -@cindex @quotesinglbase{} (single low-9 quotation mark) -@cindex Angle quotation marks -@cindex Guillemets -@cindex Guillemots -@cindex French quotation marks -@cindex Quotation marks, French -@cindex German quotation marks -@cindex Quotation marks, German -@cindex Double guillemets -@cindex Single guillemets -@cindex Double angle quotation marks -@cindex Single angle quotation marks -@cindex Left-pointing angle quotation marks -@cindex Right-pointing angle quotation marks -@cindex Double left-pointing angle quotation mark -@cindex Double right-pointing angle quotation mark -@cindex Single left-pointing angle quotation mark -@cindex Single right-pointing angle quotation mark -@findex guillemetleft -@findex guillemotleft -@cindex @guillemetleft{} -@findex guillemetright -@findex guillemotright -@cindex @guillemetright{} -@findex guilsinglleft -@cindex @guilsinglleft{} -@findex guilsinglright -@cindex @guilsinglright{} -@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)} -@headitem Command @tab Glyph @tab Unicode name (point) -@item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C) -@item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D) -@item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018) -@item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019) -@item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E) -@item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A) -@item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB) -@item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB) -@item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039) -@item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A) -@end multitable - -@cindex Auk, bird species -For the double angle quotation marks, Adobe and @LaTeX{} glyph names -are also supported: @code{@@guillemotleft} and -@code{@@guillemotright}. These names are incorrect; a -``guillemot'' is a bird species (a type of auk). - -Traditions for quotation mark usage vary to a great extent between -languages -(@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}). -Texinfo does not provide commands for typesetting quotation marks -according to the numerous traditions. Therefore, you have to choose -the commands appropriate for the language of your manual. Sometimes -aliases (@pxref{@t{@@alias}}) can simplify the usage and make the -source code more readable. For example, in German, -@code{@@quotedblbase} is used for the left double quote, and the right -double quote is the glyph produced by @code{@@quotedblleft}, which is -counter-intuitive. Thus, in this case the following aliases would be -convenient: - -@example -@@alias lgqq = quotedblbase -@@alias rgqq = quotedblleft -@end example - - -@node Inserting Math -@section @code{@@math}: Inserting Mathematical Expressions - -@anchor{math}@c old name -@findex math -@cindex Mathematical expressions, inserting -@cindex Formulas, mathematical - -You can write a short mathematical expression with the @code{@@math} -command. Write the mathematical expression between braces, like this: - -@example -@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} -@end example - -@iftex -@noindent This produces the following in @TeX{}: - -@display -@math{(a + b)(a + b) = a^2 + 2ab + b^2} -@end display - -@noindent and the following in other formats: -@end iftex -@ifnottex -@noindent This produces the following in Info and HTML: -@end ifnottex - -@example -(a + b)(a + b) = a^2 + 2ab + b^2 -@end example - -The @code{@@math} command has no special effect on the Info and HTML -output. @command{makeinfo} expands any @@-commands as usual, -but it does not try to produce good mathematical formatting in any -way. - -However, as far as the @TeX{} output is concerned, plain @TeX{} -mathematical commands are allowed in @code{@@math}, starting with -@samp{\}, and the plain @TeX{} math characters like @samp{^} and -@samp{_} are also recognized. In essence, @code{@@math} drops you -into plain @TeX{} math mode. - -This allows you to conveniently write superscripts and subscripts (as -in the above example), and also to use all the plain @TeX{} math -control sequences for symbols, functions, and so on, and thus get -proper formatting in the @TeX{} output, at least. - -It's best to use @samp{\} instead of @samp{@@} for any such -mathematical commands; otherwise, @command{makeinfo} will complain. -On the other hand, @command{makeinfo} allows input with matching (but -unescaped) braces, such as @samp{k_@{75@}}, although it complains -about such bare braces in regular input. - -Here's an example: - -@example -@@math@{\sin 2\pi \equiv \cos 3\pi@} -@end example - -@iftex -@noindent which looks like this in @TeX{}: -@display -@math{\sin 2\pi \equiv \cos 3\pi} -@end display - -@noindent and -@end iftex -@noindent which looks like the input in Info and HTML: -@example -\sin 2\pi \equiv \cos 3\pi -@end example - -@findex \ @r{(literal \ in @code{@@math})} -Since @samp{\} is an escape character inside @code{@@math}, you can -use @code{@@\} to get a literal backslash (@code{\\} will work in -@TeX{}, but you'd get the literal two characters @samp{\\} in Info). -@code{@@\} is not defined outside of @code{@@math}, since a @samp{\} -ordinarily produces a literal (typewriter) @samp{\}. You can also use -@code{@@backslashchar@{@}} in any mode to get a typewriter backslash. -@xref{Inserting a Backslash}. - -@cindex Displayed equations -@cindex Equations, displayed -For displayed equations, you must at present use @TeX{} directly -(@pxref{Raw Formatter Commands}). - - -@node Glyphs for Text -@section Glyphs for Text - -@anchor{Glyphs}@c old name -@anchor{TeX and copyright}@c another old node, now split into two -@cindex Glyphs for text -@cindex Textual glyphs - -Texinfo has support for a few additional glyphs that are commonly used -in printed text but not available in ASCII@. Of course, there are -many thousands more. It is possible to use Unicode characters as-is -as far as @code{makeinfo} is concerned, but @TeX{} is not so lucky. - -@menu -* @t{@@TeX @@LaTeX}:: The @TeX{} logos. -* @t{@@copyright}:: The copyright symbol (c in a circle). -* @t{@@registeredsymbol}:: The registered symbol (R in a circle). -* @t{@@dots}:: How to insert ellipses: @dots{} and @enddots{} -* @t{@@bullet}:: How to insert a bullet: @bullet{} -* @t{@@euro}:: How to insert the euro currency symbol. -* @t{@@pounds}:: How to insert the pounds currency symbol. -* @t{@@textdegree}:: How to insert the degrees symbol. -* @t{@@minus}:: How to insert a minus sign. -* @t{@@geq @@leq}:: How to insert greater/less-than-or-equal signs. -@end menu - - -@node @t{@@TeX @@LaTeX} -@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) - -@anchor{tex}@c old name -@findex TeX -@findex LaTeX -@cindex Logos, @TeX{} -@cindex @TeX{} logo -@cindex @LaTeX{} logo - -Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed -manual, this is a special logo that is different from three ordinary -letters. In Info, it just looks like @samp{TeX}. - -Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}', -which is even more special in printed manuals (and different from the -incorrect @code{La@@TeX@{@}}. In Info, the result is just -@samp{LaTeX}. (@LaTeX{} is another macro package built on top of -@TeX{}, very loosely analogous to Texinfo in that it emphasizes -logical structure, but much (much) larger.) - -The spelling of these commands are unusual for Texinfo, in that they -use both uppercase and lowercase letters. - - -@node @t{@@copyright} -@subsection @code{@@copyright@{@}} (@copyright{}) - -@anchor{copyright symbol}@c old name -@findex copyright -@cindex Copyright symbol - -Use the @code{@@copyright@{@}} command to generate the copyright -symbol, `@copyright{}'. Where possible, this is a @samp{c} inside a -circle; in Info, this is @samp{(C)}. - -Legally, it's not necessary to use the copyright symbol; the English -word `Copyright' suffices, according to international treaty. - - -@node @t{@@registeredsymbol} -@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) - -@anchor{registered symbol}@c old name -@findex registeredsymbol -@cindex Registered symbol - -Use the @code{@@registeredsymbol@{@}} command to generate the -registered symbol, `@registeredsymbol{}'. Where possible, this is an -@samp{R} inside a circle; in Info, this is @samp{(R)}. - - -@node @t{@@dots} -@subsection @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{}) - -@anchor{dots}@c old name -@findex dots -@findex enddots -@cindex Inserting dots -@cindex Inserting ellipsis -@cindex Dots, inserting -@cindex Ellipsis, inserting - -@anchor{Dots Bullets}@c old name - -An @dfn{ellipsis} (a sequence of dots) would be spaced wrong when -typeset as a string of periods, so a special command is used in -Texinfo: use the @code{@@dots@{@}} command to generate a normal -ellipsis, which is three dots in a row, appropriately spaced @dots{} -like so. To emphasize: do not simply write three periods in the input -file; that would work for the Info file output, but would produce the -wrong amount of space between the periods in the printed manual. - -The @code{@@enddots@{@}} command generates an end-of-sentence -ellipsis, which also has three dots, but with different spacing -afterwards, @enddots{} Look closely to see the difference. - -Here is an ellipsis: @dots{} -Here are three periods in a row: ... - -In printed (and usually HTML) output, the three periods in a row are -much closer together than the dots in the ellipsis. - - -@node @t{@@bullet} -@subsection @code{@@bullet} (@bullet{}) - -@anchor{bullet}@c old name -@findex bullet - -Use the @code{@@bullet@{@}} command to generate a large round dot, or -the closest possible thing to one. In Info, an asterisk is used. -Here is a bullet: @bullet{} - -When you use @code{@@bullet} in @code{@@itemize}, you do not need to -type the braces, because @code{@@itemize} supplies them. -(@pxref{@t{@@itemize}}). - - -@node @t{@@euro} -@subsection @code{@@euro} (@euro{}): Euro Currency Symbol - -@anchor{euro}@c old name -@findex euro -@cindex Euro symbol - -Use the @code{@@euro@{@}} command to generate `@euro{}'. Where -possible, this is the symbol for the Euro currency. Otherwise, the -word @samp{Euro} is used. - -Texinfo cannot magically synthesize support for the Euro symbol where -the underlying system (fonts, software, whatever) does not support it. -Therefore, you may find it preferable to use the word ``Euro''. (In -banking contexts, the abbreviation for the Euro is EUR.) - -@cindex ISO 8859-15, and Euro -@cindex Latin 9, and Euro -In order to get the Euro symbol in encoded Info output, for example, -it is necessary to specify @code{@@documentencoding ISO-8859-15} or -@code{@@documentencoding UTF-8} (@xref{@t{@@documentencoding}}.) -The Euro symbol is in ISO 8859-15 (aka Latin@tie{}9), and is -@emph{not} in the more widely-used ISO 8859-1 (Latin@tie{}1). - -@pindex feymr10 -@cindex Euro font -The Euro symbol does not exist in the standard @TeX{} fonts (which -were designed before the Euro was legislated into existence). -Therefore, @TeX{} uses an additional font, named @code{feymr10} (along -with other variables). It is freely available, of course; you can -download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym}, -among other places. The distribution includes installation -instructions. - - -@node @t{@@pounds} -@subsection @code{@@pounds} (@pounds{}): Pounds Sterling - -@anchor{pounds}@c old name -@findex pounds -@cindex Pounds symbol - -Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where -possible, this is the symbol for the pounds sterling British currency. -Otherwise, it is @samp{#}. - - -@node @t{@@textdegree} -@subsection @code{@@textdegree} (@textdegree{}): Degrees Symbol - -@anchor{textdegree}@c old name -@findex textdegree -@cindex Degree symbol - -Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. -Where possible, this is the normal symbol for degrees. Otherwise, -it is an @samp{o}. - - -@node @t{@@minus} -@subsection @code{@@minus} (@minus{}): Inserting a Minus Sign - -@anchor{minus}@c old name -@findex minus -@cindex Minus sign - -@cindex Em dash, compared to minus sign -@cindex Hyphen, compared to minus -Use the @code{@@minus@{@}} command to generate a minus sign. In a -fixed-width font, this is a single hyphen, but in a proportional font, -the symbol is the customary length for a minus sign---a little longer -than a hyphen, shorter than an em-dash: - -@display -@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, - -`-' is a hyphen generated with the character @samp{-}, - -`---' is an em-dash for text. -@end display - -@noindent -In the fixed-width font used by Info, @code{@@minus@{@}} is the same -as a hyphen. - -You should not use @code{@@minus@{@}} inside @code{@@code} or -@code{@@example} because the width distinction is not made in the -fixed-width font they use. - -When you use @code{@@minus} to specify the mark beginning each entry -in an itemized list, you do not need to type the braces -(@pxref{@t{@@itemize}}). - -If you actually want to typeset some math that does a subtraction, it -is better to use @code{@@math}. Then the regular @samp{-} character -produces a minus sign, as in @code{@@math@{a-b@}} (@pxref{Inserting -Math}). - - -@node @t{@@geq @@leq} -@subsection @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting Relations - -@anchor{geq leq}@c old name -@findex geq -@findex leq - -Use the @code{@@geq@{@}} and @code{@@leq@{@}} commands to generate -greater-than-or-equal and less-than-equal-signs, `@geq{}' and -`@leq{}'. When those symbols are not available, the ASCII sequences -@samp{>=} and @samp{<=} are output. - - -@node Glyphs for Programming -@section Glyphs for Programming - -@cindex Glyphs for programming -@cindex Examples, glyphs for -@cindex Programming, glyphs for - -In Texinfo, code is often illustrated in examples that are delimited -by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and -@code{@@end lisp}. In such examples, you can indicate the results of -evaluation or an expansion using @samp{@result{}} or -@samp{@expansion{}}. Likewise, there are commands to insert glyphs to -indicate printed output, error messages, equivalence of expressions, -the location of point in an editor, and GUI operation sequences. - -The glyph-insertion commands do not need to be used within an example, -but most often they are. All glyph-insertion commands are followed by -empty braces. - -@menu -* Glyphs Summary:: -* @t{@@result}:: How to show the result of expression. -* @t{@@expansion}:: How to indicate an expansion. -* @t{@@print}:: How to indicate generated output. -* @t{@@error}:: How to indicate an error message. -* @t{@@equiv}:: How to indicate equivalence. -* @t{@@point}:: How to indicate the location of point. -* Click Sequences:: Inserting GUI usage sequences. -@end menu - - -@node Glyphs Summary -@subsection Glyphs Summary - -Here is a summary of the glyph commands: - -@table @asis -@item @result{} -@code{@@result@{@}} indicates the result of an expression. - -@item @expansion{} -@code{@@expansion@{@}} indicates the results of a macro expansion. - -@item @print{} -@code{@@print@{@}} indicates printed output. - -@item @error{} -@code{@@error@{@}} indicates the following text is an error message. - -@item @equiv{} -@code{@@equiv@{@}} indicates the exact equivalence of two forms. - -@item @point{} -@code{@@point@{@}} shows the location of point. - -@item @clicksequence{A @click{} B} -@code{@@clicksequence@{A @@click@{@} B} indicates a GUI operation -sequence: first A, then clicking B, or choosing B from a menu, or -otherwise selecting it. -@end table - - -@node @t{@@result} -@subsection @code{@@result@{@}} (@result{}): Result of an Expression - -@anchor{result}@c old name -@findex result -@cindex Result of an expression -@cindex Indicating evaluation -@cindex Evaluation glyph -@cindex Value of an expression, indicating - -Use the @code{@@result@{@}} command to indicate the result of -evaluating an expression. - -The @code{@@result@{@}} command is displayed as @samp{@result{}}, -either a double stemmed arrow or (when that is not available) the -ASCII sequence @samp{=>}. - -Thus, the following, - -@lisp -(cdr '(1 2 3)) - @result{} (2 3) -@end lisp - -@noindent -may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. - - -@node @t{@@expansion} -@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion - -@anchor{expansion}@c old name -@cindex Expansion, indicating -@cindex Macro expansion, indicating -@findex expansion - -When an expression is a macro call, it expands into a new expression. -You can indicate the result of the expansion with the -@code{@@expansion@{@}} command. - -The @code{@@expansion@{@}} command is displayed as -@samp{@expansion{}}, either a long arrow with a flat base or (when -that is not available) the ASCII sequence @samp{==>}. - -@need 700 -For example, the following - -@example -@group -@@lisp -(third '(a b c)) - @@expansion@{@} (car (cdr (cdr '(a b c)))) - @@result@{@} c -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -@group -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end group -@end lisp - -@noindent -which may be read as: - -@quotation -@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; -the result of evaluating the expression is @code{c}. -@end quotation - -@noindent -Often, as in this case, an example looks better if the -@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. - - -@node @t{@@print} -@subsection @code{@@print@{@}} (@print{}): Indicating Generated Output - -@anchor{Print Glyph}@c old name -@findex print -@cindex Printed output, indicating - -Sometimes an expression will generate output during its execution. -You can indicate such displayed output with the @code{@@print@{@}} -command. - -The @code{@@print@{@}} command is displayed as @samp{@print{}}, either -a horizontal dash butting against a vertical bar or (when that is not -available) the ASCII sequence @samp{-|}. - -In the following example, the printed text is indicated with -@samp{@print{}}, and the value of the expression follows on the -last line. - -@lisp -@group -(progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end lisp - -@noindent -In a Texinfo source file, this example is written as follows: - -@lisp -@group -@@lisp -(progn (print 'foo) (print 'bar)) - @@print@{@} foo - @@print@{@} bar - @@result@{@} bar -@@end lisp -@end group -@end lisp - - -@node @t{@@error} -@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message - -@anchor{Error Glyph}@c old name -@cindex Error message, indicating -@findex error - -A piece of code may cause an error when you evaluate it. You can -designate the error message with the @code{@@error@{@}} command. - -The @code{@@error@{@}} command is displayed as @samp{@error{}}, either -the word `error' in a box in the printed output, the word error -followed by an arrow in other formats or (when no arrow is available) -@samp{error-->}. - -@need 700 -Thus, - -@example -@@lisp -(+ 23 'x) -@@error@{@} Wrong type argument: integer-or-marker-p, x -@@end lisp -@end example - -@noindent -produces - -@lisp -(+ 23 'x) -@error{} Wrong type argument: integer-or-marker-p, x -@end lisp - -@noindent -This indicates that the following error message is printed -when you evaluate the expression: - -@lisp -Wrong type argument: integer-or-marker-p, x -@end lisp - -The word @samp{@error{}} itself is not part of the error message. - - -@node @t{@@equiv} -@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence - -@anchor{Equivalence}@c oldname -@cindex Equivalence, indicating -@findex equiv - -Sometimes two expressions produce identical results. You can indicate -the exact equivalence of two forms with the @code{@@equiv@{@}} -command. The @code{@@equiv@{@}} command is displayed as -@samp{@equiv{}}, either a standard mathematical equivalence sign -(three parallel horizontal lines) or (when that is not available) as -the ASCII sequence @samp{==}. - -Thus, - -@example -@@lisp -(make-sparse-keymap) @@equiv@{@} (list 'keymap) -@@end lisp -@end example - -@noindent -produces - -@lisp -(make-sparse-keymap) @equiv{} (list 'keymap) -@end lisp - -@noindent -This indicates that evaluating @code{(make-sparse-keymap)} produces -identical results to evaluating @code{(list 'keymap)}. - - -@node @t{@@point} -@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer - -@anchor{Point Glyph}@c old name -@cindex Point, indicating in a buffer -@findex point - -Sometimes you need to show an example of text in an XEmacs buffer. In -such examples, the convention is to include the entire contents of the -buffer in question between two lines of dashes containing the buffer -name. - -You can use the @samp{@@point@{@}} command to show the location of -point in the text in the buffer. (The symbol for point, of course, is -not part of the text in the buffer; it indicates the place -@emph{between} two characters where point is located.) - -The @code{@@point@{@}} command is displayed as @samp{@point{}}, either -a pointed star or (when that is not available) the ASCII sequence -@samp{-!-}. - -The following example shows the contents of buffer @file{foo} before -and after evaluating a Lisp command to insert the word @code{changed}. - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -@example -@group -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -In a Texinfo source file, the example is written like this: - -@example -@@example ----------- Buffer: foo ---------- -This is the @@point@{@}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @@result@{@} nil ----------- Buffer: foo ---------- -This is the changed @@point@{@}contents of foo. ----------- Buffer: foo ---------- -@@end example -@end example - - -@node Click Sequences -@subsection Click Sequences - -@cindex Click sequences -@cindex Sequence of clicks -@cindex GUI click sequence - -@findex clicksequence -When documenting graphical interfaces, it is necessary to describe -sequences such as `Click on @samp{File}, then choose @samp{Open}, then -@dots{}'. Texinfo offers commands @code{@@clicksequence} and -@code{click} to represent this, typically used like this: - -@example -@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} -@end example - -@noindent -which produces: - -@display -@dots{} @clicksequence{File @click{} Open} @dots{} -@end display - -@findex click -@findex arrow -The @code{@@click} command produces a right arrow by default; this -glyph is also available independently via the command -@code{@@arrow@{@}}. - -@findex clickstyle -You can change the glyph produced by @code{@@click} with the command -@code{@@clickstyle}, which takes a command name as its single argument -on the rest of the line, much like @code{@@itemize} and friends -(@pxref{@t{@@itemize}}). The command should produce a glyph, and -the usual empty braces @samp{@{@}} are omitted. Here's an example: - -@example -@@clickstyle @@result -@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} -@end example - -@noindent -now produces: - -@display -@clickstyle @result -@dots{} @clicksequence{File @click{} Open} @dots{} -@end display - - -@node Breaks -@chapter Forcing and Preventing Breaks - -@cindex Forcing line and page breaks -@cindex Making line and page breaks -@cindex Preventing line and page breaks -@cindex Line breaks, awkward -@cindex Page breaks, awkward - -Line and page breaks can sometimes occur in the `wrong' place in one -or another form of output. It's up to you to ensure that text looks -right in all the output formats. - -For example, in a printed manual, page breaks may occur awkwardly in -the middle of an example; to prevent this, you can hold text together -using a grouping command that keeps the text from being split across -two pages. Conversely, you may want to force a page break where none -would occur normally. - -You can use the break, break prevention, or pagination commands to fix -problematic line and page breaks. - -@menu -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points. -* @t{@@allowcodebreaks}:: Controlling line breaks within @@code text. -* @t{@@w}:: Preventing unwanted line breaks in text. -* @t{@@tie}:: Inserting an unbreakable but varying space. -* @t{@@sp}:: Inserting blank lines. -* @t{@@page}:: Forcing the start of a new page. -* @t{@@group}:: Preventing unwanted page breaks. -* @t{@@need}:: Another way to prevent unwanted page breaks. -@end menu - - -@node Break Commands -@section Break Commands - -The break commands create or allow line and paragraph breaks: - -@table @code -@item @@* -Force a line break. - -@item @@sp @var{n} -Skip @var{n} blank lines. - -@item @@- -Insert a discretionary hyphen. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Define hyphen points in @var{hy-phen-a-ted words}. -@end table - -These commands hold text together on a single line: - -@table @code -@item @@w@{@var{text}@} -Prevent @var{text} from being split and hyphenated across two lines. - -@item @@tie@{@} -Insert a normal interword space at which a line break may not occur. -@end table - -The pagination commands apply only to printed output, since other -output formats do not have pages. - -@table @code -@item @@page -Start a new page. - -@item @@group -Hold text together that must appear on one page. - -@item @@need @var{mils} -Start a new page if not enough space on this one. -@end table - - -@node Line Breaks -@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks - -@findex * @r{(force line break)} -@findex / @r{(allow line break)} -@cindex Line breaks, controlling -@cindex Controlling line breaks -@cindex Breaks in a line -@cindex Force line break -@cindex Allow line break - -The @code{@@*} command forces a line break in all output formats. -The @code{@@/} command allows a line break (printed manual only). - -Here is an example with @code{@@*}: - -@example -This sentence is broken @@*into two lines. -@end example - -@noindent produces - -@example -@group -This sentence is broken -into two lines. -@end group -@end example - -The @code{@@/} command can often be useful within urls -(@pxref{@t{@@url}}), which tend to be long and are otherwise -unbreakable. For example: - -@example -The official Texinfo home page is on the GNU web site: -@@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}. -@end example - -@noindent produces - -@quotation -The official Texinfo home page is on the GNU web site: -@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. -@end quotation - -@noindent Without the @code{@@/} commands, @TeX{} would have nowhere to -break the url. @code{@@/} has no effect in other output formats. - - -@node @t{@@- @@hyphenation} -@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate - -@anchor{- and hyphenation}@c old name -@findex - @r{(discretionary hyphen)} -@findex hyphenation -@cindex Hyphenation, helping @TeX{} do -@cindex Fine-tuning, and hyphenation - -Although @TeX{}'s hyphenation algorithm is generally pretty good, it -does miss useful hyphenation points from time to time. (Or, far more -rarely, insert an incorrect hyphenation.) So, for documents with an -unusual vocabulary or when fine-tuning for a printed edition, you may -wish to help @TeX{} out. Texinfo supports two commands for this: - -@table @code -@item @@- -Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does -not have to) hyphenate. This is especially useful when you notice an -overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull -hboxes}). @TeX{} will not insert any hyphenation points itself into a -word containing @code{@@-}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you -put a @samp{-} at each hyphenation point. For example: -@example -@@hyphenation@{man-u-script man-u-scripts@} -@end example -@noindent @TeX{} only uses the specified hyphenation points when the -words match exactly, so give all necessary variants, such as plurals. -@end table - -Info, HTML, and other non-@TeX{} output is not hyphenated, so none of -these commands have any effect there. - - -@node @t{@@allowcodebreaks} -@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} - -@anchor{allowcodebreaks}@c old name -@findex allowcodebreaks -@cindex Breaks, within @code{@@code} -@cindex -, breakpoint within @code{@@code} -@cindex Hyphen, breakpoint within @code{@@code} -@cindex Dash, breakpoint within @code{@@code} -@cindex _, breakpoint within @code{@@code} -@cindex Underscore, breakpoint within @code{@@code} - -Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_} -characters within @code{@@code} and related commands -(@pxref{@t{@@code}}), more or less as if they were ``empty'' -hyphenation points. - -This is necessary since many manuals, especially for Lisp-family -languages, must document very long identifiers. On the other hand, -some manuals don't have this problems, and you may not wish to allow a -line break at the underscore in, for example, @code{SIZE_MAX}, or even -worse, after any of the four underscores in @code{__typeof__}. - -So Texinfo provides this command: - -@example -@@allowcodebreaks false -@end example - -@noindent to prevent from breaking at @samp{-} or @samp{_} within -@code{@@code}. You can go back to allowing such breaks with -@code{@@allowcodebreaks true}. Write these commands on lines by -themselves. - -These commands can be given anywhere in the document. For example, -you may have just one problematic paragraph where you need to turn off -the breaks, but want them in general, or vice versa. - -This command has no effect except in HTML and @TeX{} output. - - -@node @t{@@w} -@section @code{@@w}@{@var{text}@}: Prevent Line Breaks - -@anchor{w}@c old name -@findex w @r{(prevent line break)} -@cindex Line breaks, preventing - -@code{@@w@{@var{text}@}} outputs @var{text}, while prohibiting line -breaks within @var{text}. - -@cindex Non-breakable space, fixed -@cindex Unbreakable space, fixed -Thus, you can use @code{@@w} to produce a non-breakable space, fixed at -the width of a normal interword space: - -@example -@@w@{ @} @@w@{ @} @@w@{ @} indentation. -@end example - -@noindent produces: - -@display -@w{ } @w{ } @w{ } indentation. -@end display - -The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, -also will not stretch or shrink. Sometimes that is what you want, for -instance if you're doing manual indenting. However, usually you want -a normal interword space that does stretch and shrink (in the printed -output); for that, see the @code{@@tie} command in the next section. - -@cindex Hyphenation, preventing -You can also use the @code{@@w} command to prevent @TeX{} from -automatically hyphenating a long name or phrase that happens to fall -near the end of a line. @command{makeinfo} does not ever hyphenate -words. - -@cindex Keyword expansion, preventing -@cindex Version control keywords, preventing expansion of -@cindex $Id expansion, preventing -You can also use @code{@@w} to avoid unwanted keyword expansion in -source control systems. For example, to literally write @t{@w{$}Id$} -in your document, use @code{@@w@{$@}Id$}. This trick isn't effective -in Info or plain text output, though. - - -@node @t{@@tie} -@section @code{@@tie@{@}}: Inserting an Unbreakable Space - -@anchor{tie}@c old name -@findex tie @r{(unbreakable interword space)} -@cindex Tied space -@cindex Non-breakable space, variable -@cindex Unbreakable space, variable - -The @code{@@tie@{@}} command produces a normal interword space at which -a line break may not occur. Always write it with following (empty) -braces, as usual for commands used within a paragraph. Here's an -example: - -@example -@@TeX@{@} was written by Donald E.@@tie@{@}Knuth. -@end example - -@noindent produces: - -@display -@TeX{} was written by Donald E.@tie{}Knuth. -@end display - -There are two important differences between @code{@@tie@{@}} and -@code{@@w@{@w{ }@}}: - -@itemize -@item -The space produced by @code{@@tie@{@}} will stretch and shrink slightly -along with the normal interword spaces in the paragraph; the space -produced by @code{@@w@{@w{ }@}} will not vary. - -@item -@code{@@tie@{@}} allows hyphenation of the surrounding words, while -@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical -reasons, namely that it produces an @samp{\hbox}). - -@end itemize - - -@node @t{@@sp} -@section @code{@@sp} @var{n}: Insert Blank Lines - -@anchor{sp}@c old name -@findex sp @r{(line spacing)} -@cindex Space, inserting vertical -@cindex Blank lines -@cindex Line spacing - -A line beginning with and containing only @code{@@sp @var{n}} -generates @var{n} blank lines of space in both the printed manual and -the Info file. @code{@@sp} also forces a paragraph break. For -example, - -@example -@@sp 2 -@end example - -@noindent -generates two blank lines. - -The @code{@@sp} command is most often used in the title page. - - -@node @t{@@page} -@section @code{@@page}: Start a New Page - -@anchor{page}@c old name -@findex page -@cindex Page breaks, forcing - -A line containing only @code{@@page} starts a new page in a printed -manual. In other formats, without the concept of pages, it starts a -new paragraph. An @code{@@page} command is often used in the -@code{@@titlepage} section of a Texinfo file to start the copyright -page. - - -@node @t{@@group} -@section @code{@@group}: Prevent Page Breaks - -@anchor{group}@c old name -@findex group -@cindex Group (hold text together vertically) -@cindex Holding text together vertically -@cindex Vertically holding text together - -The @code{@@group} command (on a line by itself) is used inside an -@code{@@example} or similar construct to begin an unsplittable vertical -group, which will appear entirely on one page in the printed output. -The group is terminated by a line containing only @code{@@end group}. -These two lines produce no output of their own, and in the Info file -output they have no effect at all. - -@c Once said that these environments -@c turn off vertical spacing between ``paragraphs''. -@c Also, quotation used to work, but doesn't in texinfo-2.72 -Although @code{@@group} would make sense conceptually in a wide -variety of contexts, its current implementation works reliably only -within @code{@@example} and variants, and within @code{@@display}, -@code{@@format}, @code{@@flushleft} and @code{@@flushright}. -@xref{Quotations and Examples}. (What all these commands have in -common is that each line of input produces a line of output.) In -other contexts, @code{@@group} can cause anomalous vertical -spacing. - -@need 750 -This formatting requirement means that you should write: - -@example -@group -@@example -@@group -@dots{} -@@end group -@@end example -@end group -@end example - -@noindent -with the @code{@@group} and @code{@@end group} commands inside the -@code{@@example} and @code{@@end example} commands. - -The @code{@@group} command is most often used to hold an example -together on one page. In this Texinfo manual, more than 100 examples -contain text that is enclosed between @code{@@group} and @code{@@end -group}. - -If you forget to end a group, you may get strange and unfathomable -error messages when you run @TeX{}. This is because @TeX{} keeps -trying to put the rest of the Texinfo file onto the one page and does -not start to generate error messages until it has processed -considerable text. It is a good rule of thumb to look for a missing -@code{@@end group} if you get incomprehensible error messages in -@TeX{}. - - -@node @t{@@need} -@section @code{@@need @var{mils}}: Prevent Page Breaks - -@anchor{need}@c old name -@findex need -@cindex Need space at page bottom -@cindex Mils, argument to @code{@@need} - -A line containing only @code{@@need @var{n}} starts a new page in a -printed manual if fewer than @var{n} mils (thousandths of an inch) -remain on the current page. Do not use braces around the argument -@var{n}. The @code{@@need} command has no effect on other output -formats since they are not paginated. - -@need 800 -This paragraph is preceded by an @code{@@need} command that tells -@TeX{} to start a new page if fewer than 800 mils (eight-tenths -inch) remain on the page. It looks like this: - -@example -@group -@@need 800 -This paragraph is preceded by @dots{} -@end group -@end example - -@cindex Orphans, preventing -The @code{@@need} command is useful for preventing orphans: single -lines at the bottoms of printed pages. - - -@node Definition Commands -@chapter Definition Commands -@cindex Definition commands - -The @code{@@deffn} command and the other @dfn{definition commands} -enable you to describe functions, variables, macros, commands, user -options, special forms and other such artifacts in a uniform -format. - -In the Info file, a definition causes the entity -category---`Function', `Variable', or whatever---to appear at the -beginning of the first line of the definition, followed by the -entity's name and arguments. In the printed manual, the command -causes @TeX{} to print the entity's name and its arguments on the left -margin and print the category next to the right margin. In both -output formats, the body of the definition is indented. Also, the -name of the entity is entered into the appropriate index: -@code{@@deffn} enters the name into the index of functions, -@code{@@defvr} enters it into the index of variables, and so -on (@pxref{Predefined Indices}). - -A manual need not and should not contain more than one definition for -a given name. An appendix containing a summary should use -@code{@@table} rather than the definition commands. - -@menu -* Def Cmd Template:: Writing descriptions using definition commands. -* Def Cmd Continuation Lines:: Continuing the heading over source lines. -* Optional Arguments:: Handling optional and repeated arguments. -* @t{@@deffnx}:: Group two or more `first' lines. -* Def Cmds in Detail:: Reference for all the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: An example. -@end menu - - -@node Def Cmd Template -@section The Template for a Definition -@cindex Definition template -@cindex Template for a definition - -The @code{@@deffn} command is used for definitions of entities that -resemble functions. To write a definition using the @code{@@deffn} -command, write the @code{@@deffn} command at the beginning of a line -and follow it on the same line by the category of the entity, the name -of the entity itself, and its arguments (if any). Then write the body -of the definition on succeeding lines. (You may embed examples in the -body.) Finally, end the definition with an @code{@@end deffn} command -written on a line of its own. - -The other definition commands follow the same format: a line with the -@code{@@def@dots{}} command and whatever arguments are appropriate for -that command; the body of the definition; and a corresponding -@code{@@end} line. - -The template for a definition looks like this: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@deffn Command forward-word count -This command moves point forward @@var@{count@} words -(or backward if @@var@{count@} is negative). @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@quotation -@deffn Command forward-word count -This command moves point forward @var{count} words -(or backward if @var{count} is negative). @dots{} -@end deffn -@end quotation - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', -enclose it in braces. For example: - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@dots{} -@@end deffn -@end group -@end example - -@noindent -Otherwise, the second word will be mistaken for the name of the -entity. As a general rule, when any of the arguments in the heading -line @emph{except} the last one are more than one word, you need to -enclose them in braces. This may also be necessary if the text -contains commands, for example, @samp{@{declaraci@@'on@}} if you are -writing in Spanish. - -Some of the definition commands are more general than others. The -@code{@@deffn} command, for example, is the general definition command -for functions and the like---for entities that may take arguments. -When you use this command, you specify the category to which the -entity belongs. Three predefined, specialized variations -(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the -category for you: ``Function'', ``Macro'', and ``Special Form'' -respectively. (In Lisp, a special form is an entity much like a -function.) Similarly, the general @code{@@defvr} command is -accompanied by several specialized variations for describing -particular kinds of variables. - -@xref{Sample Function Definition}, for a detailed example of a -function definition, including the use of @code{@@example} inside the -definition. - - -@node Def Cmd Continuation Lines -@section Definition Command Continuation Lines -@cindex Continuation lines in definition commands -@cindex Definition command headings, continuing -@cindex @samp{@@} as continuation in definition commands - -The heading line of a definition command can get very long. -Therefore, Texinfo has a special syntax allowing them to be continued -over multiple lines of the source file: a lone @samp{@@} at the end of -each line to be continued. Here's an example: - -@example -@@defun fn-name @@ - arg1 arg2 arg3 -This is the basic continued defun. -@@end defun -@end example - -@noindent produces: - -@defun fn-name arg1 arg2 arg3 -This is the basic continued defun. -@end defun - -@noindent -As you can see, the continued lines are combined, as if they had been -typed on one source line. - -Although this example only shows a one-line continuation, -continuations may extend over any number of lines, in the same way; -put an @code{@@} at the end of each line to be continued. - -@cindex Whitespace, collapsed around continuations -@cindex Collapsing whitespace around continuations -In general, any number of spaces or tabs before the @code{@@} -continuation character are collapsed into a single space. There is one -exception: the Texinfo processors will not fully collapse whitespace -around a continuation inside braces. For example: - -@example -@@deffn @{Category @@ - Name@} @dots{} -@end example - -@noindent The output (not shown) has excess space between `Category' -and `Name'. To avoid this, elide the unwanted whitespace in your -input, or put the continuation @code{@@} outside braces. - -@code{@@} does not function as a continuation character in @emph{any} -other context. Ordinarily, @samp{@@} followed by a whitespace -character (space, tab, newline) produces a normal interword space -(@pxref{Multiple Spaces}). - - -@node Optional Arguments -@section Optional and Repeated Arguments -@cindex Optional and repeated arguments -@cindex Repeated and optional arguments -@cindex Arguments, repeated and optional -@cindex Syntax, optional & repeated arguments -@cindex Meta-syntactic chars for arguments - -@c This is consistent with the XEmacs Lisp Reference Manual. -Some entities take optional or repeated arguments, conventionally -specified by using square brackets and ellipses: an argument enclosed -within square brackets is optional, and an argument followed by an -ellipsis is optional and may be repeated more than once. - -Thus, [@var{optional-arg}] means that @var{optional-arg} is optional -and @var{repeated-args}@samp{@dots{}} stands for zero or more -arguments. Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. - -Here is the @code{@@defspec} line of an example of an imaginary -(complicated) special form: - -@quotation -@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -@end defspec -@c tex -@c \vskip \parskip -@c end tex -@end quotation - -@noindent -In this example, the arguments @var{from} and @var{to} are optional, -but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the -form. - -In a Texinfo source file, this @code{@@defspec} line is written like -this, including a continuation to avoid a long source line. - -@example -@group -@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} @@ - [@@var@{inc@}]]) @@var@{body@}@@dots@{@} -@end group -@end example - -@noindent -The function is listed in the Command and Variable Index under -@samp{foobar}. - - -@node @t{@@deffnx} -@section @code{@@deffnx}, et al.: Two or More `First' Lines - -@anchor{deffnx}@c old node -@findex deffnx -@cindex Two `First' Lines for @code{@@deffn} -@cindex Grouping two definitions together -@cindex Definitions grouped together - -To create two or more `first' or header lines for a definition, follow -the first @code{@@deffn} line by a line beginning with -@code{@@deffnx}. The @code{@@deffnx} command works exactly like -@code{@@deffn} except that it does not generate extra vertical white -space between it and the preceding line. - -@need 1000 -For example, - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@@deffnx @{Interactive Command@} isearch-backward -These two search commands are similar except @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@deffn {Interactive Command} isearch-forward -@deffnx {Interactive Command} isearch-backward -These two search commands are similar except @dots{} -@end deffn - -Each definition command has an `x' form: @code{@@defunx}, -@code{@@defvrx}, @code{@@deftypefunx}, etc. - -The `x' forms work similarly to @code{@@itemx} -(@pxref{@t{@@itemx}}). - - -@node Def Cmds in Detail -@section The Definition Commands - -Texinfo provides more than a dozen definition commands, all of which -are described in this section. - -The definition commands automatically enter the name of the entity in -the appropriate index: for example, @code{@@deffn}, @code{@@defun}, -and @code{@@defmac} enter function names in the index of functions; -@code{@@defvr} and @code{@@defvar} enter variable names in the index -of variables. - -Although the examples that follow mostly illustrate Lisp, the commands -can be used for other programming languages. - -@menu -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Data Types:: The definition command for data types. -* Abstract Objects:: Commands for object-oriented programming. -@end menu - -@node Functions Commands -@subsection Functions and Similar Entities - -This section describes the commands for describing functions and similar -entities: - -@table @code -@findex deffn -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -The @code{@@deffn} command is the general definition command for -functions, interactive commands, and similar entities that may take -arguments. You must choose a term to describe the category of entity -being defined; for example, ``Function'' could be used if the entity is -a function. The @code{@@deffn} command is written at the beginning of a -line and is followed on the same line by the category of entity being -described, the name of this particular entity, and its arguments, if -any. Terminate the definition with @code{@@end deffn} on a line of its -own. - -@need 750 -For example, here is a definition: - -@example -@group -@@deffn Command forward-char nchars -Move point forward @@var@{nchars@} characters. -@@end deffn -@end group -@end example - -@noindent -This shows a rather terse definition for a ``command'' named -@code{forward-char} with one argument, @var{nchars}. - -@code{@@deffn} prints argument names such as @var{nchars} in slanted -type in the printed output, because we think of these names as -metasyntactic variables---they stand for the actual argument values. -Within the text of the description, however, write an argument name -explicitly with @code{@@var} to refer to the value of the argument. -In the example above, we used @samp{@@var@{nchars@}} in this way. - -In the extremely unusual case when an argument name contains -@samp{--}, or another character sequence which is treated specially -(@pxref{Conventions}), use @code{@@code} around the special -characters. This avoids the conversion to typographic en-dashes and -em-dashes. -@c @var also works; that's what we used to recommend. - -The template for @code{@@deffn} is: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@findex defun -@item @@defun @var{name} @var{arguments}@dots{} -The @code{@@defun} command is the definition command for functions. -@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}. -Terminate the definition with @code{@@end defun} on a line of its own. -Thus, the template is: - -@example -@group -@@defun @var{function-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@findex defmac -@item @@defmac @var{name} @var{arguments}@dots{} -The @code{@@defmac} command is the definition command for macros. -@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and -works like @code{@@defun}. - -@findex defspec -@item @@defspec @var{name} @var{arguments}@dots{} -The @code{@@defspec} command is the definition command for special -forms. (In Lisp, a special form is an entity much like a function; -@pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.) -@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} -@dots{}} and works like @code{@@defun}. -@end table - -All these commands create entries in the index of functions. - - -@node Variables Commands -@subsection Variables and Similar Entities - -Here are the commands for defining variables and similar -entities: - -@table @code -@findex defvr -@item @@defvr @var{category} @var{name} -The @code{@@defvr} command is a general definition command for -something like a variable---an entity that records a value. You must -choose a term to describe the category of entity being defined; for -example, ``Variable'' could be used if the entity is a variable. -Write the @code{@@defvr} command at the beginning of a line and -follow it on the same line by the category of the entity and the -name of the entity. - -We recommend capitalizing the category name like a title. If the name -of the category contains spaces, as in the name ``User Option'', -enclose it in braces. Otherwise, the second word will be mistaken for -the name of the entity. For example, - -@example -@group -@@defvr @{User Option@} fill-column -This buffer-local variable specifies -the maximum width of filled lines. -@dots{} -@@end defvr -@end group -@end example - -Terminate the definition with @code{@@end defvr} on a line of its -own. - -The template is: - -@example -@group -@@defvr @var{category} @var{name} -@var{body-of-definition} -@@end defvr -@end group -@end example - -@code{@@defvr} creates an entry in the index of variables for @var{name}. - -@findex defvar -@item @@defvar @var{name} -The @code{@@defvar} command is the definition command for variables. -@code{@@defvar} is equivalent to @samp{@@defvr Variable -@dots{}}. - -@need 750 -For example: - -@example -@group -@@defvar kill-ring -@dots{} -@@end defvar -@end group -@end example - -The template is: - -@example -@group -@@defvar @var{name} -@var{body-of-definition} -@@end defvar -@end group -@end example - -@code{@@defvar} creates an entry in the index of variables for -@var{name}. - -@findex defopt -@item @@defopt @var{name} -@cindex User options, marking -The @code{@@defopt} command is the definition command for @dfn{user -options}, i.e., variables intended for users to change according to -taste; XEmacs has many such (@pxref{Variables,,, xemacs, XEmacs User's -Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}. It creates an entry -in the index of variables. -@end table - - -@node Typed Functions -@subsection Functions in Typed Languages - -@cindex Typed functions -@cindex Functions, in typed languages - -The @code{@@deftypefn} command and its variations are for describing -functions in languages in which you must declare types of variables -and functions, such as C and C++. - -@table @code -@findex deftypefn -@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefn} command is the general definition command for -functions and similar entities that may take arguments and that are -typed. The @code{@@deftypefn} command is written at the beginning of -a line and is followed on the same line by the category of entity -being described, the type of the returned value, the name of this -particular entity, and its arguments, if any. - -@need 800 -@noindent -For example, - -@example -@group -@@deftypefn @{Library Function@} int foobar @@ - (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefn -@end group -@end example - -produces: - -@quotation -@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefn -@end quotation - -This means that @code{foobar} is a ``library function'' that returns an -@code{int}, and its arguments are @var{foo} (an @code{int}) and -@var{bar} (a @code{float}). - -Since in typed languages, the actual names of the arguments are -typically scattered among data type names and keywords, Texinfo cannot -find them without help. You can either (a)@tie{}write everything as -straight text, and it will be printed in slanted type; (b)@tie{}use -@code{@@var} for the variable names, which will uppercase the variable -names in Info and use the slanted typewriter font in printed output; -(c)@tie{}use @code{@@var} for the variable names and @code{@@code} for -the type names and keywords, which will be dutifully obeyed. - -The template for @code{@@deftypefn} is: - -@example -@group -@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} -@var{body-of-description} -@@end deftypefn -@end group -@end example - -@noindent -Note that if the @var{category} or @var{data type} is more than one -word then it must be enclosed in braces to make it a single argument. - -If you are describing a procedure in a language that has packages, -such as Ada, you might consider using @code{@@deftypefn} in a manner -somewhat contrary to the convention described in the preceding -paragraphs. For example: - -@example -@group -@@deftypefn stacks private push @@ - (@@var@{s@}:in out stack; @@ - @@var@{n@}:in integer) -@dots{} -@@end deftypefn -@end group -@end example - -@noindent -(In these examples the @code{@@deftypefn} arguments are shown using -continuations (@pxref{Def Cmd Continuation Lines}), but could be on a -single line.) - -In this instance, the procedure is classified as belonging to the -package @code{stacks} rather than classified as a `procedure' and its -data type is described as @code{private}. (The name of the procedure -is @code{push}, and its arguments are @var{s} and @var{n}.) - -@code{@@deftypefn} creates an entry in the index of functions for -@var{name}. - -@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} -@findex deftypefun -The @code{@@deftypefun} command is the specialized definition command -for functions in typed languages. The command is equivalent to -@samp{@@deftypefn Function @dots{}}. The template is: - -@example -@group -@@deftypefun @var{type} @var{name} @var{arguments}@dots{} -@var{body-of-description} -@@end deftypefun -@end group -@end example - -@code{@@deftypefun} creates an entry in the index of functions for -@var{name}. - -@end table - -@cindex Return type, own line for -@findex deftypefnnewline -Ordinarily, the return type is printed on the same line as the -function name and arguments, as shown above. In source code, GNU -style is to put the return type on a line by itself. So Texinfo -provides an option to do that: @code{@@deftypefnnewline on}. - -This affects typed functions only---not untyped functions, not typed -variables, etc.. Specifically, it affects the commands in this -section, and the analogous commands for object-oriented languages, -namely @code{@@deftypeop} and @code{@@deftypemethod} -(@pxref{Object-Oriented Methods}). - -Specifying @code{@@deftypefnnewline off} reverts to the default. - - -@node Typed Variables -@subsection Variables in Typed Languages - -@cindex Typed variables -@cindex Variables, in typed languages - -Variables in typed languages are handled in a manner similar to -functions in typed languages. @xref{Typed Functions}. The general -definition command @code{@@deftypevr} corresponds to -@code{@@deftypefn} and the specialized definition command -@code{@@deftypevar} corresponds to @code{@@deftypefun}. - -@table @code -@findex deftypevr -@item @@deftypevr @var{category} @var{data-type} @var{name} -The @code{@@deftypevr} command is the general definition command for -something like a variable in a typed language---an entity that records -a value. You must choose a term to describe the category of the -entity being defined; for example, ``Variable'' could be used if the -entity is a variable. - -The @code{@@deftypevr} command is written at the beginning of a line -and is followed on the same line by the category of the entity -being described, the data type, and the name of this particular -entity. - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevr @{Global Flag@} int enable -@dots{} -@@end deftypevr -@end group -@end example - -@noindent -produces the following: - -@quotation -@deftypevr {Global Flag} int enable -@dots{} -@end deftypevr -@end quotation - -@need 800 -The template is: - -@example -@@deftypevr @var{category} @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevr -@end example - -@findex deftypevar -@item @@deftypevar @var{data-type} @var{name} -The @code{@@deftypevar} command is the specialized definition command -for variables in typed languages. @code{@@deftypevar} is equivalent -to @samp{@@deftypevr Variable @dots{}}. The template is: - -@example -@group -@@deftypevar @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevar -@end group -@end example -@end table - -These commands create entries in the index of variables. - - -@node Data Types -@subsection Data Types - -Here is the command for data types: - -@table @code -@findex deftp -@item @@deftp @var{category} @var{name} @var{attributes}@dots{} -The @code{@@deftp} command is the generic definition command for data -types. The command is written at the beginning of a line and is -followed on the same line by the category, by the name of the type -(which is a word like @code{int} or @code{float}), and then by names of -attributes of objects of that type. Thus, you could use this command -for describing @code{int} or @code{float}, in which case you could use -@code{data type} as the category. (A data type is a category of -certain objects for purposes of deciding which operations can be -performed on them.) - -In Lisp, for example, @dfn{pair} names a particular data -type, and an object of that type has two slots called the -@sc{car} and the @sc{cdr}. Here is how you would write the first line -of a definition of @code{pair}. - -@example -@group -@@deftp @{Data type@} pair car cdr -@dots{} -@@end deftp -@end group -@end example - -@need 950 -The template is: - -@example -@group -@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@var{body-of-definition} -@@end deftp -@end group -@end example - -@code{@@deftp} creates an entry in the index of data types. -@end table - - -@node Abstract Objects -@subsection Object-Oriented Programming - -@cindex Object-oriented programming - -Here are the commands for formatting descriptions about abstract -objects, such as are used in object-oriented programming. A class is -a defined type of abstract object. An instance of a class is a -particular object that has the type of the class. An instance -variable is a variable that belongs to the class but for which each -instance has its own value. - -@menu -* Variables: Object-Oriented Variables. -* Methods: Object-Oriented Methods. -@end menu - - -@node Object-Oriented Variables -@subsubsection Object-Oriented Variables - -@cindex Variables, object-oriented - -These commands allow you to define different sorts of variables in -object-oriented programming languages. - -@table @code -@item @@defcv @var{category} @var{class} @var{name} -@findex defcv -The @code{@@defcv} command is the general definition command for -variables associated with classes in object-oriented programming. The -@code{@@defcv} command is followed by three arguments: the category of -thing being defined, the class to which it belongs, and its -name. For instance: - -@example -@group -@@defcv @{Class Option@} Window border-pattern -@dots{} -@@end defcv -@end group -@end example - -@noindent produces: -@defcv {Class Option} Window border-pattern -@dots{} -@end defcv - -@code{@@defcv} creates an entry in the index of variables. - -@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} -@findex deftypecv -The @code{@@deftypecv} command is the definition command for typed -class variables in object-oriented programming. It is analogous to -@code{@@defcv} with the addition of the @var{data-type} parameter to -specify the type of the instance variable. Ordinarily, the data type -is a programming language construct that should be marked with -@code{@@code}. For instance: - -@example -@group -@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern -@dots{} -@@end deftypecv -@end group -@end example - -@noindent produces: - -@deftypecv {Class Option} Window @code{int} border-pattern -@dots{} -@end deftypecv - -@code{@@deftypecv} creates an entry in the index of variables. - -@item @@defivar @var{class} @var{name} -@findex defivar -The @code{@@defivar} command is the definition command for instance -variables in object-oriented programming. @code{@@defivar} is -equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For -instance: - -@example -@group -@@defivar Window border-pattern -@dots{} -@@end defivar -@end group -@end example - -@noindent produces: - -@defivar Window border-pattern -@dots{} -@end defivar - -@code{@@defivar} creates an entry in the index of variables. - -@item @@deftypeivar @var{class} @var{data-type} @var{name} -@findex deftypeivar -The @code{@@deftypeivar} command is the definition command for typed -instance variables in object-oriented programming. It is analogous to -@code{@@defivar} with the addition of the @var{data-type} parameter to -specify the type of the instance variable. Ordinarily, the data type -is a programming language construct that should be marked with -@code{@@code}. For instance: - -@example -@group -@@deftypeivar Window @@code@{int@} border-pattern -@dots{} -@@end deftypeivar -@end group -@end example - -@noindent produces: - -@deftypeivar Window @code{int} border-pattern -@dots{} -@end deftypeivar - -@code{@@deftypeivar} creates an entry in the index of variables. - -@end table - - -@node Object-Oriented Methods -@subsubsection Object-Oriented Methods - -@cindex Methods, object-oriented - -These commands allow you to define different sorts of function-like -entities resembling methods in object-oriented programming languages. -These entities take arguments, as functions do, but are associated with -particular classes of objects. - -@table @code - -@findex defop -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defop} command is the general definition command for these -method-like entities. - -For example, some systems have constructs called @dfn{wrappers} that -are associated with classes as methods are, but that act more like -macros than like functions. You could use @code{@@defop Wrapper} to -describe one of these. - -Sometimes it is useful to distinguish methods and @dfn{operations}. -You can think of an operation as the specification for a method. -Thus, a window system might specify that all window classes have a -method named @code{expose}; we would say that this window system -defines an @code{expose} operation on windows in general. Typically, -the operation has a name and also specifies the pattern of arguments; -all methods that implement the operation must accept the same -arguments, since applications that use the operation do so without -knowing which method will implement it. - -Often it makes more sense to document operations than methods. For -example, window application developers need to know about the -@code{expose} operation, but need not be concerned with whether a -given class of windows has its own method to implement this operation. -To describe this operation, you would write: - -@example -@@defop Operation windows expose -@end example - -The @code{@@defop} command is written at the beginning of a line and -is followed on the same line by the overall name of the category of -operation, the name of the class of the operation, the name of the -operation, and its arguments, if any. - -The template is: -@example -@group -@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defop -@end group -@end example - -@code{@@defop} creates an entry, such as `@code{expose} on -@code{windows}', in the index of functions. - -@findex deftypeop -@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypeop} command is the definition command for typed -operations in object-oriented programming. It is similar to -@code{@@defop} with the addition of the @var{data-type} parameter to -specify the return type of the method. @code{@@deftypeop} creates an -entry in the index of functions. - -@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} -@findex defmethod -The @code{@@defmethod} command is the definition command for methods -in object-oriented programming. A method is a kind of function that -implements an operation for a particular class of objects and its -subclasses. -@ignore -@c ADR: Who cares?!? -@c KB: Oh, I don't know, I think this info is crucial! -In the Lisp Machine, methods actually were functions, but -they were usually defined with @code{defmethod}. -@end ignore - -@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. -The command is written at the beginning of a line and is followed by -the name of the class of the method, the name of the method, and its -arguments, if any. - -@noindent -For example: -@example -@group -@@defmethod @code{bar-class} bar-method argument -@dots{} -@@end defmethod -@end group -@end example - -@noindent -illustrates the definition for a method called @code{bar-method} of -the class @code{bar-class}. The method takes an argument. - -@code{@@defmethod} creates an entry in the index of functions. - -@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -@findex defmethod -The @code{@@deftypemethod} command is the definition command for methods -in object-oriented typed languages, such as C++ and Java. It is similar -to the @code{@@defmethod} command with the addition of the -@var{data-type} parameter to specify the return type of the method. -@code{@@deftypemethod} creates an entry in the index of functions. - -@end table - -The typed commands are affected by the @code{@@deftypefnnewline} -option (@pxref{Typed Functions,, Functions in Typed Languages}). - - -@node Def Cmd Conventions -@section Conventions for Writing Definitions -@cindex Definition conventions -@cindex Conventions for writing definitions - -When you write a definition using @code{@@deffn}, @code{@@defun}, or -one of the other definition commands, please take care to use -arguments that indicate the meaning, as with the @var{count} argument -to the @code{forward-word} function. Also, if the name of an argument -contains the name of a type, such as @var{integer}, take care that the -argument actually is of that type. - - -@node Sample Function Definition -@section A Sample Function Definition -@cindex Function definitions -@cindex Command definitions -@cindex Macro definitions, programming-language -@cindex Sample function definition - -A function definition uses the @code{@@defun} and @code{@@end defun} -commands. The name of the function follows immediately after the -@code{@@defun} command and it is followed, on the same line, by the -parameter list. - -Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp -Reference Manual}. - -@quotation -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just -like @code{funcall} but with one difference: the last of -@var{arguments} is a list of arguments to give to -@var{function}, rather than a single argument. We also say -that this list is @dfn{appended} to the other arguments. - -@code{apply} returns the result of calling @var{function}. -As with @code{funcall}, @var{function} must either be a Lisp -function or a primitive function; special forms and macros -do not make sense in @code{apply}. - -@example -(setq f 'list) - @result{} list -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @result{} 10 -(apply '+ '(1 2 3 4)) - @result{} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end example - -An interesting example of using @code{apply} is found in the description -of @code{mapcar}. -@end defun -@end quotation - -In the Texinfo source file, this example looks like this: - -@example -@group -@@defun apply function &rest arguments -@@code@{apply@} calls @@var@{function@} with -@@var@{arguments@}, just like @@code@{funcall@} but with one -difference: the last of @@var@{arguments@} is a list of -arguments to give to @@var@{function@}, rather than a single -argument. We also say that this list is @@dfn@{appended@} -to the other arguments. -@end group - -@group -@@code@{apply@} returns the result of calling -@@var@{function@}. As with @@code@{funcall@}, -@@var@{function@} must either be a Lisp function or a -primitive function; special forms and macros do not make -sense in @@code@{apply@}. -@end group - -@group -@@example -(setq f 'list) - @@result@{@} list -(apply f 'x 'y 'z) -@@error@{@} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @@result@{@} 10 -(apply '+ '(1 2 3 4)) - @@result@{@} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @@result@{@} (a b c x y z) -@@end example -@end group - -@group -An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}. -@@end defun -@end group -@end example - -@noindent -In this manual, this function is listed in the Command and Variable -Index under @code{apply}. - -Ordinary variables and user options are described using a format like -that for functions except that variables do not take arguments. - - -@node Internationalization -@chapter Internationalization - -@cindex Internationalization -Texinfo has some support for writing in languages other than English, -although this area still needs considerable work. (If you are -yourself helping to translate the fixed strings written to documents, -@pxref{Internationalization of Document Strings}.) - -For a list of the various accented and special characters Texinfo -supports, see @ref{Inserting Accents}. - -@menu -* @t{@@documentlanguage}:: Declaring the current language. -* @t{@@documentencoding}:: Declaring the input encoding. -@end menu - - -@node @t{@@documentlanguage} -@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language -@anchor{documentlanguage} - -@findex documentlanguage -@cindex Language, declaring -@cindex Locale, declaring -@cindex Document language, declaring - -The @code{@@documentlanguage} command declares the current document -locale. Write it on a line by itself, near the beginning of the file, -but after @code{@@setfilename} (@pxref{@t{@@setfilename}}): - -@example -@@documentlanguage @var{ll}[_@var{cc}] -@end example - -Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following -the command name, optionally followed by an underscore and two-letter -ISO@tie{}3166 two-letter country code (@var{cc}). If you have a -multilingual document, the intent is to be able to use this command -multiple times, to declare each language change. If the command is -not used at all, the default is @code{en_US} for US English. - -As with GNU Gettext (@pxref{Top,,, gettext, Gettext}), if the country -code is omitted, the main dialect is assumed where possible. For -example, @code{de} is equivalent to @code{de_DE} (German as spoken in -Germany). - -@cindex Document strings, translation of -For Info and other online output, this command changes the translation -of various @dfn{document strings} such as ``see'' in cross references -(@pxref{Cross References}), ``Function' in defuns (@pxref{Definition -Commands}), and so on. Some strings, such as ``Node:'', ``Next:'', -``Menu:'', etc., are keywords in Info output, so are not translated -there; they are translated in other output formats. - -@cindex @file{txi-@var{cc}.tex} -For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to -be read (if it exists). If @code{@@documentlanguage} argument -contains the optional @samp{_@var{cc}} suffix, this is tried first. -For example, with @code{@@documentlanguage de_DE}, @TeX{} first looks -for @file{txi-de_DE.tex}, then @file{txi-de.tex}. - -Such a @file{txi-*} file is intended to redefine the various English -words used in @TeX{} output, such as `Chapter', `See', and so on. We -are aware that individual words like these cannot always be translated -in isolation, and that a very different strategy would be required for -ideographic (among other) scripts. Help in improving Texinfo's -language support is welcome. - -@cindex Hyphenation patterns, language-dependent -@code{@@documentlanguage} also changes @TeX{}'s current hyphenation -patterns, if the @TeX{} program being run has the necessary support -included. This will generally not be the case for @command{tex} -itself, but will usually be the case for up-to-date distributions of -the extended @TeX{} programs @command{etex} (DVI output) and -@command{pdftex} (PDF output). @command{texi2dvi} will use the -extended @TeX{}s if they are available (@pxref{Format with -@t{texi2dvi}}). - -In September 2006, the W3C Internationalization Activity released a -new recommendation for specifying languages: -@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext -supports this new scheme, Texinfo will too. - -@cindex ISO 639-2 language codes -@cindex ISO 3166 country codes -@cindex Language codes -@cindex Country codes -Since the lists of language codes and country codes are updated -relatively frequently, we don't attempt to list them here. The valid -language codes are on the official home page for ISO@tie{}639, -@url{http://www.loc.gov/standards/iso639-2/}. The country codes and -the official web site for ISO@tie{}3166 can be found via -@url{http://en.wikipedia.org/wiki/ISO_3166}. - - -@node @t{@@documentencoding} -@section @code{@@documentencoding @var{enc}}: Set Input Encoding - -@anchor{documentencoding}@c old name -@findex documentencoding -@cindex Encoding, declaring -@cindex Input encoding, declaring -@cindex Character set, declaring -@cindex Document input encoding - -The @code{@@documentencoding} command declares the input document -encoding. Write it on a line by itself, with a valid encoding -specification following, near the beginning of the file but after -@code{@@setfilename} (@pxref{@t{@@setfilename}}): - -@example -@@documentencoding @var{enc} -@end example - -At present, Texinfo supports only these encodings: - -@table @code -@item US-ASCII -This has no particular effect, but it's included for completeness. - -@item UTF-8 -The vast global character encoding, expressed in 8-bit bytes. - -@item ISO-8859-2 -@itemx ISO-8859-1 -@itemx ISO-8859-15 -These specify the standard encodings for Western European (the first -two) and Eastern European languages (the third), respectively. ISO -8859-15 replaces some little-used characters from 8859-1 (e.g., -precomposed fractions) with more commonly needed ones, such as the -Euro symbol (@euro{}). - -A full description of the encodings is beyond our scope here; -one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. - -@item koi8-r -This is the commonly used encoding for the Russian language. - -@item koi8-u -This is the commonly used encoding for the Ukrainian language. - -@end table - -Specifying an encoding @var{enc} has the following effects: - -@cindex Local Variables section, for encoding -@cindex Info output, and encoding -In Info output, a so-called `Local Variables' section (@pxref{File -Variables,,,xemacs, XEmacs User's Manual}) is output including -@var{enc}. This allows Info readers to set the encoding -appropriately. It looks like this: - -@example -Local Variables: -coding: @var{enc} -End: -@end example - -Also, in Info and plain text output, unless the option -@option{--disable-encoding} is given to @command{makeinfo}, accent -constructs and special characters, such as @code{@@'e}, are output as -the actual 8-bit or UTF-8 character in the given encoding where -possible. - -@cindex HTML output, and encodings -@cindex @code{http-equiv}, and charset specification -@cindex @code{<meta>} HTML tag, and charset specification -In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} -section of the HTML, that specifies @var{enc}. Web servers and -browsers cooperate to use this information so the correct encoding is -used to display the page, if supported by the system. That looks like -this: - -@example -<meta http-equiv="Content-Type" content="text/html; - charset=@var{enc}"> -@end example - -In XML and Docbook output, UTF-8 is always used for the output file, -since all XML processors are supposed to be able to process that -encoding. - -@cindex Computer Modern fonts -In @TeX{} output, the characters which are supported in the standard -Computer Modern fonts are output accordingly. (For example, this -means using constructed accents rather than precomposed glyphs.) -Using a missing character generates a warning message, as does -specifying an unimplemented encoding. - -Although modern @TeX{} systems support nearly every script in use in -the world, this wide-ranging support is not available in -@file{texinfo.tex}, and it's not feasible to duplicate or incorporate -all that effort. Our plan to support other scripts is to create a -@LaTeX{} back-end to @command{texi2any}, where the support is already -present. - - -@node Conditionals -@chapter Conditionally Visible Text -@cindex Conditionally visible text -@cindex Text, conditionally visible -@cindex Visibility of conditional text -@cindex If text conditionally visible - -The @dfn{conditional commands} allow you to use different text for -different output formats, or for general conditions that you define. -For example, you can use them to specify different text for the -printed manual and the Info output. - -The conditional commands comprise the following categories. - -@itemize @bullet -@item -Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). - -@item -Commands specific to any output format @emph{excluding} a given -one (e.g., not Info, not @TeX{}, @dots{}). - -@item -`Raw' formatter text for any output format, passed straight -through with minimal (but not zero) interpretation of @@-commands. - -@item -Format-independent variable substitutions, and testing if a variable -is set or clear. - -@end itemize - -@menu -* Conditional Commands:: Text for a given format. -* Conditional Not Commands:: Text for any format other than a given one. -* Raw Formatter Commands:: Using raw formatter commands. -* Inline Conditionals:: Brace-delimited conditional text. -* @t{@@set @@clear @@value}:: Variable tests and substitutions. -* Testing for Texinfo Commands:: Testing if a Texinfo command is available. -* Conditional Nesting:: Using conditionals inside conditionals. -@end menu - - -@node Conditional Commands -@section Conditional Commands - -Texinfo has an @code{@@if@var{format}} environment for each output -format, to allow conditional inclusion of text for a particular output -format. - -@findex ifinfo -@code{@@ifinfo} begins segments of text that should be ignored by -@TeX{} when it typesets the printed manual, and by @command{makeinfo} -when not producing Info output. The segment of text appears only in -the Info file and, for historical compatibility, the plain text -output. - -@findex ifdocbook -@findex ifhtml -@findex ifplaintext -@findex iftex -@findex ifxml -The environments for the other formats are analogous, but without the -special historical case: - -@table @code -@item @@ifdocbook @dots{} @@end ifdocbook -Text to appear only in the Docbook output. - -@item @@ifhtml @dots{} @@end ifhtml -Text to appear only in the HTML output. - -@item @@ifplaintext @dots{} @@end ifplaintext -Text to appear only in the plain text output. - -@item @@iftex @dots{} @@end iftex -Text to appear only in the printed manual. - -@item @@ifxml @dots{} @@end ifxml -Text to appear only in the XML output. -@end table - -The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear -on lines by themselves in your source file. The newlines following -the commands are (more or less) treated as whitespace, so that the -conditional text is flowed normally into a surrounding paragraph. - -The @code{@@if@dots{}} constructs are intended to conditionalize -normal Texinfo source; @pxref{Raw Formatter Commands}, for using -underlying format commands directly. - -Here is an example showing all these conditionals: - -@example -@@iftex -This text will appear only in the printed manual. -@@end iftex -@@ifinfo -However, this text will appear only in Info and plain text. -@@end ifinfo -@@ifhtml -And this text will only appear in HTML. -@@end ifhtml -@@ifplaintext -Whereas this text will only appear in plain text. -@@end ifplaintext -@@ifxml -Notwithstanding that this will only appear in XML@. -@@end ifxml -@@ifdocbook -Nevertheless, this will only appear in Docbook. -@@end ifdocbook -@end example - -@noindent -The preceding example produces the following line: - -@iftex -This text will appear only in the printed manual. -@end iftex -@ifinfo -However, this text will appear only in Info and plain text. -@end ifinfo -@ifhtml -And this text will only appear in HTML. -@end ifhtml -@ifplaintext -Whereas this text will only appear in plain text. -@end ifplaintext -@ifxml -Notwithstanding that this will only appear in XML@. -@end ifxml -@ifdocbook -Nevertheless, this will only appear in Docbook. -@end ifdocbook - -@noindent -Notice that you only see one of the input lines, depending on which -version of the manual you are reading. - -@findex errormsg -In complex documents, you may want Texinfo to issue an error message -in some conditionals that should not ever be processed. The -@code{@@errormsg@{@var{text}@}} command will do this; it takes one -argument, the text of the error message, which is expanded more or -less as if it were Info text. - -We mention @code{@@errormsg@{@}} here even though it is not strictly -related to conditionals, since in practice it is most likely to be -useful in that context. Technically, it can be used anywhere. -@xref{External Macro Processors}, for a caveat regarding the line -numbers which @code{@@errormsg} emits in @TeX{}. - - -@node Conditional Not Commands -@section Conditional Not Commands -@findex ifnotdocbook -@findex ifnothtml -@findex ifnotinfo -@findex ifnotplaintext -@findex ifnottex -@findex ifnotxml - -You can specify text to be included in any output format @emph{other} -than a given one with the @code{@@ifnot@dots{}} environments: - -@example -@@ifnotdocbook @dots{} @@end ifnotdocbook -@@ifnothtml @dots{} @@end ifnothtml -@@ifnotinfo @dots{} @@end ifnotinfo -@@ifnotplaintext @dots{} @@end ifnotplaintext -@@ifnottex @dots{} @@end ifnottex -@@ifnotxml @dots{} @@end ifnotxml -@end example - -@noindent -The @code{@@ifnot@dots{}} command and the @code{@@end} command must -appear on lines by themselves in your actual source file. - -If the output file is being made in the given format, the -region is @emph{ignored}. Otherwise, it is included. - -There is one exception (for historical compatibility): -@code{@@ifnotinfo} text is omitted for both Info and plain text -output, not just Info. To specify text which appears only in Info and -not in plain text, use @code{@@ifnotplaintext}, like this: - -@example -@@ifinfo -@@ifnotplaintext -This will be in Info, but not plain text. -@@end ifnotplaintext -@@end ifinfo -@end example - -The regions delimited by these commands are ordinary Texinfo source as -with @code{@@iftex}, not raw formatter source as with @code{@@tex} -(@pxref{Raw Formatter Commands}). - - -@node Raw Formatter Commands -@section Raw Formatter Commands -@cindex Raw formatter commands - -@cindex @TeX{} commands, using ordinary -@cindex Ordinary @TeX{} commands, using -@cindex Commands using raw @TeX{} -@cindex Plain @TeX{} - -The @code{@@if@dots{}} conditionals just described must be used only -with normal Texinfo source. For instance, most features of plain -@TeX{} will not work within @code{@@iftex}. The purpose of -@code{@@if@dots{}} is to provide conditional processing for Texinfo -source, not provide access to underlying formatting features. For -that, Texinfo provides so-called @dfn{raw formatter commands}. They -should only be used when truly required (most documents do not need -them). - -@findex tex -@cindex Category codes, of plain @TeX{} -The first raw formatter command is @code{@@tex}. You can enter plain -@TeX{} completely, and use @samp{\} in the @TeX{} commands, by -delineating a region with the @code{@@tex} and @code{@@end tex} -commands. All plain @TeX{} commands and category codes are restored -within an @code{@@tex} region. The sole exception is that the -@code{@@} character still introduces a command, so that @code{@@end -tex} can be recognized. Texinfo processors will not output material -in such a region, unless @TeX{} output is being produced. - -@findex \gdef @r{within @code{@@tex}} -@findex \globaldefs @r{within @code{@@tex}} -In complex cases, you may wish to define new @TeX{} macros within -@code{@@tex}. You must use @code{\gdef} to do this, not @code{\def}, -because @code{@@tex} regions are processed in a @TeX{} group. If you -need to make several definitions, you may wish to set -@code{\globaldefs=1} (its value will be restored to zero as usual when -the group ends at @code{@@end tex}, so it won't cause problems with -the rest of the document). - -@cindex Equation, displayed, in plain @TeX{} -@cindex Displayed equation, in plain @TeX{} -As an example, here is a displayed equation written in plain @TeX{}: - -@example -@@tex -$$ \chi^2 = \sum_@{i=1@}^N - \left (y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@@end tex -@end example - -@noindent -The output of this example will appear only in a printed manual. If -you are reading this in a format not generated by @TeX{}, you will not -see the equation that appears in the printed manual. - -@tex -$$ \chi^2 = \sum_{i=1}^N - \left(y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@end tex - -@cindex HTML, including raw -@findex ifhtml -@findex html -Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to -delimit Texinfo source to be included in HTML output only, and -@code{@@html @dots{} @@end html} for a region of raw HTML. - -@cindex XML, including raw -@findex ifxml -@findex xml -Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit -Texinfo source to be included in XML output only, and @code{@@xml -@dots{} @@end xml} for a region of raw XML@. Regions of raw text in -other formats will also be present in the XML output, but with -protection of XML characters and within corresponding elements. For -example, the raw HTML text: - -@example -@group -@@html -<br /> -@@end html -@end group -@end example - -@noindent -will be included in the XML output as: - -@example -@group -<html> -<br /> -</html> -@end group -@end example - -@cindex Docbook, including raw -@findex ifdocbook -@findex docbook -Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} -to delimit Texinfo source to be included in Docbook output only, and -@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. - -The behavior of newlines in raw regions is unspecified. - -In all cases, in raw processing, @code{@@} retains the same meaning as -in the remainder of the document. Thus, the Texinfo processors -recognize and even execute, to some extent, the contents of the raw -regions, regardless of the final output format. Therefore, specifying -changes that globally affect the document inside a raw region leads to -unpredictable and generally undesirable behavior. For example, it -using the @code{@@kbdinputstyle} command inside a raw region is undefined. - -The remedy is simple: don't do that. Use the raw formatter commands -for their intended purpose, of providing material directly in the -underlying format. When you simply want to give different Texinfo -specifications for different output formats, use the -@code{@@if@dots{}} conditionals and stay in Texinfo syntax. - - - -@node Inline Conditionals -@section Inline Conditionals: @code{@@inline}, @code{@@inlineifelse}, @code{@@inlineraw} -@findex inlinefmt -@findex inlinefmtifelse -@findex inlineraw -@cindex Inline conditionals -@cindex Conditional commands, inline -@cindex Brace-delimited conditional text -@cindex Newlines, avoiding in conditionals -@cindex Whitespace, controlling in conditionals - -Texinfo provides a set of conditional commands with arguments given -within braces: - -@table @code -@item @@inlinefmt@{@var{format}, @var{text}@} -Process the Texinfo @var{text} if @var{format} output is being -generated. - -@item @@inlinefmtifelse@{@var{format}, @var{then-text}, @var{else-text}@} -Process the Texinfo @var{then-text} if @var{format} output is being -generated; otherwise, process @var{else-text}. - -@item @@inlineraw@{@var{format}, @var{text}@} -Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}). -@end table - -The supported @var{format} names are: - -@example -docbook html info plaintext tex xml -@end example - -For example, - -@example -@@inlinefmt@{html, @@emph@{HTML-only text@}@} -@end example - -@noindent is nearly equivalent to - -@example -@@ifhtml -@@emph@{HTML-only text@} -@@end ifhtml -@end example - -@noindent except that no whitespace is added, as happens in the latter -(environment) case. - -In these commands, whitespace is ignored after the comma separating -the arguments, as usual, but is @emph{not} ignored at the end of -@var{text}. - -To insert a literal at sign, left brace, or right brace in one of the -arguments, you must use the alphabetic commands @code{@@atchar@{@}} -(@pxref{Inserting an Atsign}), and @code{@@lbracechar@{@}} or -@code{@@rbracechar@{@}} (@pxref{Inserting Braces}), or the parsing -will become confused. - -With @code{@@inlinefmtifelse}, it is also necessary to use -@code{@@comma@{@}} to avoid mistaking a @samp{,} in the text for the -delimiter. With @code{@@inlinefmt} and @code{@@inlineraw}, -@code{@@comma@{@}} is not required (though it's fine to use it), since -these commands always have exactly two arguments. - -For @TeX{}, the processed @var{text} cannot contain newline-delimited -commands. Text to be ignored (i.e., for non-@TeX{}) can, though. - -Two other @code{@@inline...} conditionals complement the -@code{@@ifset} and @code{@@ifclear} commands; see the next section. - - -@node @t{@@set @@clear @@value} -@section Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value} - -@anchor{set clear value}@c old name -You can direct the Texinfo formatting commands to format or ignore parts -of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, -and @code{@@ifclear} commands. - -Here are brief descriptions of these commands, see the following -sections for more details: - -@table @code -@item @@set @var{flag} [@var{value}] -Set the variable @var{flag}, to the optional @var{value} if specified. - -@item @@clear @var{flag} -Undefine the variable @var{flag}, whether or not it was previously defined. - -@item @@ifset @var{flag} -If @var{flag} is set, text through the next @code{@@end ifset} command -is formatted. If @var{flag} is clear, text through the following -@code{@@end ifset} command is ignored. - -@item @@inlineifset@{@var{flag}, @var{text}@} -Brace-delimited version of @code{@@ifset}. - -@item @@ifclear @var{flag} -If @var{flag} is set, text through the next @code{@@end ifclear} command -is ignored. If @var{flag} is clear, text through the following -@code{@@end ifclear} command is formatted. - -@item @@inlineifclear@{@var{flag}, @var{text}@} -Brace-delimited version of @code{@@ifclear}. - -@end table - -@menu -* @t{@@set @@value}:: Expand a flag variable to a string. -* @t{@@ifset @@ifclear}:: Format a region if a flag is set. -* @t{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals. -* @t{@@value} Example:: An easy way to update edition information. -@end menu - - -@node @t{@@set @@value} -@subsection @code{@@set} and @code{@@value} - -@anchor{set value}@c old name -@findex set -@findex value -@findex clear - -You use the @code{@@set} command to specify a value for a flag, which -is later expanded by the @code{@@value} command. - -A @dfn{flag} (aka @dfn{variable}) name is an identifier starting with -an alphanumeric, @samp{-}, or @samp{_}. Subsequent characters, if -any, may not be whitespace, @samp{@@}, braces, angle brackets, or any -of @samp{~`^+|}; other characters, such as @samp{%}, may work. -However, it is best to use only letters and numerals in a flag name, -not @samp{-} or @samp{_} or others---they will work in some contexts, -but not all, due to limitations in @TeX{}. - -The value is the remainder of the input line, and can contain anything. -However, unlike most other commands which take the rest of the line as -a value, @code{@@set} need not appear at the beginning of a line. - -Write the @code{@@set} command like this: - -@example -@@set foo This is a string. -@end example - -@noindent -This sets the value of the flag @code{foo} to ``This is a string.''. - -The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} -command with the string to which @var{flag} is set. Thus, when -@code{foo} is set as shown above, the Texinfo formatters convert this: - -@example -@group -@@value@{foo@} -@exdent @r{to this:} -This is a string. -@end group -@end example - -You can write an @code{@@value} command within a paragraph; but you -must write an @code{@@set} command on a line of its own. - -If you write the @code{@@set} command like this: - -@example -@@set foo -@end example - -@noindent -without specifying a string, the value of @code{foo} is the empty string. - -If you clear a previously set flag with @code{@@clear @var{flag}}, a -subsequent @code{@@value@{flag@}} command will report an error. - -For example, if you set @code{foo} as follows: - -@example -@@set howmuch very, very, very -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{howmuch@} wet day. -@exdent @r{into} -It is a very, very, very wet day. -@end group -@end example - -If you write - -@example -@@clear howmuch -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{howmuch@} wet day. -@exdent @r{into} -It is a @{No value for "howmuch"@} wet day. -@end group -@end example - -@code{@@value} cannot be reliably used as the argument to an accent -command (@pxref{Inserting Accents}). For example, this fails: - -@example -@@set myletter a -@@'@@value@{myletter@} @c fails! -@end example - - -@node @t{@@ifset @@ifclear} -@subsection @code{@@ifset} and @code{@@ifclear} - -@anchor{ifset ifclear}@c old name -@findex ifset - -When a @var{flag} is set, the Texinfo formatting commands format text -between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end -ifset} commands. When the @var{flag} is cleared, the Texinfo formatting -commands do @emph{not} format the text. @code{@@ifclear} operates -analogously. - -Write the conditionally formatted text between @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, like this: - -@example -@group -@@ifset @var{flag} -@var{conditional-text} -@@end ifset -@end group -@end example - -For example, you can create one document that has two variants, such as -a manual for a `large' and `small' model: - -@cindex Shrubbery -@example -You can use this machine to dig up shrubs -without hurting them. - -@@set large - -@@ifset large -It can also dig up fully grown trees. -@@end ifset - -Remember to replant promptly @dots{} -@end example - -@noindent -In the example, the formatting commands will format the text between -@code{@@ifset large} and @code{@@end ifset} because the @code{large} -flag is set. - -When @var{flag} is cleared, the Texinfo formatting commands do -@emph{not} format the text between @code{@@ifset @var{flag}} and -@code{@@end ifset}; that text is ignored and does not appear in either -printed or Info output. - -For example, if you clear the flag of the preceding example by writing -an @code{@@clear large} command after the @code{@@set large} command -(but before the conditional text), then the Texinfo formatting commands -ignore the text between the @code{@@ifset large} and @code{@@end ifset} -commands. In the formatted output, that text does not appear; in both -printed and Info output, you see only the lines that say, ``You can use -this machine to dig up shrubs without hurting them. Remember to replant -promptly @dots{}''. - -@findex ifclear -If a flag is cleared with an @code{@@clear @var{flag}} command, then -the formatting commands format text between subsequent pairs of -@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag -is set with @code{@@set @var{flag}}, then the formatting commands do -@emph{not} format text between an @code{@@ifclear} and an @code{@@end -ifclear} command; rather, they ignore that text. An @code{@@ifclear} -command looks like this: - -@example -@@ifclear @var{flag} -@end example - - -@node @t{@@inlineifset @@inlineifclear} -@subsection @code{@@inlineifset} and @code{@@inlineifclear} - -@findex inlineifset -@findex inlineifclear -@cindex Flag conditionals, brace-delimited -@cindex Brace-delimited flag conditionals - -@code{@@inlineifset} and @code{@@inlineifclear} provide -brace-delimited alternatives to the @code{@@ifset} and -@code{@@ifclear} forms, similar to the other @code{@@inline...} -Commands (@pxref{Inline Conditionals}). The same caveats about -argument parsing given there apply here too. - -@table @code -@item @@inlineifset@{@var{var}, @var{text}@} -Process the Texinfo @var{text} if the flag @var{var} is defined. - -@item @@inlineifclear@{@var{var}, @var{text}@} -Process the Texinfo @var{text} if the flag @var{var} is not defined. -@end table - -Except for the syntax, their general behavior and purposes is the same -as with @code{@@ifset} and @code{@@ifclear}, described in the previous -section. - - -@node @t{@@value} Example -@subsection @code{@@value} Example - -@anchor{value Example}@c old name - -You can use the @code{@@value} command to minimize the number of -places you need to change when you record an update to a manual. -@xref{GNU Sample Texts}, for the full text of an example of using this -to work with Automake distributions. - -This example is adapted from @ref{Top,,, make, The GNU Make Manual}. - -@enumerate -@item -Set the flags: - -@example -@group -@@set EDITION 0.35 Beta -@@set VERSION 3.63 Beta -@@set UPDATED 14 August 1992 -@@set UPDATE-MONTH August 1992 -@end group -@end example - -@item -Write text for the @code{@@copying} section (@pxref{@t{@@copying}}): - -@example -@group -@@copying -This is Edition @@value@{EDITION@}, -last updated @@value@{UPDATED@}, -of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, version @@value@{VERSION@}. - -Copyright @dots{} - -Permission is granted @dots{} -@@end copying -@end group -@end example - -@item -Write text for the title page, for people reading the printed manual: - -@example -@group -@@titlepage -@@title GNU Make -@@subtitle A Program for Directing Recompilation -@@subtitle Edition @@value@{EDITION@}, @dots{} -@@subtitle @@value@{UPDATE-MONTH@} -@@page -@@insertcopying -@dots{} -@@end titlepage -@end group -@end example - -@noindent -(On a printed cover, a date listing the month and the year looks less -fussy than a date listing the day as well as the month and year.) - -@item -Write text for the Top node, for people reading the Info file: - -@example -@group -@@ifnottex -@@node Top -@@top Make - -@@insertcopying -@dots{} -@@end ifnottex -@end group -@end example - -After you format the manual, the @code{@@value} constructs have been -expanded, so the output contains text like this: - -@example -@group -This is Edition 0.35 Beta, last updated 14 August 1992, -of `The GNU Make Manual', for `make', Version 3.63 Beta. -@end group -@end example -@end enumerate - -When you update the manual, you change only the values of the flags; you -do not need to edit the three sections. - - -@node Testing for Texinfo Commands -@section Testing for Texinfo Commands: @code{@@ifcommanddefined}, @code{@@ifcommandnotdefined} - -@cindex Testing for Texinfo commands -@cindex Checking for Texinfo commands -@cindex Texinfo commands, testing for -@cindex Commands, testing for Texinfo -@cindex Versions of Texinfo, adapting to -@cindex Features of Texinfo, adapting to - -Occasionally, you may want to arrange for your manual to test if a -given Texinfo command is available and (presumably) do some sort of -fallback formatting if not. There are conditionals -@code{@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this. -For example: - -@example -@@ifcommanddefined node -Good, @@samp@{@@@@node@} is defined. -@@end ifcommanddefined -@end example - -@noindent will output the expected `Good, @samp{@@node} is defined.'. - -This conditional will also consider true any new commands defined by -the document via @code{@@macro}, @code{@@alias}, -@code{@@definfoenclose}, and @code{@@def@r{(}code@r{)}index} -(@pxref{Defining New Texinfo Commands}). Caveat: the @TeX{} -implementation reports internal @TeX{} commands, in addition to all -the Texinfo commands, as being ``defined''; the @code{makeinfo} -implementation is reliable in this regard, however. - -@pindex @file{NEWS} file for Texinfo -You can check the @file{NEWS} file in the Texinfo source distribution -and linked from the Texinfo home page -(@url{http://www.gnu.org/software/texinfo}) to see when a particular -command was added. - -These command-checking conditionals themselves were added in -Texinfo@tie{}5.0, released in 2013---decades after Texinfo's -inception. In order to test if they themselves are available, -the predefined flag @code{txicommandconditionals} can be tested, like -this: - -@example -@@ifset txicommandconditionals -@@ifcommandnotdefined foobarnode -(Good, @samp{@@foobarnode} is not defined.) -@@end ifcommandnotdefined -@@end ifset -@end example - -Since flags (see the previous section) were added early in the -existence of Texinfo, there is no problem with assuming they are -available. - -We recommend avoiding these tests whenever possible---which is usually -the case. For many software packages, it is reasonable for all -developers to have a given version of Texinfo (or newer) installed, -and thus no reason to worry about older versions. (It is -straightforward for anyone to download and install the Texinfo source; -it does not have any problematic dependencies.) - -The issue of Texinfo versions does not generally arise for end-users. -With properly distributed packages, users need not process the Texinfo -manual simply to build and install the package; they can use -preformatted Info (or other) output files. This is desirable in -general, to avoid unnecessary dependencies between packages -(@pxref{Releases,,, standard, GNU Coding Standards}). - - -@node Conditional Nesting -@section Conditional Nesting -@cindex Conditionals, nested -@cindex Nesting conditionals - -Conditionals can be nested; however, the details are a little tricky. -The difficulty comes with failing conditionals, such as -@code{@@ifhtml} when HTML is not being produced, where the included -text is to be ignored. However, it is not to be @emph{completely} -ignored, since it is useful to have one @code{@@ifset} inside another, -for example---that is a way to include text only if two conditions are -met. Here's an example: - -@example -@@ifset somevar -@@ifset anothervar -Both somevar and anothervar are set. -@@end ifset -@@ifclear anothervar -Somevar is set, anothervar is not. -@@end ifclear -@@end ifset -@end example - -Technically, Texinfo requires that for a failing conditional, the -ignored text must be properly nested with respect to that failing -conditional. Unfortunately, it's not always feasible to check that -@emph{all} conditionals are properly nested, because then the -processors could have to fully interpret the ignored text, which -defeats the purpose of the command. Here's an example illustrating -these rules: - -@example -@@ifset a -@@ifset b -@@ifclear ok - ok, ignored -@@end junky - ok, ignored -@@end ifset -@@c WRONG - missing @@end ifset. -@end example - -Finally, as mentioned above, all conditional commands must be on lines -by themselves, with no text (even spaces) before or after. Otherwise, -the processors cannot reliably determine which commands to consider -for nesting purposes. - - -@node Defining New Texinfo Commands -@chapter Defining New Texinfo Commands - -@cindex Macros -@cindex Defining new Texinfo commands -@cindex New Texinfo commands, defining -@cindex Texinfo commands, defining new -@cindex User-defined Texinfo commands - -Texinfo provides several ways to define new commands (in all cases, -it's not recommended to try redefining existing commands): - -@itemize @bullet -@item -A Texinfo @dfn{macro} allows you to define a new Texinfo command as any -sequence of text and/or existing commands (including other macros). The -macro can have any number of @dfn{parameters}---text you supply each -time you use the macro. - -Incidentally, these macros have nothing to do with the @code{@@defmac} -command, which is for documenting macros in the subject area of the -manual (@pxref{Def Cmd Template}). - -@item -@samp{@@alias} is a convenient way to define a new name for an existing -command. - -@item -@samp{@@definfoenclose} allows you to define new commands with -customized output for all non-@TeX{} output formats. - -@end itemize - -Most generally of all (not just for defining new commands), it is -possible to invoke any external macro processor and have Texinfo -recognize so-called @code{#line} directives for error reporting. - -If you want to do simple text substitution, @code{@@set} and -@code{@@value} is the simplest approach (@pxref{@t{@@set @@clear -@@value}}). - -@menu -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* @t{@@alias}:: Command aliases. -* @t{@@definfoenclose}:: Customized highlighting. -* External Macro Processors:: @code{#line} directives. -@end menu - - -@node Defining Macros -@section Defining Macros -@cindex Defining macros -@cindex Macro definitions, Texinfo - -@findex macro -You use the Texinfo @code{@@macro} command to define a macro, like this: - -@example -@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@} -@var{text} @dots{} \@var{param1}\ @dots{} -@@end macro -@end example - -The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to -arguments supplied when the macro is subsequently used in the document -(described in the next section). - -@cindex Macro names, valid characters in -@cindex Names of macros, valid characters of -For a macro to work consistently with @TeX{}, @var{macroname} must -consist entirely of letters: no digits, hyphens, underscores, or other -special characters. So, we recommend using only letters. However, -@command{makeinfo} will accept anything consisting of alphanumerics, -and (except as the first character) @samp{-}. The @samp{_} character -is excluded so that macros can be called inside @code{@@math} without -a following space (@pxref{Inserting Math}). - -If a macro needs no parameters, you can define it either with an empty -list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro -foo}). - -@cindex Body of a macro -The definition or @dfn{body} of the macro can contain most Texinfo -commands, including macro invocations. However, a macro definition -that defines another macro does not work in @TeX{} due to limitations -in the design of @code{@@macro}. - -@cindex Parameters to macros -In the macro body, instances of a parameter name surrounded by -backslashes, as in @samp{\@var{param1}\} in the example above, are -replaced by the corresponding argument from the macro invocation. You -can use parameter names any number of times in the body, including zero. - -@cindex Backslash in macros -To get a single @samp{\} in the macro expansion, use @samp{\\}. Any -other use of @samp{\} in the body yields a warning. - -@cindex Spaces in macros -@cindex Whitespace in macros -The newline characters after the @code{@@macro} line and before the -@code{@@end macro} line are ignored, that is, not included in the -macro body. All other whitespace is treated according to the usual -Texinfo rules. However, there are still undesirable and unpredictable -interactions between newlines, macros, and commands which are -line-delimited, as warned about below (@pxref{Macro Details}). - -@cindex Recursive macro invocations -@findex rmacro -To allow a macro to be used recursively, that is, in an argument to a -call to itself, you must define it with @samp{@@rmacro}, like this: - -@example -@@rmacro rmac @{arg@} -a\arg\b -@@end rmacro -@dots{} -@@rmac@{1@@rmac@{text@}2@} -@end example - -This produces the output `a1atextb2b'. With @samp{@@macro} instead of -@samp{@@rmacro}, an error message is given. - -@findex unmacro -@cindex Macros, undefining -@cindex Undefining macros -You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. -It is not an error to undefine a macro that is already undefined. -For example: - -@example -@@unmacro foo -@end example - - -@node Invoking Macros -@section Invoking Macros - -@cindex Invoking macros -@cindex Expanding macros -@cindex Running macros -@cindex Macro invocation - -After a macro is defined (see the previous section), you can -@dfn{invoke} (use) it in your document like this: - -@example -@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} -@end example - -@noindent and the result will be more or less as if you typed the body of -@var{macroname} at that spot. For example: - -@example -@@macro foo @{p, q@} -Together: \p\ & \q\. -@@end macro -@@foo@{a, b@} -@end example - -@noindent produces: - -@display -Together: a & b. -@end display - -@cindex Backslash, and macros -Thus, the arguments and parameters are separated by commas and -delimited by braces; any whitespace after (but not before) a comma is -ignored. The braces are required in the invocation even when the -macro takes no arguments, consistent with other Texinfo commands. For -example: - -@example -@@macro argless @{@} -No arguments here. -@@end macro -@@argless@{@} -@end example - -@noindent produces: - -@display -No arguments here. -@end display - -@cindex Comma, in macro arguments -Passing macro arguments containing commas requires special care, since -commas also separate the arguments. To include a comma character in -an argument, the most reliable method is to use the @code{@@comma@{@}} -command. For @code{makeinfo}, you can also prepend a backslash -character, as in @samp{\,}, but this does not work with @TeX{}. - -@cindex Automatic quoting of commas for some macros -@cindex Quoting, automatic for some macros -It's not always necessary to worry about commas. To facilitate use of -macros, @command{makeinfo} implements two rules for @dfn{automatic -quoting} in some circumstances: - -@enumerate 1 -@item If a macro takes only one argument, all commas in its invocation -are quoted by default. For example: - -@example -@group -@@macro TRYME@{text@} -@@strong@{TRYME: \text\@} -@@end macro - -@@TRYME@{A nice feature, though it can be dangerous.@} -@end group -@end example - -@noindent -will produce the following output - -@example -@strong{TRYME: A nice feature, though it can be dangerous.} -@end example - -And indeed, it can. Namely, @command{makeinfo} does not control the -number of arguments passed to one-argument macros, so be careful when -you invoke them. - -@item If a macro invocation includes another command (including a -recursive invocation of itself), any commas in the nested command -invocation(s) are quoted by default. For example, in - -@example -@@say@{@@strong@{Yes, I do@}, person one@} -@end example - -the comma after @samp{Yes} is implicitly quoted. Here's another -example, with a recursive macro: - -@example -@group -@@rmacro cat@{a,b@} -\a\\b\ -@@end rmacro - -@@cat@{@@cat@{foo, bar@}, baz@} -@end group -@end example - -@noindent -will produce the string @samp{foobarbaz}. - -@item Otherwise, a comma should be explicitly quoted, as above, for it -to be treated as a part of an argument. -@end enumerate - -@cindex Braces, in macro arguments -@cindex Backslash, in macro arguments -In addition to the comma, characters that need to be quoted in macro -arguments are curly braces and backslash. For example: - -@example -@@@var{macname} @{\\\@{\@}\,@} -@end example - -@noindent -will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macname}. - -Unfortunately, this has not been reliably implemented in @TeX{}. When -macros are used in the argument to other commands, for example, errors -or incorrect output (the @samp{\} ``escape'' being included literally) -are likely to result. - -If a macro is defined to take exactly one argument, it can (but need -not) be invoked without any braces; then the entire rest of the line -after the macro name is used as the argument. (Braces around the -argument(s) are required in all other cases, i.e., if the macro takes -either zero or more than one argument.) For example: - -@example -@@macro bar @{p@} -Twice: \p\ & \p\. -@@end macro -@@bar aah -@end example - -@noindent produces: - -@display -Twice: aah & aah. -@end display - -Likewise, if a macro is defined to take exactly one argument, and is -invoked with braces, the braced text is passed as the argument, also -regardless of commas. For example: - -@example -@@macro bar @{p@} -Twice: \p\ & \p\. -@@end macro -@@bar@{a,b@} -@end example - -@noindent produces: - -@display -Twice: a,b & a,b. -@end display - -If a macro is defined to take more than one argument, but is called -with only one (in braces), the remaining arguments are set to the -empty string, and no error is given. For example: - -@example -@@macro addtwo @{p, q@} -Both: \p\\q\. -@@end macro -@@addtwo@{a@} -@end example - -@noindent produces simply: - -@display -Both: a. -@end display - - -@node Macro Details -@section Macro Details and Caveats -@cindex Macro details -@cindex Details of macro usage -@cindex Caveats for macro usage - -@cindex Macro expansion, contexts for -@cindex Expansion of macros, contexts for -By design, macro expansion does not happen in the following contexts -in @command{makeinfo}: - -@itemize @bullet -@item @code{@@macro} and @code{@@unmacro} lines; - -@item @code{@@if...} lines, including @code{@@ifset} and similar; - -@item @code{@@set}, @code{@@clear}, @code{@@value}; - -@item @code{@@clickstyle} lines; - -@item @code{@@end} lines. -@end itemize - -@noindent Unfortunately, @TeX{} may do some expansion in these situations, -possibly yielding errors. - -Also, quite a few macro-related constructs cause problems with @TeX{}; -some of the caveats are listed below. Thus, if you get macro-related -errors when producing the printed version of a manual, you might try -expanding the macros with @command{makeinfo} by invoking -@command{texi2dvi} with the @samp{-E} option (@pxref{Format with -@t{texi2dvi}}). Or, more reliably, eschew Texinfo macros altogether -and use a language designed for macro processing, such as M4 -(@pxref{External Macro Processors}). - -@itemize @bullet -@item -As mentioned earlier, macro names must consist entirely of letters. - -@item -It is not advisable to redefine any @TeX{} primitive, plain, or -Texinfo command name as a macro. Unfortunately this is a large and -open-ended set of names, and the possible resulting errors are -unpredictable. - -@item -All macros are expanded inside at least one @TeX{} group. - -@item -Macro arguments cannot cross lines. - -@item -Macros containing a command which must be on a line by itself, such as -a conditional, cannot be invoked in the middle of a line. Similarly, -macros containing line-oriented commands or text, such as -@code{@@example} environments, may behave unpredictably in @TeX{}. - -@item -White space is ignored at the beginnings of lines. - -@item -Macros can't be reliably used in the argument to accent commands -(@pxref{Inserting Accents}). - -@item -The backslash escape for commas in macro arguments does not work; -@code{@@comma@{@}} must be used. - -@item -As a consequence, if a macro takes two or more arguments, and you want -to pass an argument with the Texinfo command @code{@@,} (to produce a -cedilla, @pxref{Inserting Accents}), you have to use @code{@@value} or -another work-around. Otherwise, @TeX{} takes the comma as separating -the arguments. Example: - -@example -@@macro mactwo@{argfirst, argsecond@} -\argfirst\+\argsecond\. -@@end macro -@@set fc Fran@@,cois -@@mactwo@{@@value@{fc@}@} -@end example - -@noindent produces: - -@display -Fran@,cois+. -@end display - -The natural-seeming @code{@@mactwo@{Fran@@,cois@}} passes the two -arguments @samp{Fran@@} and @samp{cois} to the macro, and nothing good -results. And, as just mentioned, although the comma can be escaped -with a backslash for @code{makeinfo} (@samp{@@\,}), that doesn't work -in @TeX{}, so there is no other solution. - -@item -It is usually best to avoid comments inside macro definitions, but -see the next item. - -@item -In general, the interaction of newlines in the macro definitions and -invocations depends on the precise commands and context, -notwithstanding the previous statements. You may be able to work -around some problems with judicious use of @code{@@c}. Suppose you -define a macro that is always used on a line by itself: - -@example -@@macro linemac -@@cindex whatever @@c -@@end macro -... -foo -@@linemac -bar -@end example - -Without the @code{@@c}, there will be a unwanted blank line between -the @samp{@@cindex whatever} and the @samp{bar} (one newline comes -from the macro definition, one from after the invocation), causing an -unwanted paragraph break. - -On the other hand, you wouldn't want the @code{@@c} if the macro was -sometimes invoked in the middle of a line (the text after the -invocation would be treated as a comment). - -@item -In general, you can't arbitrarily substitute a macro (or -@code{@@value}) call for Texinfo command arguments, even when the text -is the same. Texinfo is not M4 (or even plain @TeX{}). It might work -with some commands, it fails with others. Best not to do it at all. -For instance, this fails: - -@example -@@macro offmacro -off -@@end macro -@@headings @@offmacro -@end example - -@noindent -This looks equivalent to @code{@@headings off}, but for @TeX{}nical -reasons, it fails with a mysterious error message (namely, -@samp{Paragraph ended before @@headings was complete}). - -@item -Macros cannot define macros in the natural way. To do this, you must -use conditionals and raw @TeX{}. For example: - -@example -@@ifnottex -@@macro ctor @{name, arg@} -@@macro \name\ -something involving \arg\ somehow -@@end macro -@@end macro -@@end ifnottex -@@tex -\gdef\ctor#1@{\ctorx#1,@} -\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} -@@end tex -@end example -@end itemize - -The @command{makeinfo} implementation also has the following -limitations (by design): - -@itemize -@item -@code{@@verbatim} and macros do not mix; for instance, you can't start -a verbatim block inside a macro and end it outside -(@pxref{@t{@@verbatim}}). Starting any environment inside a macro -and ending it outside may or may not work, for that matter. - -@item -Macros that completely define macros are ok, but it's not possible to -have incompletely nested macro definitions. That is, @code{@@macro} -and @code{@@end macro} (likewise for @code{@@rmacro}) must be -correctly paired. For example, you cannot start a macro definition -within a macro, and then end that nested definition outside the macro. -@end itemize - -In the @code{makeinfo} implementation before Texinfo 5.0, ends of -lines from expansion of an @code{@@macro} definition did not end an -@@-command line-delimited argument (@code{@@chapter}, @code{@@center}, -etc.). This is no longer the case. For example: - -@example -@@macro twolines@{@} -aaa -bbb -@@end macro -@@center @@twolines@{@} -@end example - -In the current @code{makeinfo}, this is equivalent to: - -@example -@@center aaa -bbb -@end example - -@noindent with just @samp{aaa} as the argument to @code{@@center}. In -the earlier implementation, it would have been parsed as this: - -@example -@@center aaa bbb -@end example - - -@node @t{@@alias} -@section @samp{@@alias @var{new}=@var{existing}} - -@anchor{alias}@c old name -@cindex Aliases, command -@cindex Command aliases -@findex alias - -The @samp{@@alias} command defines a new command to be just like an -existing one. This is useful for defining additional markup names, -thus preserving additional semantic information in the input even -though the output result may be the same. - -Write the @samp{@@alias} command on a line by itself, followed by the -new command name, an equals sign, and the existing command name. -Whitespace around the equals sign is optional and ignored if present. -Thus: - -@example -@@alias @var{new} = @var{existing} -@end example - -For example, if your document contains citations for both books and -some other media (movies, for example), you might like to define a -macro @code{@@moviecite@{@}} that does the same thing as an ordinary -@code{@@cite@{@}} but conveys the extra semantic information as well. -You'd do this as follows: - -@example -@@alias moviecite = cite -@end example - -Macros do not always have the same effect as aliases, due to vagaries -of argument parsing. Also, aliases are much simpler to define than -macros. So the command is not redundant. - -Unfortunately, it's not possible to alias Texinfo environments; for -example, @code{@@alias lang=example} is an error. - -Aliases must not be recursive, directly or indirectly. - -It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or -Texinfo command name as an alias. Unfortunately this is a very large -set of names, and the possible resulting errors from @TeX{} are -unpredictable. - -@command{makeinfo} will accept the same identifiers for aliases as it -does for macro names, that is, alphanumerics and (except as the first -character) @samp{-}. - - -@node @t{@@definfoenclose} -@section @code{@@definfoenclose}: Customized Highlighting - -@anchor{definfoenclose}@c old name -@cindex Highlighting, customized -@cindex Customized highlighting -@findex definfoenclose - -An @code{@@definfoenclose} command may be used to define a -highlighting command for all the non-@TeX{} output formats. A command -defined using @code{@@definfoenclose} marks text by enclosing it in -strings that precede and follow the text. You can use this to get -closer control of your output. - -Presumably, if you define a command with @code{@@definfoenclose}, you -will create a corresponding command for @TeX{}, either in -@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} of -@samp{@@tex} in your document. - -Write an @code{@@definfoenclose} command at the beginning of a line -followed by three comma-separated arguments. The first argument to -@code{@@definfoenclose} is the @@-command name (without the -@code{@@}); the second argument is the start delimiter string; and the -third argument is the end delimiter string. The latter two arguments -enclose the highlighted text in the output. - -A delimiter string may contain spaces. Neither the start nor end -delimiter is required. If you do not want a start delimiter but do -want an end delimiter, you must follow the command name with two -commas in a row; otherwise, the end delimiter string you intended will -naturally be (mis)interpreted as the start delimiter string. - -If you do an @code{@@definfoenclose} on the name of a predefined -command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or -@code{@@i}), the enclosure definition will override the built-in -definition. We don't recommend this. - -An enclosure command defined this way takes one argument in braces, -since it is intended for new markup commands (@pxref{Marking Text}). - -@findex phoo -For example, you can write: - -@example -@@definfoenclose phoo,//,\\ -@end example - -@noindent -near the beginning of a Texinfo file to define @code{@@phoo} as an Info -formatting command that inserts `//' before and `\\' after the argument -to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you -want `//bar\\' highlighted in Info. - -For @TeX{} formatting, you could write - -@example -@@iftex -@@global@@let@@phoo=@@i -@@end iftex -@end example - -@noindent -to define @code{@@phoo} as a command that causes @TeX{} to typeset the -argument to @code{@@phoo} in italics. - -Each definition applies to its own formatter: one for @TeX{}, the -other for everything else. The raw @TeX{} commands need to be in -@samp{@@iftex}. @code{@@definfoenclose} command need not be within -@samp{@@ifinfo}, unless you want to use different definitions for -different output formats. - -@findex headword -Here is another example: write - -@example -@@definfoenclose headword, , : -@end example - -@noindent -near the beginning of the file, to define @code{@@headword} as an Info -formatting command that inserts nothing before and a colon after the -argument to @code{@@headword}. - -@samp{@@definfoenclose} definitions must not be recursive, directly or -indirectly. - - -@node External Macro Processors -@section External Macro Processors: Line Directives -@cindex External macro processors -@cindex Macro processors, external - -Texinfo macros (and its other text substitution facilities) work fine -in straightforward cases. If your document needs unusually complex -processing, however, their fragility and limitations can be a problem. -In this case, you may want to use a different macro processor -altogether, such as M4 (@pxref{Top,,, m4, M4}) or CPP (@pxref{Top,,, -cpp, The C Preprocessor}). - -With one exception, Texinfo does not need to know whether its input is -``original'' source or preprocessed from some other source file. -Therefore, you can arrange your build system to invoke whatever -programs you like to handle macro expansion or other preprocessing -needs. Texinfo does not offer built-in support for any particular -preprocessor, since no one program seemed likely to suffice for the -requirements of all documents. - -@cindex Line numbers, in error messages -@cindex Error messages, line numbers in -The one exception is line numbers in error messages. In that case, -the line number should refer to the original source file, whatever it -may be. There's a well-known mechanism for this: the so-called -@samp{#line} directive. Texinfo supports this. - -@menu -* @t{#line} Directive:: -* TeX: @t{#line} and @TeX{}. -* Syntax: @t{#line} Syntax Details. -@end menu - - -@node @t{#line} Directive -@subsection @samp{#line} Directive - -@cindex @samp{#line} directive - -An input line such as this: - -@example -@hashchar{}line 100 "foo.ptexi" -@end example - -@noindent indicates that the next line was line 100 of the file -@file{foo.ptexi}, and so that's what an error message should refer to. -Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP -(@pxref{Line Control,,, cpp, The C Preprocessor}, and -@ref{Preprocessor Output,,, cpp, The C Preprocessor}) can generate -such lines. - -@vindex CPP_LINE_DIRECTIVES -The @command{makeinfo} program recognizes these lines by default, -except within @code{@@verbatim} blocks (@pxref{@t{@@verbatim}}. -Their recognition can be turned off completely with -@code{CPP_LINE_DIRECTIVES} (@pxref{Other Customization Variables}), -though there is normally no reason to do so. - -For those few programs (M4, CPP, Texinfo) which need to document -@samp{#line} directives and therefore have examples which would -otherwise match the pattern, the command @code{@@hashchar@{@}} can be -used (@pxref{Inserting a Hashsign}). The example line above looks -like this in the source for this manual: - -@example -@@hashchar@{@}line 100 "foo.ptexi" -@end example - -The @code{@@hashchar} command was added to Texinfo in 2013. If you -don't want to rely on it, you can also use @code{@@set} and -@code{@@value} to insert the literal @samp{#}: - -@example -@@set hash # -@@value@{hash@}line 1 "example.c" -@end example - -Or, if suitable, an @code{@@verbatim} environment can be used instead -of @code{@@example}. As mentioned above, @code{#line}-recognition is -disabled inside verbatim blocks. - - -@node @t{#line} and @TeX{} -@subsection @samp{#line} and @TeX{} - -@cindex @TeX{} and @samp{#line} directives -@cindex @samp{#line} directives, not processing with @TeX{} - -As mentioned, @command{makeinfo} recognizes the @samp{#line} -directives described in the previous section. However, -@file{texinfo.tex} does not and cannot. Therefore, such a line will -be incorrectly typeset verbatim if @TeX{} sees it. The solution is to -use @command{makeinfo}'s macro expansion options before running -@TeX{}. There are three approaches: - -@itemize @bullet -@item -If you run @command{texi2dvi} or its variants (@pxref{Format with -@t{texi2dvi}}), you can pass @option{-E} and @command{texi2dvi} -will run @command{makeinfo} first to expand macros and eliminate -@samp{#line}. - -@item -If you run @command{makeinfo} or its variants (@pxref{Generic -Translator @t{texi2any}}), you can specify @option{--no-ifinfo ---iftex -E somefile.out}, and then give @file{somefile.out} to -@code{texi2dvi} in a separate command. - -@item -Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf} -instead of @option{--dvi}.) @command{makeinfo} will then call -@command{texi2dvi -E}. -@end itemize - -@findex errormsg@r{, and line numbers in @TeX{}} -One last caveat regarding use with @TeX{}: since the @code{#line} -directives are not recognized, the line numbers emitted by the -@code{@@errormsg@{@}} command (@pxref{Conditional Commands}), or by -@TeX{} itself, are the (incorrect) line numbers from the derived file -which @TeX{} is reading, rather than the preprocessor-specified line -numbers. This is another example of why we recommend running -@command{makeinfo} for the best diagnostics (@pxref{@t{makeinfo} -Advantages}). - - -@node @t{#line} Syntax Details -@subsection @samp{#line} Syntax Details - -@cindex @samp{#line} syntax details -@cindex Syntax details, @samp{#line} -@cindex Regular expression, for @samp{#line} - -Syntax details for the @samp{#line} directive: the @samp{#} character -can be preceded or followed by whitespace, the word @samp{line} is -optional, and the file name can be followed by a whitespace-separated -list of integers (these are so-called ``flags'' output by CPP in some -cases). For those who like to know the gory details, the actual -(Perl) regular expression which is matched is this: - -@example -/^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/ -@end example - -As far as we've been able to tell, the trailing integer flags only -occur in conjunction with a filename, so that is reflected in the -regular expression. - -As an example, the following is a syntactically valid @samp{#line} -directive, meaning line 1 of @file{/usr/include/stdio.h}: - -@example -@hashchar{} 1 "/usr/include/stdio.h" 2 3 4 -@end example - -Unfortunately, the quoted filename (@samp{"..."}) has to be optional, -because M4 (especially) can often generate @samp{#line} directives -within a single file. Since the @samp{line} is also optional, the -result is that lines might match which you wouldn't expect, e.g., - -@example -@hashchar{} 1 -@end example - -The possible solutions are described above (@pxref{@t{#line} Directive}). - - -@node Include Files -@chapter Include Files - -@cindex Include files - -When a Texinfo processor sees an @code{@@include} command in a Texinfo -file, it processes the contents of the file named by the -@code{@@include} and incorporates them into the output files being -created. Include files thus let you keep a single large document as a -collection of conveniently small parts. - -@menu -* Using Include Files:: How to use the @code{@@include} command. -* @t{texinfo-multiple-files-update}:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. -@end menu - - -@node Using Include Files -@section How to Use Include Files - -@findex include - -To include another file within a Texinfo file, write the -@code{@@include} command at the beginning of a line and follow it on -the same line by the name of a file to be included. For example: - -@example -@@include buffers.texi -@end example - -@@-commands are expanded in file names. The one most likely to be -useful is @code{@@value} (@pxref{@t{@@set @@value}}), and even then -only in complicated situations. - -An included file should simply be a segment of text that you expect to -be included as is into the overall or @dfn{outer} Texinfo file; it -should not contain the standard beginning and end parts of a Texinfo -file. In particular, you should not start an included file with a -line saying @samp{\input texinfo}; if you do, that text is inserted -into the output file literally. Likewise, you should not end an -included file with an @code{@@bye} command; nothing after @code{@@bye} -is formatted. - -In the long-ago past, you were required to write an -@code{@@setfilename} line at the beginning of an included file, but no -longer. Now, it does not matter whether you write such a line. If an -@code{@@setfilename} line exists in an included file, it is ignored. - - -@node @t{texinfo-multiple-files-update} -@section @code{texinfo-multiple-files-update} - -@findex texinfo-multiple-files-update - -XEmacs Texinfo mode provides the -@code{texinfo-multiple-files-update} command. This command creates or -updates `Next', `Previous', and `Up' pointers of included files as -well as those in the outer or overall Texinfo file, and it creates or -updates a main menu in the outer file. Depending on whether you call -it with optional arguments, the command updates only the pointers in -the first @code{@@node} line of the included files or all of them: - -@table @kbd -@item M-x texinfo-multiple-files-update -Called without any arguments: - -@itemize @minus -@item -Create or update the `Next', `Previous', and `Up' pointers of the -first @code{@@node} line in each file included in an outer or overall -Texinfo file. - -@item -Create or update the `Top' level node pointers of the outer or -overall file. - -@item -Create or update a main menu in the outer file. -@end itemize - -@item C-u M-x texinfo-multiple-files-update -Called with @kbd{C-u} as a prefix argument: - -@itemize @minus{} -@item -Create or update pointers in the first @code{@@node} line in each -included file. - -@item -Create or update the `Top' level node pointers of the outer file. - -@item -Create and insert a master menu in the outer file. The master menu -is made from all the menus in all the included files. -@end itemize - -@item C-u 8 M-x texinfo-multiple-files-update -Called with a numeric prefix argument, such as @kbd{C-u 8}: - -@itemize @minus -@item -Create or update @strong{all} the `Next', `Previous', and `Up' pointers -of all the included files. - -@item -Create or update @strong{all} the menus of all the included -files. - -@item -Create or update the `Top' level node pointers of the outer or -overall file. - -@item -And then create a master menu in the outer file. This is similar to -invoking @code{texinfo-master-menu} with an argument when you are -working with just one file. -@end itemize -@end table - -Note the use of the prefix argument in interactive use: with a regular -prefix argument, just @w{@kbd{C-u}}, the -@code{texinfo-multiple-files-update} command inserts a master menu; -with a numeric prefix argument, such as @kbd{C-u 8}, the command -updates @strong{every} pointer and menu in @strong{all} the files and -then inserts a master menu. - - -@node Include Files Requirements -@section Include Files Requirements -@cindex Include files requirements -@cindex Requirements for include files - -If you plan to use the @code{texinfo-multiple-files-update} command, -the outer Texinfo file that lists included files within it should -contain nothing but the beginning and end parts of a Texinfo file, and -a number of @code{@@include} commands listing the included files. It -should not even include indices, which should be listed in an included -file of their own. - -Moreover, each of the included files must contain exactly one highest -level node (conventionally, @code{@@chapter} or equivalent), -and this node must be the first node in the included file. -Furthermore, each of these highest level nodes in each included file -must be at the same hierarchical level in the file structure. -Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an -@code{@@unnumbered} node. Thus, normally, each included file contains -one, and only one, chapter or equivalent-level node. - -The outer file should contain only @emph{one} node, the `Top' node. It -should @emph{not} contain any nodes besides the single `Top' node. The -@code{texinfo-multiple-files-update} command will not process -them. - - -@node Sample Include File -@section Sample File with @code{@@include} -@cindex Sample @code{@@include} file -@cindex Include file sample -@cindex @code{@@include} file sample - -Here is an example of an outer Texinfo file with @code{@@include} files -within it before running @code{texinfo-multiple-files-update}, which -would insert a main or master menu: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@c %**start of header -@@setfilename include-example.info -@@settitle Include Example -@c %**end of header -@end group - -... @xref{Sample Texinfo Files}, for -examples of the rest of the frontmatter ... - -@group -@@ifnottex -@@node Top -@@top Include Example -@@end ifnottex -@end group - -@group -@@include foo.texinfo -@@include bar.texinfo -@@include concept-index.texinfo -@@bye -@end group -@end example - -An included file, such as @file{foo.texinfo}, might look like this: - -@example -@group -@@node First -@@chapter First Chapter - -Contents of first chapter @dots{} -@end group -@end example - -The full contents of @file{concept-index.texinfo} might be as simple as this: - -@example -@group -@@node Concept Index -@@unnumbered Concept Index - -@@printindex cp -@end group -@end example - -The outer Texinfo source file for @cite{The XEmacs Lisp Reference -Manual} is named @file{lispref.texi}. This outer file contains a master -menu with 417 entries and a list of 41 @code{@@include} -files. - - -@node Include Files Evolution -@section Evolution of Include Files - -When Info was first created, it was customary to create many small -Info files on one subject. Each Info file was formatted from its own -Texinfo source file. This custom meant that XEmacs did not need to -make a large buffer to hold the whole of a large Info file when -someone wanted information; instead, XEmacs allocated just enough -memory for the small Info file that contained the particular -information sought. This way, XEmacs could avoid wasting memory. - -References from one file to another were made by referring to the file -name as well as the node name. (@xref{Other Info Files, , Referring to -Other Info Files}. Also, see @ref{Four and Five Arguments, , -@code{@@xref} with Four and Five Arguments}.) - -Include files were designed primarily as a way to create a single, -large printed manual out of several smaller Info files. In a printed -manual, all the references were within the same document, so @TeX{} -could automatically determine the references' page numbers. The Info -formatting commands used include files only for creating joint -indices; each of the individual Texinfo files had to be formatted for -Info individually. (Each, therefore, required its own -@code{@@setfilename} line.) - -However, because large Info files are now split automatically, it is -no longer necessary to keep them small. - -Nowadays, multiple Texinfo files are used mostly for large documents, -such as @cite{The XEmacs Lisp Reference Manual}, and for projects -in which several different people write different sections of a -document simultaneously. - -In addition, the Info formatting commands have been extended to work -with the @code{@@include} command so as to create a single large Info -file that is split into smaller files if necessary. This means that -you can write menus and cross references without naming the different -Texinfo files. - - -@node Hardcopy -@chapter Formatting and Printing Hardcopy -@cindex Format and print hardcopy -@cindex Printing hardcopy -@cindex Hardcopy, printing it -@cindex Making a printed manual -@cindex Sorting indices -@cindex Indices, sorting -@cindex @TeX{} index sorting - -Running the @command{texi2dvi} or @command{texi2pdf} command is the -simplest way to create printable output. These commands are installed -as part of the Texinfo package. - -More specifically, three major shell commands are used to print -formatted output from a Texinfo manual: one converts the Texinfo -source into something printable, a second sorts indices, and a third -actually prints the formatted document. When you use the shell -commands, you can either work directly in the operating system shell -or work within a shell inside XEmacs (or some other computing -environment). - -If you are using XEmacs, you can use commands provided by Texinfo -mode instead of shell commands. In addition to the three commands to -format a file, sort the indices, and print the result, Texinfo mode -offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue. - -Details are in the following sections. - -@menu -* Use @TeX{}:: Use @TeX{} to format for hardcopy. -* Format with @t{tex}/@t{texindex}:: How to format with explicit shell commands. -* Format with @t{texi2dvi}:: A simpler way to format. -* Print with @t{lpr}:: How to print. -* Within XEmacs:: How to format and print from an XEmacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using XEmacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for @TeX{}:: What to do before you use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* @t{@@smallbook}:: How to print small format books and manuals. -* A4 Paper:: How to print on A4 or A5 paper. -* @t{@@pagesizes}:: How to print with customized page sizes. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. -* Obtaining @TeX{}:: How to obtain @TeX{}. -@end menu - - -@node Use @TeX{} -@section Use @TeX{} - -The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, when used -correctly, does an exceptionally good job. - -@xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It -is not included in the Texinfo package, being a vast suite of software -itself. - - -@node Format with @t{tex}/@t{texindex} -@section Format with @code{tex}/@code{texindex} - -@cindex Shell formatting with @code{tex} and @code{texindex} -@cindex Formatting with @code{tex} and @code{texindex} -@cindex DVI file - -You can format the Texinfo file with the shell command @code{tex} -followed by the name of the Texinfo file. For example: - -@example -tex foo.texi -@end example - -@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary -files containing information for indices, cross references, etc. The -DVI file (for @dfn{DeVice Independent} file) can be printed on virtually -any device (see the following sections). - -@pindex texindex -The @code{tex} formatting command itself does not sort the indices; it -writes an output file of unsorted index data. To generate a printed -index after running the @command{tex} command, you first need a sorted -index to work from. The @command{texindex} command sorts indices. -(The source file @file{texindex.c} comes as part of the standard -Texinfo distribution, among other places.) (@command{texi2dvi} runs -@command{tex} and @command{texindex} as necessary.) - -@anchor{Names of index files} -@cindex Names of index files -@cindex Index file names -@code{tex} formatting command outputs unsorted index files under names -that obey a standard convention: the name of your main input file with -any @samp{.texinfo} (or similar, @pxref{Minimum,, What a Texinfo File -Must Have}), followed by the two letter names of indices. For -example, the raw index output files for the input file -@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, -@file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those -are exactly the arguments to give to @code{texindex}. - -@need 1000 -@cindex Wildcards -@cindex Globbing -Instead of specifying all the unsorted index file names explicitly, you -can use @samp{??} as shell wildcards and give the command in this -form: - -@example -texindex foo.?? -@end example - -@noindent -This command will run @code{texindex} on all the unsorted index files, -including any two letter indices that you have defined yourself using -@code{@@defindex} or @code{@@defcodeindex}. You can safely run -@samp{texindex foo.??} even if there are files with two letter -extensions that are not index files, such as @samp{foo.el}. The -@code{texindex} command reports but otherwise ignores such files. - -For each file specified, @code{texindex} generates a sorted index file -whose name is made by appending @samp{s} to the input file name. The -@code{@@printindex} command looks for a file with that name -(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the -raw index output file. - -After you have sorted the indices, you need to rerun @code{tex} on the -Texinfo file. This regenerates the DVI file, this time with -up-to-date index entries. - -Finally, you may need to run @code{tex} one more time, to get the page -numbers in the cross references correct. - -To summarize, this is a five step process: - -@enumerate -@item -Run @code{tex} on your Texinfo file. This generates a DVI file (with -undefined cross references and no indices), and the raw index files -(with two letter extensions). - -@item -Run @code{texindex} on the raw index files. This creates the -corresponding sorted index files (with three letter extensions). - -@item -Run @code{tex} again on your Texinfo file. This regenerates the DVI -file, this time with indices and defined cross references, but with -page numbers for the cross references from the previous run, generally -incorrect. - -@item -Sort the indices again, with @code{texindex}. - -@item -Run @code{tex} one last time. This time the correct page numbers are -written for the cross references. -@end enumerate - -@pindex texi2dvi -Alternatively, it's a one-step process: run @code{texi2dvi} -(@pxref{Format with @t{texi2dvi}}). - -You need not run @code{texindex} each time after you run @code{tex}. If -you do not, on the next run, the @code{tex} formatting command will use -whatever sorted index files happen to exist from the previous use of -@code{texindex}. This is usually ok while you are debugging. - -@cindex Auxiliary files, avoiding -@findex novalidate -@cindex Pointer validation, suppressing -@cindex Chapters, formatting one at a time -Sometimes you may wish to print a document while you know it is -incomplete, or to print just one chapter of a document. In that case, -the usual auxiliary files that @TeX{} creates and warnings @TeX{} -gives when cross references are not satisfied are just nuisances. You -can avoid them with the @code{@@novalidate} command, which you must -give @emph{before} the @code{@@setfilename} command -(@pxref{@t{@@setfilename}}). Thus, the beginning of your file -would look approximately like this: - -@example -\input texinfo -@@novalidate -@@setfilename myfile.info -@dots{} -@end example - -@noindent @code{@@novalidate} also turns off validation in -@code{makeinfo}, just like its @code{--no-validate} option -(@pxref{Pointer Validation}). - - -@node Format with @t{texi2dvi} -@section Format with @code{texi2dvi} - -@pindex texi2dvi @r{(shell script)} - -The @code{texi2dvi} command automatically runs both @TeX{} and -@command{texindex} as many times as necessary to produce a DVI file -with sorted indices and all cross references resolved. It is -therefore simpler than manually executing the -@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence -described in the previous section. - -To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where -@samp{prompt$ } is your shell prompt): - -@example -prompt$ @kbd{texi2dvi foo.texi} -@end example - -As shown in this example, the input filenames to @code{texi2dvi} must -include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under -MS-DOS and perhaps in other circumstances, you may need to run @samp{sh -texi2dvi foo.texi} instead of relying on the operating system to invoke -the shell on the @samp{texi2dvi} script. - -@opindex --command@r{, for @command{texi2dvi}} -One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}. -This inserts @var{cmd} on a line by itself after the -@code{@@setfilename} in a temporary copy of the input file before -running @TeX{}. With this, you can specify different printing -formats, such as @code{@@smallbook} (@pxref{@t{@@smallbook}}), -@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} -(@pxref{@t{@@pagesizes}}), without actually changing the document -source. (You can also do this on a site-wide basis with -@file{texinfo.cnf}; @pxref{Preparing for @TeX{}}). - -@opindex --pdf@r{, for @command{texi2dvi}} -@pindex pdftexi2dvi -With the @option{--pdf} option, @command{texi2dvi} produces PDF output -instead of DVI (@pxref{PDF Output}), by running @command{pdftex} -instead of @command{tex}. Alternatively, the command -@command{texi2pdf} is an abbreviation for running @samp{texi2dvi ---pdf}. The command @command{pdftexi2dvi} is also supported as a -convenience to AUC-@TeX{} users (@pxref{Top,,, auctex, AUC-@TeX{}}, since -that program merely prepends @samp{pdf} to DVI producing tools to have -PDF producing tools. - -@opindex --dvipdf@r{, for @command{texi2dvi}} -@pindex dvipdfmx -With the @option{--dvipdf} option, @command{texi2dvi} produces PDF -output by running @TeX{} and then a DVI-to-PDF program: if the -@env{DVIPDF} environment variable is set, that value is used, else -the first extant among @code{dvipdfmx}, @code{dvipdfm}, @code{dvipdf}, -@code{dvi2pdf}, @code{dvitopdf}. This method can support CJK -typesetting better than @command{pdftex}. - -@opindex --ps@r{, for @command{texi2dvi}} -@pindex dvips -With the @option{--ps} option, @command{texi2dvi} produces PostScript -instead of DVI, by running @command{tex} and then @command{dvips} -(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS} -environment variable, if set.) - -@cindex @LaTeX{}, processing with @command{texi2dvi} -@command{texi2dvi} can also be used to process @LaTeX{} files; simply -run @samp{texi2dvi filename.ext}. - -@opindex --language@r{, for @command{texi2dvi}} -Normally @command{texi2dvi} is able to guess the input file language -by its contents and file name suffix. If, however, it fails to do so -you can specify the input language using -@option{--language=@var{lang}} command line option, where @var{lang} -is either @samp{latex} or @samp{texinfo}. - -@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if -they are available; these extended versions of @TeX{} are not -required, and the DVI (or PDF) output is identical, but they simplify -the @TeX{} programming in some cases, and provide additional tracing -information when debugging @file{texinfo.tex}. - -@opindex --translate-file@r{, for @command{texi2dvi}} -Several options are provided for handling documents, written in -character sets other than ASCII@. The -@option{--translate-file=@var{file}} option instructs -@command{texi2dvi} to translate input into internal @TeX{} character -set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX -files, TCX files: Character translations, web2c, Web2c: A @TeX{} -implementation}). - -@opindex --recode@r{, for @command{texi2dvi}} -The options @option{--recode} and @option{--recode-from=@var{enc}} -allow conversion of an input document before running @TeX{}. The -@option{--recode} option recodes the document from encoding specified -by @samp{@@documentencoding} command -(@pxref{@t{@@documentencoding}}) to plain 7-bit @samp{texinfo} -encoding. - -@opindex --recode-from@r{, for @command{texi2dvi}} -The option @option{--recode-from=@var{enc}} recodes the document from -@var{enc} encoding to the encoding specified by -@samp{@@documentencoding}. This is useful, for example, if the -document is written in @samp{UTF-8} encoding and an equivalent 8-bit -encoding is supported by @command{makeinfo}. - -Both @option{--recode} and @option{--recode-from=@var{enc}} use -@command{recode} utility to perform the conversion. If -@command{recode} fails to process the file, @command{texi2dvi} prints -a warning and continues, using the unmodified input file. - -The option @option{-E} (equivalently, @option{-e} and -@option{--expand}) does Texinfo macro expansion using -@command{makeinfo} instead of the @TeX{} implementation (@pxref{Macro -Details}). Each implementation has its own limitations and -advantages. If this option is used, the string -@code{@@c@tie{}_texi2dvi} must not appear at the beginning of a line -in the source file. - -For the list of all options, run @samp{texi2dvi --help}. - - -@node Print with @t{lpr} -@section Print With @code{lpr -d} From Shell - -@pindex lpr @r{(DVI print command)} - -The precise command to print a DVI file depends on your system -installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr --d foo.dvi}. - -For example, the following commands will (perhaps) suffice to sort the -indices, format, and print the @cite{Bison Manual}: - -@example -@group -tex bison.texinfo -texindex bison.?? -tex bison.texinfo -lpr -d bison.dvi -@end group -@end example - -@noindent -(Remember that the shell commands may be different at your site; but -these are commonly used versions.) - -Using the @code{texi2dvi} shell script (see the previous section): - -@example -@group -texi2dvi bison.texinfo -lpr -d bison.dvi -# or perhaps dvips bison.dvi -o -@end group -@end example - -@cindex Shell printing, on MS-DOS/MS-Windows -@cindex Printing DVI files, on MS-DOS/MS-Windows -@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows} -@code{lpr} is a standard program on Unix systems, but it is usually -absent on MS-DOS/MS-Windows. Some network packages come with a -program named @code{lpr}, but these are usually limited to sending files -to a print server over the network, and generally don't support the -@samp{-d} option. If you are unfortunate enough to work on one of these -systems, you have several alternative ways of printing DVI files: - -@itemize @bullet{} -@item Find and install a Unix-like @code{lpr} program, or its clone. -If you can do that, you will be able to print DVI files just like -described above. - -@item Send the DVI files to a network printer queue for DVI files. -Some network printers have special queues for printing DVI files. You -should be able to set up your network software to send files to that -queue. In some cases, the version of @code{lpr} which comes with your -network software will have a special option to send a file to specific -queues, like this: - -@example -lpr -Qdvi -hprint.server.domain bison.dvi -@end example - -@item Convert the DVI file to a Postscript or PCL file and send it to your -local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man -pages for @code{dvilj}, for detailed description of these tools. Once -the DVI file is converted to the format your local printer understands -directly, just send it to the appropriate port, usually @samp{PRN}. -@end itemize - - -@node Within XEmacs -@section From an XEmacs Shell -@cindex Print, format from XEmacs shell -@cindex Format, print from XEmacs shell -@cindex Shell, format, print from -@cindex XEmacs shell, format, print from - -You can give formatting and printing commands from a shell within -XEmacs. To create a shell within XEmacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Hardcopy, , Format -and Print Hardcopy}, for details. - -You can switch to and from the shell buffer while @code{tex} is -running and do other editing. If you are formatting a long document -on a slow machine, this can be very convenient. - -You can also use @code{texi2dvi} from an XEmacs shell. For example, -here is how to use @code{texi2dvi} to format and print @cite{Using and -Porting GNU CC} from a shell within XEmacs: - -@example -@group -texi2dvi gcc.texinfo -lpr -d gcc.dvi -@end group -@end example - -See the next section for more information about formatting -and printing in Texinfo mode. - - -@node Texinfo Mode Printing -@section Formatting and Printing in Texinfo Mode -@cindex Region printing in Texinfo mode -@cindex Format and print in Texinfo mode -@cindex Print and format in Texinfo mode - -Texinfo mode provides several predefined key commands for @TeX{} -formatting and printing. These include commands for sorting indices, -looking at the printer queue, killing the formatting job, and -recentering the display of the buffer in which the operations -occur. - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -Run @code{texi2dvi} on the current buffer. - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -Run @TeX{} on the current region. - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}. - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -Print a DVI file that was made with @code{texinfo-tex-region} or -@code{texinfo-tex-buffer}. - -@item C-c C-t C-q -@itemx M-x tex-show-print-queue -Show the print queue. - -@item C-c C-t C-d -@itemx M-x texinfo-delete-from-print-queue -Delete a job from the print queue; you will be prompted for the job -number shown by a preceding @kbd{C-c C-t C-q} command -(@code{texinfo-show-tex-print-queue}). - -@item C-c C-t C-k -@itemx M-x tex-kill-job -Kill the currently running @TeX{} job started by either -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other -process running in the Texinfo shell buffer. - -@item C-c C-t C-x -@itemx M-x texinfo-quit-job -Quit a @TeX{} formatting job that has stopped because of an error by -sending an @key{x} to it. When you do this, @TeX{} preserves a record -of what it did in a @file{.log} file. - -@item C-c C-t C-l -@itemx M-x tex-recenter-output-buffer -Redisplay the shell buffer in which the @TeX{} printing and formatting -commands are run to show its most recent output. -@end table - -@need 1000 -Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right): - -@example -@group -C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} -C-c C-t C-p @r{Print the DVI file.} -C-c C-t C-q @r{Display the printer queue.} -@end group -@end example - -The Texinfo mode @TeX{} formatting commands start a subshell in XEmacs -called the @file{*tex-shell*}. The @code{texinfo-tex-command}, -@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} -commands are all run in this shell. - -You can watch the commands operate in the @samp{*tex-shell*} buffer, -and you can switch to and from and use the @samp{*tex-shell*} buffer -as you would any other shell buffer. - -@need 1500 -The formatting and print commands depend on the values of several variables. -The default values are: - -@example -@group - @r{Variable} @r{Default value} - -texinfo-texi2dvi-command "texi2dvi" -texinfo-tex-command "tex" -texinfo-texindex-command "texindex" -texinfo-delete-from-print-queue-command "lprm" -texinfo-tex-trailer "@@bye" -tex-start-of-header "%**start" -tex-end-of-header "%**end" -tex-dvi-print-command "lpr -d" -tex-show-queue-command "lpq" -@end group -@end example - -You can change the values of these variables with the @kbd{M-x -set-variable} command (@pxref{Examining, , Examining and Setting -Variables, xemacs, XEmacs User's Manual}), or with your @file{init.el} -initialization file (@pxref{Init File, , , xemacs, XEmacs User's -Manual}). - -@cindex Customize XEmacs package (@t{Development/Docs/Texinfo}) -Beginning with version 20, XEmacs offers a user-friendly interface, -called @dfn{Customize}, for changing values of user-definable variables. -@xref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs -User's Manual}, for more details about this. The Texinfo variables can -be found in the @samp{Development/Docs/Texinfo} group, once you invoke -the @kbd{M-x customize} command. - - -@node Compile-Command -@section Using the Local Variables List -@cindex Local variables -@cindex Compile command for formatting -@cindex Format with the compile command - -Yet another way to apply the @TeX{} formatting command to a Texinfo file -is to put that command in a @dfn{local variables list} at the end of the -Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} -commands as a @code{compile-command} and have XEmacs run it by typing -@kbd{M-x compile}. This creates a special shell called the -@file{*compilation*} buffer in which XEmacs runs the compile command. -For example, at the end of the @file{gdb.texinfo} file, after the -@code{@@bye}, you could put the following: - -@example -@group -Local Variables: -compile-command: "texi2dvi gdb.texinfo" -End: -@end group -@end example - -@noindent -This technique is most often used by programmers who also compile programs -this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}. - - -@node Requirements Summary -@section @TeX{} Formatting Requirements Summary -@cindex Requirements for formatting -@cindex Minimal requirements for formatting -@cindex Formatting requirements - -Every Texinfo file that is to be input to @TeX{} must begin with a -@code{\input} command and must contain an @code{@@setfilename} command: - -@example -\input texinfo -@@setfilename @var{arg-not-used-by-@TeX{}} -@end example - -@noindent -The first command instructs @TeX{} to load the macros it needs to -process a Texinfo file and the second command opens auxiliary files. - -Every Texinfo file must end with a line that terminates @TeX{}'s -processing and forces out unfinished pages: - -@example -@@bye -@end example - -Strictly speaking, these lines are all a Texinfo file needs to be -processed successfully by @TeX{}. - -Usually, however, the beginning includes an @code{@@settitle} command to -define the title of the printed manual, an @code{@@setchapternewpage} -command, a title page, a copyright page, and permissions. Besides an -@code{@@bye}, the end of a file usually includes indices and a table of -contents. (And of course most manuals contain a body of text as well.) - -For more information, see: - -@itemize @bullet -@item @ref{@t{@@settitle}}. -@item @ref{@t{@@setchapternewpage}}. -@item @ref{Headings}. -@item @ref{Titlepage & Copyright Page}. -@item @ref{Printing Indices & Menus}. -@item @ref{Contents}. -@end itemize - - -@node Preparing for @TeX{} -@section Preparing for @TeX{} -@cindex Preparing for @TeX{} -@cindex @TeX{} input initialization -@cindex @b{.profile} initialization file -@cindex @b{.cshrc} initialization file -@cindex Initialization file for @TeX{} input - -@TeX{} needs to know where to find the @file{texinfo.tex} file that the -@samp{\input texinfo} command on the first line reads. The -@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is -included in all standard GNU distributions. The latest version is -always available from the Texinfo source repository: -@smalldisplay -@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD} -@end smalldisplay - -@pindex texinfo.tex@r{, installing} - -Usually, the installer has put the @file{texinfo.tex} file in the -default directory that contains @TeX{} macros when GNU Texinfo, XEmacs or -other GNU software is installed. In this case, @TeX{} will find the -file and you do not need to do anything special. If this has not been -done, you can put @file{texinfo.tex} in the current directory when you -run @TeX{}, and @TeX{} will find it there. - -@pindex epsf.tex@r{, installing} -Also, you should install @file{epsf.tex}, if it is not already installed -from another distribution. More details are at the end of the description -of the @code{@@image} command (@pxref{Images}). - -@cindex European Computer Modern fonts, installing -@cindex EC fonts, installing -@cindex CM-Super fonts, installing -To be able to use quotation marks other than those used in English -you'll need to install European Computer Modern fonts and optionally -CM-Super fonts, unless they are already installed (@pxref{Inserting -Quotation Marks}). - -@pindex feymr10@r{, installing} -@cindex Euro font, installing -If you intend to use the @code{@@euro} command, you should install the -Euro font, if it is not already installed. @xref{@t{@@euro}}. - -@pindex texinfo.cnf @r{installation} -@cindex Customizing of @TeX{} for Texinfo -@cindex Site-wide Texinfo configuration file -Optionally, you may create a file @file{texinfo.cnf} for site -configuration. This file is read by @TeX{} when the -@code{@@setfilename} command is executed (@pxref{@t{@@setfilename}}). -You can put any commands you like there, according to local site-wide -conventions. They will be read by @TeX{} when processing any Texinfo -document. For example, if @file{texinfo.cnf} contains the line -@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents -will be processed with that page size in effect. If you have nothing -to put in @file{texinfo.cnf}, you do not need to create it. - -@cindex Environment variable @code{TEXINPUTS} -@vindex TEXINPUTS -If neither of the above locations for these system files suffice for -you, you can specify the directories explicitly. For -@file{texinfo.tex}, you can do this by writing the complete path for the -file after the @code{\input} command. Another way, that works for both -@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} -might read), is to set the @code{TEXINPUTS} environment variable in your -@file{.profile} or @file{.cshrc} file. - -Whether you use @file{.profile} or @file{.cshrc} depends on -whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, -@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) -command interpreter, respeictvely. - -In a @file{.profile} file, you could use the following @code{sh} command -sequence: - -@example -@group -TEXINPUTS=.:/home/me/mylib: -export TEXINPUTS -@end group -@end example - -@need 1000 -While in a @file{.cshrc} file, you could use the following @code{csh} -command sequence: - -@example -setenv TEXINPUTS .:/home/me/mylib: -@end example - - -On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use -of the @samp{;} character as directory separator, instead of @samp{:}.}: - -@example -@group -set TEXINPUTS=.;d:/home/me/mylib;c: -@end group -@end example - -@noindent -It is customary for DOS/Windows users to put such commands in the -@file{autoexec.bat} file, or in the Windows registry. - -@noindent -These settings would cause @TeX{} to look for @file{\input} file first -in the current directory, indicated by the @samp{.}, then in a -hypothetical user @samp{me}'s @file{mylib} directory, and finally in -the system directories. (A leading, trailing, or doubled @samp{:} -indicates searching the system directories at that point.) - -@cindex Dumping a .fmt file -@cindex Format file, dumping -Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, -web2c, Web2C}) so that @TeX{} can load Texinfo faster. (The -disadvantage is that then updating @file{texinfo.tex} requires -redumping.) You can do this by running this command, assuming -@file{epsf.tex} is findable by @TeX{}: - -@example -initex texinfo @@dump -@end example - -@noindent -(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to -wherever your @code{.fmt} files are found; typically, this will be in the -subdirectory @file{web2c} of your @TeX{} installation. - - -@node Overfull hboxes -@section Overfull ``hboxes'' -@cindex Overfull @samp{hboxes} -@cindex @samp{hbox}, overfull -@cindex Final output - -@TeX{} is sometimes unable to typeset a line without extending it into -the right margin. This can occur when @TeX{} comes upon what it -interprets as a long word that it cannot hyphenate, such as an -electronic mail network address or a very long title. When this -happens, @TeX{} prints an error message like this: - -@example -Overfull @@hbox (20.76302pt too wide) -@end example - -@findex hbox -@noindent -(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. -@samp{@@hbox} is a @TeX{} primitive not used in the Texinfo language.) - -@TeX{} also provides the line number in the Texinfo source file and -the text of the offending line, which is marked at all the places that -@TeX{} considered hyphenation. -@xref{Debugging with @TeX{}}, -for more information about typesetting errors. - -If the Texinfo file has an overfull hbox, you can rewrite the sentence -so the overfull hbox does not occur, or you can decide to leave it. A -small excursion into the right margin often does not matter and may not -even be noticeable. - -If you have many overfull boxes and/or an antipathy to rewriting, you -can coerce @TeX{} into greatly increasing the allowable interword -spacing, thus (if you're lucky) avoiding many of the bad line breaks, -like this: - -@findex \emergencystretch -@example -@@tex -\global\emergencystretch = .9\hsize -@@end tex -@end example - -@noindent -(You should adjust the fraction as needed.) This huge value for -@code{\emergencystretch} cannot be the default, since then the typeset -output would generally be of noticeably lower quality; the default -is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension -containing the current line width. - -@cindex Black rectangle in hardcopy -@cindex Rectangle, black in hardcopy -@cindex Box, ugly black in hardcopy -@cindex Ugly black rectangles in hardcopy -For what overfull boxes you have, however, @TeX{} will print a large, -ugly, black rectangle beside the line that contains the overfull hbox -unless told otherwise. This is so you will notice the location of the -problem if you are correcting a draft. - -@findex finalout -To prevent such a monstrosity from marring your final printout, write -the following in the beginning of the Texinfo file on a line of its own, -before the @code{@@titlepage} command: - -@example -@@finalout -@end example - - -@node @t{@@smallbook} -@section @code{@@smallbook}: Printing ``Small'' Books - -@anchor{smallbook}@c old name -@findex smallbook -@cindex Small book size -@cindex Book, printing small -@cindex Page sizes for books -@cindex Size of printed book - -By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch -format. However, you can direct @TeX{} to typeset a document in a 7 by -9.25 inch format that is suitable for bound books by inserting the -following command on a line by itself at the beginning of the Texinfo -file, before the title page: - -@example -@@smallbook -@end example - -@noindent -(Since many books are about 7 by 9.25 inches, this command might better -have been called the @code{@@regularbooksize} command, but it came to be -called the @code{@@smallbook} command by comparison to the 8.5 by 11 -inch format.) - -If you write the @code{@@smallbook} command between the -start-of-header and end-of-header lines, the Texinfo mode @TeX{} -region formatting command, @code{texinfo-tex-region}, will format the -region in ``small'' book size (@pxref{Start of Header}). - -@xref{@t{@@small@dots{}}}, for information about commands that make -it easier to produce examples for a smaller manual. - -@xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, -for other ways to format with @code{@@smallbook} that do not require -changing the source file. - - -@node A4 Paper -@section Printing on A4 Paper -@cindex A4 paper, printing on -@cindex A5 paper, printing on -@cindex Paper size, A4 -@cindex European A4 paper -@findex afourpaper - -You can tell @TeX{} to format a document for printing on European size -A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) -command. Write the command on a line by itself near the beginning of -the Texinfo file, before the title page. For example, this is how you -would write the header for this manual: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename texinfo -@@settitle Texinfo -@@afourpaper -@@c %**end of header -@end group -@end example - -@xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, -for other ways to format for different paper sizes that do not require -changing the source file. - -@findex afourlatex -@findex afourwide -You may or may not prefer the formatting that results from the command -@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in -wide format. - - -@node @t{@@pagesizes} -@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes -@anchor{pagesizes}@c old node name - -@findex pagesizes -@cindex Custom page sizes -@cindex Page sizes, customized -@cindex Text width and height -@cindex Width of text area -@cindex Height of text area -@cindex Depth of text area - -You can explicitly specify the height and (optionally) width of the main -text area on the page with the @code{@@pagesizes} command. Write this -on a line by itself near the beginning of the Texinfo file, before the -title page. The height comes first, then the width if desired, -separated by a comma. Examples: - -@example -@@pagesizes 200mm,150mm @c for b5 paper -@end example -@noindent and -@example -@@pagesizes 11.5in @c for legal paper -@end example - -@cindex B5 paper, printing on -@cindex Legal paper, printing on -This would be reasonable for printing on B5-size paper. To emphasize, -this command specifies the size of the @emph{text area}, not the size of -the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by -8.5@dmn{in} for legal). - -@cindex Margins on page, not controllable -To make more elaborate changes, such as changing any of the page -margins, you must define a new command in @file{texinfo.tex} or -@file{texinfo.cnf}. - -@xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, -for other ways to specify @code{@@pagesizes} that do not require -changing the source file. - -@code{@@pagesizes} is ignored by @code{makeinfo}. - - -@node Cropmarks and Magnification -@section Cropmarks and Magnification - -@findex cropmarks -@cindex Cropmarks for printing -@cindex Printing cropmarks -You can (attempt to) direct @TeX{} to print cropmarks at the corners -of pages with the @code{@@cropmarks} command. Write the -@code{@@cropmarks} command on a line by itself near the beginning of -the Texinfo file, before the title page, like this: - -@example -@@cropmarks -@end example - -This command is mainly for printers that typeset several pages on one -sheet of film; but you can attempt to use it to mark the corners of a -book set to 7 by 9.25 inches with the @code{@@smallbook} command. -(Printers will not produce cropmarks for regular sized output that is -printed on regular sized paper.) Since different printing machines -work in different ways, you should explore the use of this command -with a spirit of adventure. You may have to redefine the command in -@file{texinfo.tex}. - -The @code{@@cropmarks} command is recognized and ignored in non-@TeX{} -output formats. - -@findex \mag @r{(raw @TeX{} magnification)} -@cindex Magnified printing -@cindex Larger or smaller pages -You can attempt to direct @TeX{} to typeset pages larger or smaller -than usual with the @code{\mag} @TeX{} command. Everything that is -typeset is scaled proportionally larger or smaller. (@code{\mag} -stands for ``magnification''.) This is @emph{not} a Texinfo -@@-command, but is a raw @TeX{} command that is prefixed with a -backslash. You have to write this command between @code{@@tex} and -@code{@@end tex} (@pxref{Raw Formatter Commands}). - -Follow the @code{\mag} command with an @samp{=} and then a number that -is 1000 times the magnification you desire. For example, to print pages -at 1.2 normal size, write the following near the beginning of the -Texinfo file, before the title page: - -@example -@group -@@tex -\mag=1200 -@@end tex -@end group -@end example - -With some printing technologies, you can print normal-sized copies that -look better than usual by giving a larger-than-normal master to your -print shop. They do the reduction, thus effectively increasing the -resolution. - -Depending on your system, DVI files prepared with a -nonstandard-@code{\mag} may not print or may print only with certain -magnifications. Be prepared to experiment. - - -@node PDF Output -@section PDF Output -@cindex PDF output - -@pindex pdftex -The simplest way to generate PDF output from Texinfo source is to run -the convenience script @command{texi2pdf} (or @command{pdftexi2dvi}); -this executes the @command{texi2dvi} script with the @option{--pdf} -option (@pxref{Format with @t{texi2dvi}}). If for some reason you -want to process the document by hand, you can run the @command{pdftex} -program instead of plain @command{tex}. That is, run @samp{pdftex -foo.texi} instead of @samp{tex foo.texi}. - -@dfn{PDF} stands for `Portable Document Format'. It was invented by -Adobe Systems some years ago for document interchange, based on their -PostScript language. Related links: - -@itemize -@item -GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF -reader}. (It can also preview PostScript documents.) - -@item -@code{xpdf}, a freely available standalone -@uref{http://www.foolabs.com/xpdf/, PDF reader} for the X window -system. - -@item -@uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. - -@end itemize - -At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf} -commands as for the other output formats, since PDF documents contain -many internal low-level offsets and references that would be hard or -impossible to get right at the Texinfo source level. - -PDF files require dedicated software to be displayed, unlike the plain -ASCII formats (Info, HTML) that Texinfo supports. They also tend to -be much larger than the DVI files output by @TeX{} by default. -Nevertheless, a PDF file does define an actual typeset document in a -self-contained file, so it has its place. - - -@node Obtaining @TeX{} -@section Obtaining @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@TeX{} is a document formatter that is used by the FSF for its -documentation. It is the easiest way to get printed output (e.g., PDF -and PostScript) for Texinfo manuals. TeX is freely redistributable, -and you can get it over the Internet or on physical media. See -@url{http://tug.org/texlive}. - -@c please keep that text in sync with www.gnu.org/prep/FTP - - -@node Generic Translator @t{texi2any} -@chapter @code{texi2any}: The Generic Translator for Texinfo - -@command{texi2any} is the generic translator for Texinfo that can -produce different output formats and is highly customizable. It -supports these formats: - -@table @asis -@item Info (by default, or with @option{--info}), - -@item HTML (with @option{--html}), - -@item plain text (with @option{--plaintext}), - -@item Docbook (with @option{--docbook}), - -@item Texinfo XML (with @option{--xml}). -@end table - -@command{makeinfo} is an alias for @command{texi2any}. By default, -both @command{texi2any} and @command{makeinfo} generate Info output; -indeed, there are no differences in behavior based on the name. - -Beside these default formats, command line options to -@command{texi2any} can change many aspects of the output. Beyond -that, initialization files provide even more control over the final -output---nearly anything not specified in the Texinfo input file. -Initialization files are written in Perl, like the main program, and -anything which can be specified on the command line can also be -specified within a initialization file. - -The rest of this chapter goes into the details. - -@menu -* Reference Implementation:: @command{texi2any}: the reference implementation. -* Invoking @t{texi2any}:: Running the translator from a shell. -* @t{texi2any} Printed Output:: Calling @command{texi2dvi}. -* Pointer Validation:: How to check that pointers point somewhere. -* Customization Variables:: Configuring @command{texi2any}. -* Internationalization of Document Strings:: Translating program-inserted text. -* Invoking @t{pod2texi}:: Translating Perl pod to Texinfo. -* @t{texi2html}:: An ancestor of @command{texi2any}. -@end menu - - -@node Reference Implementation -@section @command{texi2any}: A Texinfo Reference Implementation - -@cindex @command{texi2any}, as reference implementation -@cindex Reference implementation -@cindex Implementation, @command{texi2any} as reference - -Above, we called @command{texi2any} ``the'' translator for Texinfo -instead of just ``a'' translator, even though (of course) it's -technically and legally possible for other implementations to be -written. The reason is that alternative implementations are very -likely to have subtle, or not-so-subtle, differences in behavior, and -thus Texinfo documents would become dependent on the processor. -Therefore, it is important to have a reference implementation that -defines parts of the language not fully specified by the manual (often -intentionally so). It is equally important to have consistent -command-line options and other behavior for all processors. - -@cindex Tree representation of documents -@cindex Syntax tree representation of documents -@cindex Abstract syntax tree representation of documents -For this reason, the once-independent @command{texi2html} Perl Texinfo -processor was made compatible with the C implementation of -@command{makeinfo}, to avoid continuing with two different -implementations (@pxref{History}). The current implementation, -@command{texi2any}, serves as the reference implementation. It -inherited the design of customization and other features from -@command{texi2html} (for more on @command{texi2html} compatibility, -@pxref{@t{texi2html}}). However, @code{texi2any} is a full -reimplementation: it constructs a tree-based representation of the -input document for all back-ends to work from. - -@cindex Texinfo language tests -@cindex Tests, of Texinfo language -Extensive tests of the language were developed at the same time as -@command{texi2any}; we plead with anyone thinking of writing a program -to parse Texinfo input to at least make use of these tests. - -@cindex Examples of using @command{texi2any} -@findex Texinfo::Parser module -The @command{texi2html} wrapper script (@pxref{@t{texi2html}}) -provides a very simple example of calling @command{texi2any} from a -shell script; it's in @file{util/texi2html} in the Texinfo sources. -More consequentially, @command{texi-elements-by-size} is an example -Perl script using the @code{Texinfo::Parser} module interface; it's -also in the @file{util} source directory. (Its functionality may also -be useful to authors; @pxref{texi-elements-by-size}.) - -@cindex Future of Texinfo implementations -With the release of @command{texi2any} as the reference -implementation, development of both the C implementation of -@command{makeinfo} and @command{texi2html} has been halted. Going -forward, we ask authors of Texinfo documents to use only -@command{texi2any}. - - -@node Invoking @t{texi2any} -@section Invoking @command{texi2any}/@code{makeinfo} from a Shell - -@anchor{Invoking makeinfo} -@pindex makeinfo -@pindex texi2any - -To process a Texinfo file, invoke @command{texi2any} or -@command{makeinfo} (the two names are synonyms for the same program; -we'll use the names interchangeably) followed by the name of the -Texinfo file. Also select the format you want to output with the -appropriate command line option (default is Info). Thus, to create -the Info file for Bison, type the following to the shell: - -@example -texi2any --info bison.texinfo -@end example - -You can specify more than one input file name; each is processed in -turn. If an input file name is @samp{-}, standard input is read. - -@anchor{@t{makeinfo} Options} -@c anchor{makeinfo options}@c prev name, but case-insensitive clash -@cindex @code{makeinfo} options -@cindex Options for @code{makeinfo} -@anchor{texi2any Options} -@cindex @code{texi2any} options -@cindex Options for @code{texi2any} - -The @command{texi2any} program accept many options. Perhaps the -most basic are those that change the output format. By default, -@command{texi2any} outputs Info. - -Each command line option is either a long name preceded by @samp{--} -or a single letter preceded by @samp{-}. You can use abbreviations -for the long option names as long as they are unique. - -For example, you could use the following shell command to create an -Info file for @file{bison.texinfo} in which lines are filled to only -68 columns: - -@example -texi2any --fill-column=68 bison.texinfo -@end example - -You can write two or more options in sequence, like this: - -@example -texi2any --no-split --fill-column=70 @dots{} -@end example - -@noindent -(This would keep the Info file together as one possibly very long -file and would also set the fill column to 70.) - -The options are (approximately in alphabetical order): - -@table @code -@item --commands-in-node-names -@opindex --commands-in-node-names -This option now does nothing, but remains for compatibility. (It used -to ensure that @@-commands in node names were expanded throughout the -document, especially @code{@@value}. This is now done by default.) - -@item --conf-dir=@var{path} -@opindex --conf-dir=@var{path} -Prepend @var{path} to the directory search list for finding -customization files that may be loaded with @option{--init-file} (see -below). The @var{path} value can be a single directory, or a list of -several directories separated by the usual path separator character -(@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading -@c Init Files}. - -@item --css-include=@var{file} -@opindex --css-include -When producing HTML, literally include the contents of @var{file}, -which should contain W3C cascading style sheets specifications, in the -@samp{<style>} block of the HTML output. If @var{file} is @samp{-}, -read standard input. @xref{HTML CSS}. - -@item --css-ref=@var{url} -@opindex --css-ref -When producing HTML, add a @samp{<link>} tag to the output which -references a cascading style sheet at @var{url}. This allows using -standalone style sheets. - -@item -D @var{var} -@opindex -D @var{var} -Cause the Texinfo variable @var{var} to be defined. This is -equivalent to @code{@@set @var{var}} in the Texinfo file -(@pxref{@t{@@set @@clear @@value}}). - -@item --disable-encoding -@itemx --enable-encoding -@opindex --disable-encoding -@opindex --enable-encoding -By default, or with @option{--enable-encoding}, output accented and -special characters in Info and plain text output based on -@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit -ASCII transliterations are output. @xref{@t{@@documentencoding}}, -and @ref{Inserting Accents}. - -@item --docbook -@opindex --docbook -Generate Docbook output (rather than Info). - -@item --document-language=@var{lang} -@opindex --document-language -Use @var{lang} to translate Texinfo keywords which end up in the -output document. The default is the locale specified by the -@code{@@documentlanguage} command if there is one, otherwise English -(@pxref{@t{@@documentlanguage}}). - -@item --dvi -@opindex --dvi -Generate a TeX DVI file using @command{texi2dvi}, rather than Info -(@pxref{@t{texi2any} Printed Output}). - -@item --dvipdf -@opindex --dvipdf -Generate a PDF file using @command{texi2dvi --dvipdf}, rather than -Info (@pxref{@t{texi2any} Printed Output}). - -@item --error-limit=@var{limit} -@itemx -e @var{limit} -@opindex --error-limit=@var{limit} -@opindex -e @var{limit} -Report @var{LIMIT} errors before aborting (on the assumption that -continuing would be useless); default 100. - -@item --fill-column=@var{width} -@itemx -f @var{width} -@opindex --fill-column=@var{width} -@opindex -f @var{width} -Specify the maximum number of columns in a line; this is the -right-hand edge of a line. Paragraphs that are filled will be filled -to this width. (Filling is the process of breaking up and connecting -lines so that lines are the same length as or shorter than the number -specified as the fill column. Lines are broken between words.) The -default value is 72. - -@item --footnote-style=@var{style} -@itemx -s @var{style} -@opindex --footnote-style=@var{style} -@opindex -s @var{style} -Set the footnote style to @var{style}: either @samp{end} for the end -node style (the default) or @samp{separate} for the separate node -style. The value set by this option overrides the value set in a -Texinfo file by an @code{@@footnotestyle} command (@pxref{Footnote -Styles}). - -When the footnote style is @samp{separate}, @code{makeinfo} makes a -new node containing the footnotes found in the current node. When the -footnote style is @samp{end}, @code{makeinfo} places the footnote -references at the end of the current node. - -In HTML, when the footnote style is @samp{end}, or if the output is -not split, footnotes are put at the end of the output. If set to -@samp{separate}, and the output is split, they are placed in a -separate file. - -@item --force -@itemx -F -@opindex --force -@opindex -F -Ordinarily, if the input file has errors, the output files are not -created. With this option, they are preserved. - -@item --help -@itemx -h -@opindex --help@r{, for @command{texi2any}} -@opindex -h -Print a message with available options and basic usage, then exit -successfully. - -@item --html -@opindex --html -Generate HTML output (rather than Info). By default, the HTML output -is split into one output file per Texinfo source node, and the split -output is written into a subdirectory based on the name of the -top-level Info file. @xref{Generating HTML}. - -@item -I @var{path} -@opindex -I @var{path} -Append @var{path} to the directory search list for finding files that -are included using the @code{@@include} command. By default, -@code{texi2any} searches only the current directory. If @var{path} is -not given, the current directory is appended. The @var{path} value -can be a single directory or a list of several directories separated -by the usual path separator character (@samp{:} on Unix-like systems, -@samp{;} on Windows). - -@item --ifdocbook -@opindex --ifdocbook -@itemx --ifhtml -@opindex --ifhtml -@itemx --ifinfo -@opindex --ifinfo -@itemx --ifplaintext -@opindex --ifplaintext -@itemx --iftex -@opindex --iftex -@itemx --ifxml -@opindex --ifxml -For the given format, process @samp{@@if@var{format}} and -@samp{@@@var{format}} commands, and do not process -@samp{@@ifnot@var{format}}, regardless of the format being output. -For instance, if @option{--iftex} is given, then @samp{@@iftex} and -@samp{@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be -ignored. - -@item --info -@opindex --info -Generate Info output. By default, if the output file contains more -than about 300,000 bytes, it is split into shorter subfiles of about -that size. The name of the output file and any subfiles is determined -by @code{@@setfilename} (@pxref{@t{@@setfilename}}). @xref{Tag and -Split Files}. - -@item --init-file=@var{file} -@opindex --init-file=@var{file} -Load @var{file} as code to modify the behavior and output of the -generated manual. It is customary to use the @code{.pm} or the -@code{.init} extensions for these customization files, but that is not -enforced; the @var{file} name can be anything. The -@option{--conf-dir} option (see above) can be used to add to the list -of directories in which these customization files are searched for. -@c @xref{Loading Init Files}. - -@item --internal-links=@var{file} -@opindex --internal-links=@var{file} -@cindex Internal links, of HTML -In HTML mode, output a tab-separated file containing three columns: -the internal link to an indexed item or item in the table of contents, -the name of the index (or table of contents) in which it occurs, and -the term which was indexed or entered. The items are in the natural -sorting order for the given element. This dump can be useful for -post-processors. - -@item --macro-expand=@var{file} -@itemx -E @var{file} -@opindex --macro-expand=@var{file} -@opindex -E @var{file} -Output the Texinfo source, with all Texinfo macros expanded, to -@var{file}. Normally, the result of macro expansion is used -internally by @code{makeinfo} and then discarded. - -@item --no-headers -@opindex --no-headers -@cindex Node separators, omitting with @option{--no-headers} -@cindex Generating plain text files with @option{--no-headers} -@cindex Menus, omitting with @option{--no-headers} -Do not include menus or node separator lines in the output. - -When generating Info, this is the same as using @option{--plaintext}, -resulting in a simple plain text file. Furthermore, -@code{@@setfilename} is ignored, and output is to standard output -unless overridden with @option{-o}. (This behavior is for backward -compatibility.) - -@cindex Navigation links, omitting -When generating HTML, and output is split, also output navigation -links only at the beginning of each file. If output is not split, do -not include navigation links at the top of each node at all. -@xref{Generating HTML}. - -@item --no-ifdocbook -@opindex --no-ifdocbook -@itemx --no-ifhtml -@opindex --no-ifhtml -@itemx --no-ifinfo -@opindex --no-ifinfo -@itemx --no-ifplaintext -@opindex --no-ifplaintext -@itemx --no-iftex -@opindex --no-iftex -@itemx --no-ifxml -@opindex --no-ifxml -For the given format, do not process @samp{@@if@var{format}} and -@samp{@@@var{format}} commands, and do process -@samp{@@ifnot@var{format}}, regardless of the format being output. -For instance, if @option{--no-ifhtml} is given, then @samp{@@ifhtml} -and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml} -blocks will be. - -@item --no-node-files -@itemx --node-files -@opindex --no-node-files -@opindex --node-files -When generating HTML, create redirection files for anchors and any -nodes not already output with the file name corresponding to the node -name (@pxref{HTML Xref Node Name Expansion}). This makes it possible -for section- and chapter-level cross-manual references to succeed -(@pxref{HTML Xref Configuration}). - -If the output is split, this is enabled by default. If the output is -not split, @option{--node-files} enables the creation of the -redirection files, in addition to the monolithic main output file. -@option{--no-node-files} suppresses the creation of redirection files -in any case. This option has no effect with any output format other -than HTML@. @xref{Generating HTML}. - -@item --no-number-footnotes -@opindex --no-number-footnotes -Suppress automatic footnote numbering. By default, footnotes are -numbered sequentially within a node, i.e., the current footnote number -is reset to 1 at the start of each node. - -@item --no-number-sections -@itemx --number-sections -@opindex --no-number-sections -@opindex --number-sections -With @option{--number_sections} (the default), output chapter, -section, and appendix numbers as in printed manuals. This works only -with hierarchically-structured manuals. You should specify -@code{--no-number-sections} if your manual is not normally structured. - -@item --no-pointer-validate -@itemx --no-validate -@opindex --no-pointer-validate -@opindex --no-validate -@cindex Pointer validation, suppressing from command line -Suppress the pointer-validation phase of @code{makeinfo}---a dangerous -thing to do. This can also be done with the @code{@@novalidate} -command (@pxref{Use @TeX{}}). Normally, consistency checks are made -to ensure that cross references can be resolved, etc. @xref{Pointer -Validation}. - -@item --no-warn -@opindex --no-warn -Suppress warning messages (but not error messages). - -@item --output=@var{file} -@itemx -o @var{file} -@opindex --output=@var{file} -@opindex -o @var{file} -Specify that the output should be directed to @var{file}. This -overrides any file name specified in an @code{@@setfilename} command -found in the Texinfo source. If neither @code{@@setfilename} nor this -option are specified, the input file name is used to determine the -output name. @xref{@t{@@setfilename}}. - -If @var{file} is @samp{-}, output goes to standard output and -@samp{--no-split} is implied. - -If @var{file} is a directory or ends with a @samp{/} the usual rules -are used to determine the output file name (namely, use -@code{@@setfilename} or the input file name) but the files are written -to the @var{file} directory. For example, @samp{makeinfo -o bar/ -foo.texi}, with or without @option{--no-split}, will write -@file{bar/foo.info}, and possibly other files, under @file{bar/}. - -When generating HTML and output is split, @var{file} is used as the -name for the directory into which all files are written. For example, -@samp{makeinfo -o bar --html foo.texi} will write -@file{bar/index.html}, among other files. - -@item --output-indent=@var{val} -@opindex --outputindent -This option now does nothing, but remains for compatibility. (It used -to alter indentation in XML/Docbook output.) - -@item -P @var{path} -@opindex -P @var{path} -Prepend @var{path} to the directory search list for @code{@@include}. -If @var{path} is not given, the current directory is prepended. See -@samp{-I} above. - -@item --paragraph-indent=@var{indent} -@itemx -p @var{indent} -@opindex --paragraph-indent=@var{indent} -@opindex -p @var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command (@pxref{@t{@@paragraphindent}}). -The value of @var{indent} is interpreted as follows: - -@table @asis -@item @samp{asis} -Preserve any existing indentation (or lack thereof) at the beginnings -of paragraphs. - -@item @samp{0} or @samp{none} -Delete any existing indentation. - -@item @var{num} -Indent each paragraph by @var{num} spaces. -@end table - -The default is to indent by two spaces, except for paragraphs -following a section heading, which are not indented. - -@item --pdf -@opindex --pdf -Generate a PDF file using @command{texi2dvi --pdf}, rather than Info -(@pxref{@t{texi2any} Printed Output}). - -@item --plaintext -@opindex --plaintext -@cindex Plain text output with @option{--plaintext} -@cindex ASCII text output with @option{--plaintext} -@cindex Generating plain text files with @option{--plaintext} -@cindex Node separators, omitting with @option{--plaintext} -@cindex Menus, omitting with @option{--plaintext} -@cindex @file{INSTALL} file, generating -Output a plain text file (rather than Info): do not include menus or -node separator lines in the output. This results in a straightforward -plain text file that you can (for example) send in email without -complications, or include in a distribution (for example, an -@file{INSTALL} file). - -With this option, @code{@@setfilename} is ignored and the output goes -to standard output by default; this can be overridden with @option{-o}. - -@item --ps -@opindex --ps -Generate a PostScript file using @command{texi2dvi --ps}, rather than -Info (@pxref{@t{texi2any} Printed Output}). - -@item --set-customization-variable @var{var}=@var{value} -@itemx -c @var{var}=@var{value} -@opindex --set-customization-variable @var{var}=@var{value} -@opindex -c @var{var}=@var{value} -Set the customization variable @var{var} to @var{value}. The @code{=} -is optional, but both @var{var} and @var{value} must be quoted to the -shell as necessary so the result is a single word. Many aspects of -@command{texi2any} behavior and output may be controlled by -customization variables, beyond what can be set in the document by -@@-commands and with other command line switches. @xref{Customization -Variables}. - -@item --split=@var{how} -@itemx --no-split -@opindex --split=@var{how} -@opindex --no-split -@cindex Splitting of output files -@cindex Output file splitting -@anchor{Splitting Output} -@c -When generating Info, by default large output files are split into -smaller subfiles, of approximately 300k bytes. When generating HTML, -by default each output file contains one node (@pxref{Generating -HTML}). @option{--no-split} suppresses this splitting of the output. - -Alternatively, @option{--split=@var{how}} may be used to specify at -which level the HTML output should be split. The possible values for -@var{how} are: - -@table @samp -@item chapter -The output is split at @code{@@chapter} and other sectioning -@@-commands at this level (@code{@@appendix}, etc.). - -@item section -The output is split at @code{@@section} and similar. - -@item node -The output is split at every node. This is the default. -@end table - -@item --split-size=@var{num} -@opindex --split-size=@var{num} -Keep Info files to at most @var{num} characters if possible; default -is 300,000. (However, a single node will never be split across Info -files.) - -@item --transliterate-file-names -@opindex --transliterate-file-names -Enable transliteration of 8-bit characters in node names for the -purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}. - -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to @code{@@clear -@var{var}} in the Texinfo file (@pxref{@t{@@set @@clear @@value}}). - -@item --verbose -@opindex --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -Normally, @code{makeinfo} only outputs messages if there are errors or -warnings. - -@item --version -@itemx -V -@opindex --version@r{, for @command{texi2any}} -@opindex -V -Print the version number, then exit successfully. - -@item --Xopt @var{str} -@opindex --Xopt @var{str} -Pass @var{str} (a single shell word) to @command{texi2dvi}; may be -repeated (@pxref{@t{texi2any} Printed Output}). - -@item --xml -@opindex --xml -Generate Texinfo XML output (rather than Info). - -@end table - -@vindex TEXINFO_OUTPUT_FORMAT -@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} -@command{makeinfo} also reads the environment variable -@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not -overridden by a command line option. The value should be one of: - -@example -docbook dvi dvipdf html info pdf plaintext ps xml -@end example - -If not set or otherwise specified, Info output is the default. - -The customization variable of the same name is also read; if set, that -overrides an environment variable setting, but not a command-line -option. @xref{Customization Variables for @@-Commands}. - - -@node @t{texi2any} Printed Output -@section @command{texi2any} Printed Output - -@cindex Printed output, through @command{texi2any} -@cindex Output, printed through @command{texi2any} - -To justify the name Texinfo-to-@emph{any}, @command{texi2any} has -basic support for creating printed output in the various formats: -@TeX{} DVI, PDF, and PostScript. This is done via the simple method -of executing the @command{texi2dvi} program when those outputs are -requested. - -The output format options for this are @option{--dvi}, -@option{--dvipdf}, @option{--pdf}, and @option{--ps}. @xref{Format -with @t{texi2dvi}}, for more details on these options and general -@command{texi2dvi} operation. In addition, the @option{--verbose}, -@option{--silent}, and @option{--quiet} options are passed on if -specified; the @option{-I} and @option{-o} options are likewise passed -on with their arguments, and @option{--debug} without its argument. - -The only option remaining that is related to the @command{texi2dvi} -invocation is @option{--Xopt}. Here, just the argument is passed on -and multiple @option{--Xopt} options accumulate. This provides a way -to construct an arbitrary command line for @command{texi2dvi}. For -example, running - -@example -texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi -@end example - -@noindent is equivalent to running - -@example -texi2dvi -t @@a4paper --pdf foo.texi -@end example - -Although one might wish that other options to @command{texi2any} would -take effect, they don't. For example, running @samp{texi2any ---no-number-sections --dvi foo.texi} still results in a DVI file with -numbered sections. (Perhaps this could be improved in the future, if -requests are received.) - -The actual name of the command that is invoked is specified by the -@code{TEXI2DVI} customization variable (@pxref{Other Customization -Variables}). As you might guess, the default is @samp{texi2dvi}. - -@command{texi2any} itself does not generate any output when it invokes -@command{texi2dvi}. - - -@node Pointer Validation -@section Pointer Validation -@cindex Pointer validation with @code{makeinfo} -@cindex Validation of pointers - -If you do not suppress pointer validation with the -@samp{--no-validate} option or the @code{@@novalidate} command in the -source file (@pxref{Use @TeX{}}), @code{makeinfo} will check the -validity of the Texinfo file. - -Most validation checks are different depending on whether node -pointers are explicitly or implicitly determined. With explicit node -pointers, here is the list of what is checked: - -@enumerate -@item -If a `Next', `Previous', or `Up' node reference is a reference to a -node in the current file and is not an external reference such as to -@file{(dir)}, then the referenced node must exist. - -@item -Every node except the `Top' node must have an `Up' pointer. - -@item -The node referenced by an `Up' pointer must itself reference the -current node through a menu item, unless the node referenced by `Up' -has the form @samp{(@var{file})}. -@end enumerate - -With implicit node pointers, the above error cannot occur, as such. -(Which is a major reason why we recommend using this feature of -@code{makeinfo}, and not specifying any node pointers yourself.) - -Instead, @code{makeinfo} checks that the tree constructed from the -document's menus matches the tree constructed from the sectioning -commands. For example, if a chapter-level menu mentions nodes -@var{n1} and @var{n2}, in that order, nodes @var{n1} and @var{n2} must -be associated with @code{@@section} commands in the chapter. - -Finally, with both explicit and implicit node pointers, -@code{makeinfo} checks that every node except the `Top' node is -referenced in a menu. - - -@node Customization Variables -@section Customization Variables - -@quotation Warning -These customization variable names and meanings may change in any -Texinfo release. We always try to avoid incompatible changes, but we -cannot absolutely promise, since needs change over time. -@end quotation - -Many aspects of the behavior and output of @command{texi2any} may be -modified by modifying so-called @dfn{customization variables}. These -fall into a few general categories: - -@itemize @bullet -@item -Those associated with @@-commands; for example, -@code{@@documentlanguage}. - -@item -Those associated with command-line options; for example, the -customization variable @code{SPLIT} is associated with the -@option{--split} command-line option, and @code{TEXINFO_OUTPUT_FORMAT} -allows specifying the output format. - -@item -Those associated with customizing the HTML output. - -@item -Other ad hoc variables. -@end itemize - -Customization variables may set on the command line using -@code{--set-customization-variable '@var{var} @var{value}'} (quoting -the variable/value pair to the shell) or -@code{--set-customization-variable @var{var}=@var{value}} (using -@code{=}). A special @var{value} is @samp{undef}, which sets the -variable to this special ``undefined'' Perl value. - -The sections below give the details for each of these. - -@menu -* Commands: Customization Variables for @@-Commands. -* Options: Customization Variables and Options. -* HTML: HTML Customization Variables. -* Other: Other Customization Variables. -@end menu - - -@node Customization Variables for @@-Commands -@subsection Customization Variables for @@-Commands - -@cindex Customization variables for @@-commands -@cindex @@-commands, customization variables for - -Each of the following @@-commands has an associated customization -variable with the same name (minus the leading @code{@@}): - -@smallexample -@@allowcodebreaks @@clickstyle @@codequotebacktick -@@codequoteundirected @@contents @@deftypefnnewline -@@documentdescription @@documentencoding @@documentlanguage -@@evenfooting @@evenfootingmarks -@@evenheading @@evenheadingmarks -@@everyfooting @@everyfootingmarks -@@everyheading @@everyheadingmarks -@@exampleindent @@firstparagraphindent -@@fonttextsize @@footnotestyle @@frenchspacing @@headings -@@kbdinputstyle @@novalidate -@@oddfooting @@oddfootingmarks -@@oddheading @@oddheadingmarks -@@pagesizes @@paragraphindent -@@setchapternewpage @@setcontentsaftertitlepage -@@setfilename -@@setshortcontentsaftertitlepage @@shortcontents -@@urefbreakstyle @@xrefautomaticsectiontitle -@end smallexample - -Setting such a customization variable to a value @samp{foo} is similar -to executing @code{@@@var{cmd} foo}. It is not exactly the same, -though, since any side effects of parsing the Texinfo source are not -redone. Also, some variables do not take Texinfo code when generating -particular formats, but an argument that is already formatted. This -is the case, for example, for HTML for @code{documentdescription}. - - -@node Customization Variables and Options -@subsection Customization Variables and Options - -@cindex Customization variables for options -@cindex Options, customization variables for - -The following table gives the customization variables associated with -some command line options. @xref{Invoking @t{texi2any}}, for the -meaning of the options. - -@multitable @columnfractions 0.5 0.5 -@headitem Option @tab Variable -@vindex ENABLE_ENCODING -@item @option{--enable-encoding} @tab @code{ENABLE_ENCODING} -@vindex documentlanguage -@item @option{--document-language} @tab @code{documentlanguage} -@vindex ERROR_LIMIT -@item @option{--error-limit} @tab @code{ERROR_LIMIT} -@vindex FILLCOLUMN -@item @option{--fill-column} @tab @code{FILLCOLUMN} -@vindex footnotestyle -@item @option{--footnote-style} @tab @code{footnotestyle} -@vindex FORCE -@item @option{--force} @tab @code{FORCE} -@vindex INTERNAL_LINKS -@item @option{--internal-links} @tab @code{INTERNAL_LINKS} -@vindex MACRO_EXPAND -@item @option{--macro-expand} @tab @code{MACRO_EXPAND} -@vindex HEADERS -@vindex SHOW_MENU -@item @option{--headers} @tab @code{HEADERS}, @code{SHOW_MENU} -@vindex NO_WARN -@item @option{--no-warn} @tab @code{NO_WARN} -@vindex novalidate -@item @option{--no-validate} @tab @code{novalidate} -@vindex NUMBER_FOOTNOTES -@item @option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES} -@vindex NUMBER_SECTIONS -@item @option{--number-sections} @tab @code{NUMBER_SECTIONS} -@vindex NODE_FILES -@item @option{--node-files} @tab @code{NODE_FILES} -@vindex OUT -@vindex OUTFILE -@vindex SUBDIR -@item @option{--output} @tab @code{OUT}, @code{OUTFILE}, - @code{SUBDIR} -@vindex paragraphindent -@item @option{--paragraph-indent} @tab @code{paragraphindent} -@vindex SILENT -@item @option{--silent} @tab @code{SILENT} -@vindex SPLIT -@item @option{--split} @tab @code{SPLIT} -@vindex SPLIT_SIZE -@item @option{--split-size} @tab @code{SPLIT_SIZE} -@vindex TRANSLITERATE_FILE_NAMES -@item @option{--transliterate-file-names} @tab @code{TRANSLITERATE_FILE_NAMES} -@vindex VERBOSE -@item @option{--verbose} @tab @code{VERBOSE} -@end multitable - -Setting such a customization variable to a value @samp{foo} is -essentially the same as specifying the @code{--@var{opt}=foo} if the -option takes an argument, or @code{--@var{opt}} if not. - -@vindex TEXINFO_OUTPUT_FORMAT -In addition, the customization variable @code{TEXINFO_OUTPUT_FORMAT} -allows specifying what @code{makeinfo} outputs, either one of the usual -output formats that can be specified with options, or various other -forms: - -@ftable @samp -@item docbook -@itemx dvi -@itemx dvipdf -@itemx html -@itemx info -@itemx pdf -@itemx plaintext -@itemx ps -@itemx xml -These correspond to the command-line options (and -@code{TEXINFO_OUTPUT_FORMAT} environment variable values) of the same -name. @xref{Invoking @t{texi2any}}. - -@item debugcount -Instead of generating a regular output format, output the count of -bytes and lines obtained when converting to Info, and other information. - -@item debugtree -@cindex tree representation, for debugging -@cindex debugging document, with tree representation -Instead of generating a regular output format, output a text representation -of the tree obtained by parsing the input texinfo document. - -@item parse -Do only Texinfo source parsing; there is no output. - -@item plaintexinfo -Output the Texinfo source with all the macros, @code{@@include} and -@code{@@value@{@}} expanded. This is similar to setting -@option{--macro-expand}, but instead of being output in addition to -the normal conversion, output of Texinfo is the main output. - -@item rawtext -@cindex raw text output -Output raw text, with minimal formatting. For example, footnotes are -ignored and there is no paragraph filling. This is used by the parser -for file names and copyright text in HTML comments, for example. - -@item structure -Do only Texinfo source parsing and determination of the document -structure; there is no output. - -@item texinfosxml -@cindex SXML output -@cindex S-expressions, output format -Output the document in TexinfoSXML representation, a syntax for -writing XML data using Lisp S-expressions. - -@item textcontent -@cindex spell checking -@cindex word counting -@pindex detexinfo -@cindex stripping Texinfo commands -Output the text content only, stripped of commands; this is useful for -spell checking or word counting, for example. The trivial -@code{detexinfo} script setting this is in the @file{util} directory -of the Texinfo source as an example. It's one line: - -@example -exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@" -@end example -@end ftable - - -@node HTML Customization Variables -@subsection HTML Customization Variables - -This table gives the customization variables which apply to HTML -output only. A few other customization variable apply to both HTML -and other output formats; those are given in the next section. - -@vtable @code -@item AVOID_MENU_REDUNDANCY -For HTML@. If set, and the menu entry and menu description are the -same, then do not print the menu description; default false. - -@item AFTER_BODY_OPEN -For HTML@. If set, the corresponding text will appear at the -beginning of each HTML file; default unset. - -@item AFTER_ABOUT -For HTML, when an About-element is output. If set, the corresponding -text will appear at the end of the About element; default unset. - -@item AFTER_OVERVIEW -@itemx AFTER_TOC_LINES -For HTML@. If set, the corresponding text is output after the short -table of contents for @code{AFTER_OVERVIEW} and after the table of -contents for @code{AFTER_TOC_LINES}; otherwise, a default string is -used. At the time of writing, a @code{</div>} element is closed. - -In general, you should set @code{BEFORE_OVERVIEW} if -@code{AFTER_OVERVIEW} is set, and you should set -@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set. - - -@item BASEFILENAME_LENGTH -For HTML@. The maximum length of the base filenames; default 245. -Changing this would make cross-manual references to such long node -names invalid (@pxref{HTML Xref Link Basics}). - -@item BEFORE_OVERVIEW -@itemx BEFORE_TOC_LINES -For HTML@. If set, the corresponding text is output before the short -table of contents for @code{BEFORE_OVERVIEW} and before the table of -contents for @code{BEFORE_TOC_LINES}, otherwise a default string is -used. At the time of writing, a @code{<div ...>} element is opened. - -In general you should set @code{AFTER_OVERVIEW} if -@code{BEFORE_OVERVIEW} is set, and you should set -@code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set. - - -@item BIG_RULE -For HTML@. Rule used after and before the top element and before -special elements, but not for footers and headers; default -@code{<hr>}. - -@item BODYTEXT -@cindex @code{<body>} text, customizing -For HTML, the text appearing in @code{<body>}. By default, set -automatically, taking into account the document language -(@pxref{@t{@@documentlanguage}}). - -@item CASE_INSENSITIVE_FILENAMES -For HTML@. Construct output file names as if the filesystem were case -insensitive (@pxref{HTML Splitting}); default false. - -@item CHAPTER_HEADER_LEVEL -For HTML@. Header formatting level used for chapter level sectioning -commands; default @samp{2}. - -@item CHECK_HTMLXREF -For HTML@. Check that manuals which are the target of external -cross references (@pxref{Four and Five Arguments}) are present in -@file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false. - -@item COMPLEX_FORMAT_IN_TABLE -For HTML@. If set, use tables for indentation of complex formats; default -false. - -@item CSS_LINES -For HTML@. CSS output, automatically determined by default (@pxref{HTML CSS}). - -@item DATE_IN_HEADER -For HTML@. Put the document generation date in the header; off by default. - -@item DEF_TABLE -For HTML@. If set, a @code{<table>} construction for @code{@@deffn} -and similar @@-commands is used (looking more like the @TeX{} output), -instead of definition lists; default false. - -@item DEFAULT_RULE -For HTML@. Rule used between element, except before and after the -top element, and before special elements, and for footers and headers; -default @code{<hr>}. - -@item DO_ABOUT -For HTML@. If set to 0 never do an About special element; -if set to 1 always do an About special element; -default 0. -@c @xref{Output Elements Defined}. - -@item EXTERNAL_DIR -For HTML@. Base directory for external manuals; default none. It is -better to use the general external cross reference mechanism -(@pxref{HTML Xref Configuration}) than this variable. - -@item EXTRA_HEAD -For HTML@. Additional text appearing within @code{<head>}; default unset. - -@item FOOTNOTE_END_HEADER_LEVEL -For HTML@. Header formatting level used for the footnotes header with -the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}. - -@item FOOTNOTE_SEPARATE_HEADER_LEVEL -For HTML@. Header formatting level used for the footnotes header with -the `separate' footnotestyle; default @samp{4}. @xref{Footnote -Styles}. - -@item FRAMES -For HTML@. If set, a file describing the frame layout is generated, -together with a file with the short table of contents; default false. - -@item FRAMESET_DOCTYPE -For HTML@. Same as DOCTYPE, but for the file containing the frame -description. - -@item HEADER_IN_TABLE -For HTML@. Use tables for header formatting rather than a simple -@code{<div>} element; default false. - -@item ICONS -For HTML@. Use icons for the navigation panel; default false. - -@item IMAGE_LINK_PREFIX -For HTML@. If set, the associated value is prepended to the image file -links; default unset. - -@item INLINE_CONTENTS -For HTML@. If set, output the contents where the @code{@@contents} and -similar @@-commands are located; default true. This is ignored if -@code{@@set*contentsaftertitlepage} is set (@pxref{Contents}). - -@item INLINE_CSS_STYLE -For HTML@. Put CSS directly in HTML elements rather than at the -beginning of the output; default false. - -@item KEEP_TOP_EXTERNAL_REF -For HTML@. If set, do not ignore @samp{Top} as the first -argument for an external ref to a manual, as is done by default. -@xref{Top Node Naming}. - -@item L2H -For HTML@. If set, @command{latex2html} is used to convert @code{@@math} -and @code{@@tex} sections; default false. Best used with @option{--iftex}. - -@item L2H_CLEAN -(Relevant only if @code{L2H} is set.) If set, the intermediate files -generated in relation with @command{latex2html} are removed; default -true. - -@item L2H_FILE -(Relevant only if @code{L2H} is set.) If set, the given file is used -as @command{latex2html}'s init file; default unset. - -@item L2H_HTML_VERSION -(Relevant only if @code{L2H} is set.) The HTML version used in the -@command{latex2html} call; default unset. - -@item L2H_L2H -(Relevant only if @code{L2H} is set.) The program invoked as -@command{latex2html}; default is @code{latex2html}. - -@item L2H_SKIP -(Relevant only if @code{L2H} is set.) If set to a true value, the -actual call to @command{latex2html} is skipped; previously generated -content is reused instead. If set to 0, the cache is not used at all. -If set to @samp{undef}, the cache is used for as many @TeX{} fragments as -possible and for any remaining the command is run. The default is -@samp{undef}. - -@item L2H_TMP -(Relevant only if @code{L2H} is set.) Set the directory used for -temporary files. None of the file name components in this directory -name may start with @samp{.}; otherwise, @command{latex2html} will -fail (because of @command{dvips}). The default is the empty string, -which means the current directory. - -@item MAX_HEADER_LEVEL -For HTML@. Maximum header formatting level used (higher header -formatting level numbers correspond to lower sectioning levels); -default @samp{4}. - -@item MENU_SYMBOL -For HTML@. Symbol used in front of menu entries when node names are used -for menu entries formatting; default @samp{•}. - -@item MONOLITHIC -For HTML@. Output only one file including the table of contents. Set -by default, but only relevant when the output is not split. - -@item NO_CSS -For HTML@. Do not use CSS; default false. @xref{HTML CSS}. - -@item NODE_FILE_EXTENSION -For HTML@. Extension for node files if @code{NODE_FILENAMES} is set; -default @samp{html}. - -@item PRE_ABOUT -For HTML, when an About element is output. If set to a text string, -this text will appear at the beginning of the About element. If set -to a reference on a subroutine, the result of the subroutine call will -appear at the beginning of the About element. If not set (the -default), default text is used. - -@item PRE_BODY_CLOSE -For HTML@. If set, the given text will appear at the footer of each -HTML file; default unset. - -@item PROGRAM_NAME_IN_FOOTER -For HTML@. If set, output the program name and miscellaneous related -information in the page footers; default false. - -@item SHORTEXTN -For HTML@. If set, use @samp{.htm} as extension; default false. - -@item SHOW_TITLE -For HTML@. If set, output the title at the beginning of the document; -default true. - -@item SIMPLE_MENU -For HTML@. If set, use a simple preformatted style for the menu, -instead of breaking down the different parts of the menu; default false. -@xref{Menu Parts}. - -@item TOC_LINKS -For HTML@. If set, links from headings to toc entries are created; -default false. - -@item TOP_FILE -This file name may be used for the top-level file. The extension is -set appropriately, if necessary. This is used to override the default, -and is, in general, only taken into account when output is split, and -for HTML@. - -@item TOP_NODE_FILE -For HTML@. File name used for the Top node, if @code{NODE_FILENAMES} -is set; default is @code{index}. - -@item TOP_NODE_FILE_TARGET -For HTML@. File name used for the Top node in cross references; -default is @code{index}. - -@item TOP_NODE_UP_URL -For HTML@. The url used for the Up pointer of the Top node; default -@code{undef}, meaning no link is generated. - -@item USE_ACCESSKEY -@cindex @code{accesskey}, customization variable for -For HTML@. Use @code{accesskey} in cross references; default true. - -@item USE_ISO -For HTML@. Use entities for doubled single-quote characters -(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--} -(@pxref{Conventions}); default true. - -@item USE_LINKS -@cindex @code{<link>} HTML tag, in @code{<head>} -@cindex @code{<head>} HTML tag, and @code{<link>} -For HTML@. Generate @code{<link>} elements in the HTML @code{<head>} -output; default true. - -@item USE_REL_REV -For HTML@. Use @code{rel} in cross references; default true. - -@item VERTICAL_HEAD_NAVIGATION -For HTML@. If set, a vertical navigation panel is used; default false. - -@item WORDS_IN_PAGE -@cindex Navigation panel, bottom of page -For HTML, with output split at nodes. Specifies the approximate -minimum page length at which a navigation panel is placed at the -bottom of a page. To avoid ever having the navigation buttons at the -bottom of a page, set this to a sufficiently large number. The -default is 300. - -@item XREF_USE_FLOAT_LABEL -For HTML@. If set, for the float name in cross references, use the -float label instead of the type followed by the float number -(@pxref{@t{@@float}}). The default is off. - -@item XREF_USE_NODE_NAME_ARG -For HTML@. Only relevant for cross reference commands with no cross -reference name (second argument). If set to@tie{}1, use the node name -(first) argument in cross reference @@-commands for the text displayed -as the hyperlink. If set to@tie{}0, use the node name if -@code{USE_NODES} is set, otherwise the section name. If set to -@samp{undef}, use the first argument in preformatted environments, -otherwise use the node name or section name depending on -@code{USE_NODES}. The default is @samp{undef}. - -@end vtable - - -@node Other Customization Variables -@subsection Other Customization Variables - -This table gives the remaining customization variables, which apply to -multiple formats, or affect global behavior, or otherwise don't fit -into the categories of the previous sections. - -@vtable @code -@item CLOSE_QUOTE_SYMBOL -When a closing quote is needed, use this character; default @code{’} -in HTML, @code{’} in Docbook. The default for Info is the same -as @code{OPEN_QUOTE_SYMBOL} (see below). - -@c @item COMPLETE_IMAGE_PATHS -@c If set, the image files are computed to be relative from the document -@c directory to the source manual directory, and then to the image. - -@item CPP_LINE_DIRECTIVES -Recognize @code{#line} directives in a ``preprocessing'' pass -(@pxref{External Macro Processors}); on by default. - -@item DEBUG -If set, debugging output is generated; default is off (zero). -@c The integer value specifies what kinds of debugging output are -@c generated. It is a bitmask. Setting it to 255 ensures having all -@c available debugging output. - -@item DOCTYPE -@vindex SystemLiteral -For Docbook, HTML, XML@. Specifies the @code{SystemLiteral}, the -entity's system identifier. This is a URI which may be used to -retrieve the entity, and identifies the canonical DTD for the -document. The default value is different for each of HTML, Docbook -and Texinfo@tie{}XML. - -@item DUMP_TEXI -For debugging. If set, no conversion is done, only parsing and macro -expansion. If the option @option{--macro-expand} is set, the Texinfo -source is also expanded to the corresponding file. Default false. - -@item DUMP_TREE -For debugging. If set, the tree constructed upon parsing a Texinfo -document is output to standard error; default false. - -@item ENABLE_ENCODING_USE_ENTITY -For HTML, XML@. If @option{--enable-encoding} is set, and there is an -entity corresponding with the letter or the symbol being output, -prefer the entity. Set by default for HTML, but not XML. - -@item EXTERNAL_CROSSREF_SPLIT -For cross references to other manuals, this determines if the other -manual is considered to be split or monolithic. By default, it is set -based on the value of @code{SPLIT}. @xref{HTML Xref}, and @pxref{HTML -Xref Configuration}. - -@item EXTENSION -The extension added to the output file name. The default is different -for each output format. - -@item FIX_TEXINFO -For ``plain Texinfo'' (see the @code{PLAINTEXINFO} item). If set to -false, the resulting Texinfo does not have all errors corrected, such -as missing @samp{@@end}; default true. This variable is only -relevant when expanding Texinfo; other converters always try to -output something sane even if the input is erroneous. - -@c @item IDX_SUMMARY -@c If set, for each @code{@@printindex} a file named -@c @file{@var{docname}_@var{idxname}.idx} is created, containing lines of -@c the form: -@c -@c @example -@c @var{key} @var{reference} -@c @end example -@c -@c @noindent sorted alphabetically (case matters). - -@item IGNORE_BEFORE_SETFILENAME -If set, begin outputting at @code{@@setfilename}, if -@code{@@setfilename} is present; default true. - -@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME -If set, spaces are ignored after an @@-command that takes braces. -Default true, matching the @TeX{} behavior. - -@item INDEX_ENTRY_COLON -Symbol used between the index entry and the associated node or section; -default @samp{:}. - -@item INFO_SPECIAL_CHARS_WARNING -If set, warn about problematic constructs for Info output (such as the -string @samp{::}) in node names, menu items, and cross references; -default true. Do not warn about index entries, since parsing problems -there don't prevent navigation; readers can still relatively easily -find their way to the node in question. - -@item INLINE_INSERTCOPYING -If set, @code{@@insertcopying} is replaced by the @code{@@copying} -content (@pxref{@t{@@copying}}) as if @code{@@insertcopying} were a -user-defined macro; default false. - -@item INPUT_ENCODING_NAME -Normalized encoding name suitable for output. Should be a usable -charset name in HTML, typically one of the preferred IANA encoding -names. You should not need to use this variable, since it is set by -@code{@@documentencoding} (@pxref{@t{@@documentencoding}}). - -@item INPUT_PERL_ENCODING -Perl encoding used to process the Texinfo source. You should not need -to use that variable, since it is set by @code{@@documentencoding} -(@pxref{@t{@@documentencoding}}). - -@item MACRO_BODY_IGNORES_LEADING_SPACE -Ignore white space at the beginning of user defined macro body line, -mimicking a @TeX{} limitation (@pxref{Macro Details}). Default off. - -@item MAX_MACRO_CALL_NESTING -The maximal number of recursive calls of @@-commands defined through -@code{@@rmacro}; default 100000. The purpose of this variable is to -avoid infinite recursions. - -@item MENU_ENTRY_COLON -Symbol used between the menu entry and the description; default -@samp{:}. - -@item NO_USE_SETFILENAME -If set, do not use @code{@@setfilename} to set the document name; -instead, base the output document name only on the input file name. -The default is false. - -@item NODE_FILENAMES -If set, node names are used to construct file names. By default, it -is set if the output is split by node, or if @code{NODE_FILES} is set -and the output is split in any way. - -@item NODE_NAME_IN_INDEX -If set, use node names in index entries, otherwise prefer section names; -default true. - -@item NODE_NAME_IN_MENU -If set, use node names in menu entries, otherwise prefer section names; -default true. - -@item OPEN_QUOTE_SYMBOL -When an opening quote is needed, e.g., for @samp{@@samp} output, use -the specified character; default @code{‘} for HTML, -@code{‘} for Docbook. For Info, the default depends on the -enabled document encoding (@pxref{@t{@@documentencoding}}); if no -document encoding is set, or the encoding is US-ASCII, etc., @samp{'} -is used. This character usually appears as an undirected single quote -on modern systems. If the document encoding is Unicode, the Info -output uses a Unicode left quote. - -@item OUTPUT_ENCODING_NAME -Normalized encoding name used for output files. Should be a usable -charset name in HTML, typically one of the preferred IANA encoding -names. By default, if an input encoding is set (typically through -@code{@@documentencoding} or @code{INPUT_ENCODING_NAME}), this -information is used to set the output encoding name. If no input -encoding is specified, the default output encoding name may be set by -the output format. In particular, the XML-based formats use -@code{utf-8} for @code{OUTPUT_ENCODING_NAME} if the encoding is not -otherwise specified. @xref{@t{@@documentencoding}}. - -@item OVERVIEW_LINK_TO_TOC -If set, the cross references in the Overview link to the corresponding -Table of Contents entries; default true. - -@item PACKAGE -@itemx PACKAGE_VERSION -@itemx PACKAGE_AND_VERSION -@itemx PACKAGE_URL -@itemx PACKAGE_NAME -The implementation's short package name, package version, package name -and version concatenated, package url, and full package name, -respectively. By default, these variables are all set through -Autoconf, Automake, and @code{configure}. - -@item PREFIX -The output file prefix, which is prepended to some output file names. -By default it is set by @code{@@setfilename} or from the input file -(@pxref{@t{@@setfilename}}). How this value is used depends on the -value of other customization variables or command line options, such -as whether the output is split and @code{NODE_FILENAMES}. The default -is unset. - -@item PROGRAM -Name of the program used. By default, it is set to the name of the -program launched, with a trailing @samp{.pl} removed. - -@item RENAMED_NODES_FILE -If set, use the value for the renamed nodes description file. If not -set, the file is @file{@var{doc_basename}-noderename.cnf}. -@xref{HTML Xref Link Preservation}. - -@item RENAMED_NODES_REDIRECTIONS -If set, create redirection files for renamed nodes. Set by default -when generating HTML@. - -@item SHOW_MENU -@opindex --no-headers -If set, Texinfo menus are output. By default, it is set unless -generating Docbook or if @option{--no-headers} is specified. - -@item SORT_ELEMENT_COUNT -@pindex texi-elements-by-size -@cindex Longest nodes, finding -@cindex Sorting nodes by size -If set, the name of a file to which a list of elements (nodes or -sections, depending on the output format) is dumped, sorted by the -number of lines they contain after removal of @@-commands; default -unset. This is used by the program @code{texi-elements-by-size} in -the @file{util/} directory of the Texinfo source distribution -(@pxref{texi-elements-by-size}). - -@item SORT_ELEMENT_COUNT_WORDS -When dumping the elements-by-size file (see preceding item), use word -counts instead of line counts; default false. - -@c @item SPLIT_INDEX -@c For HTML@. If set, the output is split, and the output from -@c @code{@@printindex} happens in a sectioning element at the level of -@c splitting, then split index pages at the next letter after they have -@c more than that many entries. If set to 0, no index splitting. - -@item TEST -If set to true, some variables which are normally dynamically -generated anew for each run (date, program name, version) are set to -fixed and given values. This is useful to compare the output to a -reference file, as is done for the tests. The default is false. - -@item TEXI2DVI -Name of the command used to produce PostScript, PDF, and DVI; default -@samp{texi2dvi}. @xref{@t{texi2any} Printed Output}. - -@item TEXI2HTML -@cindex compatibility, with @command{texi2html} -Generate HTML and try to be as compatible as possible with -@command{texi2html}; default false. - -@item TEXINFO_COLUMN_FOR_DESCRIPTION -Used with the @code{indent_menu_descriptions} tree transformation, -described below; default 32 (matching -@code{texinfo-column-for-description} in XEmacs)). - -@item TEXINFO_DTD_VERSION -For XML@. Version of the DTD used in the XML output preamble. The -default is set based on a variable in @file{configure.ac}. - -@item TEXTCONTENT_COMMENT -For stripped text content output (i.e., when -@code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}). If set, -also output comments. Default false. - -@item TOP_NODE_UP -Up node for the Top node; default @samp{(dir)}. - -@item TREE_TRANSFORMATIONS -The associated value is a comma separated list of transformations that -can be applied to the Texinfo tree prior to outputting the result. If -more than one is specified, the ordering is irrelevant; each is always -applied at the necessary point during processing. - -The only one executed by default is -@samp{move_index_entries_after_items} for HTML and Docbook output. -Here's an example of updating the master menu in a document: - -@example -makeinfo \ - -c TREE_TRANSFORMATIONS=regenerate_master_menu \ - -c PLAINTEXINFO=1 \ - mydoc.texi \ - -o /tmp/out -@end example - -@noindent (Caveat: Since @code{PLAINTEXINFO} output does expand -Texinfo macros and conditionals, it's necessary to remove any such -differences before installing the updates in the original document. -This will be remedied in a future release.) - -The following transformations are currently supported (many are used -in the @code{pod2texi} utility distributed with Texinfo; -@pxref{Invoking @t{pod2texi}}): - -@ftable @samp -@item complete_tree_nodes_menus -Add menu entries or whole menus for nodes associated with sections of -any level, based on the sectioning tree. - -@item fill_gaps_in_sectioning -Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in -sectioning. For example, an @code{@@unnumberedsec} will be inserted -if an @code{@@chapter} is followed by an @code{@@subsection}. - -@item indent_menu_descriptions -Reformat menus so that descriptions start at column -@code{TEXINFO_COLUMN_DESCRIPTION}. - -@item insert_nodes_for_sectioning_commands -Insert nodes for sectioning commands lacking a corresponding node. - -@item move_index_entries_after_items -In @code{@@enumerate} and @code{@@itemize}, move index entries -appearing just before an @code{@@item} to just after the -@code{@@item}. Comment lines between index entries are moved too. As -mentioned, this is always done for HTML and Docbook output. - -@item regenerate_master_menu -Update the Top node master menu, either replacing the (first) -@code{@@detailmenu} in the Top node menu, or creating it at the end of -the Top node menu. - -@item simple_menu -Mostly the same as @code{SIMPLE_MENU}: use a simple preformatted style -for the menu. It differs from setting @code{SIMPLE_MENU} in that -@code{SIMPLE_MENU} only has an effect in HTML output. - -@end ftable - -@item USE_NODES -Preferentially use nodes to decide where elements are separated. If -set to false, preferentially use sectioning to decide where elements -are separated. The default is true. - -@item USE_NODE_TARGET -If set, use the node associated with a section for the section target -in cross references; default true. - -@item USE_NUMERIC_ENTITY -For HTML and XML@. If set, use numeric entities instead of ASCII -characters when there is no named entity. By default, set to true for -HTML. - -@item USE_UP_NODE_FOR_ELEMENT_UP -Fill in up sectioning direction with node direction when there is no -sectioning up direction. In practice this can only happen when there -is no @@top section. Not set by default. - -@item USE_SETFILENAME_EXTENSION -Default is on for Info, off for other output. If set, use exactly -what @code{@@setfilename} gives for the output file name, including -the extension. You should not need to explicitly set this variable. - -@item USE_TITLEPAGE_FOR_TITLE -Use the full @code{@@titlepage} as the title, not a simple title string; -default false. - -@item USE_UNIDECODE -@pindex Text::Unidecode -If set to false, do not use the @code{Text::Unidecode} Perl module to -transliterate more characters; default true. - -@end vtable - - -@node Internationalization of Document Strings -@section Internationalization of Document Strings - -@cindex I18n, of document strings -@cindex Internationalization of document strings -@cindex Document strings, internationalization of -@cindex Output document strings, internationalization of -@cindex Translating strings in output documents - -@vindex documentlanguage @r{customization variable} -@command{texi2any} writes fixed strings into the output document at -various places: cross references, page footers, the help page, -alternate text for images, and so on. The string chosen depends on -the value of the @code{documentlanguage} at the time of the string -being output (@pxref{@t{@@documentlanguage}}, for the Texinfo -command interface). - -@pindex libintl-perl @r{Gettext implementation} -The Gettext framework is used for those strings (@pxref{Top,,, -gettext, Gettext}). The @code{libintl-perl} package is used as the -@code{gettext} implementation; more specifically, the pure Perl -implementation is used, so Texinfo can support consistent behavior -across all platforms and installations, which would not otherwise be -possible. @code{libintl-perl} is included in the Texinfo distribution -and always installed, to ensure that it is available if needed. It is -also possible to use the system @code{gettext} (the choice can be made -at build-time). - -@vindex texinfo_document @r{Gettext domain} -@cindex Perl format strings for translation -The Gettext domain @samp{texinfo_document} is used for the strings. -Translated strings are written as Texinfo, and may include -@@-commands. In translated strings, the varying parts of the string -are not usually denoted by @code{%s} and the like, but by -@samp{@{arg_name@}}. (This convention is common for @code{gettext} in -Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl -Format Strings, gettext, GNU Gettext}.) For example, in the -following, @samp{@{section@}} will be replaced by the section name: - -@example -see @{section@} -@end example - -These Perl-style brace format strings are used for two reasons: first, -changing the order of @code{printf} arguments is only available since -Perl@tie{}5.8.0; second, and more importantly, the order of arguments -is unpredictable, since @@-command expansion may lead to different -orders depending on the output format. - -The expansion of a translation string is done like this: - -@enumerate -@item First, the string is translated. The locale -is @var{@@documentlanguage}@code{.}@var{@@documentencoding}. - -@cindex @code{us-ascii} encoding, and translations -If the @var{@@documentlanguage} has the form @samp{ll_CC}, that is -tried first, and then just @samp{ll}. If that does not exist, and the -encoding is not @code{us-ascii}, then @code{us-ascii} is tried. - -The idea is that if there is a @code{us-ascii} encoding, it means that -all the characters in the charset may be expressed as @@-commands. -For example, there is a @code{fr.us-ascii} locale that can accommodate -any encoding, since all the Latin@tie{}1 characters have associated -@@-commands. On the other hand, Japanese has only a translation -@code{ja.utf-8}, since there are no @@-commands for Japanese -characters. - -@item Next, the string is expanded as Texinfo, and converted. -The arguments are substituted; for example, @samp{@{arg_name@}} is -replaced by the corresponding actual argument. - -@end enumerate - -In the following example, @samp{@{date@}}, @samp{@{program_homepage@}} -and @samp{@{program@}} are the arguments of the string. Since they -are used in @code{@@uref}, their order is not predictable. -@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are -substituted after the expansion: - -@example -Generated on @@emph@{@{date@}@} using -@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}. -@end example - -This approach is admittedly a bit complicated. Its usefulness is that -it supports having translations available in different encodings for -encodings which can be covered by @@-commands, and also specifying how -the formatting for some commands is done, independently of the output -format---yet still be language-dependent. For example, the -@samp{@@pxref} translation string can be like this: - -@example -see @{node_file_href@} section `@{section@}\' in @@cite@{@{book@}@} -@end example - -@noindent -which allows for specifying a string independently of the output -format, while nevertheless with rich formatting it may be translated -appropriately in many languages. - - -@node Invoking @t{pod2texi} -@section Invoking @t{pod2texi}: Convert POD to Texinfo - -@pindex pod2texi -@cindex Invoking @code{pod2texi} -@cindex POD, converting to Texinfo -@cindex Perl POD, converting to Texinfo - -The @code{pod2texi} program translates Perl pod documentation file(s) -to Texinfo. There are two basic modes of operation: generating a -standalone manual from each input pod, or (if @code{--base-level=1} or -higher is given) generating Texinfo subfiles suitable for use -with @code{@@include}. - -Although ordinarily this documentation in the Texinfo manual would be -the best place to look, in this case we have documented all the -options and examples in the @code{pod2texi} program itself, since it -may be useful outside of the rest of Texinfo. Thus, please see the -output of @code{pod2texi --help}, the version on the web at -@url{http://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc. - -For an example of using @code{pod2texi} to make Texinfo out of the -Perl documentation itself, see -@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo, -@file{contrib/perldoc-all}} in the Texinfo source distribution (the -output is available at @url{http://www.gnu.org/software/perl/manual}). - - -@node @t{texi2html} -@section @code{texi2html}: Ancestor of @code{texi2any} - -@pindex texi2html - -@cindex Cons, Lionel -Conceptually, the @command{texi2html} program is the parent of today's -@command{texi2any} program. @command{texi2html} was developed -independently, originally by Lionel Cons in 1998; at the time, -@command{makeinfo} could not generate HTML@. Many other people -contributed to @command{texi2html} over the years. - -The present @command{texi2any} uses little of the actual code of -@command{texi2html}, and has quite a different basic approach to the -implementation (namely, parsing the Texinfo document into a tree), but -still, there is a family resemblance. - -By design, @command{texi2any} supports nearly all the features of -@command{texi2html} in some way. However, we did not attempt to -maintain strict compatibility, so no @command{texi2html} executable is -installed by the Texinfo package. An approximation can be run with an -invocation like this (available as @file{util/texi2html} in the -Texinfo source): - -@example -texi2any --set-customization-variable TEXI2HTML=1 ... -@end example - -@noindent but, to emphasize, this is @emph{not} a drop-in replacement -for the previous @command{texi2html}. Here are the biggest differences: - -@itemize @bullet -@item Most blatantly, the command line options of @command{texi2html} -are now customization variables, for the most part. A table of -approximate equivalents is given below. - -@item The program-level customization API is very different in -@command{texi2any}. - -@item Indices cannot be split. - -@item Translated strings cannot be customized; we hope to introduce -this feature in @command{texi2any} in the future. - -@end itemize - -Aside from the last, we do not intend to reimplement these -differences. Therefore, the route forward for authors is alter -manuals and build processes as necessary to use the new features and -methods of @command{texi2any}. The @command{texi2html} maintainers -(one of whom is the principal author of @command{texi2any}) do not -intend to make further releases. - -@cindex Options of @command{texi2html} -@cindex Command-line options of @command{texi2html} -Here is the table showing @command{texi2html} options and -corresponding @command{texi2any} customization variables. -@c (@pxref{texi2any Output Customization,, @command{texi2any} Output -@c Customization}). - -@multitable {@option{--ignore-preamble-text}} {@code{IGNORE_PREAMBLE_TEXT}} -@item @option{--toc-links} @tab @code{TOC_LINKS} -@item @option{--short-ext} @tab @code{SHORTEXTN} -@item @option{--prefix} @tab @code{PREFIX} -@item @option{--short-ref} @tab @code{SHORT_REF} -@item @option{--idx-sum} @tab @code{IDX_SUMMARY} -@item @option{--def-table} @tab @code{DEF_TABLE} -@item @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT} -@item @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR} -@item @option{--l2h} @tab @code{L2H} -@item @option{--l2h-l2h} @tab @code{L2H_L2H} -@item @option{--l2h-skip} @tab @code{L2H_SKIP} -@item @option{--l2h-tmp} @tab @code{L2H_TMP} -@item @option{--l2h-file} @tab @code{L2H_FILE} -@item @option{--l2h-clean} @tab @code{L2H_CLEAN} -@item @option{--use-nodes} @tab @code{USE_NODES} -@item @option{--monolithic} @tab @code{MONOLITHIC} -@item @option{--top-file} @tab @code{TOP_FILE} -@item @option{--toc-file} @tab @code{TOC_FILE} -@item @option{--frames} @tab @code{FRAMES} -@item @option{--menu} @tab @code{SHOW_MENU} -@item @option{--debug} @tab @code{DEBUG} -@item @option{--doctype} @tab @code{DOCTYPE} -@item @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE} -@item @option{--test} @tab @code{TEST} -@end multitable - -@cindex @file{texi2oldapi.texi}, for @command{texi2any} -Finally, any @command{texi2html} users seeking more detailed -information can check the draft file @file{doc/texi2oldapi.texi} in -the Texinfo source repository. It consists mainly of very rough -notes, but may still be useful to some. - - -@node Creating and Installing Info Files -@chapter Creating and Installing Info Files - -This chapter describes how to create and install Info files. -@xref{Info Files}, for general information about the file format -itself. - -@menu -* Creating an Info File:: -* Installing an Info File:: -@end menu - - -@node Creating an Info File -@section Creating an Info File -@cindex Creating an Info file -@cindex Info, creating an online file -@cindex Formatting a file for Info - -@code{makeinfo} is a program that converts a Texinfo file into an Info -file, HTML file, or plain text. @code{texinfo-format-region} and -@code{texinfo-format-buffer} are XEmacs functions that convert -Texinfo to Info. - -For information on installing the Info file in the Info system, -@pxref{Installing an Info File}. - -@menu -* @t{makeinfo} Advantages:: @code{makeinfo} provides better error checking. -* @t{makeinfo} in XEmacs:: How to run @code{makeinfo} from XEmacs. -* @t{texinfo-format} commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in XEmacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. -@end menu - - -@node @t{makeinfo} Advantages -@subsection @code{makeinfo} Advantages - -@anchor{makeinfo advantages}@c old name - -The @code{makeinfo} utility creates an Info file from a Texinfo source -providing better error messages than either of the XEmacs formatting -commands. We recommend it. The @code{makeinfo} program is -independent of XEmacs. You can run @code{makeinfo} in any of three -ways: from an operating system shell, from a shell inside XEmacs, or by -typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in -Texinfo mode in XEmacs. - -The @code{texinfo-format-region} and the @code{texinfo-format-buffer} -commands may be useful if you cannot run @code{makeinfo}. - - -@node @t{makeinfo} in XEmacs -@subsection Running @code{makeinfo} Within XEmacs - -@c anchor{makeinfo in XEmacs}@c prev name -@cindex Running @code{makeinfo} in XEmacs -@cindex @code{makeinfo} inside XEmacs -@cindex Shell, running @code{makeinfo} in - -You can run @code{makeinfo} in XEmacs Texinfo mode by using either the -@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In -Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c -C-m C-b} by default. - -@table @kbd -@item C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info. -@findex makeinfo-region - -@item C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info. -@findex makeinfo-buffer -@end table - -When you invoke @code{makeinfo-region} the output goes to a temporary -buffer. When you invoke @code{makeinfo-buffer} output goes to the -file set with @code{@@setfilename} (@pxref{@t{@@setfilename}}). - -The XEmacs @code{makeinfo-region} and @code{makeinfo-buffer} commands -run the @code{makeinfo} program in a temporary shell buffer. If -@code{makeinfo} finds any errors, XEmacs displays the error messages in -the temporary buffer. - -@cindex Errors, parsing -@cindex Parsing errors -@findex next-error -You can parse the error messages by typing @kbd{C-x `} -(@code{next-error}). This causes XEmacs to go to and position the -cursor on the line in the Texinfo source that @code{makeinfo} thinks -caused the error. @xref{Compilation, , Running @code{make} or -Compilers Generally, xemacs, XEmacs User's Manual}, for more -information about using the @code{next-error} command. - -In addition, you can kill the shell in which the @code{makeinfo} -command is running or make the shell buffer display its most recent -output. - -@table @kbd -@item C-c C-m C-k -@itemx M-x makeinfo-kill-job -@findex makeinfo-kill-job -Kill the current running @code{makeinfo} job -(from @code{makeinfo-region} or @code{makeinfo-buffer}). - -@item C-c C-m C-l -@itemx M-x makeinfo-recenter-output-buffer -@findex makeinfo-recenter-output-buffer -Redisplay the @code{makeinfo} shell buffer to display its most recent -output. -@end table - -@noindent -(Note that the parallel commands for killing and recentering a @TeX{} -job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode -Printing}.) - -You can specify options for @code{makeinfo} by setting the -@code{makeinfo-options} variable with either the @kbd{M-x -customize} or the @kbd{M-x set-variable} command, or by setting the -variable in your @file{init.el} initialization file. - -For example, you could write the following in your @file{init.el} file: - -@example -@group -(setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") -@end group -@end example - -@noindent -@c Writing these three cross references using xref results in -@c three references to the same named manual, which looks strange. -@iftex -For more information, see @ref{@t{makeinfo} Options}, as well as -``Easy Customization Interface,'' ``Examining and Setting Variables,'' -and ``Init File'' in @cite{XEmacs User's Manual}. -@end iftex -@ifnottex -For more information, see@* -@ref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs User's Manual},@* -@ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@* -@ref{Init File, , , xemacs, XEmacs User's Manual}, and@* -@ref{@t{makeinfo} Options}. -@end ifnottex - - -@node @t{texinfo-format} commands -@subsection The @code{texinfo-format@dots{}} Commands - -@c anchor{texinfo-format commands}@c prev name - -In XEmacs in Texinfo mode, you can format part or all of a Texinfo -file with the @code{texinfo-format-region} command. This formats the -current region and displays the formatted text in a temporary buffer -called @samp{*Info Region*}. - -Similarly, you can format a buffer with the -@code{texinfo-format-buffer} command. This command creates a new -buffer and generates the Info file in it. Typing @kbd{C-x C-s} will -save the Info file under the name specified by the -@code{@@setfilename} line which must be near the beginning of the -Texinfo file. - -@table @kbd -@item C-c C-e C-r -@itemx @code{texinfo-format-region} -@findex texinfo-format-region -Format the current region for Info. - -@item C-c C-e C-b -@itemx @code{texinfo-format-buffer} -@findex texinfo-format-buffer -Format the current buffer for Info. -@end table - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands provide you with some error checking, and other functions can -provide you with further help in finding formatting errors. These -procedures are described in an appendix; see @ref{Catching Mistakes}. -However, the @code{makeinfo} program provides better error checking -(@pxref{@t{makeinfo} in XEmacs}). - - -@node Batch Formatting -@subsection Batch Formatting -@cindex Batch formatting for Info -@cindex Info batch formatting - -You can format Texinfo files for Info using @code{batch-texinfo-format} -and XEmacs Batch mode. You can run XEmacs in Batch mode from any shell, -including a shell inside of XEmacs. (@xref{Command Arguments,,, -xemacs, XEmacs User's Manual}.) - -Here is a shell command to format all the files that end in -@file{.texinfo} in the current directory: - -@example -xemacs -batch -funcall batch-texinfo-format *.texinfo -@end example - -@noindent -XEmacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them. - -Run @code{batch-texinfo-format} only with XEmacs in Batch mode as shown; -it is not interactive. It kills the Batch mode XEmacs on completion. - -@code{batch-texinfo-format} is convenient if you lack @code{makeinfo} -and want to format several Texinfo files at once. When you use Batch -mode, you create a new XEmacs process. This frees your current XEmacs, so -you can continue working in it. (When you run -@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot -use that XEmacs for anything else until the command finishes.) - -@node Tag and Split Files -@subsection Tag Files and Split Files -@cindex Making a tag table automatically -@cindex Tag table, making automatically - -If a Texinfo file has more than 30,000 bytes, -@code{texinfo-format-buffer} automatically creates a tag table -for its Info file; @code{makeinfo} always creates a tag table. With -a @dfn{tag table}, Info can jump to new nodes more quickly than it can -otherwise. - -@cindex Indirect subfiles -In addition, if the Texinfo file contains more than about 300,000 -bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the -large Info file into shorter @dfn{indirect} subfiles of about 300,000 -bytes each. Big files are split into smaller files so that XEmacs does -not need to make a large buffer to hold the whole of a large Info -file; instead, XEmacs allocates just enough memory for the small, split-off -file that is needed at the time. This way, XEmacs avoids wasting -memory when you run Info. (Before splitting was implemented, Info -files were always kept short and @dfn{include files} were designed as -a way to create a single, large printed manual out of the smaller Info -files. @xref{Include Files}, for more information. Include files are -still used for very large documents, such as @cite{The XEmacs Lisp -Reference Manual}, in which each chapter is a separate file.) - -When a file is split, Info itself makes use of a shortened version of -the original file that contains just the tag table and references to -the files that were split off. The split-off files are called -@dfn{indirect} files. - -The split-off files have names that are created by appending @w{@samp{-1}}, -@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the -@code{@@setfilename} command. The shortened version of the original file -continues to have the name specified by @code{@@setfilename}. - -At one stage in writing this document, for example, the Info file was saved -as the file @file{test-texinfo} and that file looked like this: - -@example -@group -Info file: test-texinfo, -*-Text-*- -produced by texinfo-format-buffer -from file: new-texinfo-manual.texinfo - -^_ -Indirect: -test-texinfo-1: 102 -test-texinfo-2: 50422 -@end group -@group -test-texinfo-3: 101300 -^_^L -Tag table: -(Indirect) -Node: overview^?104 -Node: info file^?1271 -@end group -@group -Node: printed manual^?4853 -Node: conventions^?6855 -@dots{} -@end group -@end example - -@noindent -(But @file{test-texinfo} had far more nodes than are shown here.) Each of -the split-off, indirect files, @file{test-texinfo-1}, -@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file -after the line that says @samp{Indirect:}. The tag table is listed after -the line that says @samp{Tag table:}. - -In the list of indirect files, the number following the file name -records the cumulative number of bytes in the preceding indirect -files, not counting the file list itself, the tag table, or any -permissions text in the first file. In the tag table, the number -following the node name records the location of the beginning of the -node, in bytes from the beginning of the (unsplit) output. - -If you are using @code{texinfo-format-buffer} to create Info files, -you may want to run the @code{Info-validate} command. (The -@code{makeinfo} command does such a good job on its own, you do not -need @code{Info-validate}.) However, you cannot run the @kbd{M-x -Info-validate} node-checking command on indirect files. For -information on how to prevent files from being split and how to -validate the structure of the nodes, see @ref{Using -@t{Info-validate}}. - - -@node Installing an Info File -@section Installing an Info File -@cindex Installing an Info file -@cindex Info file installation -@cindex @file{dir} directory for Info installation - -Info files are usually kept in the @file{info} directory. You can -read Info files using the standalone Info program or the Info reader -built into XEmacs. (@xref{Top,,, info, Info}, for an introduction to -Info.) - -@menu -* Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new Info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking @t{install-info}:: @code{install-info} options. -@end menu - - -@node Directory File -@subsection The Directory File @file{dir} - -For Info to work, the @file{info} directory must contain a file that -serves as a top level directory for the Info system. By convention, -this file is called @file{dir}. (You can find the location of this file -within XEmacs by typing @kbd{C-h i} to enter Info and then typing -@kbd{C-x C-f} to see the pathname to the @file{info} directory.) - -The @file{dir} file is itself an Info file. It contains the top level -menu for all the Info files in the system. The menu looks like -this: - -@example -@group -* Menu: -* Info: (info). Documentation browsing system. -* XEmacs: (xemacs). The extensible, self-documenting - text editor. -* Texinfo: (texinfo). With one source file, make - either a printed manual using - @@TeX@{@} or an Info file. -@dots{} -@end group -@end example - -Each of these menu entries points to the `Top' node of the Info file -that is named in parentheses. (The menu entry does not need to -specify the `Top' node, since Info goes to the `Top' node if no node -name is mentioned. @xref{Other Info Files, , Nodes in Other Info -Files}.) - -Thus, the @samp{Info} entry points to the `Top' node of the -@file{info} file and the @samp{XEmacs} entry points to the `Top' node -of the @file{xemacs} file. - -In each of the Info files, the `Up' pointer of the `Top' node refers -back to the @code{dir} file. For example, the line for the `Top' -node of the Emacs manual looks like this in Info: - -@example -File: xemacs Node: Top, Up: (DIR), Next: Distrib -@end example - -@noindent -In this case, the @file{dir} file name is written in uppercase -letters---it can be written in either upper- or lowercase. This is not -true in general, it is a special case for @file{dir}. - - -@node New Info File -@subsection Listing a New Info File -@cindex Adding a new Info file -@cindex Listing a new Info file -@cindex New Info file, listing it in @file{dir} file -@cindex Info file, listing a new -@cindex @file{dir} file listing - -To add a new Info file to your system, you must write a menu entry to -add to the menu in the @file{dir} file in the @file{info} directory. -For example, if you were adding documentation for GDB, you would write -the following new entry: - -@example -* GDB: (gdb). The source-level C debugger. -@end example - -@noindent -The first part of the menu entry is the menu entry name, followed by a -colon. The second part is the name of the Info file, in parentheses, -followed by a period. The third part is the description. - -The name of an Info file often has a @file{.info} extension. Thus, the -Info file for GDB might be called either @file{gdb} or @file{gdb.info}. -The Info reader programs automatically try the file name both with and -without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will -try the @file{.inf} extension as well.}; so it is better to avoid -clutter and not to write @samp{.info} explicitly in the menu entry. For -example, the GDB menu entry should use just @samp{gdb} for the file -name, not @samp{gdb.info}. - - -@node Other Info Directories -@subsection Info Files in Other Directories -@cindex Installing Info in another directory -@cindex Info installed in another directory -@cindex Another Info directory -@cindex @file{dir} files and Info directories - -If an Info file is not in the @file{info} directory, there are three -ways to specify its location: - -@enumerate -@item -Write the pathname in the @file{dir} file as the second part of the menu. - -@item -Specify the Info directory name in the @code{INFOPATH} environment -variable in your @file{.profile} or @file{.cshrc} initialization file. -(Only you and others who set this environment variable will be able to -find Info files whose location is specified this way.) - -@item -If you are using XEmacs, list the name of the file in a second @file{dir} -file, in its directory; and then add the name of that directory to the -@code{Info-directory-list} variable in your personal or site -initialization file. - -This variable tells XEmacs where to look for @file{dir} files (the files -must be named @file{dir}). XEmacs merges the files named @file{dir} from -each of the listed directories. (In XEmacs version 18, you can set the -@code{Info-directory} variable to the name of only one -directory.) -@end enumerate - -For example, to reach a test file in the @file{/home/bob/info} -directory, you could add an entry like this to the menu in the -standard @file{dir} file: - -@example -* Test: (/home/bob/info/info-test). Bob's own test file. -@end example - -@noindent -In this case, the absolute file name of the @file{info-test} file is -written as the second part of the menu entry. - -@vindex INFOPATH -@cindex Environment variable @code{INFOPATH} -If you don't want to edit the system @file{dir} file, you can tell -Info where to look by setting the @code{INFOPATH} environment variable -in your shell startup file. This works with both the XEmacs and -standalone Info readers. - -Specifically, if you use a Bourne-compatible shell such as @code{sh} -or @code{bash} for your shell command interpreter, you set the -@code{INFOPATH} environment variable in the @file{.profile} -initialization file; but if you use @code{csh} or @code{tcsh}, you set -the variable in the @file{.cshrc} initialization file. On -MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in your -@file{autoexec.bat} file or in the registry. Each type of shell uses -a different syntax. - -@itemize @bullet -@item -In a @file{.cshrc} file, you could set the @code{INFOPATH} -variable as follows: - -@smallexample -setenv INFOPATH .:~/info:/usr/local/xemacs/info -@end smallexample - -@item -In a @file{.profile} file, you would achieve the same effect by writing: - -@smallexample -INFOPATH=.:$HOME/info:/usr/local/xemacs/info -export INFOPATH -@end smallexample - -@item -@pindex autoexec.bat -In a @file{autoexec.bat} file, you write this command (note the -use of @samp{;} as the directory separator, and a different syntax for -using values of other environment variables): - -@smallexample -set INFOPATH=.;%HOME%/info;c:/usr/local/Xemacs/info -@end smallexample -@end itemize - -@noindent -The @samp{.} indicates the current directory as usual. XEmacs uses the -@code{INFOPATH} environment variable to initialize the value of XEmacs's -own @code{Info-directory-list} variable. The standalone Info reader -merges any files named @file{dir} in any directory listed in the -@env{INFOPATH} variable into a single menu presented to you in the node -called @samp{(dir)Top}. - -@cindex Colon, last in @env{INFOPATH} -However you set @env{INFOPATH}, if its last character is a colon (on -MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced -by the default (compiled-in) path. This gives you a way to augment -the default path with new directories without having to list all the -standard places. For example (using @code{sh} syntax): - -@example -INFOPATH=/home/bob/info: -export INFOPATH -@end example - -@noindent -will search @file{/home/bob/info} first, then the standard directories. -Leading or doubled colons are not treated specially. - -@cindex @file{dir} file, creating your own -When you create your own @file{dir} file for use with -@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by -copying an existing @file{dir} file and replace all the text after the -@samp{* Menu:} with your desired entries. That way, the punctuation -and special @kbd{CTRL-_} characters that Info needs will be present. - -As one final alternative, which works only with XEmacs Info, you can -change the @code{Info-directory-list} variable. For example: - -@example -(add-hook 'Info-mode-hook '(lambda () - (add-to-list 'Info-directory-list - (expand-file-name "~/info")))) -@end example - - -@node Installing Dir Entries -@subsection Installing Info Directory Files - -When you install an Info file onto your system, you can use the program -@code{install-info} to update the Info directory file @file{dir}. -Normally the makefile for the package runs @code{install-info}, just -after copying the Info file into its proper installed location. - -@findex dircategory -@findex direntry -In order for the Info file to work with @code{install-info}, you include -the commands @code{@@dircategory} and -@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source -file. Use @code{@@direntry} to specify the menu entries to add to the -Info directory file, and use @code{@@dircategory} to specify which part -of the Info directory to put it in. Here is how these commands are used -in this manual: - -@smallexample -@@dircategory Texinfo documentation system -@@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -@@end direntry -@end smallexample - -Here's what this produces in the Info file: - -@smallexample -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -END-INFO-DIR-ENTRY -@end smallexample - -@noindent -The @code{install-info} program sees these lines in the Info file, and -that is how it knows what to do. - -Always use the @code{@@direntry} and @code{@@dircategory} commands near -the beginning of the Texinfo input, before the first @code{@@node} -command. If you use them later on in the input, @code{install-info} -will not notice them. - -@code{install-info} will automatically reformat the description of the -menu entries it is adding. As a matter of convention, the description -of the main entry (above, @samp{The GNU documentation format}) should -start at column 32, starting at zero (as in -@code{what-cursor-position} in XEmacs). This will make it align with -most others. Description for individual utilities best start in -column 48, where possible. For more information about formatting see -the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in -@ref{Invoking @t{install-info}}. - -If you use @code{@@dircategory} more than once in the Texinfo source, -each usage specifies the `current' category; any subsequent -@code{@@direntry} commands will add to that category. - -@cindex Free Software Directory -@cindex Dir categories, choosing -@cindex Categories, choosing -When choosing a category name for the @code{@@dircategory} command, we -recommend consulting the @uref{http://www.gnu.org/directory, -Free Software Directory}. If your program is not listed there, -or listed incorrectly or incompletely, please report the situation to -the directory maintainers (@email{bug-directory@@gnu.org}) so that the -category names can be kept in sync. - -Here are a few examples (see the @file{util/dir-example} file in the -Texinfo distribution for large sample @code{dir} file): - -@display -XEmacs -Localization -Printing -Software development -Software libraries -Text creation and manipulation -@end display - -@cindex Invoking nodes, including in dir file -Each `Invoking' node for every program installed should have a -corresponding @code{@@direntry}. This lets users easily find the -documentation for the different programs they can run, as with the -traditional @command{man} system. - - -@node Invoking @t{install-info} -@subsection Invoking @command{install-info} - -@pindex install-info - -@code{install-info} inserts menu entries from an Info file into the -top-level @file{dir} file in the Info system (see the previous sections -for an explanation of how the @file{dir} file works). @code{install-info} -also removes menu entries from the @file{dir} file. It's most often -run as part of software installation, or when constructing a @file{dir} file -for all manuals on a system. Synopsis: - -@example -install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] -@end example - -If @var{info-file} or @var{dir-file} are not specified, the options -(described below) that define them must be. There are no compile-time -defaults, and standard input is never used. @code{install-info} can -read only one Info file and write only one @file{dir} file per invocation. - -@cindex @file{dir}, created by @code{install-info} -If @var{dir-file} (however specified) does not exist, -@code{install-info} creates it if possible (with no entries). - -@cindex Compressed dir files, reading -@cindex XZ-compressed dir files, reading -@cindex Bzipped dir files, reading -@cindex Lzip-compressed dir files, reading -@cindex LZMA-compressed dir files, reading -@cindex Dir files, compressed -If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip, -Gzip}), @code{install-info} automatically uncompresses it for reading. -And if @var{dir-file} is compressed, @code{install-info} also -automatically leaves it compressed after writing any changes. If -@var{dir-file} itself does not exist, @code{install-info} tries to -open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz}, -@file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and -@file{@var{dir-file}.lzma}, in that order. - -Options: - -@table @code -@item --add-once -@opindex --add-once@r{, for @command{install-info}} -Specifies that the entry or entries will only be put into a single section. - -@item --align=@var{column} -@opindex --align=@var{column}@r{, for @command{install-info}} -Specifies the column that the second and subsequent lines of menu entry's -description will be formatted to begin at. The default for this option is -@samp{35}. It is used in conjunction with the @samp{--max-width} option. -@var{column} starts counting at 1. - -@item --append-new-sections -@opindex --append-new-sections@r{, for @command{install-info}} -Instead of alphabetizing new sections, place them at the end of the DIR file. - -@item --calign=@var{column} -@opindex --calign=@var{column}@r{, for @command{install-info}} -Specifies the column that the first line of menu entry's description will -be formatted to begin at. The default for this option is @samp{33}. It is -used in conjunction with the @samp{--max-width} option. -When the name of the menu entry exceeds this column, entry's description -will start on the following line. -@var{column} starts counting at 1. - -@item --debug -@opindex --debug@r{, for @command{install-info}} -Report what is being done. - -@item --delete -@opindex --delete@r{, for @command{install-info}} -Delete the entries in @var{info-file} from @var{dir-file}. The file -name in the entry in @var{dir-file} must be @var{info-file} (except for -an optional @samp{.info} in either one). Don't insert any new entries. -Any empty sections that result from the removal are also removed. - -@item --description=@var{text} -@opindex --description=@var{text}@r{, for @command{install-info}} -Specify the explanatory portion of the menu entry. If you don't specify -a description (either via @samp{--entry}, @samp{--item} or this option), -the description is taken from the Info file itself. - -@item --dir-file=@var{name} -@opindex --dir-file=@var{name}@r{, for @command{install-info}} -Specify file name of the Info directory file. This is equivalent to -using the @var{dir-file} argument. - -@item --dry-run -@opindex --dry-run@r{, for @command{install-info}} -Same as @samp{--test}. - -@item --entry=@var{text} -@opindex --entry=@var{text}@r{, for @command{install-info}} -Insert @var{text} as an Info directory entry; @var{text} should have the -form of an Info menu item line plus zero or more extra lines starting -with whitespace. If you specify more than one entry, they are all -added. If you don't specify any entries, they are determined from -information in the Info file itself. - -@item --help -@opindex --help@r{, for @command{texindex}} -Display a usage message with basic usage and all available options, -then exit successfully. - -@item --info-file=@var{file} -@opindex --info-file=@var{file}@r{, for @command{install-info}} -Specify Info file to install in the directory. This is -equivalent to using the @var{info-file} argument. - -@item --info-dir=@var{dir} -@opindex --info-dir=@var{dir}@r{, for @command{install-info}} -Specify the directory where the directory file @file{dir} resides. -Equivalent to @samp{--dir-file=@var{dir}/dir}. - -@item --infodir=@var{dir} -@opindex --infodir=@var{dir}@r{, for @command{install-info}} -Same as @samp{--info-dir}. - -@item --item=@var{text} -@opindex --item=@var{text}@r{, for @command{install-info}} -Same as @samp{--entry=@var{text}}. An Info directory entry is actually -a menu item. - -@item --keep-old -@opindex --keep-old@r{, for @command{install-info}} -Do not replace pre-existing menu entries. When @samp{--remove} is specified, -this option means that empty sections are not removed. - -@item --max-width=@var{column} -@opindex --max-width=@var{column}@r{, for @command{install-info}} -Specifies the column that the menu entry's description will be word-wrapped -at. @var{column} starts counting at 1. - -@item --maxwidth=@var{column} -@opindex --maxwidth=@var{column}@r{, for @command{install-info}} -Same as @samp{--max-width}. - -@item --menuentry=@var{text} -@opindex --menuentry=@var{text}@r{, for @command{install-info}} -Same as @samp{--name}. - -@item --name=@var{text} -@opindex --name=@var{text}@r{, for @command{install-info}} -Specify the name portion of the menu entry. If the @var{text} does -not start with an asterisk @samp{*}, it is presumed to be the text -after the @samp{*} and before the parentheses that specify the Info -file. Otherwise @var{text} is taken verbatim, and is taken as -defining the text up to and including the first period (a space is -appended if necessary). If you don't specify the name (either via -@samp{--entry}, @samp{--item} or this option), it is taken from the -Info file itself. If the Info does not contain the name, the basename -of the Info file is used. - -@item --no-indent -@opindex --no-indent@r{, for @command{install-info}} -Suppress formatting of new entries into the @file{dir} file. - -@item --quiet -@itemx --silent -@opindex --quiet@r{, for @command{install-info}} -@opindex --silent@r{, for @command{install-info}} -Suppress warnings, etc., for silent operation. - -@item --remove -@opindex --remove@r{, for @command{install-info}} -Same as @samp{--delete}. - -@item --remove-exactly -@opindex --remove-exactly@r{, for @command{install-info}} -Also like @samp{--delete}, but only entries if the Info file name -matches exactly; @code{.info} and/or @code{.gz} suffixes are -@emph{not} ignored. - -@item --section=@var{sec} -@opindex --section=@var{sec}@r{, for @command{install-info}} -Put this file's entries in section @var{sec} of the directory. If you -specify more than one section, all the entries are added in each of the -sections. If you don't specify any sections, they are determined from -information in the Info file itself. If the Info file doesn't specify -a section, the menu entries are put into the Miscellaneous section. - -@item --section @var{regex} @var{sec} -@opindex --section @var{regex} @var{sec}@r{, for @command{install-info}} -Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}. - -@code{install-info} tries to detect when this alternate syntax is used, -but does not always guess correctly. Here is the heuristic that -@code{install-info} uses: -@enumerate -@item -If the second argument to @code{--section} starts with a hyphen, the -original syntax is presumed. - -@item -If the second argument to @code{--section} is a file that can be -opened, the original syntax is presumed. - -@item -Otherwise the alternate syntax is used. -@end enumerate - -When the heuristic fails because your section title starts with a -hyphen, or it happens to be a filename that can be opened, the syntax -should be changed to @samp{--regex=@var{regex} --section=@var{sec} ---add-once}. - -@item --regex=@var{regex} -@opindex --regex=@var{regex}@r{, for @command{install-info}} -Put this file's entries into any section that matches @var{regex}. If -more than one section matches, all of the entries are added in each of the -sections. Specify @var{regex} using basic regular expression syntax, more -or less as used with @command{grep}, for example. - -@item --test -@opindex --test@r{, for @command{install-info}} -Suppress updating of the directory file. - -@item --version -@opindex --version@r{, for @command{install-info}} -@cindex Version number, for install-info -Display version information and exit successfully. - -@end table - - -@node Generating HTML -@chapter Generating HTML - -@cindex Generating HTML -@cindex Outputting HTML - -@command{makeinfo} generates Info output by default, but given the -@option{--html} option, it will generate HTML, for web browsers and -other programs. This chapter gives some details on such HTML output. - -@command{makeinfo} has many user-definable customization variables -with which you can influence the HTML output. @xref{Customization -Variables}. - -@command{makeinfo} can also produce output in XML and Docbook formats, -but we do not as yet describe these in detail. @xref{Output Formats}, -for a brief overview of all the output formats. - -@menu -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: Influencing HTML output with Cascading Style Sheets. -* HTML Xref:: Cross references in HTML output. -@end menu - - -@node HTML Translation -@section HTML Translation - -@command{makeinfo} will include segments of Texinfo source between -@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not -any of the other conditionals, by default). Source between -@code{@@html} and @code{@@end html} is passed without change to the -output (i.e., suppressing the normal escaping of input @samp{<}, -@samp{>} and @samp{&} characters which have special significance in -HTML). @xref{Conditional Commands}. - -@cindex Navigation bar, in HTML output -By default, a navigation bar is inserted at the start of each node, -analogous to Info output. If the @samp{--no-headers} option is used, -the navigation bar is only inserted at the beginning of split files. -Header @code{<link>} elements in split output can support Info-like -navigation with browsers like Lynx and @w{XEmacs W3} which implement -this HTML@tie{}1.0 feature. - -@cindex Footnote styles, in HTML -In HTML, when the footnote style is @samp{end}, or if the output is -not split, footnotes are put at the end of the output. If set to -@samp{separate}, and the output is split, they are placed in a -separate file. @xref{Footnote Styles}. - -@cindex HTML output, browser compatibility of -The HTML generated is standard HTML@tie{}4. It also tries to be as -compatible as possible with earlier standards (e.g., HTML@tie{}2.0, -RFC-1866). Some minor exceptions: 1)@tie{}HTML@tie{}3.2 tables are -generated for the @code{@@multitable} command (@pxref{Multi-column -Tables}), but they should degrade reasonably in browsers without table -support; 2)@tie{}The HTML@tie{}4 @samp{lang} attribute on the -@samp{<html>} attribute is used; 3)@tie{} Entities that are not in the -HTML@tie{}3.2 standard are also used. 4)@tie{} CSS is used -(@pxref{HTML CSS}). 5)@tie{} A few HTML@tie{}4 elements are used -(@code{thead}, @code{abbr}, @code{acronym}). - -Using @samp{--init-file=html32.pm} produces strict HTML@tie{}3.2 -output (@pxref{Invoking @t{texi2any}}). - -Please report output from an error-free run of @code{makeinfo} which -has browser portability problems as a bug (@pxref{Reporting Bugs}). - - -@node HTML Splitting -@section HTML Splitting -@cindex Split HTML output -@cindex HTML output, split - -When splitting output at nodes (which is the default), -@command{makeinfo} writes HTML output into (basically) one output file -per Texinfo source @code{@@node}. - -Each output file name is the node name with spaces replaced by -@samp{-}'s and special characters changed to @samp{_} followed by -their code point in hex (@pxref{HTML Xref}). This is to make it -portable and easy to use as a filename. In the unusual case of two -different nodes having the same name after this treatment, they are -written consecutively to the same file, with HTML anchors so each can -be referred to independently. - -If @command{makeinfo} is run on a system which does not distinguish -case in file names, nodes which are the same except for case (e.g., -@samp{index} and @samp{Index}) will also be folded into the same -output file with anchors. You can also pretend to be on a case -insensitive filesystem by setting the customization variable -@code{CASE_INSENSITIVE_FILENAMES}. - -It is also possible to split at chapters or sections with -@option{--split} (@pxref{Invoking @t{texi2any}}). In that case, -the file names are constructed after the name of the node associated -with the relevant sectioning command. Also, unless -@option{--no-node-files} is specified, a redirection file is output -for every node in order to more reliably support cross references to -that manual (@pxref{HTML Xref}). - -When splitting, the HTML output files are written into a subdirectory, -with the name chosen as follows: - -@enumerate -@item -@command{makeinfo} first tries the subdirectory with the base name -from @code{@@setfilename} (that is, any extension is removed). For -example, HTML output for @code{@@setfilename gcc.info} would be -written into a subdirectory named @samp{gcc/}. - -@item -If that directory cannot be created for any reason, then -@command{makeinfo} tries appending @samp{.html} to the directory name. -For example, output for @code{@@setfilename texinfo} would be written -to @samp{texinfo.html/}. - -@item -If the @samp{@var{name}.html} directory can't be created either, -@code{makeinfo} gives up. - -@end enumerate - -@noindent In any case, the top-level output file within the directory -is always named @samp{index.html}. - -Monolithic output (@code{--no-split}) is named according to -@code{@@setfilename} (with any @samp{.info} extension is replaced with -@samp{.html}), @code{--output} (the argument is used literally), or -based on the input file name as a last resort -(@pxref{@t{@@setfilename}}). - - -@node HTML CSS -@section HTML CSS -@cindex HTML, and CSS -@cindex CSS, and HTML output -@cindex Cascading Style Sheets, and HTML output - -Cascading Style Sheets (CSS for short) is an Internet standard for -influencing the display of HTML documents: see -@uref{http://www.w3.org/Style/CSS/}. - -By default, @command{makeinfo} includes a few simple CSS commands to -better implement the appearance of some Texinfo environments. Here -are two of them, as an example: - -@example -pre.display @{ font-family:inherit @} -pre.smalldisplay @{ font-family:inherit; font-size:smaller @} -@end example - -A full explanation of CSS is (far) beyond this manual; please see the -reference above. In brief, however, the above tells the web browser -to use a `smaller' font size for @code{@@smalldisplay} text, and to -use the same font as the main document for both @code{@@smalldisplay} -and @code{@@display}. By default, the HTML @samp{<pre>} command uses -a monospaced font. - -You can influence the CSS in the HTML output with two -@command{makeinfo} options: @option{--css-include=@var{file}} and -@option{--css-ref=@var{url}}. - -@pindex texinfo-bright-colors.css -@cindex Visualizing Texinfo CSS -The option @option{--css-ref=@var{url}} adds to each output HTML file -a @samp{<link>} tag referencing a CSS at the given @var{url}. This -allows using external style sheets. You may find the file -@file{texi2html/examples/texinfo-bright-colors.css} useful for -visualizing the CSS elements in Texinfo output. - -The option @option{--css-include=@var{file}} includes the contents -@var{file} in the HTML output, as you might expect. However, the -details are somewhat tricky, as described in the following, to provide -maximum flexibility. - -@cindex @@import specifications, in CSS files -The CSS file may begin with so-called @samp{@@import} directives, -which link to external CSS specifications for browsers to use when -interpreting the document. Again, a full description is beyond our -scope here, but we'll describe how they work syntactically, so we can -explain how @command{makeinfo} handles them. - -@cindex Comments, in CSS files -There can be more than one @samp{@@import}, but they have to come -first in the file, with only whitespace and comments interspersed, no -normal definitions. (Technical exception: an @samp{@@charset} -directive may precede the @samp{@@import}'s. This does not alter -@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if -present.) Comments in CSS files are delimited by @samp{/* ... */}, as -in C@. An @samp{@@import} directive must be in one of these two forms: - -@example -@@import url(http://example.org/foo.css); -@@import "http://example.net/bar.css"; -@end example - -As far as @command{makeinfo} is concerned, the crucial characters are -the @samp{@@} at the beginning and the semicolon terminating the -directive. When reading the CSS file, it simply copies any such -@samp{@@}-directive into the output, as follows: - -@itemize -@item If @var{file} contains only normal CSS declarations, it is -included after @command{makeinfo}'s default CSS, thus overriding it. - -@item If @var{file} begins with @samp{@@import} specifications (see -below), then the @samp{import}'s are included first (they have to come -first, according to the standard), and then @command{makeinfo}'s -default CSS is included. If you need to override @command{makeinfo}'s -defaults from an @samp{@@import}, you can do so with the @samp{!@: -important} CSS construct, as in: -@example -pre.smallexample @{ font-size: inherit ! important @} -@end example - -@item If @var{file} contains both @samp{@@import} and inline CSS -specifications, the @samp{@@import}'s are included first, then -@command{makeinfo}'s defaults, and lastly the inline CSS from -@var{file}. - -@item Any @@-directive other than @samp{@@import} and @samp{@@charset} -is treated as a CSS declaration, meaning @command{makeinfo} includes -its default CSS and then the rest of the file. -@end itemize - -If the CSS file is malformed or erroneous, @command{makeinfo}'s output -is unspecified. @command{makeinfo} does not try to interpret the -meaning of the CSS file in any way; it just looks for the special -@samp{@@} and @samp{;} characters and blindly copies the text into the -output. Comments in the CSS file may or may not be included in the -output. - -In addition to the possibilities offered by CSS, @command{makeinfo} -has many user-definable customization variables with which you can -influence the HTML output. @xref{Customization Variables}. - - -@node HTML Xref -@section HTML Cross References -@cindex HTML cross references -@cindex Cross references, in HTML output - -Cross references between Texinfo manuals in HTML format become, in the -end, a standard HTML @code{<a>} link, but the details are -unfortunately complex. This section describes the algorithm used in -detail, so that Texinfo can cooperate with other programs, such as -@command{texi2html}, by writing mutually compatible HTML files. - -This algorithm may or may not be used for links @emph{within} HTML -output for a Texinfo file. Since no issues of compatibility arise in -such cases, we do not need to specify this. - -We try to support references to such ``external'' manuals in both -monolithic and split forms. A @dfn{monolithic} (mono) manual is -entirely contained in one file, and a @dfn{split} manual has a file -for each node. (@xref{HTML Splitting}.) - -@cindex Dumas, Patrice -The algorithm was primarily devised by Patrice Dumas in 2003--04. - -@menu -* Link Basics: HTML Xref Link Basics. -* Node Expansion: HTML Xref Node Name Expansion. -* Command Expansion: HTML Xref Command Expansion. -* 8-bit Expansion: HTML Xref 8-bit Character Expansion. -* Mismatch: HTML Xref Mismatch. -* Configuration: HTML Xref Configuration. htmlxref.cnf. -* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. -@end menu - - -@node HTML Xref Link Basics -@subsection HTML Cross Reference Link Basics -@cindex HTML cross reference link basics - -For our purposes, an HTML link consists of four components: a host -name, a directory part, a file part, and a target part. We -always assume the @code{http} protocol. For example: - -@example -http://@var{host}/@var{dir}/@var{file}.html#@var{target} -@end example - -The information to construct a link comes from the node name and -manual name in the cross reference command in the Texinfo source -(@pxref{Cross References}), and from @dfn{external information} -(@pxref{HTML Xref Configuration}). - -We now consider each part in turn. - -The @var{host} is hardwired to be the local host. This could either -be the literal string @samp{localhost}, or, according to the rules for -HTML links, the @samp{http://localhost/} could be omitted entirely. - -The @var{dir} and @var{file} parts are more complicated, and depend on -the relative split/mono nature of both the manual being processed and -the manual that the cross reference refers to. The underlying idea is -that there is one directory for Texinfo manuals in HTML, and a given -@var{manual} is either available as a monolithic file -@file{@var{manual}.html}, or a split subdirectory -@file{@var{manual}/*.html}. Here are the cases: - -@itemize @bullet -@item -If the present manual is split, and the referent manual is also split, -the directory is @samp{../@var{referent/}} and the file is the -expanded node name (described later). - -@item -If the present manual is split, and the referent manual is mono, the -directory is @samp{../} and the file is @file{@var{referent}.html}. - -@item -If the present manual is mono, and the referent manual is split, the -directory is @file{@var{referent}/} and the file is the expanded node -name. - -@item -If the present manual is mono, and the referent manual is also mono, -the directory is @file{./} (or just the empty string), and the file is -@file{@var{referent}.html}. - -@end itemize - -@vindex BASEFILENAME_LENGTH -Another rule, that only holds for filenames, is that base filenames -are truncated to 245 characters, to allow for an extension to be -appended and still comply with the 255-character limit which is common -to many filesystems. Although technically this can be changed with -the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other -Customization Variables}), doing so would make cross-manual references -to such nodes invalid. - -Any directory part in the filename argument of the source cross -reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} and -@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. This -is because any such attempted hardwiring of the directory is very -unlikely to be useful for both Info and HTML output. - -Finally, the @var{target} part is always the expanded node name. - -Whether the present manual is split or mono is determined by user -option; @command{makeinfo} defaults to split, with the -@option{--no-split} option overriding this. - -Whether the referent manual is split or mono, however, is another bit -of the external information (@pxref{HTML Xref Configuration}). By -default, @command{makeinfo} uses the same form of the referent manual -as the present manual. - -Thus, there can be a mismatch between the format of the referent -manual that the generating software assumes, and the format it's -actually present in. @xref{HTML Xref Mismatch}. - - -@node HTML Xref Node Name Expansion -@subsection HTML Cross Reference Node Name Expansion -@cindex HTML cross reference node name expansion -@cindex node name expansion, in HTML cross references -@cindex expansion, of node names in HTML cross references - -As mentioned in the previous section, the key part of the HTML cross -reference algorithm is the conversion of node names in the Texinfo -source into strings suitable for XHTML identifiers and filenames. The -restrictions are similar for each: plain ASCII letters, numbers, and -the @samp{-} and @samp{_} characters are all that can be used. -(Although HTML anchors can contain most characters, XHTML is more -restrictive.) - -Cross references in Texinfo can refer either to nodes or anchors -(@pxref{@t{@@anchor}}). However, anchors are treated identically -to nodes in this context, so we'll continue to say ``node'' names for -simplicity. - -A special exception: the Top node (@pxref{The Top Node}) is always -mapped to the file @file{index.html}, to match web server software. -However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): - -@example -@@xref@{Top,,, xemacs, XEmacs User's Manual@}. -@result{} <a href="xemacs/index.html#Top"> -@end example - -@enumerate -@item -The standard ASCII letters (a-z and A-Z) are not modified. All other -characters may be changed as specified below. - -@item -The standard ASCII numbers (0-9) are not modified except when a number -is the first character of the node name. In that case, see below. - -@item -Multiple consecutive space, tab and newline characters are transformed -into just one space. (It's not possible to have newlines in node -names with the current implementation, but we specify it anyway, just -in case.) - -@item -Leading and trailing spaces are removed. - -@item -After the above has been applied, each remaining space character is -converted into a @samp{-} character. - -@item -Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}}, -where @var{xx} is the ASCII character code in (lowercase) hexadecimal. -This includes @samp{_}, which is mapped to @samp{_005f}. - -@item -If the node name does not begin with a letter, the literal string -@samp{g_t} is prefixed to the result. (Due to the rules above, that -string can never occur otherwise; it is an arbitrary choice, standing -for ``GNU Texinfo''.) This is necessary because XHTML requires that -identifiers begin with a letter. - -@end enumerate - -For example: - -@example -@@node A node --- with _'% -@result{} A-node-_002d_002d_002d-with-_005f_0027_0025 -@end example - -Notice in particular: - -@itemize @bullet -@item @samp{_} @result{} @samp{_005f} -@item @samp{-} @result{} @samp{_002d} -@item @samp{A node} @result{} @samp{A-node} -@end itemize - -On case-folding computer systems, nodes differing only by case will be -mapped to the same file. In particular, as mentioned above, Top -always maps to the file @file{index.html}. Thus, on a case-folding -system, Top and a node named `Index' will both be written to -@file{index.html}. Fortunately, the targets serve to distinguish -these cases, since HTML target names are always case-sensitive, -independent of operating system. - - -@node HTML Xref Command Expansion -@subsection HTML Cross Reference Command Expansion -@cindex HTML cross reference command expansion - -Node names may contain @@-commands (@pxref{Node Line Requirements}). -This section describes how they are handled. - -First, comments are removed. - -Next, any @code{@@value} commands (@pxref{@t{@@set @@value}}) and -macro invocations (@pxref{Invoking Macros}) are fully expanded. - -Then, for the following commands, the command name and braces are removed, -and the text of the argument is recursively transformed: - -@example -@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless -@@emph @@env @@file @@i @@indicateurl @@kbd @@key -@@samp @@sansserif @@sc @@slanted @@strong @@t @@var @@verb @@w -@end example - -@noindent For @code{@@sc}, any letters are capitalized. - -In addition, the following commands are replaced by constant text, as -shown below. If any of these commands have non-empty arguments, as in -@code{@@TeX@{bad@}}, it is an error, and the result is unspecified. -In this table, `(space)' means a space character and `(nothing)' means -the empty string. The notation `U+@var{hhhh}' means Unicode code -point @var{hhhh} (in hex, as usual). There are further -transformations of many of these expansions for the final file or -target name, such as space characters to @samp{-}, etc., according to -the other rules. - -@multitable @columnfractions .3 .5 -@item @code{@@(newline)} @tab (space) -@item @code{@@(space)} @tab (space) -@item @code{@@(tab)} @tab (space) -@item @code{@@!} @tab @samp{!} -@item @code{@@*} @tab (space) -@item @code{@@-} @tab (nothing) -@item @code{@@.} @tab @samp{.} -@item @code{@@:} @tab (nothing) -@item @code{@@?} @tab @samp{?} -@item @code{@@@@} @tab @samp{@@} -@item @code{@@@{} @tab @samp{@{} -@item @code{@@@}} @tab @samp{@}} -@item @code{@@LaTeX} @tab @samp{LaTeX} -@item @code{@@TeX} @tab @samp{TeX} -@item @code{@@arrow} @tab U+2192 -@item @code{@@bullet} @tab U+2022 -@item @code{@@comma} @tab @samp{,} -@item @code{@@copyright} @tab U+00A9 -@item @code{@@dots} @tab U+2026 -@item @code{@@enddots} @tab @samp{...} -@item @code{@@equiv} @tab U+2261 -@item @code{@@error} @tab @samp{error-->} -@item @code{@@euro} @tab U+20AC -@item @code{@@exclamdown} @tab U+00A1 -@item @code{@@expansion} @tab U+21A6 -@item @code{@@geq} @tab U+2265 -@item @code{@@leq} @tab U+2264 -@item @code{@@minus} @tab U+2212 -@item @code{@@ordf} @tab U+00AA -@item @code{@@ordm} @tab U+00BA -@item @code{@@point} @tab U+2605 -@item @code{@@pounds} @tab U+00A3 -@item @code{@@print} @tab U+22A3 -@item @code{@@questiondown} @tab U+00BF -@item @code{@@registeredsymbol} @tab U+00AE -@item @code{@@result} @tab U+21D2 -@item @code{@@textdegree} @tab U+00B0 -@item @code{@@tie} @tab (space) -@end multitable - -Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like), -are likewise replaced by their Unicode values. Normal quotation -@emph{characters} (e.g., ASCII ` and ') are not altered. -@xref{Inserting Quotation Marks}. - -Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and -@code{@@image} commands are replaced by their first argument. (For -these commands, all subsequent arguments are optional, and ignored -here.) @xref{@t{@@acronym}}, and @ref{@t{@@email}}, and @ref{Images}. - -Any other command is an error, and the result is unspecified. - - -@node HTML Xref 8-bit Character Expansion -@subsection HTML Cross Reference 8-bit Character Expansion -@cindex HTML cross reference 8-bit character expansion -@cindex 8-bit characters, in HTML cross references -@cindex Expansion of 8-bit characters in HTML cross references -@cindex Transliteration of 8-bit characters in HTML cross references - -Usually, characters other than plain 7-bit ASCII are transformed into -the corresponding Unicode code point(s) in Normalization Form@tie{}C, -which uses precomposed characters where available. (This is the -normalization form recommended by the W3C and other bodies.) This -holds when that code point is @code{0xffff} or less, as it almost -always is. - -These will then be further transformed by the rules above into the -string @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex. - -For example, combining this rule and the previous section: - -@example -@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} -@result{} A-TeX-B_0306-_2605_002e_002e_002e -@end example - -Notice: 1)@tie{}@code{@@enddots} expands to three periods which in -turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' -with a breve accent, which does not exist as a pre-accented Unicode -character, therefore expands to @samp{B_0306} (B with combining -breve). - -When the Unicode code point is above @code{0xffff}, the transformation -is @samp{__@var{xxxxxx}}, that is, two leading underscores followed by -six hex digits. Since Unicode has declared that their highest code -point is @code{0x10ffff}, this is sufficient. (We felt it was better -to define this extra escape than to always use six hex digits, since -the first two would nearly always be zeros.) - -This method works fine if the node name consists mostly of ASCII -characters and contains only few 8-bit ones. If the document is -written in a language whose script is not based on the Latin alphabet -(for example, Ukrainian), it will create file names consisting -entirely of @samp{_@var{xxxx}} notations, which is inconvenient and -all but unreadable. - -To handle such cases, @command{makeinfo} offers the -@option{--transliterate-file-names} command line option. This option -enables @dfn{transliteration} of node names into ASCII characters for -the purposes of file name creation and referencing. The -transliteration is based on phonetic principles, which makes the -generated file names more easily understanable. - -@cindex Normalization Form C, Unicode -For the definition of Unicode Normalization Form@tie{}C, see Unicode -report UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many -related documents and implementations are available elsewhere on the -web. - - -@node HTML Xref Mismatch -@subsection HTML Cross Reference Mismatch -@cindex HTML cross reference mismatch -@cindex Mismatched HTML cross reference source and target - -As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating -software may need to guess whether a given manual being cross -referenced is available in split or monolithic form---and, inevitably, -it might guess wrong. However, when the @emph{referent} manual is -generated, it is possible to handle at least some mismatches. - -In the case where we assume the referent is split, but it is actually -available in mono, the only recourse would be to generate a -@file{manual/} subdirectory full of HTML files which redirect back to -the monolithic @file{manual.html}. Since this is essentially the same -as a split manual in the first place, it's not very appealing. - -On the other hand, in the case where we assume the referent is mono, -but it is actually available in split, it is possible to use -JavaScript to redirect from the putatively monolithic -@file{manual.html} to the different @file{manual/node.html} files. -Here's an example: - -@example -function redirect() @{ - switch (location.hash) @{ - case "#Node1": - location.replace("manual/Node1.html#Node1"); break; - case "#Node2" : - location.replace("manual/Node2.html#Node2"); break; - @dots{} - default:; - @} -@} -@end example - -Then, in the @code{<body>} tag of @file{manual.html}: - -@example -<body onLoad="redirect();"> -@end example - -Once again, this is something the software which generated the -@emph{referent} manual has to do in advance, it's not something the -software generating the cross reference in the present manual can -control. - - -@node HTML Xref Configuration -@subsection HTML Cross Reference Configuration: @file{htmlxref.cnf} - -@pindex htmlxref.cnf -@cindex HTML cross reference configuration -@cindex Cross reference configuration, for HTML -@cindex Configuration, for HTML cross-manual references - -@command{makeinfo} reads a file named @file{htmlxref.cnf} to gather -information for cross references to other manuals in HTML output. It -is looked for in the following directories: - -@table @file -@item ./ -(the current directory) - -@item ./.texinfo/ -(under the current directory) - -@item ~/.texinfo/ -(where @code{~} is the current user's home directory) - -@item @var{sysconfdir}/texinfo/ -(where @var{sysconfdir} is the system configuration directory -specified at compile-time, e.g., @file{/usr/local/etc}) - -@item @var{datadir}/texinfo/ -(likewise specified at compile time, e.g., @file{/usr/local/share}) -@end table - -All files found are used, with earlier entries overriding later ones. -The Texinfo distribution includes a default file which handles many -GNU manuals; it is installed in the last of the above directories, -i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}. - -The file is line-oriented. Lines consisting only of whitespace are -ignored. Comments are indicated with a @samp{#} at the beginning of a -line, optionally preceded by whitespace. Since @samp{#} can occur in -urls (like almost any character), it does not otherwise start a -comment. - -Each non-blank non-comment line must be either a @dfn{variable -assignment} or @dfn{manual information}. - -A variable assignment line looks like this: - -@example -@var{varname} = @var{varvalue} -@end example - -Whitespace around the @samp{=} is optional and ignored. The -@var{varname} should consist of letters; case is significant. The -@var{varvalue} is an arbitrary string, continuing to the end of the -line. Variables are then referenced with @samp{$@{@var{varname}@}}; -variable references can occur in the @var{varvalue}. - -A manual information line looks like this: - -@example -@var{manual} @var{keyword} @var{urlprefix} -@end example - -@noindent -with @var{manual} the short identifier for a manual, @var{keyword} -being one of: @code{mono}, @code{node}, @code{section}, -@code{chapter}, and @var{urlprefix} described below. Variable -references can occur only in the @var{urlprefix}. For example (used -in the canonical @file{htmlxref.cnf}): - -@smallexample -G = http://www.gnu.org -GS = $@{G@}/software -hello mono $@{GS@}/hello/manual/hello.html -hello chapter $@{GS@}/hello/manual/html_chapter/ -hello section $@{GS@}/hello/manual/html_section/ -hello node $@{GS@}/hello/manual/html_node/ -@end smallexample - -@cindex monolithic manuals, for HTML cross references -If the keyword is @code{mono}, @var{urlprefix} gives the host, -directory, and file name for @var{manual} as one monolithic file. - -@cindex split manuals, for HTML cross references -If the keyword is @code{node}, @code{section}, or @code{chapter}, -@var{urlprefix} gives the host and directory for @var{manual} split -into nodes, sections, or chapters, respectively. - -When available, @command{makeinfo} will use the ``corresponding'' -value for cross references between manuals. That is, when generating -monolithic output (@option{--no-split}), the @code{mono} url will be -used, when generating output that is split by node, the @code{node} -url will be used, etc. However, if a manual is not available in that -form, anything that is available can be used. Here is the search -order for each style: - -@smallexample -node @result{} node, section, chapter, mono -section @result{} section, chapter, node, mono -chapter @result{} chapter, section, node, mono -mono @result{} mono, chapter, section, node -@end smallexample - -@opindex --node-files@r{, and HTML cross references} -These section- and chapter-level cross-manual references can succeed -only when the target manual was created using @option{--node-files}; -this is the default for split output. - -If you have additions or corrections to the @file{htmlxref.cnf} -distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as -usual. You can get the latest version from -@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}. - - -@node HTML Xref Link Preservation -@subsection HTML Cross Reference Link Preservation: @var{manual}@file{-noderename.cnf} - -@pindex noderename.cnf -@pindex @var{manual}-noderename.cnf -@cindex HTML cross reference link preservation -@cindex Preserving HTML links to old nodes -@cindex Old nodes, preserving links to -@cindex Renaming nodes, and preserving links -@cindex Links, preserving to renamed nodes -@cindex Node renaming, and preserving links - -Occasionally changes in a program require removing (or renaming) nodes -in the manual in order to have the best documentation. Given the -nature of the web, however, links may exist anywhere to such a removed -node (renaming appears the same as removal for this purpose), and it's -not ideal for those links to simply break. - -@vindex RENAMED_NODES_FILE -Therefore, Texinfo provides a way for manual authors to specify old -node names and the new nodes to which the old names should be -redirected, via the file @var{manual}@file{-noderename.cnf}, where -@var{manual} is the base name of the manual. For example, the manual -@file{texinfo.texi} would be supplemented by a file -@file{texinfo-noderename}.cnf. (This name can be overridden by -setting the @file{RENAMED_NODES_FILE} customization variable; -@pxref{Customization Variables}). - -The file is read in pairs of lines, as follows: - -@example -@var{old-node-name} -@@@@@{@} @var{new-node-name} -@end example - -The usual conversion from Texinfo node names to HTML names is applied; -see this entire section for details (@pxref{HTML Xref}). The unusual -@samp{@@@@@{@}} separator is used because it is not a valid Texinfo -construct, so can't appear in the node names. - -The effect is that @command{makeinfo} generates a redirect from -@var{old-node-name} to @var{new-node-name} when producing HTML output. -Thus, external links to the old node are preserved. - -Lines consisting only of whitespace are ignored. Comments are -indicated with an @samp{@@c} at the beginning of a line, optionally -preceded by whitespace. - -Another approach to preserving links to deleted or renamed nodes is to -use anchors (@pxref{@t{@@anchor}}). There is no effective -difference between the two approaches. - - -@node Command List -@appendix @@-Command List -@cindex Alphabetical @@-command list -@cindex List of @@-commands -@cindex @@-command list -@cindex Reference to @@-commands - -Here is an alphabetical list of the @@-commands in Texinfo. Square -brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, -@samp{@dots{}}, indicates repeated text. - -More specifics on the general syntax of different @@-commands are -given in the section below. - -@menu -* Command Syntax:: General syntax for varieties of @@-commands. -* Command Contexts:: Guidelines for which commands can be used where. -@end menu - -@sp 1 -@table @code -@item @@@var{whitespace} -An @code{@@} followed by a space, tab, or newline produces a normal, -stretchable, interword space. @xref{Multiple Spaces}. - -@item @@! -Produce an exclamation point that ends a sentence (usually after an -end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@" -@itemx @@' -Generate an umlaut or acute accent, respectively, over the next -character, as in @"o and @'o. @xref{Inserting Accents}. - -@item @@* -Force a line break. @xref{Line Breaks}. - -@item @@,@{@var{c}@} -Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting -Accents}. - -@item @@- -Insert a discretionary hyphenation point. @xref{@t{@@- @@hyphenation}}. - -@item @@. -Produce a period that ends a sentence (usually after an -end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@/ -Produces no output, but allows a line break. @xref{Line Breaks}. - -@item @@: -Tell @TeX{} to refrain from inserting extra whitespace after an -immediately preceding period, question mark, exclamation mark, or -colon, as @TeX{} normally would. @xref{Not Ending a Sentence}. - -@item @@= -Generate a macron (bar) accent over the next character, as in @=o. -@xref{Inserting Accents}. - -@item @@? -Produce a question mark that ends a sentence (usually after an -end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@@@ -@itemx @@atchar@{@} -Insert an at sign, @samp{@@}. @xref{Inserting an Atsign}. - -@item @@\ -@itemx @@backslashchar@{@} -Insert a backslash, @samp{\}; @code{@@backslashchar@{@}} works -anywhere, while @code{@@\} works only inside @code{@@math}. -@xref{Inserting a Backslash}, and @ref{Inserting Math}. - -@item @@^ -@itemx @@` -Generate a circumflex (hat) or grave accent, respectively, over the next -character, as in @^o and @`e. -@xref{Inserting Accents}. - -@item @@@{ -@itemx @@lbracechar@{@} -Insert a left brace, @samp{@{}. @xref{Inserting Braces}. - -@item @@@} -@itemx @@rbracechar@{@} -Insert a right brace, @samp{@}}. @xref{Inserting Braces}. - -@item @@~ -Generate a tilde accent over the next character, as in @~N. -@xref{Inserting Accents}. - -@item @@AA@{@} -@itemx @@aa@{@} -Generate the uppercase and lowercase Scandinavian A-ring letters, -respectively: @AA{}, @aa{}. @xref{Inserting Accents}. - -@item @@abbr@{@var{abbreviation}@} -Indicate a general abbreviation, such as `Comput.'. -@xref{@t{@@abbr}}. - -@item @@acronym@{@var{acronym}@} -Indicate an acronym in all capital letters, such as `NASA'. -@xref{@t{@@acronym}}. - -@item @@AE@{@} -@itemx @@ae@{@} -Generate the uppercase and lowercase AE ligatures, respectively: -@AE{}, @ae{}. @xref{Inserting Accents}. - -@item @@afivepaper -Change page dimensions for the A5 paper size. @xref{A4 Paper}. - -@item @@afourlatex -@itemx @@afourpaper -@itemx @@afourwide -Change page dimensions for the A4 paper size. @xref{A4 Paper}. - -@item @@alias @var{new}=@var{existing} -Make the command @samp{@@@var{new}} a synonym for the existing command -@samp{@@@var{existing}}. @xref{@t{@@alias}}. - -@item @@allowcodebreaks @var{true-false} -Control breaking at @samp{-} and @samp{_} in @TeX{}. -@xref{@t{@@allowcodebreaks}}. - -@item @@anchor@{@var{name}@} -Define @var{name} as the current location for use as a cross reference -target. @xref{@t{@@anchor}}. - -@item @@appendix @var{title} -Begin an appendix. The title appears in the table of contents. In -Info, the title is underlined with asterisks. -@xref{@t{@@unnumbered @@appendix}}. - -@item @@appendixsec @var{title} -@itemx @@appendixsection @var{title} -Begin an appendix section within an appendix. The section title -appears in the table of contents. In Info, the title is underlined -with equal signs. @code{@@appendixsection} is a longer spelling of -the @code{@@appendixsec} command. @xref{@t{@@unnumberedsec -@@appendixsec @@heading}}. - -@item @@appendixsubsec @var{title} -Begin an appendix subsection. The title appears in the table of -contents. In Info, the title is underlined with hyphens. -@xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. - -@item @@appendixsubsubsec @var{title} -Begin an appendix subsubsection. The title appears in the table of -contents. In Info, the title is underlined with periods. -@xref{@t{@@subsubsection}}. - -@item @@arrow@{@} -Generate a right arrow glyph: @samp{@arrow{}}. Used by default -for @code{@@click}. @xref{Click Sequences}. - -@item @@asis -Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to -print the table's first column without highlighting (``as is''). -@xref{@t{@@asis}}. - -@item @@author @var{author} -Typeset @var{author} flushleft and underline it. @xref{@t{@@title -@@subtitle @@author}}. - -@item @@b@{@var{text}@} -Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}. - -@item @@bullet@{@} -Generate a large round dot, @bullet{} (@samp{*} in Info). Often used -with @code{@@table}. @xref{@t{@@bullet}}. - -@item @@bye -Stop formatting a file. The formatters do not see anything in the -input file following @code{@@bye}. @xref{Ending a File}. - -@item @@c @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -any output. A synonym for @code{@@comment}. @kbd{DEL} also -starts a comment. @xref{Comments}. - -@item @@caption -Define the full caption for an @code{@@float}. @xref{@t{@@caption -@@shortcaption}}. - -@item @@cartouche -Highlight an example or quotation by drawing a box with rounded -corners around it. Pair with @code{@@end cartouche}. No effect in -Info. @xref{@t{@@cartouche}}. - -@item @@center @var{line-of-text} -Center the line of text following the command. -@xref{@t{@@titlefont @@center @@sp}}. - -@item @@centerchap @var{line-of-text} -Like @code{@@chapter}, but centers the chapter title. @xref{@t{@@chapter}}. - -@item @@chapheading @var{title} -Print an unnumbered chapter-like heading, but omit from the table of -contents. In Info, the title is underlined with asterisks. -@xref{@t{@@majorheading @@chapheading}}. - -@item @@chapter @var{title} -Begin a numbered chapter. The chapter title appears in the table of -contents. In Info, the title is underlined with asterisks. -@xref{@t{@@chapter}}. - -@item @@cindex @var{entry} -Add @var{entry} to the index of concepts. @xref{Index Entries, , -Defining the Entries of an Index}. - -@item @@cite@{@var{reference}@} -Highlight the name of a book or other reference that has no companion -Info file. @xref{@t{@@cite}}. - -@item @@clear @var{flag} -Unset @var{flag}, preventing the Texinfo formatting commands from -formatting text between subsequent pairs of @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, and preventing -@code{@@value@{@var{flag}@}} from expanding to the value to which -@var{flag} is set. @xref{@t{@@set @@clear @@value}}. - -@item @@click@{@} -Represent a single ``click'' in a GUI@. Used within -@code{@@clicksequence}. @xref{Click Sequences}. - -@item @@clicksequence@{@var{action} @@click@{@} @var{action}@} -Represent a sequence of clicks in a GUI@. @xref{Click Sequences}. - -@item @@clickstyle @@@var{cmd} -Execute @@@var{cmd} for each @code{@@click}; the default is -@code{@@arrow}. The usual following empty braces on @@@var{cmd} are -omitted. @xref{Click Sequences}. - -@item @@code@{@var{sample-code}@} -Indicate an expression, a syntactically complete token of a program, -or a program name. Unquoted in Info output. @xref{@t{@@code}}. - -@item @@codequotebacktick @var{on-off} -@itemx @@codequoteundirected @var{on-off} -Control output of @code{`} and @code{'} in code examples. -@xref{Inserting Quote Characters}. - -@item @@comma@{@} -Insert a comma `,' character; only needed when a literal comma would -be taken as an argument separator. @xref{Inserting a Comma}. - -@item @@command@{@var{command-name}@} -Indicate a command name, such as @command{ls}. @xref{@t{@@command}}. - -@item @@comment @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -any output. A synonym for @code{@@c}. -@xref{Comments}. - -@item @@contents -Print a complete table of contents. Has no effect in Info, which uses -menus instead. @xref{Contents, , Generating a Table of Contents}. - -@item @@copying -Specify copyright holders and copying conditions for the document Pair -with @code{@@end cartouche}. @xref{@t{@@copying}}. - -@item @@copyright@{@} -Generate the copyright symbol @copyright{}. -@xref{@t{@@copyright}}. - -@item @@defcodeindex @var{index-name} -Define a new index and its indexing command. Print entries in an -@code{@@code} font. @xref{New Indices, , Defining New Indices}. - -@item @@defcv @var{category} @var{class} @var{name} -@itemx @@defcvx @var{category} @var{class} @var{name} -Format a description for a variable associated with a class in -object-oriented programming. Takes three arguments: the category of -thing being defined, the class to which it belongs, and its name. -@xref{Definition Commands}. - -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} -Format a description for a function, interactive command, or similar -entity that may take arguments. @code{@@deffn} takes as arguments the -category of entity being described, the name of this particular -entity, and its arguments, if any. @xref{Definition Commands}. - -@item @@defindex @var{index-name} -Define a new index and its indexing command. Print entries in a roman -font. @xref{New Indices, , Defining New Indices}. - -@item @@definfoenclose @var{newcmd}, @var{before}, @var{after} -Must be used within @code{@@ifinfo}; create a new command -@code{@@@var{newcmd}} for Info that marks text by enclosing it in -strings that precede and follow the text. -@xref{@t{@@definfoenclose}}. - -@item @@defivar @var{class} @var{instance-variable-name} -@itemx @@defivarx @var{class} @var{instance-variable-name} -Format a description for an instance variable in object-oriented -programming. The command is equivalent to @samp{@@defcv @{Instance -Variable@} @dots{}}. @xref{Definition Commands}. - -@item @@defmac @var{macroname} @var{arguments}@dots{} -@itemx @@defmacx @var{macroname} @var{arguments}@dots{} -Format a description for a macro; equivalent to @samp{@@deffn Macro -@dots{}}. @xref{Definition Commands}. - -@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} -Format a description for a method in object-oriented programming; -equivalent to @samp{@@defop Method @dots{}}. @xref{Definition -Commands}. - -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} -Format a description for an operation in object-oriented programming. -@code{@@defop} takes as arguments the name of the category of -operation, the name of the operation's class, the name of the -operation, and its arguments, if any. @xref{Definition Commands}, and -@ref{Abstract Objects}. - -@item @@defopt @var{option-name} -@itemx @@defoptx @var{option-name} -Format a description for a user option; equivalent to @samp{@@defvr -@{User Option@} @dots{}}. @xref{Definition Commands}. - -@item @@defspec @var{special-form-name} @var{arguments}@dots{} -@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} -Format a description for a special form; equivalent to @samp{@@deffn -@{Special Form@} @dots{}}. @xref{Definition Commands}. - -@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} -Format a description for a data type; its arguments are the category, -the name of the type (e.g., @samp{int}) , and then the names of -attributes of objects of that type. @xref{Definition Commands}, and -@ref{Data Types}. - -@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} -@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name} -Format a description for a typed class variable in object-oriented programming. -@xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a function or similar entity that may take -arguments and that is typed. @code{@@deftypefn} takes as arguments the -category of entity being described, the type, the name of the -entity, and its arguments, if any. @xref{Definition Commands}. - -@item @@deftypefnnewline @var{on-off} -Specifies whether return types for @code{@@deftypefn} and similar are -printed on lines by themselves; default is off. @xref{Typed -Functions,, Functions in Typed Languages}. - -@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} -@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} -Format a description for a function in a typed language. -The command is equivalent to @samp{@@deftypefn Function @dots{}}. -@xref{Definition Commands}. - -@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} -@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} -Format a description for a typed instance variable in object-oriented -programming. @xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -Format a description for a typed method in object-oriented programming. -@xref{Definition Commands}. - -@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a typed operation in object-oriented programming. -@xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypevar @var{data-type} @var{variable-name} -@itemx @@deftypevarx @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}. - -@item @@deftypevr @var{category} @var{data-type} @var{name} -@itemx @@deftypevrx @var{category} @var{data-type} @var{name} -Format a description for something like a variable in a typed -language---an entity that records a value. Takes as arguments the -category of entity being described, the type, and the name of the -entity. @xref{Definition Commands}. - -@item @@defun @var{function-name} @var{arguments}@dots{} -@itemx @@defunx @var{function-name} @var{arguments}@dots{} -Format a description for a function; equivalent to -@samp{@@deffn Function @dots{}}. @xref{Definition Commands}. - -@item @@defvar @var{variable-name} -@itemx @@defvarx @var{variable-name} -Format a description for a variable; equivalent to @samp{@@defvr -Variable @dots{}}. @xref{Definition Commands}. - -@item @@defvr @var{category} @var{name} -@itemx @@defvrx @var{category} @var{name} -Format a description for any kind of variable. @code{@@defvr} takes -as arguments the category of the entity and the name of the entity. -@xref{Definition Commands}. - -@item @@detailmenu -Mark the (optional) detailed node listing in a master menu. -@xref{Master Menu Parts}. - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term. @xref{@t{@@dfn}}. - -@item @@DH@{@} -@itemx @@dh@{@} -Generate the uppercase and lowercase Icelandic letter eth, respectively: -@DH{}, @dh{}. @xref{Inserting Accents}. - -@item @@dircategory @var{dirpart} -Specify a part of the Info directory menu where this file's entry should -go. @xref{Installing Dir Entries}. - -@item @@direntry -Begin the Info directory menu entry for this file. Pair with -@code{@@end direntry}. @xref{Installing Dir Entries}. - -@item @@display -Begin a kind of example. Like @code{@@example} (indent text, do not -fill), but do not select a new font. Pair with @code{@@end display}. -@xref{@t{@@display}}. - -@item @@dmn@{@var{dimension}@} -Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a -thin space before @var{dimension}. No effect in Info. -@xref{@t{@@dmn}}. - -@item @@docbook -Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw -Formatter Commands}. - -@item @@documentdescription -Set the document description text, included in the HTML output. Pair -with @code{@@end documentdescription}. @xref{@t{@@documentdescription}}. - -@item @@documentencoding @var{enc} -Declare the input encoding to be @var{enc}. -@xref{@t{@@documentencoding}}. - -@item @@documentlanguage @var{CC} -Declare the document language as the two-character ISO-639 abbreviation -@var{CC}. @xref{@t{@@documentlanguage}}. - -@item @@dotaccent@{@var{c}@} -Generate a dot accent over the character @var{c}, as in @dotaccent{o}. -@xref{Inserting Accents}. - -@item @@dotless@{@var{i-or-j}@} -Generate dotless i (`@dotless{i}') and dotless j (`@dotless{j}'). -@xref{Inserting Accents}. - -@item @@dots@{@} -Generate an ellipsis, @samp{@dots{}}. -@xref{@t{@@dots}}. - -@item @@email@{@var{address}[, @var{displayed-text}]@} -Indicate an electronic mail address. @xref{@t{@@email}}. - -@item @@emph@{@var{text}@} -Emphasize @var{text}, by using @emph{italics} where possible, and -enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}. - -@item @@end @var{environment} -Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting -Commands,,@@-commands}. - -@item @@enddots@{@} -Generate an end-of-sentence ellipsis, like this: @enddots{} -@xref{@t{@@dots}}. - -@item @@enumerate [@var{number-or-letter}] -Begin a numbered list, using @code{@@item} for each entry. -Optionally, start list with @var{number-or-letter}. Pair with -@code{@@end enumerate}. @xref{@t{@@enumerate}}. - -@item @@env@{@var{environment-variable}@} -Indicate an environment variable name, such as @env{PATH}. -@xref{@t{@@env}}. - -@item @@equiv@{@} -Indicate to the reader the exact equivalence of two forms with a -glyph: @samp{@equiv{}}. @xref{@t{@@equiv}}. - -@item @@error@{@} -Indicate to the reader with a glyph that the following text is -an error message: @samp{@error{}}. @xref{@t{@@error}}. - -@item @@errormsg@{@var{msg}@} -Report @var{msg} as an error to standard error, and exit unsuccessfully. -Texinfo commands within @var{msg} are expanded to plain text. -@xref{Conditionals}, and @ref{External Macro Processors}. - -@item @@euro@{@} -Generate the Euro currency sign. @xref{@t{@@euro}}. - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for even-numbered (left-hand) -pages. @xref{Custom Headings, , -How to Make Your Own Headings}. - -@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for every page. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}. - -@item @@example -Begin an example. Indent text, do not fill, and select fixed-width -font. Pair with @code{@@end example}. @xref{@t{@@example}}. - -@item @@exampleindent @var{indent} -Indent example-like environments by @var{indent} number of spaces -(perhaps 0). @xref{@t{@@exampleindent}}. - -@item @@exclamdown@{@} -Generate an upside-down exclamation point. @xref{Inserting Accents}. - -@item @@exdent @var{line-of-text} -Remove any indentation a line might have. @xref{@t{@@exdent}}. - -@item @@expansion@{@} -Indicate the result of a macro expansion to the reader with a special -glyph: @samp{@expansion{}}. @xref{@t{@@expansion}}. - -@item @@file@{@var{filename}@} -Highlight the name of a file, buffer, node, directory, etc. -@xref{@t{@@file}}. - -@item @@finalout -Prevent @TeX{} from printing large black warning rectangles beside -over-wide lines. @xref{Overfull hboxes}. - -@item @@findex @var{entry} -Add @var{entry} to the index of functions. @xref{Index Entries, , -Defining the Entries of an Index}. - -@item @@firstparagraphindent @var{word} -Control indentation of the first paragraph after section headers -according to @var{word}, one of `none' or `insert'. -@xref{@t{@@firstparagraphindent}}. - -@item @@float -Environment to define floating material. Pair with @code{@@end float}. -@xref{Floats}. - -@item @@flushleft -@itemx @@flushright -Do not fill text; left (right) justify every line while leaving the -right (left) end ragged. Leave font as is. Pair with @code{@@end -flushleft} (@code{@@end flushright}). @xref{@t{@@flushleft -@@flushright}}. - -@item @@fonttextsize @var{10-11} -Change the size of the main body font in the @TeX{} output. -@xref{Fonts}. - -@item @@footnote@{@var{text-of-footnote}@} -Enter a footnote. Footnote text is printed at the bottom of the page -by @TeX{}; Info may format in either `End' node or `Separate' node style. -@xref{Footnotes}. - -@item @@footnotestyle @var{style} -Specify an Info file's footnote style, either @samp{end} for the end -node style or @samp{separate} for the separate node style. -@xref{Footnotes}. - -@item @@format -Begin a kind of example. Like @code{@@display}, but do not indent. -Pair with @code{@@end format}. @xref{@t{@@example}}. - -@item @@frenchspacing @var{on-off} -Control spacing after punctuation. @xref{@t{@@frenchspacing}}. - -@item @@ftable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of functions. Pair with @code{@@end ftable}. The same as -@code{@@table}, except for indexing. @xref{@t{@@ftable @@vtable}}. - -@item @@geq@{@} -Generate a greater-than-or-equal sign, `@geq{}'. @xref{@t{@@geq @@leq}}. - -@item @@group -Disallow page breaks within following text. Pair with @code{@@end -group}. Ignored in Info. @xref{@t{@@group}}. - -@item @@guillemetleft@{@} -@itemx @@guillemetright@{@} -@item @@guillemotleft@{@} -@itemx @@guillemotright@{@} -@itemx @@guilsinglleft@{@} -@itemx @@guilsinglright@{@} -Double and single angle quotation marks: @guillemetleft{} -@guillemetright{} @guilsinglleft{} @guilsinglright{}. -@code{@@guillemotleft} and @code{@@guillemotright} are synonyms for -@code{@@guillemetleft} and @code{@@guillemetright}. @xref{Inserting -Quotation Marks}. - -@item @@H@{@var{c}@} -Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. - -@item @@hashchar@{@} -Insert a hash `#' character; only needed when a literal hash would -introduce @code{#line} directive. @xref{Inserting a Hashsign}, and -@ref{External Macro Processors}. - -@item @@heading @var{title} -Print an unnumbered section-like heading, but omit from the table of -contents. In Info, the title is underlined with equal signs. -@xref{@t{@@unnumberedsec @@appendixsec @@heading}}. - -@item @@headings @var{on-off-single-double} -Turn page headings on or off, and/or specify single-sided or double-sided -page headings for printing. @xref{@t{@@headings}}. - -@item @@headitem -Begin a heading row in a multitable. @xref{Multitable Rows}. - -@item @@headitemfont@{@var{text}@} -Set @var{text} in the font used for multitable heading rows; mostly -useful in multitable templates. @xref{Multitable Rows}. - -@item @@html -Enter HTML completely. Pair with @code{@@end html}. @xref{Raw -Formatter Commands}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Explicitly define hyphenation points. @xref{@t{@@- @@hyphenation}}. - -@item @@i@{@var{text}@} -Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}. - -@item @@ifclear @var{txivar} -If the Texinfo variable @var{txivar} is not set, format the following -text. Pair with @code{@@end ifclear}. @xref{@t{@@set @@clear -@@value}}. - -@item @@ifcommanddefined @var{txicmd} -@itemx @@ifcommandnotdefined @var{txicmd} -If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the -follow text. Pair with the corresponding @code{@@end ifcommand...}. -@xref{Testing for Texinfo Commands}. - -@item @@ifdocbook -@itemx @@ifhtml -@itemx @@ifinfo -Begin text that will appear only in the given output format. -@code{@@ifinfo} output appears in both Info and (for historical -compatibility) plain text output. Pair with @code{@@end ifdocbook} -resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. -@xref{Conditionals}. - -@item @@ifnotdocbook -@itemx @@ifnothtml -@itemx @@ifnotplaintext -@itemx @@ifnottex -@itemx @@ifnotxml -Begin text to be ignored in one output format but not the others. -@code{@@ifnothtml} text is omitted from HTML output, etc. Pair with -the corresponding @code{@@end ifnot@var{format}}. -@xref{Conditionals}. - -@item @@ifnotinfo -Begin text to appear in output other than Info and (for historical -compatibility) plain text. Pair with @code{@@end ifnotinfo}. -@xref{Conditionals}. - -@item @@ifplaintext -Begin text that will appear only in the plain text output. -Pair with @code{@@end ifplaintext}. @xref{Conditionals}. - -@item @@ifset @var{txivar} -If the Texinfo variable @var{txivar} is set, format the following -text. Pair with @code{@@end ifset}. @xref{@t{@@set @@clear -@@value}}. - -@item @@iftex -Begin text to appear only in the @TeX{} output. Pair with @code{@@end -iftex}. @xref{Conditionals, , Conditionally Visible Text}. - -@item @@ifxml -Begin text that will appear only in the XML output. Pair with -@code{@@end ifxml}. @xref{Conditionals}. - -@item @@ignore -Begin text that will not appear in any output. Pair with @code{@@end -ignore}. @xref{Comments, , Comments and Ignored Text}. - -@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} -Include graphics image in external @var{filename} scaled to the given -@var{width} and/or @var{height}, using @var{alt} text and looking for -@samp{@var{filename}.@var{ext}} in HTML@. @xref{Images}. - -@item @@include @var{filename} -Read the contents of Texinfo source file @var{filename}. @xref{Include Files}. - -@item @@indent -Insert paragraph indentation. @xref{@t{@@indent}}. - -@item @@indentedblock -Indent a block of arbitary text on the left. Pair with @code{@@end -indentedblock}. @xref{@t{@@indentedblock}}. - -@item @@indicateurl@{@var{indicateurl}@} -Indicate text that is a uniform resource locator for the World Wide -Web. @xref{@t{@@indicateurl}}. - -@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} -Make a cross reference to an Info file for which there is no printed -manual. @xref{@t{@@inforef}}. - -@item @@inlinefmt@{@var{fmt}, @var{text}@} -Insert @var{text} only if the output format is @var{fmt}. -@xref{Inline Conditionals}. - -@item @@inlinefmtifelse@{@var{fmt}, @var{text}, @var{else-text}@} -Insert @var{text} if the output format is @var{fmt}, else @var{else-text}. - -@item @@inlineifclear@{@var{var}, @var{text}@} -@itemx @@inlineifset@{@var{var}, @var{text}@} -Insert @var{text} only if the Texinfo variable @var{var} is (not) set. - -@item @@inlineraw@{@var{fmt}, @var{raw-text}@} -Insert @var{text} as in a raw conditional, only if the output format -is @var{fmt}. - -@item \input @var{macro-definitions-file} -Use the specified macro definitions file. This command is used only -in the first line of a Texinfo file to cause @TeX{} to make use of the -@file{texinfo} macro definitions file. The @code{\} in @code{\input} -is used instead of an @code{@@} because @TeX{} does not recognize -@code{@@} until after it has read the definitions file. @xref{Texinfo -File Header}. - -@item @@insertcopying -Insert the text previously defined with the @code{@@copying} -environment. @xref{@t{@@insertcopying}}. - -@item @@item -Indicate the beginning of a marked paragraph for @code{@@itemize} and -@code{@@enumerate}; indicate the beginning of the text of a first column -entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. -@xref{Lists and Tables}. - -@item @@itemize @var{mark-generating-character-or-command} -Begin an unordered list: indented paragraphs with a mark, such as -@code{@@bullet}, inside the left margin at the beginning of each item. -Pair with @code{@@end itemize}. @xref{@t{@@itemize}}. - -@item @@itemx -Like @code{@@item} but do not generate extra vertical space above the -item text. Thus, when several items have the same description, use -@code{@@item} for the first and @code{@@itemx} for the others. -@xref{@t{@@itemx}}. - -@item @@kbd@{@var{keyboard-characters}@} -Indicate characters of input to be typed by users. @xref{@t{@@kbd}}. - -@item @@kbdinputstyle @var{style} -Specify when @code{@@kbd} should use a font distinct from -@code{@@code} according to @var{style}: @code{code}, @code{distinct}, -@code{example}. @xref{@t{@@kbd}}. - -@item @@key@{@var{key-name}@} -Indicate the name of a key on a keyboard. @xref{@t{@@key}}. - -@item @@kindex @var{entry} -Add @var{entry} to the index of keys. -@xref{Index Entries, , Defining the Entries of an Index}. - -@item @@L@{@} -@itemx @@l@{@} -Generate the uppercase and lowercase Polish suppressed-L letters, -respectively: @L{}, @l{}. - -@item @@LaTeX@{@} -Generate the @LaTeX{} logo. @xref{@t{@@TeX @@LaTeX}}. - -@item @@leq@{@} -Generate a less-than-or-equal sign, `@leq{}'. @xref{@t{@@geq @@leq}}. - -@item @@lisp -Begin an example of Lisp code. Indent text, do not fill, and select -fixed-width font. Pair with @code{@@end lisp}. @xref{@t{@@lisp}}. - -@item @@listoffloats -Produce a table-of-contents-like listing of @code{@@float}s. -@xref{@t{@@listoffloats}}. - -@item @@lowersections -Change subsequent chapters to sections, sections to subsections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}. - -@item @@macro @var{macroname} @{@var{params}@} -Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. -Pair with @code{@@end macro}. @xref{Defining Macros}. - -@item @@majorheading @var{title} -Print an unnumbered chapter-like heading, but omit from the table of -contents. This generates more vertical whitespace before the heading -than the @code{@@chapheading} command. @xref{@t{@@majorheading -@@chapheading}}. - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. @xref{Inserting Math}. - -@item @@menu -Mark the beginning of a menu of nodes. No effect in a printed manual. -Pair with @code{@@end menu}. @xref{Menus}. - -@item @@minus@{@} -Generate a minus sign, `@minus{}'. @xref{@t{@@minus}}. - -@item @@multitable @var{column-width-spec} -Begin a multi-column table. Begin each row with @code{@@item} or -@code{@@headitem}, and separate columns with @code{@@tab}. Pair with -@code{@@end multitable}. @xref{Multitable Column Widths}. - -@item @@need @var{n} -Start a new page in a printed manual if fewer than @var{n} mils -(thousandths of an inch) remain on the current page. -@xref{@t{@@need}}. - -@item @@node @var{name}, @var{next}, @var{previous}, @var{up} -Begin a new node. @xref{@t{@@node}}. - -@item @@noindent -Prevent text from being indented as if it were a new paragraph. -@xref{@t{@@noindent}}. - -@item @@novalidate -Suppress validation of node references and omit creation of auxiliary -files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer -Validation}. - -@item @@O@{@} -@itemx @@o@{@} -Generate the uppercase and lowercase O-with-slash letters, respectively: -@O{}, @o{}. - -@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for odd-numbered (right-hand) -pages. @xref{Custom Headings, , -How to Make Your Own Headings}. - -@item @@OE@{@} -@itemx @@oe@{@} -Generate the uppercase and lowercase OE ligatures, respectively: -@OE{}, @oe{}. @xref{Inserting Accents}. - -@item @@ogonek@{@var{c}@} -Generate an ogonek diacritic under the next character, as in -@ogonek{a}. @xref{Inserting Accents}. - -@item @@option@{@var{option-name}@} -Indicate a command-line option, such as @option{-l} or -@option{--help}. @xref{@t{@@option}}. - -@item @@ordf@{@} -@itemx @@ordm@{@} -Generate the feminine and masculine Spanish ordinals, respectively: -@ordf{}, @ordm{}. @xref{Inserting Accents}. - -@item @@page -Start a new page in a printed manual. No effect in Info. -@xref{@t{@@page}}. - -@item @@pagesizes [@var{width}][, @var{height}] -Change page dimensions. @xref{pagesizes}. - -@item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve -source file indentation if @var{indent} is @code{asis}. -@xref{@t{@@paragraphindent}}. - -@item @@part @var{title} -Begin a group of chapters or appendixes; included in the tables of -contents and produces a page of its own in printed output. -@xref{@t{@@part}}. - -@item @@pindex @var{entry} -Add @var{entry} to the index of programs. @xref{Index Entries, , Defining -the Entries of an Index}. - -@item @@point@{@} -Indicate the position of point in a buffer to the reader with a glyph: -@samp{@point{}}. @xref{@t{@@point}}. - -@item @@pounds@{@} -Generate the pounds sterling currency sign. -@xref{@t{@@pounds}}. - -@item @@print@{@} -Indicate printed output to the reader with a glyph: @samp{@print{}}. -@xref{@t{@@print}}. - -@item @@printindex @var{index-name} -Generate the alphabetized index for @var{index-name} (using two -columns in a printed manual). @xref{Printing Indices & Menus}. - -@item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with a lowercase `see' in a printed -manual. Use within parentheses only. Only the first argument is -mandatory. @xref{@t{@@pxref}}. - -@item @@questiondown@{@} -Generate an upside-down question mark. @xref{Inserting Accents}. - -@item @@quotation -Narrow the margins to indicate text that is quoted from another work. -Takes optional argument specifying prefix text, e.g., an author name. -Pair with @code{@@end quotation}. @xref{@t{@@quotation}}. - -@item @@quotedblleft@{@} -@itemx @@quotedblright@{@} -@itemx @@quoteleft@{@} -@itemx @@quoteright@{@} -@itemx @@quotedblbase@{@} -@itemx @@quotesinglbase@{@} -Produce various quotation marks: @quotedblleft{} @quotedblright{} -@quoteleft{} @quoteright{} @quotedblbase{} @quotesinglbase{}. -@xref{Inserting Quotation Marks}. - -@item @@r@{@var{text}@} -Set @var{text} in the regular @r{roman} font. No effect in Info. -@xref{Fonts}. - -@item @@raggedright -Fill text; left justify every line while leaving the right end ragged. -Leave font as is. Pair with @code{@@end raggedright}. No effect in -Info. @xref{@t{@@raggedright}}. - -@item @@raisesections -Change subsequent sections to chapters, subsections to sections, and so -on. @xref{Raise/lower sections}. - -@item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} -Make a plain reference that does not start with any special text. -Follow command with a punctuation mark. Only the first argument is -mandatory. @xref{@t{@@ref}}. - -@item @@refill -@findex refill -This command used to refill and indent the paragraph after all the -other processing has been done. It is no longer needed, since all -formatters now automatically refill as needed, but you may still see -it in the source to some manuals, as it does no harm. - -@item @@registeredsymbol@{@} -Generate the legal symbol @registeredsymbol{}. -@xref{@t{@@registeredsymbol}}. - -@item @@result@{@} -Indicate the result of an expression to the reader with a special -glyph: @samp{@result{}}. @xref{@t{@@result}}. - -@item @@ringaccent@{@var{c}@} -Generate a ring accent over the next character, as in @ringaccent{o}. -@xref{Inserting Accents}. - -@item @@samp@{@var{text}@} -Indicate a literal example of a sequence of characters, in general. -Quoted in Info output. @xref{@t{@@samp}}. - -@item @@sansserif@{@var{text}@} -Set @var{text} in a @sansserif{sans serif} font if possible. No -effect in Info. @xref{Fonts}. - -@item @@sc@{@var{text}@} -Set @var{text} in a small caps font in printed output, and uppercase -in Info. @xref{Smallcaps}. - -@item @@section @var{title} -Begin a section within a chapter. The section title appears in the -table of contents. In Info, the title is underlined with equal signs. -Within @code{@@chapter} and @code{@@appendix}, the section title is -numbered; within @code{@@unnumbered}, the section is unnumbered. -@xref{@t{@@section}}. - -@item @@set @var{txivar} [@var{string}] -Define the Texinfo variable @var{txivar}, optionally to the value -@var{string}. @xref{@t{@@set @@clear @@value}}. - -@item @@setchapternewpage @var{on-off-odd} -Specify whether chapters start on new pages, and if so, whether on -odd-numbered (right-hand) new pages. @xref{@t{@@setchapternewpage}}. - -@item @@setcontentsaftertitlepage -Put the table of contents after the @samp{@@end titlepage} even if the -@code{@@contents} command is at the end. @xref{Contents}. - -@item @@setfilename @var{info-file-name} -Provide a name to be used for the output files. This command is essential -for @TeX{} formatting as well, even though it produces no output of -its own. @xref{@t{@@setfilename}}. - -@item @@setshortcontentsaftertitlepage -Place the short table of contents after the @samp{@@end titlepage} -command even if the @code{@@shortcontents} command is at the end. -@xref{Contents}. - -@item @@settitle @var{title} -Specify the title for page headers in a printed manual, and the -default document title for HTML @samp{<head>}. -@xref{@t{@@settitle}}. - -@item @@shortcaption -Define the short caption for an @code{@@float}. @xref{@t{@@caption -@@shortcaption}}. - -@item @@shortcontents -Print a short table of contents, with chapter-level entries only. Not -relevant to Info, which uses menus rather than tables of contents. -@xref{Contents, , Generating a Table of Contents}. - -@item @@shorttitlepage @var{title} -Generate a minimal title page. @xref{@t{@@titlepage}}. - -@item @@slanted@{@var{text}@} -Set @var{text} in a @slanted{slanted} font if possible. No effect -in Info. @xref{Fonts}. - -@item @@smallbook -Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format. -@xref{@t{@@smallbook}}. Also, see @ref{@t{@@small@dots{}}}. - -@item @@smalldisplay -Begin a kind of example. Like @code{@@display}, but use a smaller -font size where possible. Pair with @code{@@end smalldisplay}. -@xref{@t{@@small@dots{}}}. - -@item @@smallexample -Begin an example. Like @code{@@example}, but use a smaller font size -where possible. Pair with @code{@@end smallexample}. -@xref{@t{@@small@dots{}}}. - -@item @@smallformat -Begin a kind of example. Like @code{@@format}, but use a smaller font -size where possible. Pair with @code{@@end smallformat}. -@xref{@t{@@small@dots{}}}. - -@item @@smallindentedblock -Like @code{@@indentedblock}, but use a smaller font size where -possible. Pair with @code{@@end smallindentedblock}. -@xref{@t{@@small@dots{}}}. - -@item @@smalllisp -Begin an example of Lisp code. Same as @code{@@smallexample}. Pair -with @code{@@end smalllisp}. @xref{@t{@@small@dots{}}}. - -@item @@smallquotation -Like @code{@@quotation}, but use a smaller font size where possible. -Pair with @code{@@end smallquotation}. @xref{@t{@@small@dots{}}}. - -@item @@sp @var{n} -Skip @var{n} blank lines. @xref{@t{@@sp}}. - -@item @@ss@{@} -Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. - -@item @@strong @{@var{text}@} -Emphasize @var{text} more strongly than @code{@@emph}, by using -@strong{boldface} where possible; enclosed in asterisks in Info. -@xref{emph & strong, , Emphasizing Text}. - -@item @@subheading @var{title} -Print an unnumbered subsection-like heading, but omit from the table -of contents of a printed manual. In Info, the title is underlined -with hyphens. @xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. - -@item @@subsection @var{title} -Begin a subsection within a section. The subsection title appears in -the table of contents. In Info, the title is underlined with hyphens. -Same context-dependent numbering as @code{@@section}. -@xref{@t{@@subsection}}. - -@item @@subsubheading @var{title} -Print an unnumbered subsubsection-like heading, but omit from the -table of contents of a printed manual. In Info, the title is -underlined with periods. @xref{@t{@@subsubsection}}. - -@item @@subsubsection @var{title} -Begin a subsubsection within a subsection. The subsubsection title -appears in the table of contents. In Info, the title is underlined -with periods. Same context-dependent numbering as @code{@@section}. -@xref{@t{@@subsubsection}}. - -@item @@subtitle @var{title} -In a printed manual, set a subtitle in a normal sized font flush to -the right-hand side of the page. Not relevant to Info, which does not -have title pages. @xref{@t{@@title @@subtitle @@author}}. - -@item @@summarycontents -Print a short table of contents. Synonym for @code{@@shortcontents}. -@xref{Contents, , Generating a Table of Contents}. - -@item @@syncodeindex @var{from-index} @var{to-index} -Merge the index named in the first argument into the index named in -the second argument, formatting the entries from the first index with -@code{@@code}. @xref{Combining Indices}. - -@item @@synindex @var{from-index} @var{to-index} -Merge the index named in the first argument into the index named in -the second argument. Do not change the font of @var{from-index} -entries. @xref{Combining Indices}. - -@item @@t@{@var{text}@} -Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect -in Info. @xref{Fonts}. - -@item @@tab -Separate columns in a row of a multitable. @xref{Multitable Rows}. - -@item @@table @var{formatting-command} -Begin a two-column table (description list), using @code{@@item} for -each entry. Write each first column entry on the same line as -@code{@@item}. First column entries are printed in the font resulting -from @var{formatting-command}. Pair with @code{@@end table}. -@xref{Two-column Tables, , Making a Two-column Table}. Also see -@ref{@t{@@ftable @@vtable}}, and @ref{@t{@@itemx}}. - -@item @@TeX@{@} -Generate the @TeX{} logo. @xref{@t{@@TeX @@LaTeX}}. - -@item @@tex -Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw -Formatter Commands}. - -@item @@textdegree@{@} -Generate the degree symbol. @xref{@t{@@textdegree}}. - -@item @@thischapter -@itemx @@thischaptername -@itemx @@thischapternum -@itemx @@thisfile -@itemx @@thispage -@itemx @@thistitle -Only allowed in a heading or footing. Stands for, respectively, the -number and name of the current chapter (in the format `Chapter 1: -Title'), the current chapter name only, the current chapter number -only, the filename, the current page number, and the title of the -document, respectively. @xref{Custom Headings, , How to Make Your Own -Headings}. - -@item @@TH@{@} -@itemx @@th@{@} -Generate the uppercase and lowercase Icelandic letter thorn, respectively: -@TH{}, @th{}. @xref{Inserting Accents}. - -@item @@tie@{@} -Generate a normal interword space at which a line break is not -allowed. @xref{@t{@@tie}}. - -@item @@tieaccent@{@var{cc}@} -Generate a tie-after accent over the next two characters @var{cc}, as in -`@tieaccent{oo}'. @xref{Inserting Accents}. - -@item @@tindex @var{entry} -Add @var{entry} to the index of data types. @xref{Index Entries, , -Defining the Entries of an Index}. - -@item @@title @var{title} -In a printed manual, set a title flush to the left-hand side of the -page in a larger than normal font and underline it with a black rule. -Not relevant to Info, which does not have title pages. -@xref{@t{@@title @@subtitle @@author}}. - -@item @@titlefont@{@var{text}@} -In a printed manual, print @var{text} in a larger than normal font. -@xref{@t{@@titlefont @@center @@sp}}. - -@item @@titlepage -Begin the title page. Write the command on a line of its own, paired -with @code{@@end titlepage}. Nothing between @code{@@titlepage} and -@code{@@end titlepage} appears in Info. @xref{@t{@@titlepage}}. - -@item @@today@{@} -Insert the current date, in `1 Jan 1900' style. @xref{Custom -Headings, , How to Make Your Own Headings}. - -@item @@top @var{title} -Mark the topmost @code{@@node} in the file, which must be defined on -the line immediately preceding the @code{@@top} command. The title is -formatted as a chapter-level heading. The entire top node, including -the @code{@@node} and @code{@@top} lines, are normally enclosed with -@code{@@ifnottex ... @@end ifnottex}. In @TeX{} and -@code{texinfo-format-buffer}, the @code{@@top} command is merely a -synonym for @code{@@unnumbered}. @xref{@t{makeinfo} Pointer -Creation}. - -@item @@u@{@var{c}@} -@itemx @@ubaraccent@{@var{c}@} -@itemx @@udotaccent@{@var{c}@} -Generate a breve, underbar, or underdot accent, respectively, over or -under the character @var{c}, as in @u{o}, @ubaraccent{o}, -@udotaccent{o}. @xref{Inserting Accents}. - -@item @@unmacro @var{macroname} -Undefine the macro @code{@@@var{macroname}} if it has been defined. -@xref{Defining Macros}. - -@item @@unnumbered @var{title} -Begin a chapter that appears without chapter numbers of any kind. The -title appears in the table of contents. In Info, the title is -underlined with asterisks. @xref{@t{@@unnumbered @@appendix}}. - -@item @@unnumberedsec @var{title} -Begin a section that appears without section numbers of any kind. The -title appears in the table of contents of a printed manual. In Info, -the title is underlined with equal signs. @xref{@t{@@unnumberedsec -@@appendixsec @@heading}}. - -@item @@unnumberedsubsec @var{title} -Begin an unnumbered subsection. The title appears in the table of -contents. In Info, the title is underlined with hyphens. -@xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. - -@item @@unnumberedsubsubsec @var{title} -Begin an unnumbered subsubsection. The title appears in the table of -contents. In Info, the title is underlined with periods. -@xref{@t{@@subsubsection}}. - -@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} -@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} -Define a cross reference to an external uniform resource locator, -e.g., for the World Wide Web. @xref{@t{@@url}}. - -@item @@urefbreakstyle @var{style} -Specify how @code{@@uref}/@code{@@url} should break at special -characters: @code{after}, @code{before}, @code{none}. -@xref{@t{@@url}}. - -@item @@v@{@var{c}@} -Generate check accent over the character @var{c}, as in @v{o}. -@xref{Inserting Accents}. - -@item @@value@{@var{txivar}@} -Insert the value, if any, of the Texinfo variable @var{txivar}, -previously defined by @code{@@set}. @xref{@t{@@set @@clear -@@value}}. - -@item @@var@{@var{metasyntactic-variable}@} -Highlight a metasyntactic variable, which is something that stands for -another piece of text. @xref{@t{@@var}}. - -@item @@verb@{@var{delim} @var{literal} @var{delim}@} -Output @var{literal}, delimited by the single character @var{delim}, -exactly as is (in the fixed-width font), including any whitespace or -Texinfo special characters. @xref{@t{@@verb}}. - -@item @@verbatim -Output the text of the environment exactly as is (in the fixed-width -font). Pair with @code{@@end verbatim}. @xref{@t{@@verbatim}}. - -@item @@verbatiminclude @var{filename} -Output the contents of @var{filename} exactly as is (in the -fixed-width font). @xref{@t{@@verbatiminclude}}. - -@item @@vindex @var{entry} -Add @var{entry} to the index of variables. @xref{Index Entries, , -Defining the Entries of an Index}. - -@item @@vskip @var{amount} -In a printed manual, insert whitespace so as to push text on the -remainder of the page towards the bottom of the page. Used in -formatting the copyright page with the argument @samp{0pt plus -1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used -only in contexts ignored for Info. @xref{Copyright}. - -@item @@vtable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -Automatically enter each of the items in the first column into the -index of variables. Pair with @code{@@end vtable}. The same as -@code{@@table}, except for indexing. @xref{@t{@@ftable @@vtable}}. - -@item @@w@{@var{text}@} -Disallow line breaks within @var{text}. @xref{@t{@@w}}. - -@item @@xml -Enter XML completely. Pair with @code{@@end xml}. @xref{Raw -Formatter Commands}. - -@item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with `See' in a printed manual. Follow -command with a punctuation mark. Only the first argument is -mandatory. @xref{@t{@@xref}}. - -@item @@xrefautomaticsectiontitle @var{on-off} -By default, use the section title instead of the node name in cross -references. @xref{Three Arguments}. - -@end table - - -@node Command Syntax -@section @@-Command Syntax -@cindex @@-command syntax -@cindex Syntax, of @@-commands -@cindex Command syntax - -The character @samp{@@} is used to start all Texinfo commands. (It -has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo has -four types of @@-command: - -@table @asis -@item 1. Non-alphabetic commands. -These commands consist of an @@ followed by a punctuation mark or -other character that is not part of the Latin alphabet. Non-alphabetic -commands are almost always part of the text within a paragraph. The -non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}}, -@code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and -many more. - -@item 2. Alphabetic commands that do not require arguments. -These commands start with @@ followed by a word followed by a -left and right- brace. These commands insert special symbols in -the document; they do not take arguments. Some examples: -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', and -@code{@@bullet@{@}} @result{} @samp{@bullet{}}. - -@item 3. Alphabetic commands that require arguments within braces. -These commands start with @@ followed by a letter or a word, followed by an -argument within braces. For example, the command @code{@@dfn} indicates -the introductory or defining use of a term; it is used as follows: @samp{In -Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.} - -@item 4. Alphabetic commands that occupy an entire line. -These commands occupy an entire line. The line starts with @@, -followed by the name of the command (a word); for example, @code{@@center} -or @code{@@cindex}. If no argument is needed, the word is followed by -the end of the line. If there is an argument, it is separated from -the command name by a space. Braces are not used. -@end table - -Whitespace following an @@-command name are optional and (usually) -ignored if present. The exceptions are contexts whee whitespace is -significant, e.g., an @code{@@example} environment. - -@cindex Braces and argument syntax -Thus, the alphabetic commands fall into classes that have -different argument syntaxes. You cannot tell to which class a command -belongs by the appearance of its name, but you can tell by the -command's meaning: if the command stands for a glyph, it is in -class 2 and does not require an argument; if it makes sense to use the -command among other text as part of a paragraph, the command -is in class 3 and must be followed by an argument in braces; -otherwise, it is in class 4 and uses the rest of the line as its -argument. - -The purpose of having a different syntax for commands of classes 3 -and@tie{}4 is to make Texinfo files easier to read, and also to help -the XEmacs paragraph and filling commands work properly. There is -only one exception to this rule: the command @code{@@refill}, which is -always used at the end of a paragraph immediately following the final -period or other punctuation character. @code{@@refill} takes no -argument and does @emph{not} require braces. @code{@@refill} never -confuses the XEmacs paragraph commands because it cannot appear at the -beginning of a line. It is also no longer needed, since all -formatters now refill paragraphs automatically. - - -@node Command Contexts -@section @@-Command Contexts - -@cindex Contexts, of @@-commands - -Here we describe approximately which @@-commands can be used in which -contexts. It merely gives the general idea and is not exhaustive or -meant to be a complete reference. Discrepancies between the -information here and the @code{makeinfo} or @TeX{} implementations -are most likely to be resolved in favor of the implementation. - -By @dfn{general text} below, we mean anything except sectioning and -other such outer-level document commands, such as @code{@@section}, -@code{@@node}, and @code{@@setfilename}. - -@code{@@c}, @code{@@comment} and @code{@@if ... @@end if} conditional -commands may appear anywhere (except the conditionals must still be on -lines by themselves). @code{@@caption} may only appear in -@code{@@float} but may contain general text. @code{@@footnote} -content likewise. - -@@-commands with braces marking text (such as @code{@@strong}, -@code{@@sc}, @code{@@asis}) may contain raw formatter commands such as -@code{@@html} but no other block commands (other commands terminated -by @code{@@end}) and may not be split across paragraphs, but may -otherwise contain general text. - -In addition to the block command restriction, on @code{@@center}, -@code{@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands -that makes only sense in a paragraph are not accepted, such as -@code{@@indent}. - -In addition to the above, sectioning commands cannot contain -@code{@@anchor}, @code{@@footnote} or @code{@@verb}. - -In addition to the above, remaining commands (@code{@@node}, -@code{@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math}, -@code{@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot -contain cross reference commands (@code{@@ref}, @code{@@xref}, -@code{@@pxref} and @code{@@inforef}). In one last addition, -@code{@@shortcaption} may only appear inside @code{@@float}. - -For precise and complete information, we suggest looking into the -extensive test suite in the sources, which exhaustively try -combinations. - - -@node Tips -@appendix Tips and Hints - -Here are some tips for writing Texinfo documentation: - -@cindex Tips -@cindex Usage tips -@cindex Hints -@itemize @bullet -@item -Write in the present tense, not in the past or the future. - -@item -Write actively! For example, write ``We recommend that @dots{}'' rather -than ``It is recommended that @dots{}''. - -@item -Use 70 or 72 as your fill column. Longer lines are hard to read. - -@item -Include a copyright notice and copying permissions. -@end itemize - - -@subsubheading Index, Index, Index! - -Write many index entries, in different ways. -Readers like indices; they are helpful and convenient. - -Although it is easiest to write index entries as you write the body of -the text, some people prefer to write entries afterwards. In either -case, write an entry before the paragraph to which it applies. This -way, an index entry points to the first page of a paragraph that is -split across pages. - -Here are more index-related hints we have found valuable: - -@itemize @bullet -@item -Write each index entry differently, so each entry refers to a different -place in the document. - -@item -Write index entries only where a topic is discussed significantly. For -example, it is not useful to index ``debugging information'' in a -chapter on reporting bugs. Someone who wants to know about debugging -information will certainly not find it in that chapter. - -@item -Consistently capitalize the first word of every concept index entry, -or else consistently use lowercase. Terse entries often call for -lowercase; longer entries for capitalization. Whichever case -convention you use, please use one or the other consistently! Mixing -the two styles looks bad. - -@item -Always capitalize or use uppercase for those words in an index for -which this is proper, such as names of countries or acronyms. Always -use the appropriate case for case-sensitive names, such as those in C or -Lisp. - -@item -Write the indexing commands that refer to a whole section immediately -after the section command, and write the indexing commands that refer to -a paragraph before that paragraph. - -In the example that follows, a blank line comes after the index -entry for ``Leaping'': - -@example -@group -@@section The Dog and the Fox -@@cindex Jumping, in general -@@cindex Leaping - -@@cindex Dog, lazy, jumped over -@@cindex Lazy dog jumped over -@@cindex Fox, jumps over dog -@@cindex Quick fox jumps over dog -The quick brown fox jumps over the lazy dog. -@end group -@end example - -@noindent -(Note that the example shows entries for the same concept that are -written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so -readers can look up the concept in different ways.) -@end itemize - - -@subsubheading Blank Lines - -@itemize @bullet -@item -Insert a blank line between a sectioning command and the first following -sentence or paragraph, or between the indexing commands associated with -the sectioning command and the first following sentence or paragraph, as -shown in the tip on indexing. It makes the source easier to read. - -@item -Always insert a blank line before an @code{@@table} command and after an -@code{@@end table} command; but never insert a blank line after an -@code{@@table} command. - -@need 1000 -For example, - -@example -@group -Types of fox: - -@@table @@samp -@@item Quick -Jump over lazy dogs. -@end group - -@group -@@item Brown -Also jump over lazy dogs. -@@end table - -@end group -@group -@@noindent -On the other hand, @dots{} -@end group -@end example - -Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end -itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the -same way. -@end itemize - - -@subsubheading Complete Phrases - -Complete phrases are easier to read than @dots{} - -@itemize @bullet -@item -Write entries in an itemized list as complete sentences; or at least, as -complete phrases. Incomplete expressions @dots{} awkward @dots{} like -this. - -@item -Write the prefatory sentence or phrase for a multi-item list or table as -a complete expression. Do not write ``You can set:''; instead, write -``You can set these variables:''. The former expression sounds cut off. -@end itemize - - -@subsubheading Editions, Dates and Versions - -Include edition numbers, version numbers, and dates in the -@code{@@copying} text (for people reading the Texinfo file, and for the -legal copyright in the output files). Then use @code{@@insertcopying} -in the @code{@@titlepage} section for people reading the printed -output (@pxref{Short Sample}). - -It is easiest to handle such version information using @code{@@set} -and @code{@@value}. @xref{@t{@@value} Example}, and @ref{GNU -Sample Texts}. - - -@subsubheading Definition Commands - -Definition commands are @code{@@deffn}, @code{@@defun}, -@code{@@defmac}, and the like, and enable you to write descriptions in -a uniform format. - -@itemize @bullet -@item -Write just one definition command for each entity you define with a -definition command. The automatic indexing feature creates an index -entry that leads the reader to the definition. - -@item -Use @code{@@table} @dots{} @code{@@end table} in an appendix that -contains a summary of functions, not @code{@@deffn} or other definition -commands. -@end itemize - - -@subsubheading Capitalization - -@itemize @bullet -@item -Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or -@samp{i} in uppercase. - -@item -Capitalize ``Info''; it is a name. - -@item -Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase -@samp{T} and @samp{X}. This command causes the formatters to -typeset the name according to the wishes of Donald Knuth, who wrote -@TeX{}. (Likewise @code{@@LaTeX@{@}} for @LaTeX{}.) -@end itemize - - -@subsubheading Spaces - -Do not use spaces to format a Texinfo file, except inside of -@code{@@example} @dots{} @code{@@end example} and other literal -environments and commands. - -@need 700 -For example, @TeX{} fills the following: - -@example -@group - @@kbd@{C-x v@} - @@kbd@{M-x vc-next-action@} - Perform the next logical operation - on the version-controlled file - corresponding to the current buffer. -@end group -@end example - -@need 950 -@noindent -so it looks like this: - -@iftex -@quotation - @kbd{C-x v} - @kbd{M-x vc-next-action} - Perform the next logical operation on the version-controlled file - corresponding to the current buffer. -@end quotation -@end iftex -@ifnottex -@quotation -`C-x v' `M-x vc-next-action' Perform the next logical operation on the -version-controlled file corresponding to the current buffer. -@end quotation -@end ifnottex - -@noindent -In this case, the text should be formatted with -@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. - - -@subsubheading @@code, @@samp, @@var, and @samp{---} - -@itemize @bullet -@item -Use @code{@@code} around Lisp symbols, including command names. -For example, - -@example -The main function is @@code@{vc-next-action@}, @dots{} -@end example - -@item -Avoid putting letters such as @samp{s} immediately after an -@samp{@@code}. Such letters look bad. - -@item -Use @code{@@var} around meta-variables. Do not write angle brackets -around them. - -@item -Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} -typesets these as a long dash and the Info formatters reduce three -hyphens to two. -@end itemize - - -@subsubheading Periods Outside of Quotes - -Place periods and other punctuation marks @emph{outside} of quotations, -unless the punctuation is part of the quotation. This practice goes -against some publishing conventions in the United States, but enables the -reader to distinguish between the contents of the quotation and the -whole passage. - -For example, you should write the following sentence with the period -outside the end quotation marks: - -@example -Evidently, @samp{au} is an abbreviation for ``author''. -@end example - -@noindent -since @samp{au} does @emph{not} serve as an abbreviation for -@samp{author.} (with a period following the word). - - -@subsubheading Introducing New Terms - -@itemize @bullet -@item -Introduce new terms so that a reader who does not know them can -understand them from context; or write a definition for the term. - -For example, in the following, the terms ``check in'', ``register'' and -``delta'' are all appearing for the first time; the example sentence should be -rewritten so they are understandable. - -@quotation -The major function assists you in checking in a file to your -version control system and registering successive sets of changes to -it as deltas. -@end quotation - -@item -Use the @code{@@dfn} command around a word being introduced, to indicate -that the reader should not expect to know the meaning already, and -should expect to learn the meaning from this passage. -@end itemize - - -@subsubheading Program Invocation Nodes - -You can invoke programs such as XEmacs, GCC, and @code{gawk} from a -shell. The documentation for each program should contain a section that -describes this. Unfortunately, if the node names and titles for these -sections are all different, they are difficult for users to find. - -So, there is a convention to name such sections with a phrase beginning -with the word `Invoking', as in `Invoking XEmacs'; this way, users can -find the section easily. - - -@subsubheading ANSI C Syntax - -When you use @code{@@example} to describe a C function's calling -conventions, use the ANSI C syntax, like this: - -@example -void dld_init (char *@@var@{path@}); -@end example - -@noindent -And in the subsequent discussion, refer to the argument values by -writing the same argument names, again highlighted with -@code{@@var}. - -@need 800 -Avoid the obsolete style that looks like this: - -@example -#include <dld.h> - -dld_init (path) - char *path; -@end example - -Also, it is best to avoid writing @code{#include} above the -declaration just to indicate that the function is declared in a -header file. The practice may give the misimpression that the -@code{#include} belongs near the declaration of the function. Either -state explicitly which header file holds the declaration or, better -yet, name the header file used for a group of functions at the -beginning of the section that describes the functions. - -@anchor{texi-elements-by-size} -@subsubheading Node Length - -Keep nodes (sections) to a reasonable length, whatever reasonable -might be in the given context. Don't hesitate break up long nodes -into subnodes and have an extensive tree structure; that's what it's -there for. Many times, readers will probably try to find a single -specific point in the manual, using search, indexing, or just plain -guessing, rather than reading the whole thing from beginning to end. - -You can use the @command{texi-elements-by-size} utility to see a list -of all nodes (or sections) in the document, sorted by size (either -lines or words), to find candidates for splitting. It's in the -@file{util/} subdirectory of the Texinfo sources. - - -@subsubheading Bad Examples - -Here are several examples of bad writing to avoid: - -In this example, say, `` @dots{} you must @code{@@dfn}@{check -in@} the new version.'' That flows better. - -@quotation -When you are done editing the file, you must perform a -@code{@@dfn}@{check in@}. -@end quotation - -In the following example, say, ``@dots{} makes a unified interface such as VC -mode possible.'' - -@quotation -SCCS, RCS and other version-control systems all perform similar -functions in broadly similar ways (it is this resemblance which makes -a unified control mode like this possible). -@end quotation - -And in this example, you should specify what `it' refers to: - -@quotation -If you are working with other people, it assists in coordinating -everyone's changes so they do not step on each other. -@end quotation - - -@subsubheading And Finally @dots{} - -@itemize @bullet -@item -Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last -sound in the name `Bach'. But pronounce Texinfo as in `speck': -``teckinfo''. - -@item -Write notes for yourself at the very end of a Texinfo file after the -@code{@@bye}. None of the formatters process text after the -@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} -@code{@@end ignore}. -@end itemize - - -@node Sample Texinfo Files -@appendix Sample Texinfo Files -@cindex Sample Texinfo files - -The first example is from the first chapter (@pxref{Short Sample}), -given here in its entirety, without commentary. The second -includes the full texts to be used in GNU manuals. - -@menu -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: -@end menu - - -@node Short Sample Texinfo File -@section Short Sample -@cindex Sample Texinfo file, no comments - -Here is a complete, short sample Texinfo file, without any commentary. -You can see this file, with comments, in the first chapter. @xref{Short -Sample}. - -In a nutshell: The @command{makeinfo} program transforms a Texinfo -source file such as this into an Info file or HTML; and @TeX{} typesets -it for a printed manual. - - -@sp 1 -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Manual 1.0 -@@c %**end of header - -@@copying -This is a short example of a complete Texinfo file. - -Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. -@@end copying - -@@titlepage -@@title Sample Title -@@page -@@vskip 0pt plus 1filll -@@insertcopying -@@end titlepage - -@@c Output the table of the contents at the beginning. -@@contents - -@@ifnottex -@@node Top -@@top GNU Sample - -@@insertcopying -@@end ifnottex - -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Index:: Complete index. -@@end menu - - -@@node First Chapter -@@chapter First Chapter - -@@cindex chapter, first - -This is the first chapter. -@@cindex index entry, another - -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate - - -@@node Index -@@unnumbered Index - -@@printindex cp - -@@bye -@end example - - -@node GNU Sample Texts -@section GNU Sample Texts - -@cindex GNU sample texts -@cindex Sample texts, GNU -@cindex Full texts, GNU - -Following is a sample Texinfo document with the full texts that should -be used (adapted as necessary) in GNU manuals. - -As well as the legal texts, it also serves as a practical example of how -many elements in a GNU system can affect the manual. If you're not -familiar with all these different elements, don't worry. They're not -required and a perfectly good manual can be written without them. -They're included here nonetheless because many manuals do (or could) -benefit from them. - -@xref{Short Sample}, for a minimal example of a Texinfo file. -@xref{Beginning a File}, for a full explanation of that minimal -example. - -Here are some notes on the example: - -@itemize @bullet -@item -@cindex $Id -@cindex CVS $Id -@cindex RCS $Id -@cindex Documentation identification -@cindex Identification of documentation -The @samp{$Id:} comment is for the CVS (@pxref{Top,,, cvs, Concurrent -Versions System}), RCS (@pxref{Top,,, rcs, Revision Control System}) -and other version control systems, which expand it into a string such -as: - -@example -$Id: texinfo.texi 5381 2013-09-26 23:03:58Z karl $ -@end example - -(This is potentially useful in all sources that use version control, -not just manuals.) You may wish to include the @samp{$Id:} comment in -the @code{@@copying} text, if you want a completely unambiguous -reference to the documentation source version. - -If you want to literally write @t{@w{$}Id$}, use @code{@@w}: -@code{@@w@{$@}Id$}. Unfortunately, this technique does not work in -plain text output, where it's not clear what should be done. - -@item -@pindex automake@r{, and version info} -@vindex UPDATED @r{Automake variable} -@vindex VERSION @r{Automake variable} -@pindex time-stamp.el -The @file{version.texi} in the @code{@@include} command is maintained -automatically by Automake (@pxref{Top,,, automake, GNU Automake}). It -sets the @samp{VERSION} and @samp{UPDATED} values used elsewhere. If -your distribution doesn't use Automake, but you do use XEmacs, you may -find the time-stamp.el package helpful (@pxref{Time Stamps,,, xemacs, -XEmacs User's Manual}). - -@item -The @code{@@syncodeindex} command reflects the recommendation to use -only one index where possible, to make it easier for readers to look up -index entries. - -@item -The @code{@@dircategory} is for constructing the Info directory. -@xref{Installing Dir Entries}, which includes a variety of recommended -category names. - -@item -The `Invoking' node is a GNU standard to help users find the basic -information about command-line usage of a given program. @xref{Manual -Structure Details,,, standards, GNU Coding Standards}. - -@item -@cindex GNU Free Documentation License, including entire -@cindex Free Documentation License, including entire -It is best to include the entire GNU Free Documentation License in a GNU -manual, unless the manual is only a few pages long. Of course this -sample is even shorter than that, but it includes the FDL anyway in -order to show one conventional way to do so. The @file{fdl.texi} file -is available on the GNU machines and in the Texinfo and other GNU -source distributions. - -The FDL provides for omitting itself under certain conditions, but in -that case the sample texts given here have to be modified. @xref{GNU -Free Documentation License}. - -@item -If the FSF is not the copyright holder, then use the appropriate name. - -@item -If your manual is published on paper by the FSF or is longer than 400 -pages, you should include the standard FSF cover texts (@pxref{License -Notices for Documentation,,, maintain, GNU Maintainer Information}). - -@item -For documents that express your personal views, feelings or -experiences, it is more appropriate to use a license permitting only -verbatim copying, rather than the FDL@. @xref{Verbatim Copying -License}. - -@end itemize - -Here is the sample document: - -@verbatim -\input texinfo @c -*-texinfo-*- -@comment $Id@w{$} -@comment %**start of header -@setfilename sample.info -@include version.texi -@settitle GNU Sample @value{VERSION} -@syncodeindex pg cp -@comment %**end of header -@copying -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), -which is an example in the Texinfo documentation. - -Copyright @copyright{} 2013 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled -``GNU Free Documentation License''. -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* sample: (sample)Invoking sample. -@end direntry - -@titlepage -@title GNU Sample -@subtitle for version @value{VERSION}, @value{UPDATED} -@author A.U. Thor (@email{bug-sample@@gnu.org}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Sample - -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). -@end ifnottex - -@menu -* Invoking sample:: -* GNU Free Documentation License:: -* Index:: -@end menu - - -@node Invoking sample -@chapter Invoking sample - -@pindex sample -@cindex invoking @command{sample} - -This is a sample manual. There is no sample program to -invoke, but if there were, you could see its basic usage -and command line options here. - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include fdl.texi - - -@node Index -@unnumbered Index - -@printindex cp - -@bye -@end verbatim - - -@node Verbatim Copying License -@section Verbatim Copying License - -@cindex Verbatim copying license -@cindex License for verbatim copying - -For software manuals and other documentation, it is critical to use a -license permitting free redistribution and updating, so that when a free -program is changed, the documentation can be updated as well. - -On the other hand, for documents that express your personal views, -feelings or experiences, it is more appropriate to use a license -permitting only verbatim copying. - -Here is sample text for such a license permitting verbatim copying only. -This is just the license text itself. For a complete sample document, -see the previous sections. - -@verbatim -@copying -This document is a sample for allowing verbatim copying only. - -Copyright @copyright{} 2013 Free Software Foundation, Inc. - -@quotation -Permission is granted to make and distribute verbatim copies -of this entire document without royalty provided the -copyright notice and this permission notice are preserved. -@end quotation -@end copying -@end verbatim - - -@node All-permissive Copying License -@section All-permissive Copying License - -@cindex All-permissive copying license -@cindex License for all-permissive copying - -For software manuals and other documentation, it is important to use a -license permitting free redistribution and updating, so that when a free -program is changed, the documentation can be updated as well. - -On the other hand, for small supporting files, short manuals (under 300 -lines long) and rough documentation (README files, INSTALL files, etc.), -the full FDL would be overkill. They can use a simple all-permissive -license. - -Here is sample text for such an all-permissive license. This is just -the license text itself. For a complete sample document, see the -previous sections. - -@example -Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. - -Copying and distribution of this file, with or without modification, -are permitted in any medium without royalty provided the copyright -notice and this notice are preserved. -@end example - - -@node Headings -@appendix Page Headings -@cindex Headings -@cindex Footings -@cindex Page numbering -@cindex Page headings -@cindex Formatting headings and footings - -Most printed manuals contain headings along the top of every page -except the title and copyright pages. Some manuals also contain -footings. @c HTML output also supports something like these, but in a -@c completely different way: @pxref{Customizing HTML Page Layout}. -Headings and footings have no meaning in Info or the other output -formats. - -@menu -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. -@end menu - -@node Headings Introduced -@section Headings Introduced - -Texinfo provides standard page heading formats for manuals that are -printed on one side of each sheet of paper and for manuals that are -printed on both sides of the paper. Typically, you will use these -formats, but you can specify your own format if you wish. - -In addition, you can specify whether chapters should begin on a new -page, or merely continue the same page as the previous chapter; and if -chapters begin on new pages, you can specify whether they must be -odd-numbered pages. - -By convention, a book is printed on both sides of each sheet of paper. -When you open a book, the right-hand page is odd-numbered, and -chapters begin on right-hand pages---a preceding left-hand page is -left blank if necessary. Reports, however, are often printed on just -one side of paper, and chapters begin on a fresh page immediately -following the end of the preceding chapter. In short or informal -reports, chapters often do not begin on a new page at all, but are -separated from the preceding text by a small amount of whitespace. - -The @code{@@setchapternewpage} command controls whether chapters begin -on new pages, and whether one of the standard heading formats is used. -In addition, Texinfo has several heading and footing commands that you -can use to generate your own heading and footing formats. - -In Texinfo, headings and footings are single lines at the tops and -bottoms of pages; you cannot create multiline headings or footings. -Each header or footer line is divided into three parts: a left part, a -middle part, and a right part. Any part, or a whole line, may be left -blank. Text for the left part of a header or footer line is set -flushleft; text for the middle part is centered; and, text for the -right part is set flushright. - - -@node Heading Format -@section Standard Heading Formats - -Texinfo provides two standard heading formats, one for manuals printed -on one side of each sheet of paper, and the other for manuals printed -on both sides of the paper. - -By default, nothing is specified for the footing of a Texinfo file, -so the footing remains blank. - -The standard format for single-sided printing consists of a header -line in which the left-hand part contains the name of the chapter, the -central part is blank, and the right-hand part contains the page -number. - -@need 950 -A single-sided page looks like this: - -@example -@group - _______________________ - | | - | chapter page number | - | | - | Start of text ... | - | ... | - | | -@end group -@end example - -The standard format for two-sided printing depends on whether the page -number is even or odd. By convention, even-numbered pages are on the -left- and odd-numbered pages are on the right. (@TeX{} will adjust the -widths of the left- and right-hand margins. Usually, widths are -correct, but during double-sided printing, it is wise to check that -pages will bind properly---sometimes a printer will produce output in -which the even-numbered pages have a larger right-hand margin than the -odd-numbered pages.) - -In the standard double-sided format, the left part of the left-hand -(even-numbered) page contains the page number, the central part is -blank, and the right part contains the title (specified by the -@code{@@settitle} command). The left part of the right-hand -(odd-numbered) page contains the name of the chapter, the central part -is blank, and the right part contains the page number. - -@need 750 -Two pages, side by side as in an open book, look like this: - -@example -@group - _______________________ _______________________ - | | | | - | page number title | | chapter page number | - | | | | - | Start of text ... | | More text ... | - | ... | | ... | - | | | | -@end group -@end example - -@noindent -The chapter name is preceded by the word ``Chapter'', the chapter number -and a colon. This makes it easier to keep track of where you are in the -manual. - -@node Heading Choice -@section Specifying the Type of Heading - -@TeX{} does not begin to generate page headings for a standard Texinfo -file until it reaches the @code{@@end titlepage} command. Thus, the -title and copyright pages are not numbered. The @code{@@end -titlepage} command causes @TeX{} to begin to generate page headings -according to a standard format specified by the -@code{@@setchapternewpage} command that precedes the -@code{@@titlepage} section. - -@need 1000 -There are four possibilities: - -@table @asis -@item No @code{@@setchapternewpage} command -Cause @TeX{} to specify the single-sided heading format, with chapters -on new pages. This is the same as @code{@@setchapternewpage on}. - -@item @code{@@setchapternewpage on} -Specify the single-sided heading format, with chapters on new pages. - -@item @code{@@setchapternewpage off} -Cause @TeX{} to start a new chapter on the same page as the last page -of the preceding chapter, after skipping some vertical whitespace. -Also cause @TeX{} to typeset for single-sided printing. (You can -override the headers format with the @code{@@headings double} command; -@pxref{@t{@@headings}}.) - -@item @code{@@setchapternewpage odd} -Specify the double-sided heading format, with chapters on new pages. -@end table - -@noindent -Texinfo lacks an @code{@@setchapternewpage even} command. - - -@node Custom Headings -@section How to Make Your Own Headings - -You can use the standard headings provided with Texinfo or specify -your own. By default, Texinfo has no footers, so if you specify them, -the available page size for the main text will be slightly reduced. - -Texinfo provides six commands for specifying headings and -footings: -@itemize @bullet -@item -@code{@@everyheading} and @code{@@everyfooting} generate page headers and -footers that are the same for both even- and odd-numbered pages. -@item -@code{@@evenheading} and @code{@@evenfooting} command generate headers -and footers for even-numbered (left-hand) pages. -@item -@code{@@oddheading} and @code{@@oddfooting} generate headers and footers -for odd-numbered (right-hand) pages. -@end itemize - -Write custom heading specifications in the Texinfo file immediately -after the @code{@@end titlepage} command. You must cancel the -predefined heading commands with the @code{@@headings off} command -before defining your own specifications. - -@need 1000 -Here is how to tell @TeX{} to place the chapter name at the left, the -page number in the center, and the date at the right of every header -for both even- and odd-numbered pages: - -@example -@group -@@headings off -@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} -@end group -@end example - -@noindent -You need to divide the left part from the central part and the central -part from the right part by inserting @samp{@@|} between parts. -Otherwise, the specification command will not be able to tell where -the text for one part ends and the next part begins. - -Each part can contain text or @@-commands. The text is printed as if -the part were within an ordinary paragraph in the body of the page. -The @@-commands replace themselves with the page number, date, chapter -name, or whatever. - -@need 950 -Here are the six heading and footing commands: - -@table @code -@item @@everyheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} -@findex everyheading -@findex everyfooting -The `every' commands specify the format for both even- and odd-numbered -pages. These commands are for documents that are printed on one side -of each sheet of paper, or for documents in which you want symmetrical -headers or footers. - -@item @@evenheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} -@findex evenheading -@findex evenfooting -@findex oddheading -@findex oddfooting -The `even' and `odd' commands specify the format for even-numbered -pages and odd-numbered pages. These commands are for books and -manuals that are printed on both sides of each sheet of paper. -@end table - -Use the @samp{@@this@dots{}} series of @@-commands to -provide the names of chapters -and sections and the page number. You can use the -@samp{@@this@dots{}} commands in the left, center, or right portions -of headers and footers, or anywhere else in a Texinfo file so long as -they are between @code{@@iftex} and @code{@@end iftex} commands. - -@need 1000 -Here are the @samp{@@this@dots{}} commands: - -@table @code -@item @@thispage -@findex thispage -Expands to the current page number. - -@item @@thissectionname -@findex thissectionname -Expands to the name of the current section. - -@item @@thissectionnum -@findex thissectionnum -Expands to the number of the current section. - -@item @@thissection -@findex thissection -Expands to the number and name of the current section, in the format -`Section 1: Title'. - -@item @@thischaptername -@findex thischaptername -Expands to the name of the current chapter. - -@item @@thischapternum -@findex thischapternum -Expands to the number of the current chapter, or letter of the current -appendix. - -@item @@thischapter -@findex thischapter -Expands to the number and name of the current -chapter, in the format `Chapter 1: Title'. - -@item @@thistitle -@findex thistitle -Expands to the name of the document, as specified by the -@code{@@settitle} command. - -@item @@thisfile -@findex thisfile -For @code{@@include} files only: expands to the name of the current -@code{@@include} file. If the current Texinfo source file is not an -@code{@@include} file, this command has no effect. This command does -@emph{not} provide the name of the current Texinfo source file unless -it is an @code{@@include} file. (@xref{Include Files}, for more -information about @code{@@include} files.) -@end table - -@noindent -You can also use the @code{@@today@{@}} command, which expands to the -current date, in `1 Jan 1900' format. -@findex today - -Other @@-commands and text are printed in a header or footer just as -if they were in the body of a page. It is useful to incorporate text, -particularly when you are writing drafts: - -@example -@group -@@headings off -@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter -@@everyfooting @@| @@| Version: 0.27: @@today@{@} -@end group -@end example - -Beware of overlong titles: they may overlap another part of the -header or footer and blot it out. - -If you have very short chapters and/or sections, several of them can -appear on a single page. You can specify which chapters and sections -you want @code{@@thischapter}, @code{@@thissection} and other such -macros to refer to on such pages as follows: - -@table @code -@item @@everyheadingmarks @var{ref} -@itemx @@everyfootingmarks @var{ref} -@findex everyheadingmarks -@findex everyfootingmarks -The @var{ref} argument can be either @code{top} (the @code{@@this...} -commands will refer to the chapter/section at the top of a page) or -@code{bottom} (the commands will reflect the situation at the bottom -of a page). These @samp{@@every...} commands specify what to do on -both even- and odd-numbered pages. - -@item @@evenheadingmarks @var{ref} -@itemx @@oddheadingmarks @var{ref} -@itemx @@evenfootingmarks @var{ref} -@itemx @@oddfootingmarks @var{ref} -@findex evenheadingmarks -@findex oddheadingmarks -@findex evenfootingmarks -@findex oddfootingmarks -These @samp{@@even...} and @samp{@@odd...} commands specify what to do -on only even- or odd-numbered pages, respectively. The @var{ref} -argument is the same as with the @samp{@@every...} commands. -@end table - -Write these commands immediately after the @code{@@...contents} -commands, or after the @code{@@end titlepage} command if you don't -have a table of contents or if it is printed at the end of your -manual. - -By default the @code{@@this...} commands reflect the situation at the -bottom of a page both in headings and in footings. - - -@node Catching Mistakes -@appendix Catching Mistakes -@cindex Structure, catching mistakes in -@cindex Nodes, catching mistakes -@cindex Catching mistakes -@cindex Correcting mistakes -@cindex Mistakes, catching -@cindex Problems, catching -@cindex Debugging the Texinfo structure - -Besides mistakes in the content of your documentation, there are two -kinds of mistake you can make with Texinfo: you can make mistakes with -@@-commands, and you can make mistakes with the structure of the nodes -and chapters. - -XEmacs has two tools for catching the @@-command mistakes and two for -catching structuring mistakes. - -For finding problems with @@-commands, you can run @TeX{} or a region -formatting command on the region that has a problem; indeed, you can -run these commands on each region as you write it. - -For finding problems with the structure of nodes and chapters, you can use -@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} -command and you can use the @kbd{M-x Info-validate} command. - -@menu -* @t{makeinfo} Preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting. -* Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}. -* Using @t{occur}:: How to list all lines containing a pattern. -* Running @t{Info-validate}:: How to find badly referenced nodes. -@end menu - - -@node @t{makeinfo} Preferred -@section @code{makeinfo} Preferred - -@c anchor{makeinfo Preferred}@c prev name - -The @code{makeinfo} program does an excellent job of catching errors -and reporting them---far better than @code{texinfo-format-region} or -@code{texinfo-format-buffer}. In addition, the various functions for -automatically creating and updating node pointers and menus remove -many opportunities for human error. - -If you can, use the updating commands to create and insert pointers -and menus. These prevent many errors. Then use @code{makeinfo} (or -its Texinfo mode manifestations, @code{makeinfo-region} and -@code{makeinfo-buffer}) to format your file and check for other -errors. This is the best way to work with Texinfo. But if you -cannot use @code{makeinfo}, or your problem is very puzzling, then you -may want to use the tools described in this appendix. - - -@node Debugging with Info -@section Catching Errors with Info Formatting -@cindex Catching errors with Info formatting -@cindex Debugging with Info formatting - -After you have written part of a Texinfo file, you can use the -@code{texinfo-format-region} or the @code{makeinfo-region} command to -see whether the region formats properly. - -Most likely, however, you are reading this section because for some -reason you cannot use the @code{makeinfo-region} command; therefore, the -rest of this section presumes that you are using -@code{texinfo-format-region}. - -If you have made a mistake with an @@-command, -@code{texinfo-format-region} will stop processing at or after the -error and display an error message. To see where in the buffer the -error occurred, switch to the @samp{*Info Region*} buffer; the cursor -will be in a position that is after the location of the error. Also, -the text will not be formatted after the place where the error -occurred (or more precisely, where it was detected). - -For example, if you accidentally end a menu with the command @code{@@end -menus} with an `s' on the end, instead of with @code{@@end menu}, you -will see an error message that says: - -@example -@@end menus is not handled by texinfo -@end example - -@noindent -The cursor will stop at the point in the buffer where the error -occurs, or not long after it. The buffer will look like this: - -@example -@group ----------- Buffer: *Info Region* ---------- -* Menu: - -* Using texinfo-show-structure:: How to use - `texinfo-show-structure' - to catch mistakes. -* Running Info-validate:: How to check for - unreferenced nodes. -@@end menus -@point{} ----------- Buffer: *Info Region* ---------- -@end group -@end example - -The @code{texinfo-format-region} command sometimes provides slightly -odd error messages. For example, the following cross reference fails to format: - -@example -(@@xref@{Catching Mistakes, for more info.) -@end example - -@noindent -In this case, @code{texinfo-format-region} detects the missing closing -brace but displays a message that says @samp{Unbalanced parentheses} -rather than @samp{Unbalanced braces}. This is because the formatting -command looks for mismatches between braces as if they were -parentheses. - -Sometimes @code{texinfo-format-region} fails to detect mistakes. For -example, in the following, the closing brace is swapped with the -closing parenthesis: - -@example -(@@xref@{Catching Mistakes), for more info.@} -@end example - -@noindent -Formatting produces: -@example -(*Note for more info.: Catching Mistakes) -@end example - -The only way for you to detect this error is to realize that the -reference should have looked like this: - -@example -(*Note Catching Mistakes::, for more info.) -@end example - -Incidentally, if you are reading this node in Info and type @kbd{f -@key{RET}} (@code{Info-follow-reference}), you will generate an error -message that says: - -@example -No such node: "Catching Mistakes) The only way @dots{} -@end example - -@noindent -This is because Info perceives the example of the error as the first -cross reference in this node and if you type a @key{RET} immediately -after typing the Info @kbd{f} command, Info will attempt to go to the -referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info -will complete the node name of the correctly written example and take -you to the `Catching Mistakes' node. (If you try this, you can return -from the `Catching Mistakes' node by typing @kbd{l} -(@code{Info-last}).) - - -@node Debugging with @TeX{} -@section Debugging with @TeX{} -@cindex Catching errors with @TeX{} formatting -@cindex Debugging with @TeX{} formatting - -You can also catch mistakes when you format a file with @TeX{}. - -Usually, you will want to do this after you have run -@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on -the same file, because @code{texinfo-format-buffer} sometimes displays -error messages that make more sense than @TeX{}. (@xref{Debugging -with Info}, for more information.) - -For example, @TeX{} was run on a Texinfo file, part of which is shown -here: - -@example ----------- Buffer: texinfo.texi ---------- -name of the Texinfo file as an extension. The -@@samp@{??@} are `wildcards' that cause the shell to -substitute all the raw index files. (@@xref@{sorting -indices, for more information about sorting -indices.)@@refill ----------- Buffer: texinfo.texi ---------- -@end example - -@noindent -(The cross reference lacks a closing brace.) -@TeX{} produced the following output, after which it stopped: - -@example ----------- Buffer: *tex-shell* ---------- -Runaway argument? -@{sorting indices, for more information about sorting -indices.) @@refill @@ETC. -! Paragraph ended before @@xref was complete. -<to be read again> - @@par -l.27 - -? ----------- Buffer: *tex-shell* ---------- -@end example - -In this case, @TeX{} produced an accurate and -understandable error message: - -@example -Paragraph ended before @@xref was complete. -@end example - -@noindent -@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. -@samp{l.27} means that @TeX{} detected the problem on line 27 of the -Texinfo file. The @samp{?} is the prompt @TeX{} uses in this -circumstance. - -Unfortunately, @TeX{} is not always so helpful, and sometimes you must -truly be a Sherlock Holmes to discover what went wrong. - -In any case, if you run into a problem like this, you can do one of three -things. - -@enumerate -@item -You can tell @TeX{} to continue running and ignore just this error by -typing @key{RET} at the @samp{?} prompt. - -@item -You can tell @TeX{} to continue running and to ignore all errors as best -it can by typing @kbd{r @key{RET}} at the @samp{?} prompt. - -This is often the best thing to do. However, beware: the one error -may produce a cascade of additional error messages as its consequences -are felt through the rest of the file. To stop @TeX{} when it is -producing such an avalanche of error messages, type @kbd{C-c} (or -@kbd{C-c C-c}, if you are running a shell inside XEmacs). - -@item -You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} -at the @samp{?} prompt. -@end enumerate - -If you are running @TeX{} inside XEmacs, you need to switch to the shell -buffer and line at which @TeX{} offers the @samp{?} prompt. - -Sometimes @TeX{} will format a file without producing error messages even -though there is a problem. This usually occurs if a command is not ended -but @TeX{} is able to continue processing anyhow. For example, if you fail -to end an itemized list with the @code{@@end itemize} command, @TeX{} will -write a DVI file that you can print out. The only error message that -@TeX{} will give you is the somewhat mysterious comment: - -@example -(@@end occurred inside a group at level 1) -@end example - -@noindent -However, if you print the DVI file, you will find that the text -of the file that follows the itemized list is entirely indented as if -it were part of the last item in the itemized list. The error message -is the way @TeX{} says that it expected to find an @code{@@end} -command somewhere in the file; but that it could not determine where -it was needed. - -Another source of notoriously hard-to-find errors is a missing -@code{@@end group} command. If you ever are stumped by -incomprehensible errors, look for a missing @code{@@end group} command -first. - -If the Texinfo file lacks header lines, -@TeX{} may stop in the -beginning of its run and display output that looks like the following. -The @samp{*} indicates that @TeX{} is waiting for input. - -@example -This is TeX, Version 3.14159 (Web2c 7.0) -(test.texinfo [1]) -* -@end example - -@noindent -In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then -write the header lines in the Texinfo file and run the @TeX{} command -again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} -instead of @samp{@@}; and in this circumstance, you are working -directly with @TeX{}, not with Texinfo.) - -@node Using @t{texinfo-show-structure} -@section Using @code{texinfo-show-structure} - -@cindex Showing the structure of a file -@findex texinfo-show-structure - -It is not always easy to keep track of the nodes, chapters, sections, and -subsections of a Texinfo file. This is especially true if you are revising -or adding to a Texinfo file that someone else has written. - -In XEmacs, in Texinfo mode, the @code{texinfo-show-structure} -command lists all the lines that begin with the @@-commands that -specify the structure: @code{@@chapter}, @code{@@section}, -@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} -as prefix argument, if interactive), -the command also shows the @code{@@node} lines. The -@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in -Texinfo mode, by default. - -The lines are displayed in a buffer called the @samp{*Occur*} buffer, -indented by hierarchical level. For example, here is a part of what was -produced by running @code{texinfo-show-structure} on this manual: - -@example -@group -Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| -unnum\\|major\\|chapheading \\|heading \\|appendix\\)" -in buffer texinfo.texi. -@dots{} -4177:@@chapter Nodes -4198: @@heading Two Paths -4231: @@section Node and Menu Illustration -4337: @@section The @@code@{@@@@node@} Command -4393: @@subheading Choosing Node and Pointer Names -4417: @@subsection How to Write an @@code@{@@@@node@} Line -4469: @@subsection @@code@{@@@@node@} Line Tips -@dots{} -@end group -@end example - -This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin -with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} -commands respectively. If you move your cursor into the @samp{*Occur*} -window, you can position the cursor over one of the lines and use the -@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to -the corresponding spot in the Texinfo file. @xref{Other Repeating -Search, , Using Occur, xemacs, XEmacs User's Manual}, for more -information about @code{occur-mode-goto-occurrence}. - -The first line in the @samp{*Occur*} window describes the @dfn{regular -expression} specified by @var{texinfo-heading-pattern}. This regular -expression is the pattern that @code{texinfo-show-structure} looks for. -@xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual}, -for more information. - -When you invoke the @code{texinfo-show-structure} command, XEmacs will -display the structure of the whole buffer. If you want to see the -structure of just a part of the buffer, of one chapter, for example, -use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the -region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is -how the example used above was generated. (To see the whole buffer -again, use @kbd{C-x n w} (@code{widen}).) - -If you call @code{texinfo-show-structure} with a prefix argument by -typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with -@code{@@node} as well as the lines beginning with the @@-sign commands -for @code{@@chapter}, @code{@@section}, and the like. - -You can remind yourself of the structure of a Texinfo file by looking at -the list in the @samp{*Occur*} window; and if you have mis-named a node -or left out a section, you can correct the mistake. - -@node Using @t{occur} -@section Using @code{occur} - -@cindex Occurrences, listing with @code{@@occur} -@findex occur - -Sometimes the @code{texinfo-show-structure} command produces too much -information. Perhaps you want to remind yourself of the overall structure -of a Texinfo file, and are overwhelmed by the detailed list produced by -@code{texinfo-show-structure}. In this case, you can use the @code{occur} -command directly. To do this, type: - -@example -@kbd{M-x occur} -@end example - -@noindent -and then, when prompted, type a @dfn{regexp}, a regular expression for -the pattern you want to match. (@xref{Regexps, , Regular Expressions, -xemacs, XEmacs User's Manual}.) The @code{occur} command works from -the current location of the cursor in the buffer to the end of the -buffer. If you want to run @code{occur} on the whole buffer, place -the cursor at the beginning of the buffer. - -For example, to see all the lines that contain the word -@samp{@@chapter} in them, just type @samp{@@chapter}. This will -produce a list of the chapters. It will also list all the sentences -with @samp{@@chapter} in the middle of the line. - -If you want to see only those lines that start with the word -@samp{@@chapter}, type @samp{^@@chapter} when prompted by -@code{occur}. If you want to see all the lines that end with a word -or phrase, end the last word with a @samp{$}; for example, -@samp{catching mistakes$}. This can be helpful when you want to see -all the nodes that are part of the same chapter or section and -therefore have the same `Up' pointer. - -@xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual}, -for more information. - - -@node Running @t{Info-validate} -@section Finding Badly Referenced Nodes - -@anchor{Running Info-Validate}@c old name -@findex Info-validate -@cindex Nodes, checking for badly referenced -@cindex Checking for badly referenced nodes -@cindex Looking for badly referenced nodes -@cindex Finding badly referenced nodes -@cindex Badly referenced nodes - -You can use the @code{Info-validate} command to check whether any of -the `Next', `Previous', `Up' or other node pointers fail to point to a -node. This command checks that every node pointer points to an -existing node. The @code{Info-validate} command works only on Info -files, not on Texinfo files. - -The @code{makeinfo} program validates pointers automatically, so you -do not need to use the @code{Info-validate} command if you are using -@code{makeinfo}. You only may need to use @code{Info-validate} if you -are unable to run @code{makeinfo} and instead must create an Info file -using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or -if you write an Info file from scratch. - -@menu -* Using @t{Info-validate}:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. -@end menu - - -@node Using @t{Info-validate} -@subsection Using @code{Info-validate} - -@cindex Using @code{Info-validate} -@cindex Info validating a large file -@cindex Validating a large file - -To use @code{Info-validate}, visit the Info file you wish to check and -type: - -@example -M-x Info-validate -@end example - -@noindent -Note that the @code{Info-validate} command requires an uppercase -`I'@. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}. - -If your file is valid, you will receive a message that says ``File appears -valid''. However, if you have a pointer that does not point to a node, -error messages will be displayed in a buffer called @samp{*problems in -info file*}. - -For example, @code{Info-validate} was run on a test file that contained -only the first node of this manual. One of the messages said: - -@example -In node "Overview", invalid Next: Texinfo Mode -@end example - -@noindent -This meant that the node called @samp{Overview} had a `Next' pointer that -did not point to anything (which was true in this case, since the test file -had only one node in it). - -Now suppose we add a node named @samp{Texinfo Mode} to our test case -but we do not specify a `Previous' for this node. Then we will get -the following error message: - -@example -In node "Texinfo Mode", should have Previous: Overview -@end example - -@noindent -This is because every `Next' pointer should be matched by a -`Previous' (in the node where the `Next' points) which points back. - -@code{Info-validate} also checks that all menu entries and cross references -point to actual nodes. - -@code{Info-validate} requires a tag table and does not work with files -that have been split. (The @code{texinfo-format-buffer} command -automatically splits large files.) In order to use @code{Info-validate} -on a large file, you must run @code{texinfo-format-buffer} with an -argument so that it does not split the Info file; and you must create a -tag table for the unsplit file. - -@node Unsplit -@subsection Creating an Unsplit File -@cindex Creating an unsplit file -@cindex Unsplit file creation - -You can run @code{Info-validate} only on a single Info file that has a -tag table. The command will not work on the indirect subfiles that -are generated when a master file is split. If you have a large file -(longer than 300,000 bytes or so), you need to run the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such -a way that it does not create indirect subfiles. You will also need -to create a tag table for the Info file. After you have done this, -you can run @code{Info-validate} and look for badly referenced -nodes. - -The first step is to create an unsplit Info file. To prevent -@code{texinfo-format-buffer} from splitting a Texinfo file into -smaller Info files, give a prefix to the @kbd{M-x -texinfo-format-buffer} command: - -@example -C-u M-x texinfo-format-buffer -@end example - -@noindent -or else - -@example -C-u C-c C-e C-b -@end example - -@noindent -When you do this, Texinfo will not split the file and will not create -a tag table for it. -@cindex Making a tag table manually -@cindex Tag table, making manually - -@node Tagifying -@subsection Tagifying a File - -After creating an unsplit Info file, you must create a tag table for -it. Visit the Info file you wish to tagify and type: - -@example -M-x Info-tagify -@end example - -@noindent -(Note the uppercase @samp{I} in @code{Info-tagify}.) This creates an -Info file with a tag table that you can validate. - -The third step is to validate the Info file: - -@example -M-x Info-validate -@end example - -@noindent -(Note the uppercase @samp{I} in @code{Info-validate}.) -In brief, the steps are: - -@example -@group -C-u M-x texinfo-format-buffer -M-x Info-tagify -M-x Info-validate -@end group -@end example - -After you have validated the node structure, you can rerun -@code{texinfo-format-buffer} in the normal way so it will construct a -tag table and split the file automatically, or you can make the tag -table and split the file manually. - -@node Splitting -@subsection Splitting a File Manually -@cindex Splitting an Info file manually -@cindex Info file, splitting manually - -You should split a large file or else let the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it -for you automatically. (Generally you will let one of the formatting -commands do this job for you. @xref{Creating an Info File}.) - -The split-off files are called the indirect subfiles. - -Info files are split to save memory. With smaller files, XEmacs does not -have to make such a large buffer to hold the information. - -If an Info file has more than 30 nodes, you should also make a tag -table for it. @xref{Using @t{Info-validate}}, for information -about creating a tag table. (Again, tag tables are usually created -automatically by the formatting command; you only need to create a tag -table yourself if you are doing the job manually. Most likely, you -will do this for a large, unsplit file on which you have run -@code{Info-validate}.) - -Visit the Info file you wish to tagify and split and type the two -commands: - -@example -M-x Info-tagify -M-x Info-split -@end example - -@noindent -(Note that the @samp{I} in @samp{Info} is uppercase.) - -When you use the @code{Info-split} command, the buffer is modified into a -(small) Info file which lists the indirect subfiles. This file should be -saved in place of the original visited file. The indirect subfiles are -written in the same directory the original file is in, with names generated -by appending @samp{-} and a number to the original file name. - -The primary file still functions as an Info file, but it contains just -the tag table and a directory of subfiles. - - -@node Info Format Specification -@appendix Info Format Specification - -@cindex Info format specification -@cindex Specification of Info format -@cindex Definition of Info format - -Here we describe the technical details of the Info format. - -This format definition was written some 25 years after the Info format -was first devised. So in the event of conflicts between this -definition and actual practice, practice wins. It also assumes some -general knowledge of Texinfo; it is meant to be a guide for -implementors rather than a rigid technical standard. We often refer -back to other parts of this manual for examples and definitions, -rather than redundantly spelling out every detail. - -In this formal description, the characters @code{<>*()|=#} are used -for the language of the description itself. Other characters are -literal. The formal constructs used are typical: @code{<...>} -indicates a metavariable name, @samp{=} means definition, @samp{*} -repetition, @samp{?} optional, @samp{()} grouping, @samp{|} -alternation, @samp{#} comment. Exception: @samp{*} at the beginning -of a line is literal. - -We specify literal parentheses (those that are part of the Info -format) with @t{<lparen>} and @t{<rparen>}, meaning the single -characters @samp{(} and @samp{)} respectively. - -Finally, the two-character sequence @samp{^@var{x}} means the single -character @samp{CTRL-@var{x}}, for any @var{x}. - -@menu -* General: Info Format General Layout. -* Text: Info Format Text Constructs. -@end menu - - -@node Info Format General Layout -@section Info Format General Layout - -This section describes the overall layout of Info manuals. - -@menu -* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals. -* Preamble: Info Format Preamble. -* Indirect: Info Format Indirect Tag Table. -* Tag table: Info Format Tag Table. -* Local variables: Info Format Local Variables. -* Regular nodes: Info Format Regular Nodes. -@end menu - - -@node Info Format Whole Manual -@subheading Info Format: A Whole Manual - -@cindex Nonsplit manuals, Info format of -@cindex Split manuals, Info format of -@cindex Whole manual, in Info format - -To begin, an Info manual is either @dfn{nonsplit} (contained wholly -within a single file) or @dfn{split} (across several files). - -The syntax for a nonsplit manual is: - -@example - <nonsplit info file> = -<preamble> -<node>* -<tag table> -(<local variables>)? -@end example - -When split, there is a @dfn{main file}, which contains only pointers -to the nodes given in other @dfn{subfiles}. The main file looks -like this: - -@example - <split info main file> = -<preamble> -<indirect table> -<tag table> -(<local variables>)? -@end example - -The subfiles in a split manual have the following syntax: - -@example - <split info subfile> = -<preamble> -<node>* -@end example - - -@node Info Format Preamble -@subheading Info Format: Preamble - -@cindex Preamble, in Info format - -The @t{<preamble>} is text at the beginning of all output files. -It is not intended to be visible by default in an Info viewer, but -may be displayed upon user request. - -@example - <preamble> = -<identification> # "This is FILENAME, produced by ..." -<copying text> # Expansion of @@copying text. -<dir entries> # Derived from @@dircategory and @@direntry. -@end example - -These pieces are: - -@table @t -@item <identification line> -An arbitrary string beginning the output file, followed by a blank -line. - -@item <copying text> -The expansion of an @code{@@copying} environment, if the manual has -one (@pxref{@t{@@copying}}). - -@item <dir entries> -The result of any @code{@@dircategory} and @code{@@direntry} -commands present in the manual (@pxref{Installing Dir Entries}). - -@end table - - -@node Info Format Indirect Tag Table -@subheading Info Format: Indirect Tag Table - -@cindex Indirect tag table, in Info format - -The indirect table is written to the main file in the case of split -output only. It specifies the starting byte position of each split -output file (as a decimal integer): - -@example - <indirect table> = -^_ -Indirect: -(<filename>: <bytepos>)* -@end example - -The number of preamble bytes written to each output file is included -in the positions. Neither the preamble nor the size of the top-level -output file is included. - -The first actual node of content will be pointed to by the first -entry. - -Unfortunately, Info-creating programs such as @code{makeinfo} have not -always implemented these rules perfectly, due to various bugs and -oversights. Therefore, robust Info viewers should fall back to -searching ``nearby'' the given position for a node, instead of just -giving up if the position is not perfectly at a node beginning. - -As an example, suppose split output is generated for the GDB manual. -The top-level file @file{gdb.info} will contain something like this: - -@example -^_ -Indirect: -gdb.info-1: 1878 -gdb.info-2: 295733 -... -@end example - -This tells Info viewers that the first node of the manual occurs at -byte 1878 (i.e., after the preamble) of the file @file{gdb.info-1}. -The first node written to @file{gdb.info-2} would start at byte 295733 -if the subsequent @file{gdb.info-*} files (not including -@file{gdb.info} files were appended to @file{gdb.info-1}, including -their preambles. - - -@node Info Format Tag Table -@subheading Info Format: Tag Table - -@cindex Tag table, in Info format - -The tag table specifies the starting byte position of each node and anchor -in the file. It is written in the main output file only, not (in the -case of split output) any subfiles. - -@example - <tag table> = -^_ -Tag Table: -<lparen>Indirect<rparen> # this line appears in split output only -(Node|Ref): <nodeid>^?<bytepos> -^_ -End Tag Table -@end example - -The @samp{(Indirect)} line is the next line after @samp{Tag Table:} -in the case of split output only. - -Each following line defines an identifier as either an anchor or a -node, as specific. It is an error to define the same identifier both -ways. For example, @samp{Node: Top^?1647} says that the node named -@samp{Top} starts at byte 1647 while @samp{Ref: -Overview-Footnote-1^?30045} says that the anchor named -@samp{Overview-Footnote-1} starts at byte 30045. - -In the case of nonsplit output, the byte positions simply refer to the -location in the output file. In the case of split output, the byte -positions refer to an imaginary file created by concatenating all the -split files (but not the top-level file). See the previous section. - -Here is an example: - -@example -^_ -Tag Table: -Node: Top^_89 -Node: Ch1^_292 -^_ -End Tag Table -@end example - -This specifies a manual with two nodes, `Top' and `Ch1', at byte -positions 89 and 292 respectively. Because the @samp{(Indirect)} line -is not present, the manual is not split. - - -@node Info Format Local Variables -@subheading Info Format: Local Variables - -@cindex Local variable section, in Info format - -The local variables section is optional and is currently used to give the -encoding information. It may be augmented in the future. - -@example - <local variables> = -^_ -Local Variables: -coding: <encoding> -End: -@end example - -@xref{@t{@@documentencoding}}. - - -@node Info Format Regular Nodes -@subheading Info Format: Regular Nodes - -@cindex Info nodes, in Info format - -Regular nodes look like this: - -@example - <node> = -^_ -File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4> - -<general text, until the next ^_ or end-of-file> -@end example - -The @code{Next} and @code{Prev} pointers are optional. The @code{Up} -pointer may technically also be absent, although this is most likely the -case of a wrongly-structured Info manual. At least one space must be -present after each colon and comma, but any number of spaces are -ignored. - -This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically -just @samp{manualname} or perhaps @samp{manualname.info}. Each of the -other references @t{<id2>}, @t{<id3>}, and @t{<id4>} must be defined -with either @samp{Node} or @samp{Ref} in the @t{<tag table>}. - -Conventionally the nodes are arranged to form a tree, but this is not -a requirement of the format. Each pointer can refer to any defined -identifier. - -Identifiers cannot include periods, commas, colons or parentheses -(including @@-commands which produce any of these); these can confuse -Info readers. @xref{Node Line Requirements}. - -The @t{<general text>} of the node can include the special constructs -described next. - - -@node Info Format Text Constructs -@section Info Format Text Constructs - -@cindex Info format text constructs -@cindex text constructs, Info format - -These special Info constructs can appear within the text of a node. - -@menu -* Menu: Info Format Menu. -* Image: Info Format Image. -* Printindex: Info Format Printindex. -* Xref: Info Format Cross Reference. -@end menu - - -@node Info Format Menu -@subsection Info Format: Menu - -@cindex Menus, in Info format - -Conventionally menus appear at the end of nodes, but the Info format -places no restrictions on their location. - -@example - <menu> = -* Menu: -(<menu entry> | <menu comment>)* -@end example - -The parts of a @t{<menu entry>} are described in @ref{Menu Parts}. - -A @t{<menu comment>} is any line not beginning with @samp{*} that -appears either at the beginning of the menu or is separated from a -menu entry by one or more blank lines. These comments are intended to -be displayed as part of the menu, as-is (@pxref{Writing a Menu}). - - -@node Info Format Image -@subsection Info Format: Image - -@cindex Images, in Info format - -The @code{@@image} command results in the following special directive -within the Info file (@pxref{Images}): - -@example - <image> = -^@@^H[image src="<image file>" - (text="<txt file contents>")? - (alt="<alt text>")? -^@@^H] -@end example - -The line breaks and indentation in this description are editorial; the -whitespace between the different parts of the directive in Info files -is arbitrary. - -In the string @t{<image file>}, @t{<txt file contents>} and @t{<alt -text>}, @samp{"} is quoted as @samp{\"} and @samp{\} is quoted as -@samp{\\}. The text and alt specifications are optional. - -The @t{alt} value serves the same purpose as in HTML: A prose -description of the image. In text-only displays or speech systems, -for example, the @t{alt} value may be used instead of displaying the -(typically graphical) @t{<image file>}. - -The @t{<txt file contents>}, if present, should be taken as an ASCII -representation of the image, and also may be used on a text-only -display. - -The format does not prescribe the choice between displaying the -@t{<image file>}, the @t{<alt text>} or @t{<txt file contents>}. - - -@node Info Format Printindex -@subsection Info Format: Printindex - -@cindex Indices, in Info format - -Indices in Info format are generally written as a menu -(@pxref{Indices}), but with an additional directive at the beginning -marking this as an index node: - -@example - <printindex> = -^@@^H[index^@@^H] -* Menu: - -<index entry>* -@end example - -The @t{<index entry>} items are similar to normal menu entries, but -the free-format description is replaced by the line number of where -the entries occurs in the text: - -@example - <index entry> = -* <entry text>: <entry node>. <lparen>line <lineno><rparen> -@end example - -@noindent -The @t{<entry text>} is the index term. The @t{<lineno>} is an -unsigned integer, given relative to the start of the @t{<entry node>}. -There may be arbitrary whitespace after the colon and period, as usual -in menus. Here is an example: - -@example -^@@^H[index^@@^H] -* Menu: - -* thunder: Weather Phenomena. (line 5) -@end example - -This means that an index entry for `thunder' appears at line 5 of the -node `Weather Phenomena'. - - -@node Info Format Cross Reference -@subsection Info Format: Cross Reference - -@cindex Cross references, in Info format - -A general cross reference in Info format is written as follows: - -@example - <cross-reference> = -* (N|n)ote (<id>:: | <label>:(<lparen><infofile><rparen>)?<id>(.|,)) -@end example - -Whether @samp{note} or @samp{Note} is used is not significant. - -The @samp{<id>::} form indicates a node or anchor reference within the -current manual. - -The longer form indicates a general reference, typically used to refer -to a node or anchor in a different manual, but possibly to the current -manual. The @t{<label>} is descriptive text; the optional -@samp{(<infofile>)} is the filename of the manual being referenced, -and the @t{<id>} is the node or anchor within that manual, terminated -by a comma or period. That final punctuation is part of the -surrounding sentence, and should be displayed. - -Here are some examples: - -@example -*note GNU Free Documentation License:: -*note Tag table: Info Format Tag Table, for details. -*Note Overview: (make)Top. -@end example - -The first shows the short form, a reference to a node in the current -manual. - -The second also refers to a node in the current manual, namely `Info -Format Tag Table'; the `Tag table' before the @samp{:} is only a label -on this particular reference. - -The third example refers to the node `Top' in another manual, namely -@samp{make}, with `Overview' being the label for this cross reference. - -@xref{Cross References}. - - -@c The simple description in the command summary seems sufficient to me -@c these days, so ignore this appendix. --karl, 13mar04. -@c -@c @node Refilling Paragraphs -@c @appendix Refilling Paragraphs -@c @cindex Refilling paragraphs -@c @cindex Filling paragraphs -@c @cindex Paragraphs, filling -@c @findex refill -@c -@c The @code{@@refill} command refills and, optionally, indents the first -@c line of a paragraph.@footnote{Perhaps the command should have been -@c called the @code{@@refillandindent} command, but @code{@@refill} is -@c shorter and the name was chosen before indenting was possible.} The -@c @code{@@refill} command is no longer important, but we describe it here -@c because you once needed it. You will see it in many old Texinfo -@c files. -@c -@c Without refilling, paragraphs containing long @@-constructs may look -@c bad after formatting because the formatter removes @@-commands and -@c shortens some lines more than others. In the past, neither the -@c @code{texinfo-format-region} command nor the -@c @code{texinfo-format-buffer} command refilled paragraphs -@c automatically. The @code{@@refill} command had to be written at the -@c end of every paragraph to cause these formatters to fill them. (Both -@c @TeX{} and @code{makeinfo} have always refilled paragraphs -@c automatically.) Now, all the Info formatters automatically fill and -@c indent those paragraphs that need to be filled and indented. -@c -@c The @code{@@refill} command causes @code{texinfo-format-region} and -@c @code{texinfo-format-buffer} to refill a paragraph in the Info file -@c @emph{after} all the other processing has been done. For this reason, -@c you can not use @code{@@refill} with a paragraph containing either -@c @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will -@c override those two commands. -@c -@c The @code{texinfo-format-region} and @code{texinfo-format-buffer} -@c commands now automatically append @code{@@refill} to the end of each -@c paragraph that should be filled. They do not append @code{@@refill} to -@c the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} -@c and therefore do not refill or indent them. - - -@c These are no longer ``new'', and the explanations -@c are all given elsewhere anyway. So ignore the entire appendix. -@c --karl, 25apr97. -@c node New Features, Command and Variable Index, Obtaining TeX, Top -@c appendix Second Edition Features - -@c @tex -@c % Widen the space for the first column so three control-character % -@c strings fit in the first column. Switched back to default .8in % -@c value at end of chapter. \global\tableindent=1.0in -@c @end tex -@c -@c The second edition of the Texinfo manual describes more than 20 new -@c Texinfo mode commands and more than 50 previously undocumented Texinfo -@c @@-commands. This edition is more than twice the length of the first -@c edition. -@c -@c Here is a brief description of the new commands. -@c -@c @c menu -@c * New Texinfo Mode Commands:: The updating commands are especially useful. -@c * New Commands:: Many newly described @@-commands. -@c @c end menu -@c -@c @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX -@c @c appendixsec New Texinfo Mode Commands -@c -@c Texinfo mode provides commands and features especially designed for -@c working with Texinfo files. More than 20 new commands have been -@c added, including commands for automatically creating and updating -@c both nodes and menus. This is a tedious task when done by hand. -@c -@c The keybindings are intended to be somewhat mnemonic. -@c -@c @c subheading Update all nodes and menus -@c -@c The @code{texinfo-master-menu} command is the primary command: -@c -@c @table @kbd -@c @item C-c C-u m -@c @itemx M-x texinfo-master-menu -@c Create or update a master menu. -@c With @kbd{C-u} as a prefix argument, -@c first create or update all nodes -@c and regular menus. -@c @end table -@c -@c @c subheading Update Pointers -@c -@c @noindent -@c Create or update `Next', `Previous', and `Up' node pointers. -@c -@c @noindent -@c @xref{Updating Nodes and Menus}. -@c -@c @table @kbd -@c @item C-c C-u C-n -@c @itemx M-x texinfo-update-node -@c Update a node. -@c -@c @item C-c C-u C-e -@c @itemx M-x texinfo-every-node-update -@c Update every node in the buffer. -@c @end table -@c -@c @c subheading Update Menus -@c -@c @noindent -@c Create or update menus. -@c -@c @noindent -@c @xref{Updating Nodes and Menus}. -@c -@c @table @kbd -@c @item C-c C-u C-m -@c @itemx M-x texinfo-make-menu -@c Make or update a menu. -@c -@c @item C-c C-u C-a -@c @itemx M-x texinfo-all-menus-update -@c Make or update all the menus in a buffer. -@c With @kbd{C-u} as a prefix argument, -@c first update all the nodes. -@c @end table -@c -@c @c subheading Insert Title as Description -@c -@c @noindent -@c Insert a node's chapter or section title in the space for the -@c description in a menu entry line; position point so you can edit the -@c insert. (This command works somewhat differently than the other -@c insertion commands, which insert only a predefined string.) -@c -@c @noindent -@c @xref{Inserting, Inserting Frequently Used Commands}. -@c -@c @table @kbd -@c @item C-c C-c C-d -@c Insert title. -@c @end table -@c -@c @c subheading Format for Info -@c -@c @noindent -@c Provide keybindings both for the Info formatting commands that are -@c written in Emacs Lisp and for @code{makeinfo} that is written in -@c C. -@c -@c @noindent -@c @xref{Info Formatting}. -@c -@c @noindent -@c Use the Emacs lisp @code{texinfo-format@dots{}} commands: -@c -@c @table @kbd -@c @item C-c C-e C-r -@c Format the region. -@c -@c @item C-c C-e C-b -@c Format the buffer. -@c @end table -@c -@c @noindent -@c Use @code{makeinfo}: -@c -@c @table @kbd -@c @item C-c C-m C-r -@c Format the region. -@c -@c @item C-c C-m C-b -@c Format the buffer. -@c -@c @item C-c C-m C-l -@c Recenter the @code{makeinfo} output buffer. -@c -@c @item C-c C-m C-k -@c Kill the @code{makeinfo} formatting job. -@c @end table -@c -@c @c subheading Typeset and Print -@c -@c @noindent -@c Typeset and print Texinfo documents from within XEmacs. -@c -@c @noindent -@c @xref{Printing}. -@c -@c @table @kbd -@c @item C-c C-t C-b -@c Run @code{texi2dvi} on the buffer. -@c -@c @item C-c C-t C-r -@c Run @TeX{} on the region. -@c -@c @item C-c C-t C-i -@c Run @code{texindex}. -@c -@c @item C-c C-t C-p -@c Print the DVI file. -@c -@c @item C-c C-t C-q -@c Show the print queue. -@c -@c @item C-c C-t C-d -@c Delete a job from the print queue. -@c -@c @item C-c C-t C-k -@c Kill the current @TeX{} formatting job. -@c -@c @item C-c C-t C-x -@c Quit a currently stopped @TeX{} formatting job. -@c -@c @item C-c C-t C-l -@c Recenter the output buffer. -@c @end table -@c -@c @c subheading Other Updating Commands -@c -@c @noindent -@c The ``other updating commands'' do not have standard keybindings because -@c they are used less frequently. -@c -@c @noindent -@c @xref{Other Updating Commands}. -@c -@c @table @kbd -@c @item M-x texinfo-insert-node-lines -@c Insert missing @code{@@node} lines using -@c section titles as node names. -@c -@c @item M-x texinfo-multiple-files-update -@c Update a multi-file document. -@c With a numeric prefix, such as @kbd{C-u 8}, -@c update @strong{every} pointer and -@c menu in @strong{all} the files and -@c then insert a master menu. -@c -@c @item M-x texinfo-indent-menu-description -@c Indent descriptions in menus. -@c -@c @item M-x texinfo-sequential-node-update -@c Insert node pointers in strict sequence. -@c @end table -@c -@c @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX -@c @c appendix.sec New Texinfo @@-Commands -@c -@c The second edition of the Texinfo manual describes more than 50 -@c commands that were not described in the first edition. A third or so -@c of these commands existed in Texinfo but were not documented in the -@c manual; the others are new. Here is a listing, with brief -@c descriptions of them: -@c -@c @c subheading Indexing -@c -@c @noindent -@c Create your own index, and merge indices. -@c -@c @noindent -@c @xref{Indices}. -@c -@c @table @kbd -@c @item @@defindex @var{index-name} -@c Define a new index and its indexing command. -@c See also the @code{@@defcodeindex} command. -@c -@c @c written verbosely to avoid overfull hbox -@c @item @@synindex @var{from-index} @var{into-index} -@c Merge the @var{from-index} index into the @var{into-index} index. -@c See also the @code{@@syncodeindex} command. -@c @end table -@c -@c @c subheading Definitions -@c -@c @noindent -@c Describe functions, variables, macros, -@c commands, user options, special forms, and other such artifacts in a -@c uniform format. -@c -@c @noindent -@c @xref{Definition Commands}. -@c -@c @table @kbd -@c @item @@deffn @var{category} @var{name} @var{arguments}@dots{} -@c Format a description for functions, interactive -@c commands, and similar entities. -@c -@c @item @@defvr, @@defop, @dots{} -@c 15 other related commands. -@c @end table -@c -@c @c subheading Glyphs -@c -@c @noindent -@c Indicate the results of evaluation, expansion, -@c printed output, an error message, equivalence of expressions, and the -@c location of point. -@c -@c @noindent -@c @xref{Glyphs}. -@c -@c @table @kbd -@c @item @@equiv@{@} -@c @itemx @equiv{} -@c Equivalence: -@c -@c @item @@error@{@} -@c @itemx @error{} -@c Error message -@c -@c @item @@expansion@{@} -@c @itemx @expansion{} -@c Macro expansion -@c -@c @item @@point@{@} -@c @itemx @point{} -@c Position of point -@c -@c @item @@print@{@} -@c @itemx @print{} -@c Printed output -@c -@c @item @@result@{@} -@c @itemx @result{} -@c Result of an expression -@c @end table -@c -@c @c subheading Page Headings -@c -@c @noindent -@c Customize page headings. -@c -@c @noindent -@c @xref{Headings}. -@c -@c @table @kbd -@c @item @@headings @var{on-off-single-double} -@c Headings on or off, single, or double-sided. -@c -@c @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@c Footings for even-numbered (left-hand) pages. -@c -@c @item @@evenheading, @@everyheading, @@oddheading, @dots{} -@c Five other related commands. -@c -@c @item @@thischapter -@c Insert name of chapter and chapter number. -@c -@c @item @@thischaptername, @@thisfile, @@thistitle, @@thispage -@c Related commands. -@c @end table -@c -@c @c subheading Formatting -@c -@c @noindent -@c Format blocks of text. -@c -@c @noindent -@c @xref{Quotations and Examples}, and@* -@c @ref{Lists and Tables, , Making Lists and Tables}. -@c -@c @table @kbd -@c @item @@cartouche -@c Draw rounded box surrounding text (no effect in Info). -@c -@c @item @@enumerate @var{optional-arg} -@c Enumerate a list with letters or numbers. -@c -@c @item @@exdent @var{line-of-text} -@c Remove indentation. -@c -@c @item @@flushleft -@c Left justify. -@c -@c @item @@flushright -@c Right justify. -@c -@c @item @@format -@c Do not narrow nor change font. -@c -@c @item @@ftable @var{formatting-command} -@c @itemx @@vtable @var{formatting-command} -@c Two-column table with indexing. -@c -@c @item @@lisp -@c For an example of Lisp code. -@c -@c @item @@smallexample -@c @itemx @@smalllisp -@c Like @@table and @@lisp, but for (originally) @@smallbook. -@c @end table -@c -@c @c subheading Conditionals -@c -@c @noindent -@c Conditionally format text. -@c -@c @noindent -@c @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. -@c -@c @table @kbd -@c @item @@set @var{flag} [@var{string}] -@c Set a flag. Optionally, set value -@c of @var{flag} to @var{string}. -@c -@c @item @@clear @var{flag} -@c Clear a flag. -@c -@c @item @@value@{@var{flag}@} -@c Replace with value to which @var{flag} is set. -@c -@c @item @@ifset @var{flag} -@c Format, if @var{flag} is set. -@c -@c @item @@ifclear @var{flag} -@c Ignore, if @var{flag} is set. -@c @end table -@c -@c @c subheading @@heading series for Titles -@c -@c @noindent -@c Produce unnumbered headings that do not appear in a table of contents. -@c -@c @noindent -@c @xref{Structuring}. -@c -@c @table @kbd -@c @item @@heading @var{title} -@c Unnumbered section-like heading not listed -@c in the table of contents of a printed manual. -@c -@c @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading -@c Related commands. -@c @end table -@c -@c @need 1000 -@c @c subheading Font commands -@c -@c @need 1000 -@c @noindent -@c @xref{Smallcaps}, and @* -@c @ref{Fonts}. -@c -@c @table @kbd -@c @item @@r@{@var{text}@} -@c Print in roman font. -@c -@c @item @@sc@{@var{text}@} -@c Print in @sc{small caps} font. -@c @end table -@c -@c @c subheading Miscellaneous -@c -@c @noindent -@c See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* -@c see @ref{Customized Highlighting},@* -@c see @ref{Overfull hboxes},@* -@c see @ref{Footnotes},@* -@c see @ref{dmn, , Format a Dimension},@* -@c see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* -@c see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* -@c see @ref{minus, , Inserting a Minus Sign},@* -@c see @ref{paragraphindent, , Paragraph Indenting},@* -@c see @ref{Cross Reference Commands},@* -@c see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* -@c see @ref{Custom Headings, , How to Make Your Own Headings}. -@c -@c @table @kbd -@c @item @@author @var{author} -@c Typeset author's name. -@c -@c @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -@c @c Define a highlighting command for Info. (Info only.) -@c -@c @item @@finalout -@c Produce cleaner printed output. -@c -@c @item @@footnotestyle @var{end-or-separate} -@c Specify footnote style, either @samp{end} or @samp{separate}. -@c @xref{Footnote Styles}. -@c -@c @item @@dmn@{@var{dimension}@} -@c Format a dimension. -@c -@c @item @@global@@let@var{new-cmd}=@var{existing-cmd} -@c Define a highlighting command for @TeX{}. (@TeX{} only.) -@c -@c @item @@lowersections -@c Reduce hierarchical level of sectioning commands. -@c -@c @item @@math@{@var{mathematical-expression}@} -@c Format a mathematical expression. -@c -@c @item @@minus@{@} -@c Generate a minus sign. -@c -@c @item @@paragraphindent @var{asis-or-number} -@c Specify amount of paragraph indentation. -@c -@c @item @@raisesections -@c Raise hierarchical level of sectioning commands. -@c -@c @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} -@c Make a reference. In the printed manual, the -@c reference does not start with the word `see'. -@c -@c @item @@title @var{title} -@c Typeset @var{title} in the alternative -@c title page format. -@c -@c @item @@subtitle @var{subtitle} -@c Typeset @var{subtitle} in the alternative -@c title page format. -@c -@c @item @@today@{@} -@c Insert the current date. -@c @end table -@c @tex -@c % Switch width of first column of tables back to default value -@c \global\tableindent=.8in -@c @end tex - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include fdl.texi - - -@node Command and Variable Index -@unnumbered Command and Variable Index - -This is an alphabetical list of all the @@-commands, assorted XEmacs Lisp -functions, and several variables. To make the list easier to use, the -commands are listed without their preceding @samp{@@}. - -@printindex fn - - -@node General Index -@unnumbered General Index - -@printindex cp - - -@bye
--- a/man/texinfo/version.texi Fri Apr 25 23:38:16 2014 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ -@c Synced up with: Texinfo 5.2 of 26 Sep 2013. -@c Synced by: Jerry James, 11 Feb 2014. -@set UPDATED 26 September 2013 -@set UPDATED-MONTH September 2013 -@set EDITION 5.2 -@set VERSION 5.2