| This is texinfo.info, produced by texi2any version 6.1 from |
| texinfo.texi. |
| |
| This manual is for GNU Texinfo (version 6.1, 6 February 2016), a |
| documentation system that can produce both online information and a |
| printed manual from a single source using semantic markup. |
| |
| Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, |
| 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, |
| 2012, 2013, 2014, 2015, 2016 Free Software Foundation, Inc. |
| |
| 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." |
| INFO-DIR-SECTION Texinfo documentation system |
| START-INFO-DIR-ENTRY |
| * 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-INFO-DIR-ENTRY |
| |
| |
| File: texinfo.info, Node: Top, Next: Copying Conditions, Up: (dir) |
| |
| Texinfo |
| ******* |
| |
| This manual is for GNU Texinfo (version 6.1, 6 February 2016), 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. |
| |
| * Menu: |
| |
| * Copying Conditions:: Your rights. |
| * Overview:: Texinfo in brief. |
| * Writing a Texinfo File:: Format of a Texinfo source file. |
| * Beginning and Ending a File:: Beginning and end of a Texinfo file. |
| * Nodes:: Writing nodes, the basic unit of Texinfo. |
| * Chapter Structuring:: Creating chapters, sections, appendices, etc. |
| * 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 texi2any:: 'texi2any', an all-purpose converter. |
| * Creating and Installing Info Files:: Details on Info output. |
| * Generating HTML:: Details on HTML output. |
| |
| Appendices |
| |
| * @-Command Details:: Details of the Texinfo @-commands. |
| * Tips:: Hints on how to write a Texinfo document. |
| * Sample Texinfo Files:: Complete examples, including full texts. |
| * Texinfo Mode:: Using the GNU Emacs Texinfo mode. |
| * 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. |
| |
| -- The Detailed Node Listing -- |
| |
| Overview of Texinfo |
| |
| * Reporting Bugs:: Submitting effective bug reports. |
| * Output Formats:: Overview of the supported output formats. |
| * Info Files:: What is an Info file? |
| * Printed Books:: Characteristics of a printed book or manual. |
| * Adding Output Formats:: Man pages and implementing new formats. |
| * History:: Acknowledgements, contributors and genesis. |
| |
| Writing a Texinfo File |
| |
| * Command Syntax:: @-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. |
| * Short Sample:: A short sample Texinfo file. |
| |
| Beginning and Ending 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. |
| * Ending a File:: What is at the end of a Texinfo file? |
| |
| Texinfo File Header |
| |
| * First Line:: The first line of a Texinfo file. |
| * Start of Header:: Formatting a region requires this. |
| * @setfilename:: Tell Info the name of the Info file. |
| * @settitle:: Create a title for the printed work. |
| * End of Header:: Formatting a region requires this. |
| |
| Document Permissions |
| |
| * @copying:: Declare the document's copying permissions. |
| * @insertcopying:: Where to insert the permissions. |
| |
| Title and Copyright Pages |
| |
| * @titlepage:: Create a title for the printed document. |
| * @titlefont @center @sp:: The '@titlefont', '@center', |
| and '@sp' commands. |
| * @title @subtitle @author:: The '@title', '@subtitle', |
| and '@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 |
| |
| * @documentdescription:: Document summary for the HTML output. |
| * @setchapternewpage:: Start chapters on right-hand pages. |
| * @headings:: An option for turning headings on and off |
| and double or single sided printing. |
| * @paragraphindent:: Specify paragraph indentation. |
| * @firstparagraphindent:: Suppressing first paragraph indentation. |
| * @exampleindent:: Specify environment indentation. |
| |
| Nodes |
| |
| * Texinfo Document Structure:: How Texinfo manuals are usually arranged. |
| * Node Names:: How to choose node names. |
| * Writing a Node:: How to write an '@node' line. |
| * Node Line Requirements:: Keep names unique. |
| * First Node:: How to write a 'Top' node. |
| * @top Command:: How to use the '@top' command. |
| * Node Menu Illustration:: A diagram, and sample nodes and menus. |
| * makeinfo Pointer Creation:: Letting makeinfo determine node pointers. |
| * Menus:: Listing subordinate nodes. |
| |
| Menus |
| |
| * Writing a Menu:: What is a menu? |
| * Menu Example:: Two and three part menu entries. |
| * Menu Location:: Menus go at the ends of nodes. |
| * Menu Parts:: A menu entry has three parts. |
| * Less Cluttered Menu Entry:: Two part menu entry. |
| * Other Info Files:: How to refer to a different Info file. |
| |
| Chapter Structuring |
| |
| * Tree Structuring:: A manual is like an upside down tree ... |
| * Structuring Command Types:: How to divide a manual into parts. |
| * @chapter:: Chapter structuring. |
| * @unnumbered @appendix:: |
| * @majorheading @chapheading:: |
| * @section:: |
| * @unnumberedsec @appendixsec @heading:: |
| * @subsection:: |
| * @unnumberedsubsec @appendixsubsec @subheading:: |
| * @subsubsection:: Commands for the lowest level sections. |
| * @part:: Collections of chapters. |
| * Raise/lower sections:: How to change commands' hierarchical level. |
| |
| Cross-references |
| |
| * References:: What cross-references are for. |
| * Cross Reference Commands:: A summary of the different commands. |
| * Cross Reference Parts:: A cross-reference has several parts. |
| * @xref:: Begin a reference with 'See' ... |
| * Referring to a Manual as a Whole:: Refer to an entire manual. |
| * @ref:: A reference for the last part of a sentence. |
| * @pxref:: How to write a parenthetical cross-reference. |
| * @anchor:: Defining arbitrary cross-reference targets |
| * @inforef:: How to refer to an Info-only file. |
| * @url:: How to refer to a uniform resource locator. |
| * @cite:: How to refer to books not in the Info system. |
| |
| '@xref' |
| |
| * One Argument:: '@xref' with one argument. |
| * Two Arguments:: '@xref' with two arguments. |
| * Three Arguments:: '@xref' with three arguments. |
| * Four and Five Arguments:: '@xref' with four and five arguments. |
| |
| '@url', '@uref{URL[, TEXT][, REPLACEMENT]}' |
| |
| * @url Examples:: Examples of using all the forms of '@url'. |
| * URL Line Breaking:: How lines are broken within '@url' text. |
| * @url PDF Output Format:: A special option to hide links in PDF output. |
| * PDF Colors:: Colorizing urls and other links in PDF output. |
| |
| 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. |
| * @code:: Indicating program code. |
| * @kbd:: Showing keyboard input. |
| * @key:: Specifying keys. |
| * @samp:: Indicating a literal sequence of characters. |
| * @verb:: Indicating a verbatim sequence of characters. |
| * @var:: Indicating metasyntactic variables. |
| * @env:: Indicating environment variables. |
| * @file:: Indicating file names. |
| * @command:: Indicating command names. |
| * @option:: Indicating option names. |
| * @dfn:: Specifying definitions. |
| * @abbr:: Indicating abbreviations. |
| * @acronym:: Indicating acronyms. |
| * @indicateurl:: Indicating an example url. |
| * @email:: Indicating an electronic mail address. |
| |
| Emphasizing Text |
| |
| * @emph @strong:: How to emphasize text in Texinfo. |
| * Smallcaps:: How to use the small caps font. |
| * Fonts:: Various font commands for printed output. |
| |
| Quotations and Examples |
| |
| * Block Enclosing Commands:: Different constructs for different purposes. |
| * @quotation:: Writing a quotation. |
| * @indentedblock:: Block of text indented on left. |
| * @example:: Writing an example in a fixed-width font. |
| * @verbatim:: Writing a verbatim example. |
| * @verbatiminclude:: Including a file verbatim. |
| * @lisp:: Illustrating Lisp code. |
| * @small...:: Examples in a smaller font. |
| * @display:: Writing an example in the current font. |
| * @format:: Writing an example without narrowed margins. |
| * @exdent:: Undo indentation on a line. |
| * @flushleft @flushright:: Pushing text flush left or flush right. |
| * @raggedright:: Avoiding justification on the right. |
| * @noindent:: Preventing paragraph indentation. |
| * @indent:: Forcing paragraph indentation. |
| * @cartouche:: Drawing rounded rectangles around text. |
| |
| Lists and Tables |
| |
| * Introducing Lists:: Texinfo formats lists for you. |
| * @itemize:: How to construct a simple list. |
| * @enumerate:: How to construct a numbered list. |
| * Two-column Tables:: How to construct a two-column table. |
| * Multi-column Tables:: How to construct generalized tables. |
| |
| Making a Two-column Table |
| |
| * @table:: How to construct a two-column table. |
| * @ftable @vtable:: Automatic indexing for two-column tables. |
| * @itemx:: How to put more entries in the first column. |
| |
| '@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 |
| |
| * @float:: Producing floating material. |
| * @caption @shortcaption:: Specifying descriptions for floats. |
| * @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. |
| * Printing Indices & Menus:: How to print an index in hardcopy and |
| generate index menus in Info. |
| * Combining Indices:: How to combine indices. |
| * New Indices:: How to define your own indices. |
| |
| Combining Indices |
| |
| * @syncodeindex:: How to merge two indices, using '@code' |
| font for the merged-from index. |
| * @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 Subscripts and Superscripts:: Inserting sub/superscripts. |
| * 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. |
| * Inserting Unicode:: Inserting a Unicode character by code point. |
| |
| Special Characters: Inserting @ {} , \ # |
| |
| * Inserting an Atsign:: '@@', '@atchar{}'. |
| * Inserting Braces:: '@{ @}', '@l rbracechar{}'. |
| * Inserting a Comma:: , and '@comma{}'. |
| * Inserting a Backslash:: \ and '@backslashchar{}'. |
| * Inserting a Hashsign:: # and '@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. |
| * @frenchspacing:: Specifying end-of-sentence spacing. |
| * @dmn:: Formatting a dimension. |
| |
| Glyphs for Text |
| |
| * @TeX @LaTeX:: The TeX logos. |
| * @copyright:: The copyright symbol (c in a circle). |
| * @registeredsymbol:: The registered symbol (R in a circle). |
| * @dots:: How to insert ellipses: ... and ... |
| * @bullet:: How to insert a bullet: * |
| * @euro:: How to insert the euro currency symbol. |
| * @pounds:: How to insert the pounds currency symbol. |
| * @textdegree:: How to insert the degrees symbol. |
| * @minus:: How to insert a minus sign. |
| * @geq @leq:: How to insert greater/less-than-or-equal signs. |
| |
| Glyphs for Programming |
| |
| * Glyphs Summary:: |
| * @result:: How to show the result of expression. |
| * @expansion:: How to indicate an expansion. |
| * @print:: How to indicate generated output. |
| * @error:: How to indicate an error message. |
| * @equiv:: How to indicate equivalence. |
| * @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. |
| * @- @hyphenation:: Helping TeX with hyphenation points. |
| * @allowcodebreaks:: Controlling line breaks within @code text. |
| * @w:: Preventing unwanted line breaks in text. |
| * @tie:: Inserting an unbreakable but varying space. |
| * @sp:: Inserting blank lines. |
| * @page:: Forcing the start of a new page. |
| * @group:: Preventing unwanted page breaks. |
| * @need:: Another way to prevent unwanted page breaks. |
| |
| Definition Commands |
| |
| * Def Cmd Template:: Writing descriptions using definition commands. |
| * Def Cmd Continuation Lines:: Continuing the heading over source lines. |
| * Optional Arguments:: Handling optional and repeated arguments. |
| * @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 |
| |
| * @documentlanguage:: Declaring the current language. |
| * @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. |
| * @set @clear @value:: Variable tests and substitutions. |
| * Testing for Texinfo Commands:: Testing if a Texinfo command is available. |
| * Conditional Nesting:: Using conditionals inside conditionals. |
| |
| Flags: '@set', '@clear', conditionals, and '@value' |
| |
| * @set @value:: Expand a flag variable to a string. |
| * @ifset @ifclear:: Format a region if a flag is set. |
| * @inlineifset @inlineifclear:: Brace-delimited flag conditionals. |
| * @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. |
| * @alias:: Command aliases. |
| * @definfoenclose:: Customized highlighting. |
| * External Macro Processors:: '#line' directives. |
| |
| External Macro Processors: Line Directives |
| |
| * #line Directive:: |
| * TeX: #line and TeX. |
| * Syntax: #line Syntax Details. |
| |
| Include Files |
| |
| * Using Include Files:: How to use the '@include' command. |
| * texinfo-multiple-files-update:: How to create and update nodes and |
| menus when using included files. |
| * Include Files Requirements:: '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 '@include' command |
| has changed over time. |
| |
| Formatting and Printing Hardcopy |
| |
| * Use TeX:: Use TeX to format for hardcopy. |
| * Format with texi2dvi:: The simplest way to format. |
| * Format with tex/texindex:: Formatting with explicit shell commands. |
| * Print with lpr:: How to print. |
| * Within Emacs:: How to format and print from an Emacs shell. |
| * Texinfo Mode Printing:: How to format and print in Texinfo mode. |
| * Compile-Command:: How to print using Emacs's compile command. |
| * Requirements Summary:: TeX formatting requirements summary. |
| * Preparing for TeX:: What to do before you use TeX. |
| * Overfull hboxes:: What are and what to do with overfull hboxes. |
| * @smallbook:: How to print small format books and manuals. |
| * A4 Paper:: How to print on A4 or A5 paper. |
| * @pagesizes:: How to print with customized page sizes. |
| * Cropmarks and Magnification:: How to print marks to indicate the size |
| of pages and how to print scaled up output. |
| * PDF Output:: Portable Document Format output. |
| * Obtaining TeX:: How to obtain TeX. |
| |
| Format with 'tex'/'texindex' |
| |
| * Formatting Partial Documents:: |
| * Details of texindex:: |
| |
| 'texi2any': The Generic Translator for Texinfo |
| |
| * Reference Implementation:: 'texi2any': the reference implementation. |
| * Invoking texi2any:: Running the translator from a shell. |
| * texi2any Printed Output:: Calling 'texi2dvi'. |
| * Pointer Validation:: How to check that pointers point somewhere. |
| * Customization Variables:: Configuring 'texi2any'. |
| * Internationalization of Document Strings:: Translating program-inserted text. |
| * Invoking pod2texi:: Translating Perl pod to Texinfo. |
| * texi2html:: An ancestor of 'texi2any'. |
| |
| Customization Variables |
| |
| * Commands: Customization Variables for @-Commands. |
| * Options: Customization Variables and Options. |
| * HTML: HTML Customization Variables. |
| * Other: Other Customization Variables. |
| |
| Creating and Installing Info Files |
| |
| * Creating an Info File:: |
| * Installing an Info File:: |
| |
| Creating an Info File |
| |
| * makeinfo Advantages:: 'makeinfo' provides better error checking. |
| * makeinfo in Emacs:: How to run 'makeinfo' from Emacs. |
| * texinfo-format commands:: Two Info formatting commands written |
| in Emacs Lisp are an alternative |
| to 'makeinfo'. |
| * Batch Formatting:: How to format for Info in Emacs batch mode. |
| * Tag and Split Files:: How tagged and split files help Info |
| to run better. |
| |
| Installing an Info File |
| |
| * Directory File:: The top level menu for all Info files. |
| * New Info File:: Listing a new Info file. |
| * Other Info Directories:: How to specify Info files that are |
| located in other directories. |
| * Installing Dir Entries:: How to specify what menu entry to add |
| to the Info directory. |
| * Invoking install-info:: '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. |
| |
| Sample Texinfo Files |
| |
| * Short Sample Texinfo File:: |
| * GNU Sample Texts:: |
| * Verbatim Copying License:: |
| * All-permissive Copying License:: |
| |
| Using Texinfo Mode |
| |
| * Texinfo Mode Overview:: How Texinfo mode can help you. |
| * Emacs Editing:: Texinfo mode adds to GNU Emacs' general |
| purpose editing features. |
| * Inserting:: How to insert frequently used @-commands. |
| * Showing the Structure:: How to show the structure of a file. |
| * Updating Nodes and Menus:: How to update or create new nodes and menus. |
| * Info Formatting:: How to format for Info. |
| * Printing:: How to format and print part or all of a file. |
| * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. |
| |
| Updating Nodes and Menus |
| |
| * Updating Commands:: Five major updating commands. |
| * Updating Requirements:: How to structure a Texinfo file for |
| using the updating command. |
| * Other Updating Commands:: How to indent descriptions, insert |
| missing nodes lines, and update |
| nodes in sequence. |
| |
| 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 |
| |
| * makeinfo Preferred:: 'makeinfo' finds errors. |
| * Debugging with Info:: How to catch errors with Info formatting. |
| * Debugging with TeX:: How to catch errors with TeX formatting. |
| * Using texinfo-show-structure:: How to use 'texinfo-show-structure'. |
| * Using occur:: How to list all lines containing a pattern. |
| * Running Info-validate:: How to find badly referenced nodes. |
| |
| Finding Badly Referenced Nodes |
| |
| * Using Info-validate:: How to run '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 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. |
| |
| |
| 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 |
| |
| |
| File: texinfo.info, Node: Copying Conditions, Next: Overview, Prev: Top, Up: Top |
| |
| Texinfo Copying Conditions |
| ************************** |
| |
| GNU Texinfo is "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 (*note GNU Free Documentation License::). |
| |
| |
| File: texinfo.info, Node: Overview, Next: Writing a Texinfo File, Prev: Copying Conditions, Up: Top |
| |
| 1 Overview of Texinfo |
| ********************* |
| |
| "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 several different documents, one for each output |
| format, you need only write one document. |
| |
| Using Texinfo, you can create a printed document (via the TeX |
| typesetting system) in PDF or PostScript format, including chapters, |
| sections, cross-references, and indices. From the same Texinfo source |
| file, you can create an HTML output file suitable for use with a web |
| browser, you can create an Info file with special features to make |
| browsing documentation easy, and also create a Docbook file or a |
| transliteration to XML format. |
| |
| A Texinfo source file is a plain text file containing text |
| interspersed with "@-commands" (words preceded by an '@') that tell the |
| Texinfo processors what to do. Texinfo's markup commands are almost |
| entirely "semantic"; that is, they specify the intended meaning of text |
| in the document, rather than physical formatting instructions. You can |
| edit a Texinfo file with any text editor, but it is especially |
| convenient to use GNU Emacs since that editor has a special mode, called |
| Texinfo mode, that provides various Texinfo-related features. (*Note |
| Texinfo Mode::.) |
| |
| Texinfo was devised specifically for the purpose of writing software |
| documentation and manuals. If you want to write a good manual for your |
| program, Texinfo has many features which we hope will make your job |
| easier. However, it provides almost no commands for controlling the |
| final formatting. Texinfo is not intended to be a general-purpose |
| formatting program, so if you need to lay out a newspaper, devise a |
| glossy magazine ad, or follow the exact formatting requirements of a |
| publishing house, Texinfo may not be the simplest tool. |
| |
| Spell "Texinfo" with a capital "T" and the other letters in |
| lowercase. The first syllable of "Texinfo" is pronounced like "speck", |
| not "hex". This odd pronunciation is derived from the pronunciation of |
| TeX. Pronounce TeX as if the 'X' were the last sound in the name |
| 'Bach'. In the word TeX, the 'X' is, rather than the English letter |
| "ex", actually the Greek letter "chi". |
| |
| Texinfo is the official documentation format of the GNU project. |
| More information, including manuals for GNU packages, is available at |
| the GNU documentation web page (http://www.gnu.org/doc/). |
| |
| * Menu: |
| |
| * Reporting Bugs:: Submitting effective bug reports. |
| * Output Formats:: Overview of the supported output formats. |
| * Info Files:: What is an Info file? |
| * Printed Books:: Characteristics of a printed book or manual. |
| * Adding Output Formats:: Man pages and implementing new formats. |
| * History:: Acknowledgements, contributors and genesis. |
| |
| |
| File: texinfo.info, Node: Reporting Bugs, Next: Output Formats, Up: Overview |
| |
| 1.1 Reporting Bugs |
| ================== |
| |
| We welcome bug reports and suggestions for any aspect of the Texinfo |
| system: programs, documentation, installation, etc. Please email them |
| to <bug-texinfo@gnu.org>. You can get the latest version of Texinfo via |
| its home page, <http://www.gnu.org/software/texinfo>. |
| |
| For bug reports, please include enough information for the |
| maintainers to reproduce the problem. Generally speaking, that means: |
| |
| * The version number of Texinfo and the program(s) or manual(s) |
| involved. |
| * The contents of any input files necessary to reproduce the bug. |
| * Precisely how you ran any program(s) involved. |
| * A description of the problem and samples of any erroneous output. |
| * Hardware and operating system names and versions. |
| * Anything else that you think would be helpful. |
| |
| 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.) |
| |
| Patches are most welcome; if possible, please make them with |
| 'diff -c' (*note (diffutils)Top::) and include 'ChangeLog' entries |
| (*note (emacs)Change Log::), and follow the existing coding style. |
| |
| |
| File: texinfo.info, Node: Output Formats, Next: Info Files, Prev: Reporting Bugs, Up: Overview |
| |
| 1.2 Output Formats |
| ================== |
| |
| Here is a brief overview of the output formats currently supported by |
| Texinfo. |
| |
| Info |
| (Generated via 'makeinfo'.) Info format is mostly a plain text |
| transliteration of the Texinfo source. It adds a few control |
| characters to provide navigational information for |
| cross-references, indices, and so on. The Emacs Info subsystem |
| (*note (info)Top::), and the standalone 'info' program (*note |
| (info-stnd)Top::), among others, can read these files. *Note Info |
| Files::, and *note Creating and Installing Info Files::. |
| |
| Plain text |
| (Generated via 'makeinfo --plaintext'.) This is almost the same as |
| Info output with the navigational control characters are omitted. |
| |
| HTML |
| (Generated via '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 Emacs-W3, can render this language online. |
| There are many versions of HTML, both different standards and |
| browser-specific variations. 'makeinfo' tries to use a subset of |
| the language that can be interpreted by any common browser, |
| intentionally not using many newer or less widely-supported tags. |
| Although the native output is thus rather plain, it can be |
| customized at various levels, if desired. For details of the HTML |
| language and much related information, see |
| <http://www.w3.org/MarkUp/>. *Note Generating HTML::. |
| |
| DVI |
| (Generated via 'texi2dvi'.) The DeVIce Independent binary format |
| is output by the TeX typesetting program (<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 (*note (dvips)Top::) and Xdvi |
| for viewing on an X display |
| (<http://sourceforge.net/projects/xdvi/>). *Note Hardcopy::. (Be |
| aware that the Texinfo language is very different from and much |
| stricter than TeX's usual languages: plain TeX, LaTeX, ConTeXt, |
| etc.) |
| |
| PostScript |
| (Generated via 'texi2dvi --ps'.) PostScript is a page description |
| language that became widely used around 1985 and is still used |
| today. <http://en.wikipedia.org/wiki/PostScript> gives a basic |
| description and more preferences. By default, Texinfo uses the |
| 'dvips' program to convert TeX's DVI output to PostScript. *Note |
| (dvips)Top::. |
| |
| PDF |
| (Generated via 'texi2dvi --pdf' or '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; |
| <http://en.wikipedia.org/wiki/Portable_Document_Format> and |
| <http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf> have some |
| background. By default, Texinfo uses the 'pdftex' program, an |
| extension of TeX, to output PDF; see |
| <http://tug.org/applications/pdftex>. *Note PDF Output::. |
| |
| Docbook |
| (Generated via '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 <http://www.docbook.org>. Various converters from Docbook _to_ |
| Texinfo have also been developed; see the Texinfo web pages. |
| |
| XML |
| (Generated via 'makeinfo --xml'.) XML is a generic syntax |
| specification usable for any sort of content (a reference is at |
| <http://www.w3.org/XML>). The '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 '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 'txixml2texi' to do that backward transformation. |
| |
| |
| File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Output Formats, Up: Overview |
| |
| 1.3 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. 'makeinfo', also known as 'texi2any', is the principal |
| command that converts a Texinfo file into an Info file; *note Generic |
| Translator 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 (*note (info)Top::). |
| |
| If you want to read through an Info file in sequence, as if it were a |
| printed manual, you can hit <SPC> repeatedly, or you get the whole file |
| with the advanced Info command 'g *'. (*Note Advanced Info commands: |
| (info)Advanced.) |
| |
| The 'dir' file in the '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. |
| |
| 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 |
| Emacs/W3, for example: |
| info:emacs#Dissociated%20Press |
| info:///usr/info/emacs#Dissociated%20Press |
| info://localhost/usr/info/emacs#Dissociated%20Press |
| |
| The 'info' program itself does not follow URIs of any kind. |
| |
| |
| File: texinfo.info, Node: Printed Books, Next: Adding Output Formats, Prev: Info Files, Up: Overview |
| |
| 1.4 Printed Books |
| ================= |
| |
| 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 'texinfo.tex' that contains information (definitions or "macros") |
| that TeX uses when it typesets a Texinfo file. ('texinfo.tex' tells TeX |
| how to convert the Texinfo @-commands to TeX commands, which TeX can |
| then process to create the typeset document.) 'texinfo.tex' contains |
| the specifications for printing a document. You can get the latest |
| version of 'texinfo.tex' from the Texinfo home page, |
| <http://www.gnu.org/software/texinfo/>. |
| |
| In the United States, documents are most often printed on 8.5 inch by |
| 11 inch pages (216mm by 280mm); this is the default size. But you can |
| also print for 7 inch by 9.25 inch pages (178mm by 235mm, the |
| '@smallbook' size; or on A4 or A5 size paper ('@afourpaper', |
| '@afivepaper'). *Note @smallbook::, and *note A4 Paper::. |
| |
| 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. |
| |
| *Note Obtaining TeX::, for information on acquiring TeX. It is not |
| part of the Texinfo distribution. |
| |
| |
| File: texinfo.info, Node: Adding Output Formats, Next: History, Prev: Printed Books, Up: Overview |
| |
| 1.5 Adding Output Formats |
| ========================= |
| |
| The output formats in the previous sections handle a wide variety of |
| usage, but of course there is always room for more. |
| |
| 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 '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 'tp/Texinfo/Convert/Converter.pm' is a good place to start. *Note |
| Generic Translator texi2any::. |
| |
| Another viable approach is use the Texinfo XML output from '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. |
| |
| 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. You are |
| advised to check that the tests of the language that come with |
| 'texi2any' give correct results with your new program. |
| |
| 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 from that needed for 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. |
| |
| As an alternative way to support man pages, you may find the program |
| 'help2man' to be useful. It generates a traditional man page from the |
| '--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 |
| <http://www.gnu.org/software/help2man>. |
| |
| |
| File: texinfo.info, Node: History, Prev: Adding Output Formats, Up: Overview |
| |
| 1.6 History |
| =========== |
| |
| Richard M. Stallman invented the Texinfo format, wrote the initial |
| processors, and created Edition 1.0 of this manual. Robert 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 'makeinfo' and 'info' |
| programs. Karl Berry has continued maintenance since Texinfo 3.8 |
| (manual edition 2.22). |
| |
| 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. Franc,ois Pinard and David D. Zuhn, tirelessly |
| recorded and reported mistakes and obscurities. Zack Weinberg did the |
| impossible by implementing the macro syntax in '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 'ChangeLog' file. Our mistakes are our |
| own. |
| |
| Beginnings |
| ---------- |
| |
| In the 1970's at CMU, Brian Reid developed a program and format named |
| Scribe to mark up documents for printing. It used the '@' 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. |
| |
| Meanwhile, people at MIT developed another, not too dissimilar format |
| called Bolio. This then was converted to using TeX as its typesetting |
| language: BoTeX. The earliest BoTeX version seems to have been 0.02 on |
| October 31, 1984. |
| |
| BoTeX 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 BoTeX. He also developed a nifty on-line help format |
| called Info, and then combined BoTeX 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 |
| 'texinfo-format-buffer' and other functions. In the early 1990s, Brian |
| Fox reimplemented the conversion program in C, now called 'makeinfo'. |
| |
| Reimplementing in Perl |
| ---------------------- |
| |
| In 2012, the C 'makeinfo' was itself replaced by a Perl implementation |
| generically called 'texi2any'. This version supports the same level of |
| output customization as 'texi2html', an independent program originally |
| written by Lionel Cons, later with substantial work by many others. The |
| many additional features needed to make 'texi2html' a replacement for |
| 'makeinfo' were implemented by Patrice Dumas. The first never-released |
| version of 'texi2any' was based on the '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 '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 'makeinfo' to extend to different output styles, |
| back-end output formats, and all other customizations. In more detail: |
| |
| * HTML customization. Many GNU and other free software packages had |
| been happily using the HTML customization features in '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 'texi2html' to a |
| C program would have been an enormous effort. |
| |
| * 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 'makeinfo', it |
| would have been tantamount to rewriting the entire program. In |
| Perl, much of that comes essentially for free. |
| |
| * Additional back-ends. The '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, ...), and they will |
| now be much more feasible to implement. Which leads to the last |
| 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. |
| |
| *Note Reference Implementation::, for more on the rationale for and |
| role of 'texi2any'. |
| |
| |
| File: texinfo.info, Node: Writing a Texinfo File, Next: Beginning and Ending a File, Prev: Overview, Up: Top |
| |
| 2 Writing a Texinfo File |
| ************************ |
| |
| This chapter describes Texinfo syntax and what is required in a Texinfo |
| file, and gives a short sample file. |
| |
| * Menu: |
| |
| * Conventions:: General rules for writing a Texinfo file. |
| * Comments:: Writing comments and ignored text in general. |
| * Minimum:: What a Texinfo file must have. |
| * Short Sample:: A short sample Texinfo file. |
| |
| |
| File: texinfo.info, Node: Conventions, Next: Comments, Up: Writing a Texinfo File |
| |
| 2.1 General Syntactic Conventions |
| ================================= |
| |
| This section describes the general conventions used in all Texinfo |
| documents. |
| |
| * All printable ASCII characters except '@', '{' and '}' can appear |
| in a Texinfo file and stand for themselves. '@' is the escape |
| character which introduces commands, while '{' and '}' are used to |
| surround arguments to certain commands. To put one of these |
| special characters into the document, put an '@' character in front |
| of it, like this: '@@', '@{', and '@}'. |
| |
| * In a Texinfo file, the commands you write to describe the contents |
| of the manual are preceded by an '@' character; they are called |
| "@-commands". (The '@' in Texinfo has the same meaning that '\' |
| has in plain TeX.) |
| |
| Depending on what they do or what arguments(1) they take, you need |
| to write @-commands on lines of their own, or as part of sentences. |
| 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. For more details of Texinfo command syntax, see *note Command |
| Syntax::. |
| |
| * Whitespace following an @-command name is optional and (usually) |
| ignored if present. The exceptions are contexts when whitespace is |
| significant, e.g., an '@example' environment. |
| |
| * Texinfo supports the usual quotation marks used in English and in |
| other languages; see *note Inserting Quotation Marks::. |
| |
| * Use three hyphens in a row, '---', to produce a long dash--like |
| this (called an "em dash"), used for punctuation in sentences. Use |
| two hyphens, '--', to produce a medium dash (called an "en dash"), |
| used primarily for numeric ranges, as in "June 25-26". Use a |
| single hyphen, '-', 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' and '@example'. |
| |
| * Form feed ('CTRL-l') characters in the input are handled as |
| follows: |
| |
| PDF/DVI |
| In normal text, treated as ending any open paragraph; |
| essentially ignored between paragraphs. |
| |
| 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). |
| |
| HTML |
| Written as a numeric entity except contexts where spaces are |
| ignored; for example, in '@footnote{ ^L foo}', the form feed |
| is ignored. |
| |
| XML |
| Keep them everywhere; in attributes, escaped as '\f'; also, |
| '\' is escaped as '\\' and newline as '\n'. |
| |
| Docbook |
| Completely removed, as they are not allowed. |
| |
| As you can see, because of these differing requirements of the |
| output formats, it's not possible to use form feeds completely |
| portably. |
| |
| * *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, 'makeinfo' does nothing special with tabs, and thus a |
| tab character in your input file will usually have a different |
| appearance in the output. |
| |
| To avoid this problem, Texinfo mode in GNU Emacs inserts multiple |
| spaces when you press the <TAB> key. Also, you can run 'untabify' |
| in Emacs to convert tabs in a region to multiple spaces, or use the |
| 'unexpand' command from the shell. |
| |
| ---------- Footnotes ---------- |
| |
| (1) The word "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 'Oxford English |
| Dictionary', the word derives from the Latin for "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. |
| |
| |
| File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Writing a Texinfo File |
| |
| 2.2 Comments |
| ============ |
| |
| You can write comments in a Texinfo file by using the '@comment' |
| command, which may be abbreviated to '@c'. Such comments are for a |
| person looking at the Texinfo source file. All the text on a line that |
| follows either '@comment' or '@c' is a comment; the rest of the line |
| does not appear in the visible output. (To be precise, the character |
| after the '@c' or '@comment' must be something other than a dash or |
| alphanumeric, or it will be taken as part of the command.) |
| |
| Often, you can write the '@comment' or '@c' in the middle of a line, |
| and only the text that follows after the '@comment' or '@c' command does |
| not appear; but some commands, such as '@settitle', work on a whole |
| line. You cannot use '@comment' or '@c' within a line beginning with |
| such a command. |
| |
| In cases of nested command invocations, complicated macro |
| definitions, etc., '@c' and '@comment' may provoke an error when |
| processing with TeX. Therefore, you can also use the '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 'DEL' will be ignored. |
| |
| You can also have long stretches of text ignored by the Texinfo |
| processors with the '@ignore' and '@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 '@ignore' and '@end ignore' for |
| writing comments. (For some caveats regarding nesting of such commands, |
| *note Conditional Nesting::.) |
| |
| |
| File: texinfo.info, Node: Minimum, Next: Short Sample, Prev: Comments, Up: Writing a Texinfo File |
| |
| 2.3 What a Texinfo File Must Have |
| ================================= |
| |
| By convention, the name of a Texinfo file ends with one of the |
| extensions '.texinfo', '.texi', '.txi', or '.tex'.(1) |
| |
| In order to be made into a printed manual and other output formats, a |
| Texinfo file must begin with lines like this: |
| |
| \input texinfo |
| @settitle NAME-OF-MANUAL |
| |
| The contents of the file follow this beginning, and then you must end |
| the Texinfo source with a line like this: |
| |
| @bye |
| |
| Here's an explanation: |
| |
| * The '\input texinfo' line tells TeX to use the 'texinfo.tex' file, |
| which tells TeX how to translate the Texinfo @-commands into TeX |
| typesetting commands. (Note the use of the backslash, '\'; this is |
| correct for TeX.) |
| |
| * The '@settitle' line specifies a title for the page headers (or |
| footers) of the printed manual, and the default title and document |
| description for the '<head>' in HTML. Strictly speaking, |
| '@settitle' is optional--if you don't mind your document being |
| titled 'Untitled'. |
| |
| * The '@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. If |
| you leave this out, you'll be dumped at TeX's prompt at the end of |
| the run. |
| |
| 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 |
| two lines at the beginning and the one line at the end. |
| |
| ---------- Footnotes ---------- |
| |
| (1) 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. |
| |
| |
| File: texinfo.info, Node: Short Sample, Prev: Minimum, Up: Writing a Texinfo File |
| |
| 2.4 A Short Sample Texinfo File |
| =============================== |
| |
| Here is a short but complete Texinfo file, so you can see how Texinfo |
| source appears in practice. The first three parts of the file are |
| mostly boilerplate: when writing a manual, you simply change the names |
| as appropriate. |
| |
| The complete file, without interspersed comments, is shown in *note |
| Short Sample Texinfo File::. |
| |
| *Note Beginning and Ending a File::, for more documentation on the |
| commands listed here. |
| |
| Header |
| ------ |
| |
| The header tells TeX which definitions file to use, names the manual, |
| and carries out other such housekeeping tasks. |
| |
| \input texinfo |
| @settitle Sample Manual 1.0 |
| |
| Summary Description and Copyright |
| --------------------------------- |
| |
| This segment describes the document and contains the copyright notice |
| and copying permissions. This is done with the '@copying' command. |
| |
| A real manual includes more text here, according to the license under |
| which it is distributed. *Note GNU Sample Texts::. |
| |
| @copying |
| This is a short example of a complete Texinfo file, version 1.0. |
| |
| Copyright @copyright{} 2016 Free Software Foundation, Inc. |
| @end copying |
| |
| Titlepage, Copyright, Contents |
| ------------------------------ |
| |
| The title and copyright segment contains the title and copyright pages |
| for the printed manual. The segment must be enclosed between |
| '@titlepage' and '@end titlepage' commands. The title and copyright |
| page does not appear in the online output. |
| |
| We use the '@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 '@contents' command generates a table |
| of contents. |
| |
| @titlepage |
| @title Sample Title |
| |
| @c The following two commands start the copyright page. |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| @end titlepage |
| |
| @c Output the table of contents at the beginning. |
| @contents |
| |
| 'Top' Node and Master Menu |
| -------------------------- |
| |
| The 'Top' node starts off the online output; it does not appear in the |
| printed manual. We repeat the short description from the beginning of |
| the '@copying' text, but there's no need to repeat the copyright |
| information, so we don't use '@insertcopying' here. |
| |
| The '@top' command itself helps 'makeinfo' determine the |
| relationships between nodes. The 'Top' node contains at least a |
| top-level "menu" listing the chapters, and possibly a "Master Menu" |
| listing all the nodes in the entire document. |
| |
| @ifnottex |
| @node Top |
| @top Short Sample |
| |
| This is a short sample Texinfo file. |
| @end ifnottex |
| |
| @menu |
| * First Chapter:: The first chapter is the |
| only chapter in this sample. |
| * Index:: Complete index. |
| @end menu |
| |
| The Body of the Document |
| ------------------------ |
| |
| 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. |
| |
| @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 |
| |
| The End of the Document |
| ----------------------- |
| |
| This may contain commands for printing indices, and closes with the |
| '@bye' command, which marks the end of the document. |
| |
| @node Index |
| @unnumbered Index |
| |
| @printindex cp |
| |
| @bye |
| |
| Some Results |
| ------------ |
| |
| Here is what the contents of the first chapter of the sample look like: |
| |
| |
| This is the first chapter. |
| |
| Here is a numbered list. |
| |
| 1. This is the first item. |
| |
| 2. This is the second item. |
| |
| |
| File: texinfo.info, Node: Beginning and Ending a File, Next: Nodes, Prev: Writing a Texinfo File, Up: Top |
| |
| 3 Beginning and Ending a Texinfo File |
| ************************************* |
| |
| This chapter expands on the minimal complete Texinfo source file |
| previously given (*note Short Sample::). |
| |
| Certain pieces of information must be provided at the beginning of a |
| Texinfo file, such the title of the document and the Top node. A table |
| of contents is also generally produced here. |
| |
| 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. |
| * Ending a File:: What is at the end of a Texinfo file? |
| |
| |
| File: texinfo.info, Node: Sample Beginning, Next: Texinfo File Header, Up: Beginning and Ending a File |
| |
| 3.1 Sample Texinfo File Beginning |
| ================================= |
| |
| 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. |
| |
| *Note GNU Sample Texts::, for the full texts to be used in GNU |
| manuals. |
| |
| \input texinfo |
| @settitle NAME-OF-MANUAL VERSION |
| |
| @copying |
| This manual is for PROGRAM, version VERSION. |
| |
| Copyright @copyright{} YEARS COPYRIGHT-OWNER. |
| |
| @quotation |
| Permission is granted to ... |
| @end quotation |
| @end copying |
| |
| @titlepage |
| @title NAME-OF-MANUAL-WHEN-PRINTED |
| @subtitle SUBTITLE-IF-ANY |
| @subtitle SECOND-SUBTITLE |
| @author AUTHOR |
| |
| @c The following two commands |
| @c start the copyright page. |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| |
| Published by ... |
| @end titlepage |
| |
| @c So the toc is printed at the start. |
| @contents |
| |
| @ifnottex |
| @node Top |
| @top TITLE |
| |
| This manual is for PROGRAM, version VERSION. |
| @end ifnottex |
| |
| @menu |
| * First Chapter:: Getting started ... |
| * Second Chapter:: ... |
| ... |
| * Copying:: Your rights and freedoms. |
| @end menu |
| |
| @node First Chapter |
| @chapter First Chapter |
| |
| @cindex first chapter |
| @cindex chapter, first |
| ... |
| |
| |
| File: texinfo.info, Node: Texinfo File Header, Next: Document Permissions, Prev: Sample Beginning, Up: Beginning and Ending a File |
| |
| 3.2 Texinfo File Header |
| ======================= |
| |
| Texinfo files start with at least two lines. These are the '\input |
| texinfo' line and the '@settitle' line. |
| |
| Also, if you want to format just part of the Texinfo file in Emacs, |
| you must write the '@settitle' line 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. '@synindex' (*note @synindex::), for |
| instance, is another command often included in the header. |
| |
| Thus, the beginning of a Texinfo file looks approximately like this: |
| |
| \input texinfo |
| @settitle Sample Manual 1.0 |
| |
| (*Note 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. |
| * @setfilename:: Tell Info the name of the Info file. |
| * @settitle:: Create a title for the printed work. |
| * End of Header:: Formatting a region requires this. |
| |
| |
| File: texinfo.info, Node: First Line, Next: Start of Header, Up: Texinfo File Header |
| |
| 3.2.1 The First Line 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: |
| |
| \input texinfo |
| |
| When the file is processed by TeX, the '\input texinfo' command tells |
| TeX to load the macros needed for processing a Texinfo file. These are |
| in a file called 'texinfo.tex', which should have been installed on your |
| system along with either the TeX or Texinfo software. TeX uses the |
| backslash, '\', to mark the beginning of a command, exactly as Texinfo |
| uses '@'. The 'texinfo.tex' file causes the switch from '\' to '@'; |
| before the switch occurs, TeX requires '\', which is why it appears at |
| the beginning of the file. |
| |
| You may optionally follow this line with a comment to tell GNU Emacs |
| to use Texinfo mode when the file is edited: |
| |
| \input texinfo @c -*-texinfo-*- |
| |
| This may be useful when Emacs doesn't detect the file type from the file |
| extension automatically. |
| |
| |
| File: texinfo.info, Node: Start of Header, Next: @setfilename, Prev: First Line, Up: Texinfo File Header |
| |
| 3.2.2 Start of Header |
| --------------------- |
| |
| A start-of-header line is a Texinfo comment that looks like this: |
| |
| @c %**start of header |
| |
| Write the start-of-header line on the second line of a Texinfo file. |
| Follow the start-of-header line with an '@settitle' line and, |
| optionally, with other commands that globally affect the document |
| formatting, such as '@synindex' or '@footnotestyle'; and then by an |
| end-of-header line (*note End of Header::). |
| |
| The start- and end-of-header lines allow you to format only part of a |
| Texinfo file for Info or printing. *Note texinfo-format commands::. |
| |
| The odd string of characters, '%**', 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 'tex-start-of-header' and/or |
| 'tex-end-of-header' Emacs variables. *Note Texinfo Mode Printing::. |
| |
| |
| File: texinfo.info, Node: @setfilename, Next: @settitle, Prev: Start of Header, Up: Texinfo File Header |
| |
| 3.2.3 '@setfilename': Set the Output File Name |
| ---------------------------------------------- |
| |
| The '@setfilename' line specifies the name of the output file to be |
| generated. When present, it should be the first Texinfo command (that |
| is, afte '\input texinfo'). Write the '@setfilename' command at the |
| beginning of a line and follow it on the same line by the Info file |
| name. |
| |
| @setfilename INFO-FILE-NAME |
| |
| The 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 '.texi') entirely from the input file name, or |
| (recommended) replace it with the '.info' extension. |
| |
| When a '@setfilename' line is present, the Texinfo processors ignore |
| everything written before the '@setfilename' line. This is why the very |
| first line of the file (the '\input' line) does not show up in the |
| output. |
| |
| If there is no '@setfilename' line, 'makeinfo' uses the input file |
| name to determine the output name: first, any of the extensions '.texi', |
| '.tex', '.txi' or '.texinfo' is removed from the input file name; then, |
| the output format specific extension is added--'.html' when generating |
| HTML, '.info' when generating Info, etc. The '\input' line is still |
| ignored in this processing, as well as leading blank lines. |
| |
| When producing another output format, 'makeinfo' will replace any |
| final extension with the output format-specific extension ('html' when |
| generating HTML, for example), or add a dot followed by the extension |
| ('.html' for HTML) if the given name has no extension. |
| |
| '@setfilename' used to be required by the Texinfo processors, and |
| some other programs may still expect it to be present; for example, |
| Automake (*note (automake)Texinfo::). |
| |
| Although an explicit '.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 '-1', '-2', ..., '-10', '-11', and |
| so on, to the original file name. (*Note Tag and Split Files::.) The |
| subfile name '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 'texinfo' rather than 'texinfo.info'. When '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 |
| 'texin-10', 'gcc.i12', etc. |
| |
| See also the '--output' option in *note Invoking texi2any::. |
| |
| |
| File: texinfo.info, Node: @settitle, Next: End of Header, Prev: @setfilename, Up: Texinfo File Header |
| |
| 3.2.4 '@settitle': Set the Document Title |
| ----------------------------------------- |
| |
| A Texinfo file should contain a line that looks like this: |
| |
| @settitle TITLE |
| |
| Write the '@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 '@settitle' command should precede everything that generates |
| actual output. The best place for it is right after the '@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 *note Heading Generation::. |
| |
| In the HTML file produced by 'makeinfo', TITLE serves as the document |
| '<title>'. It also becomes the default document description in the |
| '<head>' part (*note @documentdescription::). |
| |
| When the title page is used in the output, the title in the |
| '@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 '@settitle' title; on the title page, the version number generally |
| appears as a '@subtitle' so it would be omitted from the '@title'. |
| *Note @titlepage::. |
| |
| |
| File: texinfo.info, Node: End of Header, Prev: @settitle, Up: Texinfo File Header |
| |
| 3.2.5 End of Header |
| ------------------- |
| |
| Follow the header lines with an end-of-header line, which is a Texinfo |
| comment that looks like this: |
| |
| @c %**end of header |
| |
| *Note Start of Header::. |
| |
| |
| File: texinfo.info, Node: Document Permissions, Next: Titlepage & Copyright Page, Prev: Texinfo File Header, Up: Beginning and Ending a File |
| |
| 3.3 Document 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 ('@copying') to declare this text |
| once, and another command ('@insertcopying') to insert the text at |
| appropriate points. |
| |
| 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: |
| |
| * @copying:: Declare the document's copying permissions. |
| * @insertcopying:: Where to insert the permissions. |
| |
| |
| File: texinfo.info, Node: @copying, Next: @insertcopying, Up: Document Permissions |
| |
| 3.3.1 '@copying': Declare Copying Permissions |
| --------------------------------------------- |
| |
| The '@copying' command should be given very early in the document; the |
| recommended location is right after the header material (*note 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: |
| |
| @copying |
| This manual is for PROGRAM (version VERSION, updated |
| DATE), which ... |
| |
| Copyright @copyright{} YEARS COPYRIGHT-OWNER. |
| |
| @quotation |
| Permission is granted to ... |
| @end quotation |
| @end copying |
| |
| The '@quotation' has no legal significance; it's there to improve |
| readability in some contexts. |
| |
| The text of '@copying' is output as a comment at the beginning of |
| Info, HTML, XML, and Docbook output files. It is _not_ output |
| implicitly in plain text or TeX; it's up to you to use '@insertcopying' |
| to emit the copying information. See the next section for details. |
| |
| The '@copyright{}' command generates a '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 '(C)'. |
| |
| The copyright notice itself has the following legally-prescribed |
| form: |
| |
| Copyright (C) YEARS COPYRIGHT-OWNER. |
| |
| 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. |
| |
| 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. |
| |
| 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 '@copying' block) in the source file. |
| |
| *Note (maintain)Copyright Notices::, for additional information. |
| *Note GNU Sample Texts::, for the full text to be used in GNU manuals. |
| *Note GNU Free Documentation License::, for the license itself under |
| which GNU and other free manuals are distributed. |
| |
| |
| File: texinfo.info, Node: @insertcopying, Prev: @copying, Up: Document Permissions |
| |
| 3.3.2 '@insertcopying': Include Permissions Text |
| ------------------------------------------------ |
| |
| The '@insertcopying' command is simply written on a line by itself, like |
| this: |
| |
| @insertcopying |
| |
| This inserts the text previously defined by '@copying'. To meet |
| legal requirements, it must be used on the copyright page in the printed |
| manual (*note Copyright::). |
| |
| The '@copying' command itself causes the permissions text to appear |
| in an Info file _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 _not_ |
| see this text (except when using the advanced Info command 'g *'), but |
| this does not matter for legal purposes, because the text is present. |
| |
| Similarly, the '@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 '@copying' also appears automatically |
| at the beginning of the XML and Docbook output files. |
| |
| |
| File: texinfo.info, Node: Titlepage & Copyright Page, Next: Contents, Prev: Document Permissions, Up: Beginning and Ending a File |
| |
| 3.4 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: |
| |
| * @titlepage:: Create a title for the printed document. |
| * @titlefont @center @sp:: The '@titlefont', '@center', |
| and '@sp' commands. |
| * @title @subtitle @author:: The '@title', '@subtitle', |
| and '@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. |
| |
| |
| File: texinfo.info, Node: @titlepage, Next: @titlefont @center @sp, Up: Titlepage & Copyright Page |
| |
| 3.4.1 '@titlepage' |
| ------------------ |
| |
| Start the material for the title page and following copyright page with |
| '@titlepage' on a line by itself and end it with '@end titlepage' on a |
| line by itself. |
| |
| The '@end titlepage' command starts a new page and turns on page |
| numbering (*note Heading Generation::). All the material that you want |
| to appear on unnumbered pages should be put between the '@titlepage' and |
| '@end titlepage' commands. You can force the table of contents to |
| appear there with the '@setcontentsaftertitlepage' command (*note |
| Contents::). |
| |
| By using the '@page' command you can force a page break within the |
| region delineated by the '@titlepage' and '@end titlepage' commands and |
| thereby create more than one unnumbered page. This is how the copyright |
| page is produced. (The '@titlepage' command might perhaps have been |
| better named the '@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(1) 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 *note The Top Node::.) |
| |
| Texinfo provides two main methods for creating a title page. One |
| method uses the '@titlefont', '@sp', and '@center' commands to generate |
| a title page in which the words on the page are centered. |
| |
| The second method uses the '@title', '@subtitle', and '@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. |
| |
| For sufficiently simple documents, and for the bastard title page in |
| traditional book frontmatter, Texinfo also provides a command |
| '@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. |
| |
| ---------- Footnotes ---------- |
| |
| (1) 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. |
| |
| |
| File: texinfo.info, Node: @titlefont @center @sp, Next: @title @subtitle @author, Prev: @titlepage, Up: Titlepage & Copyright Page |
| |
| 3.4.2 '@titlefont', '@center', and '@sp' |
| ---------------------------------------- |
| |
| You can use the '@titlefont', '@sp', and '@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 '@titlefont' command to select a large font suitable for the |
| title itself. You can use '@titlefont' more than once if you have an |
| especially long title. |
| |
| For HTML output, each '@titlefont' command produces an '<h1>' |
| heading, but the HTML document '<title>' is not affected. For that, you |
| must put a '@settitle' command before the '@titlefont' command (*note |
| @settitle::). |
| |
| For example: |
| |
| @titlefont{Texinfo} |
| |
| Use the '@center' command at the beginning of a line to center the |
| remaining text on that line. Thus, |
| |
| @center @titlefont{Texinfo} |
| |
| centers the title, which in this example is "Texinfo" printed in the |
| title font. |
| |
| Use the '@sp' command to insert vertical space. For example: |
| |
| @sp 2 |
| |
| This inserts two blank lines on the printed page. (*Note @sp::, for |
| more information about the '@sp' command.) |
| |
| A template for this method looks like this: |
| |
| @titlepage |
| @sp 10 |
| @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED} |
| @sp 2 |
| @center SUBTITLE-IF-ANY |
| @sp 2 |
| @center AUTHOR |
| ... |
| @end titlepage |
| |
| 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. |
| |
| |
| File: texinfo.info, Node: @title @subtitle @author, Next: Copyright, Prev: @titlefont @center @sp, Up: Titlepage & Copyright Page |
| |
| 3.4.3 '@title', '@subtitle', and '@author' |
| ------------------------------------------ |
| |
| You can use the '@title', '@subtitle', and '@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 '@sp' command is needed to adjust |
| vertical spacing. |
| |
| Write the '@title', '@subtitle', or '@author' commands at the |
| beginning of a line followed by the title, subtitle, or author. The |
| '@author' command may be used for a quotation in an '@quotation' block |
| (*note @quotation::); except for that, it is an error to use any of |
| these commands outside of '@titlepage'. |
| |
| The '@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 '@*' 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 |
| (*note Conditionals::). For example: |
| |
| @title This Long Title@inlinefmt{tex,@*} Is Broken in @TeX{} |
| |
| The '@subtitle' command sets subtitles in a normal-sized font flush |
| to the right-hand side of the page. |
| |
| The '@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 '@author' command: you can write the |
| name or names on the remaining part of the line that starts with an |
| '@author' command: |
| |
| @author by Jane Smith and John Doe |
| |
| or you can write the names one above each other by using multiple |
| '@author' commands: |
| |
| @author Jane Smith |
| @author John Doe |
| |
| A template for this method looks like this: |
| |
| @titlepage |
| @title NAME-OF-MANUAL-WHEN-PRINTED |
| @subtitle SUBTITLE-IF-ANY |
| @subtitle SECOND-SUBTITLE |
| @author AUTHOR |
| @page |
| ... |
| @end titlepage |
| |
| |
| File: texinfo.info, Node: Copyright, Next: Heading Generation, Prev: @title @subtitle @author, Up: Titlepage & Copyright Page |
| |
| 3.4.4 Copyright Page |
| -------------------- |
| |
| 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 '@titlepage' and '@end titlepage' commands. |
| |
| Use the '@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 '@page': |
| |
| @vskip 0pt plus 1filll |
| |
| The '@vskip' command inserts whitespace in the TeX output; it is ignored |
| in all other output formats. The '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 'l's in the word 'filll'; this is correct. |
| |
| To insert the copyright text itself, write '@insertcopying' next |
| (*note Document Permissions::): |
| |
| @insertcopying |
| |
| Follow the copying text by the publisher, ISBN numbers, cover art |
| credits, and other such information. |
| |
| Here is an example putting all this together: |
| |
| @titlepage |
| ... |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| |
| Published by ... |
| |
| Cover art by ... |
| @end titlepage |
| |
| 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: |
| |
| @ifplaintext |
| @insertcopying |
| @end ifplaintext |
| |
| You could include other title-like information for the plain text |
| output in the same place. |
| |
| |
| File: texinfo.info, Node: Heading Generation, Prev: Copyright, Up: Titlepage & Copyright Page |
| |
| 3.4.5 Heading Generation |
| ------------------------ |
| |
| Like all '@end' commands (*note Quotations and Examples::), the '@end |
| titlepage' command must be written at the beginning of a line by itself, |
| with only one space between the '@end' and the '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: |
| |
| * The conventional way is to write a '@setchapternewpage' command |
| before the title page commands, if required, and then have the |
| '@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 '@setchapternewpage odd' |
| for double-sided printing and (almost always) no |
| '@setchapternewpage' command for single-sided printing (*note |
| @setchapternewpage::). |
| |
| * Alternatively, you can use the '@headings' command to prevent page |
| headings from being generated or to start them for either single or |
| double-sided printing. Write a '@headings' command immediately |
| after the '@end titlepage' command. To turn off headings, write |
| '@headings off'. *Note @headings::. |
| |
| * Or, you may specify your own page heading and footing format. |
| *Note Headings::. |
| |
| |
| File: texinfo.info, Node: Contents, Next: The Top Node, Prev: Titlepage & Copyright Page, Up: Beginning and Ending a File |
| |
| 3.5 Generating a Table of Contents |
| ================================== |
| |
| The '@chapter', '@section', and other structuring commands (*note |
| 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 '@contents' and/or '@summarycontents' |
| command(s). |
| |
| '@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 '@majorheading', |
| '@chapheading', and the other '@...heading' commands do not appear |
| in the table of contents (*note Structuring Command Types::). |
| |
| '@shortcontents' |
| '@summarycontents' |
| ('@summarycontents' is a synonym for '@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. |
| |
| Both contents commands should be written on a line by themselves, and |
| placed near the beginning of the file, after the '@end titlepage' (*note |
| @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 |
| '@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 'makeinfo --plaintext') and |
| in other output formats, such as HTML. |
| |
| When '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 '@bye', but we no |
| longer recommend this. |
| |
| However, since many existing Texinfo documents still do have the |
| '@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 '@setcontentsaftertitlepage' and/or |
| '@setshortcontentsaftertitlepage'. The first prints only the main |
| contents after the '@end titlepage'; the second prints both the short |
| contents and the main contents. In either case, any subsequent |
| '@contents' or '@shortcontents' is ignored. |
| |
| You need to include the '@set...contentsaftertitlepage' commands |
| early in the document (just after '@setfilename', for example). We |
| recommend using 'texi2dvi' (*note Format with texi2dvi::) to specify |
| this without altering the source file at all. For example: |
| |
| texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi |
| |
| An alternative invocation, using 'texi2any': |
| |
| texi2any --dvi --Xopt --texinfo=@setcontentsaftertitlepage foo.texi |
| |
| |
| File: texinfo.info, Node: The Top Node, Next: Global Document Commands, Prev: Contents, Up: Beginning and Ending a File |
| |
| 3.6 The 'Top' Node and Master Menu |
| ================================== |
| |
| 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. |
| |
| It is conventional and desirable to write a '@top' sectioning command |
| line containing the title of the document immediately after the '@node |
| Top' line (*note @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 '@ifnottex' and '@end ifnottex' commands. (TeX does not print |
| either an '@node' line or a menu; they appear only in Info; strictly |
| speaking, you are not required to enclose these parts between |
| '@ifnottex' and '@end ifnottex', but it is simplest to do so. *Note |
| Conditionally Visible Text: Conditionals.) |
| |
| * Menu: |
| |
| * Top Node Example:: |
| * Master Menu Parts:: |
| |
| |
| File: texinfo.info, Node: Top Node Example, Next: Master Menu Parts, Up: The Top Node |
| |
| 3.6.1 Top Node Example |
| ---------------------- |
| |
| Here is an example of a Top node. |
| |
| @ifnottex |
| @node Top |
| @top Sample Title |
| |
| This is the text of the top node. |
| @end ifnottex |
| |
| Additional general information. |
| |
| @menu |
| * First Chapter:: |
| * Second Chapter:: |
| ... |
| * Index:: |
| @end menu |
| |
| |
| File: texinfo.info, Node: Master Menu Parts, Prev: Top Node Example, Up: The Top Node |
| |
| 3.6.2 Parts of a Master Menu |
| ---------------------------- |
| |
| A "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 '@menu' and '@end |
| menu' and does not appear in the printed output. |
| |
| Generally, a master menu is divided into parts. |
| |
| * The first part contains the major nodes in the Texinfo file: the |
| nodes for the chapters, chapter-like sections, and the appendices. |
| |
| * The second part contains nodes for the indices. |
| |
| * 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 '@detailmenu' before the |
| first one, and '@end detailmenu' after the last; otherwise, |
| 'makeinfo' will get confused. |
| |
| 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. (*Note Writing a Menu::, for more information.) |
| |
| For example, the master menu for this manual looks like the following |
| (but has many more entries): |
| |
| @menu |
| * Copying Conditions:: Your rights. |
| * Overview:: Texinfo in brief. |
| ... |
| * Command and Variable Index:: |
| * General Index:: |
| |
| @detailmenu |
| --- The Detailed Node Listing --- |
| |
| Overview of Texinfo |
| |
| * Reporting Bugs:: ... |
| ... |
| |
| Beginning a Texinfo File |
| |
| * Sample Beginning:: ... |
| ... |
| @end detailmenu |
| @end menu |
| |
| |
| File: texinfo.info, Node: Global Document Commands, Next: Ending a File, Prev: The Top Node, Up: Beginning and Ending a File |
| |
| 3.7 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: |
| |
| * @documentdescription:: Document summary for the HTML output. |
| * @setchapternewpage:: Start chapters on right-hand pages. |
| * @headings:: An option for turning headings on and off |
| and double or single sided printing. |
| * @paragraphindent:: Specify paragraph indentation. |
| * @firstparagraphindent:: Suppressing first paragraph indentation. |
| * @exampleindent:: Specify environment indentation. |
| |
| |
| File: texinfo.info, Node: @documentdescription, Next: @setchapternewpage, Up: Global Document Commands |
| |
| 3.7.1 '@documentdescription': Summary Text |
| ------------------------------------------ |
| |
| When producing HTML output for a document, 'makeinfo' writes a '<meta>' |
| element in the '<head>' to give some idea of the content of the |
| document. By default, this "description" is the title of the document, |
| taken from the '@settitle' command (*note @settitle::). To change this, |
| use the '@documentdescription' environment, as in: |
| |
| @documentdescription |
| descriptive text. |
| @end documentdescription |
| |
| This will produce the following output in the '<head>' of the HTML: |
| |
| <meta name=description content="descriptive text."> |
| |
| '@documentdescription' must be specified before the first node of the |
| document. |
| |
| |
| File: texinfo.info, Node: @setchapternewpage, Next: @headings, Prev: @documentdescription, Up: Global Document Commands |
| |
| 3.7.2 '@setchapternewpage': Blank Pages Before Chapters |
| ------------------------------------------------------- |
| |
| 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 '@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 '@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: |
| |
| @setchapternewpage odd |
| |
| You can specify one of three alternatives with the |
| '@setchapternewpage' command: |
| |
| '@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. |
| |
| '@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. |
| |
| '@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. |
| |
| Texinfo does not have a '@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 '@setchapternewpage' sets, |
| you can explicit control them with the '@headings' command. *Note |
| @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 '@setchapternewpage' has no effect in output formats that do not |
| have pages, such as Info and HTML. |
| |
| We recommend not including any '@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 |
| '--texinfo' option to 'texi2dvi' to specify the output you want. |
| |
| |
| File: texinfo.info, Node: @headings, Next: @paragraphindent, Prev: @setchapternewpage, Up: Global Document Commands |
| |
| 3.7.3 The '@headings' Command |
| ----------------------------- |
| |
| The '@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 '@setchapternewpage' command. You need the |
| '@headings' command only if the '@setchapternewpage' command does not do |
| what you want, or if you want to turn off predefined page headings prior |
| to defining your own. Write a '@headings' command immediately after the |
| '@end titlepage' command. |
| |
| You can use '@headings' as follows: |
| |
| '@headings off' |
| Turn off printing of page headings. |
| |
| '@headings single' |
| Turn on page headings appropriate for single-sided printing. |
| |
| '@headings double' |
| Turn on page headings appropriate for double-sided printing. |
| |
| '@headings singleafter' |
| '@headings doubleafter' |
| Turn on 'single' or 'double' headings, respectively, after the |
| current page is output. |
| |
| '@headings on' |
| Turn on page headings: 'single' if '@setchapternewpage on', |
| 'double' otherwise. |
| |
| For example, suppose you write '@setchapternewpage off' before the |
| '@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 '@headings double' after the '@end |
| titlepage' command. |
| |
| You can stop TeX from generating any page headings at all by writing |
| '@headings off' on a line of its own immediately after the line |
| containing the '@end titlepage' command, like this: |
| |
| @end titlepage |
| @headings off |
| |
| The '@headings off' command overrides the '@end titlepage' command, |
| which would otherwise cause TeX to print page headings. |
| |
| You can also specify your own style of page heading and footing. |
| *Note Page Headings: Headings, for more information. |
| |
| |
| File: texinfo.info, Node: @paragraphindent, Next: @firstparagraphindent, Prev: @headings, Up: Global Document Commands |
| |
| 3.7.4 '@paragraphindent': Controlling Paragraph Indentation |
| ----------------------------------------------------------- |
| |
| The Texinfo processors may insert whitespace at the beginning of the |
| first line of each paragraph, thereby indenting that paragraph. You can |
| use the '@paragraphindent' command to specify this indentation. Write a |
| '@paragraphindent' command at the beginning of a line followed by either |
| 'asis' or a number: |
| |
| @paragraphindent INDENT |
| |
| The indentation is according to the value of INDENT: |
| |
| 'asis' |
| Do not change the existing indentation (not implemented in TeX). |
| |
| 'none' |
| 0 |
| Omit all indentation. |
| |
| N |
| Indent by N space characters in Info output, by N ems in TeX. |
| |
| The default value of INDENT is 3. '@paragraphindent' is ignored for |
| HTML output. |
| |
| It is best to write the '@paragraphindent' command before the |
| end-of-header line at the beginning of a Texinfo file, so the region |
| formatting commands indent paragraphs as specified. *Note Start of |
| Header::. |
| |
| |
| File: texinfo.info, Node: @firstparagraphindent, Next: @exampleindent, Prev: @paragraphindent, Up: Global Document Commands |
| |
| 3.7.5 '@firstparagraphindent': Indenting After Headings |
| ------------------------------------------------------- |
| |
| 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 '@firstparagraphindent' command: |
| |
| @firstparagraphindent WORD |
| |
| The first paragraph after a heading is indented according to the |
| value of WORD: |
| |
| 'none' |
| Prevents the first paragraph from being indented (default). This |
| option is ignored by 'makeinfo' if '@paragraphindent asis' is in |
| effect. |
| |
| 'insert' |
| Include normal paragraph indentation. This respects the paragraph |
| indentation set by a '@paragraphindent' command (*note |
| @paragraphindent::). |
| |
| '@firstparagraphindent' is ignored for HTML and Docbook output. |
| |
| It is best to write the '@firstparagraphindent' command before the |
| end-of-header line at the beginning of a Texinfo file, so the region |
| formatting commands indent paragraphs as specified. *Note Start of |
| Header::. |
| |
| |
| File: texinfo.info, Node: @exampleindent, Prev: @firstparagraphindent, Up: Global Document Commands |
| |
| 3.7.6 '@exampleindent': Environment Indenting |
| --------------------------------------------- |
| |
| The Texinfo processors indent each line of '@example' and similar |
| environments. You can use the '@exampleindent' command to specify this |
| indentation. Write an '@exampleindent' command at the beginning of a |
| line followed by either 'asis' or a number: |
| |
| @exampleindent INDENT |
| |
| The indentation is according to the value of INDENT: |
| |
| 'asis' |
| Do not change the existing indentation (not implemented in TeX). |
| |
| 0 |
| Omit all indentation. |
| |
| N |
| Indent environments by N space characters in Info output, by N ems |
| in TeX. |
| |
| The default value of INDENT is 5 spaces in Info, and 0.4in in TeX, |
| which is somewhat less. (The reduction is to help TeX fit more |
| characters onto physical lines.) |
| |
| It is best to write the '@exampleindent' command before the |
| end-of-header line at the beginning of a Texinfo file, so the region |
| formatting commands indent paragraphs as specified. *Note Start of |
| Header::. |
| |
| |
| File: texinfo.info, Node: Ending a File, Prev: Global Document Commands, Up: Beginning and Ending a File |
| |
| 3.8 Ending a Texinfo File |
| ========================= |
| |
| The end of a Texinfo file should include commands to create indices |
| (*note Printing Indices & Menus::), and the '@bye' command to mark the |
| last line to be processed. For example: |
| |
| @node Index |
| @unnumbered Index |
| |
| @printindex cp |
| |
| @bye |
| |
| An '@bye' command terminates Texinfo processing. None of the |
| formatters process anything following '@bye'; any such text is |
| completely ignored. The '@bye' command should be on a line by itself. |
| |
| Thus, if you wish, you may follow the '@bye' line with arbitrary |
| notes. Also, you may follow the '@bye' line with a local variables list |
| for Emacs, most typically a 'compile-command' (*note Using the Local |
| Variables List: Compile-Command.). |
| |
| |
| File: texinfo.info, Node: Nodes, Next: Chapter Structuring, Prev: Beginning and Ending a File, Up: Top |
| |
| 4 Nodes |
| ******* |
| |
| A "node" is a region of text that begins at a '@node' command, and |
| continues until the next '@node' command. To specify a node, write a |
| '@node' command at the beginning of a line, and follow it with the name |
| of the node. Each node contains the discussion of one topic. 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. |
| |
| Nodes are used as the targets of cross-references. Cross-references, |
| such as the one at the end of this sentence, are made with '@xref' and |
| related commands; see *note Cross References::. Cross-references can be |
| sprinkled throughout the text, and provide a way to represent links that |
| do not fit a hierarchical structure. |
| |
| Normally, you put a node command immediately before each chapter |
| structuring command--for example, an '@section' or '@subsection' line. |
| (*Note Chapter Structuring::.). You must do this even if you do not |
| intend to format the file for Info. This is because TeX uses both |
| '@node' names and chapter-structuring names in the output for |
| cross-references. 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: |
| |
| * Texinfo Document Structure:: Double structure of documents. |
| * Node Names:: How to choose node names. |
| * Writing a Node:: How to write an '@node' line. |
| * Node Line Requirements:: Keep names unique. |
| * First Node:: How to write a 'Top' node. |
| * @top Command:: How to use the '@top' command. |
| * Node Menu Illustration:: A diagram, and sample nodes and menus. |
| * makeinfo Pointer Creation:: Letting makeinfo determine node pointers. |
| * Menus:: Listing subordinate nodes. |
| |
| |
| File: texinfo.info, Node: Texinfo Document Structure, Next: Node Names, Up: Nodes |
| |
| 4.1 Texinfo Document Structure |
| ============================== |
| |
| Nodes can contain "menus", which contain the names of "child nodes" |
| 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 contain "node pointers" that name other nodes. |
| The 'Next' and 'Previous' pointers form nodes at the same sectioning |
| level into a chain. As you might imagine, the 'Next' pointer links to |
| the next node, and the 'Previous' pointer links to the previous node. |
| 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 the parent chapter. |
| Each child node records the parent node name as its 'Up' pointer. |
| |
| The Info and HTML output from 'makeinfo' for each node includes links |
| to the 'Next', 'Previous', and 'Up' nodes. The HTML also uses the |
| 'accesskey' attribute with the values 'n', 'p', and 'u' respectively. |
| This allows people using web browsers to follow the navigation using |
| (typically) 'M-LETTER', e.g., 'M-n' for the 'Next' node, from anywhere |
| within the node. 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. *Note Texinfo Document |
| Structure::. |
| |
| 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. |
| |
| 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 _not at all recommended_. To the best |
| of our knowledge, all the Texinfo manuals currently in general use do |
| follow the conventional parallel structure. |
| |
| |
| File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: Texinfo Document Structure, Up: Nodes |
| |
| 4.2 Choosing Node Names |
| ======================= |
| |
| The name of a node identifies the node. For all the details of node |
| names, *note Node Line Requirements::). |
| |
| Here are some suggestions for node names: |
| |
| * 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.) |
| |
| * 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. |
| |
| * 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. |
| |
| 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. *Note |
| HTML Xref Link Preservation::. |
| |
| 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 'makeinfo' can determine them (*note |
| 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 'dir' file, which contains the main menu for |
| all of Info. |
| |
| |
| File: texinfo.info, Node: Writing a Node, Next: Node Line Requirements, Prev: Node Names, Up: Nodes |
| |
| 4.3 Writing an '@node' Line |
| =========================== |
| |
| The easiest way to write an '@node' line is to write '@node' at the |
| beginning of a line and then the name of the node, like this: |
| |
| @node NODE-NAME |
| |
| After you have inserted an '@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. |
| |
| If you wish, you can ignore '@node' lines altogether in your first |
| draft and then use the 'texinfo-insert-node-lines' command to create |
| '@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. |
| |
| 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. |
| |
| You may optionally follow the node name argument to '@node' with up |
| to three optional arguments on the rest of the same line, separating the |
| arguments with commas. These are the names of the 'Next', 'Previous', |
| and 'Up' pointers, in that order. We recommend omitting them if your |
| Texinfo document is hierarchically organized, as virtually all are |
| (*note makeinfo Pointer Creation::). |
| |
| Any spaces before or after each name on the '@node' line are ignored. |
| |
| The template for a fully-written-out node line with 'Next', |
| 'Previous', and 'Up' pointers looks like this: |
| |
| @node NODE-NAME, NEXT, PREVIOUS, UP |
| |
| The 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: '@node mynode,,,uppernode'. However, we recommend |
| leaving off all the pointers and letting 'makeinfo' determine them. |
| |
| If you are using GNU Emacs, you can use the update node commands |
| provided by Texinfo mode to insert the names of the pointers; or |
| (recommended), you can leave the pointers out of the Texinfo file and |
| let 'makeinfo' insert node pointers into the Info file it creates. |
| (*Note Texinfo Mode::, and *note 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 'C-c C-c n'. This command inserts '@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. |
| |
| |
| File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Writing a Node, Up: Nodes |
| |
| 4.4 '@node' Line Requirements |
| ============================= |
| |
| Names used with '@node' have several requirements: |
| |
| * 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. |
| |
| * Node names can contain @-commands. The output is generally the |
| natural result of the command; for example, using '@TeX{}' in a |
| node name results in the TeX logo being output, as it would be in |
| normal text. Cross-references should use '@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, |
| '@TeX{}' expands to the three letters 'TeX' in the Info node name. |
| However, cross-references to the node should not take the |
| "shortcut" of using 'TeX'; stick to the actual node name, commands |
| and all. |
| |
| Some commands do not make sense in node names; for instance, |
| environments (e.g., '@quotation'), commands that read a whole line |
| as their argument (e.g., '@sp'), and plenty of others. |
| |
| For the complete list of commands that are allowed, and their |
| expansion for HTML identifiers and file names, *note 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 '--commands-in-node-names' option to |
| 'makeinfo'). Now it is part of the language. |
| |
| * 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 '(not)allowed', since this syntax is used to |
| specify an external manual. (Perhaps these limitations will be |
| removed some day.) |
| |
| '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 |
| 'INFO_SPECIAL_CHARS_WARNING' to '0' (*note 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 (*note Inserting a |
| Comma::) or '@asis' (*note @asis::). For example: |
| |
| @node foo@asis{::}bar |
| |
| As an example of avoiding the special characters, the following is |
| a section title in this manual: |
| |
| @section @code{@@unnumbered}, @code{@@appendix}: ... |
| |
| But the corresponding node name lacks the commas and the subtitle: |
| |
| @node @unnumbered @appendix |
| |
| * Case is significant in node names. |
| |
| * Spaces before and after names on the '@node' line are ignored. |
| Multiple whitespace characters "inside" a name are collapsed to a |
| single space. For example: |
| |
| @node foo bar |
| @node foo bar, |
| @node foo bar , |
| @node foo bar, |
| @node foo bar , |
| |
| all define the same node, namely 'foo bar'. In menu entries, this |
| is the name that should be used: no leading or trailing spaces, and |
| a single internal space. (For cross-references, the node name used |
| in the Texinfo sources is automatically normalized in this way.) |
| |
| * The next/previous/up pointers on '@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; *note makeinfo |
| Pointer Creation::.) |
| |
| |
| File: texinfo.info, Node: First Node, Next: @top Command, Prev: Node Line Requirements, Up: Nodes |
| |
| 4.5 The First Node |
| ================== |
| |
| The first node of a Texinfo file is the "Top" node, except in an |
| included file (*note Include Files::). The Top node should contain a |
| short summary, copying permissions, and a master menu. *Note 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: |
| |
| * The Top node (which must be named 'top' or '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 available through a single virtual Info |
| tree, constructed from multiple directories. In this case, use |
| '(dir)' as the parent of the Top node; this specifies the top-level |
| node in the 'dir' file, which contains the main menu for the Info |
| system as a whole. (Each directory with Info files is intended to |
| contain a file named 'dir'.) |
| |
| That's fine for Info, but for HTML output, one might well want the |
| Up link from the Top node to go somewhere other than 'dir.html'. |
| For example, for GNU the natural place would be |
| <http://www.gnu.org/manual/> (a web page collecting links to most |
| GNU manuals), better specified as just '/manual/' if the manual |
| will be installed on 'www.gnu.org'. This can be specified with the |
| 'TOP_NODE_UP_URL' customization variable (*note HTML Customization |
| Variables::), as in |
| |
| $ makeinfo --html -c TOP_NODE_UP_URL=/manual/ ... |
| |
| All links to '(dir)' will be replaced by the given url. |
| |
| * The 'Prev' node of the Top node is usually either omitted or also |
| set to '(dir)'. Either is fine. |
| |
| * The 'Next' node of the Top node should be the first chapter in your |
| document. |
| |
| *Note Installing an Info File::, for more information about |
| installing an Info file in the 'info' directory. |
| |
| It is usually best to leave the pointers off entirely and let the |
| tools implicitly define them, with this simple result: |
| |
| @node Top |
| |
| |
| File: texinfo.info, Node: @top Command, Next: Node Menu Illustration, Prev: First Node, Up: Nodes |
| |
| 4.6 The '@top' Sectioning Command |
| ================================= |
| |
| The '@top' command is a special sectioning command that you should only |
| use after a '@node Top' line at the beginning of a Texinfo file. The |
| '@top' command tells the 'makeinfo' formatter which node is to be used |
| as the root of the node tree. |
| |
| It produces the same sort of output as '@unnumbered' (*note |
| @unnumbered @appendix::). |
| |
| The '@top' node is conventionally wrapped in an '@ifnottex' |
| conditional so that it will not appear in TeX output (*note |
| Conditionals::). Thus, in practice, a Top node usually looks like this: |
| |
| @ifnottex |
| @node Top |
| @top YOUR-MANUAL-TITLE |
| |
| VERY-HIGH-LEVEL-SUMMARY |
| @end ifnottex |
| |
| '@top' is ignored when raising or lowering sections. That is, it is |
| never lowered and nothing can be raised to it (*note Raise/lower |
| sections::). |
| |
| |
| File: texinfo.info, Node: Node Menu Illustration, Next: makeinfo Pointer Creation, Prev: @top Command, Up: Nodes |
| |
| 4.7 Node and Menu Illustration |
| ============================== |
| |
| Here is a diagram 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. |
| |
| 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 |
| |
| Using explicit pointers (not recommended, but for shown for purposes |
| of the example), the fully-written command to start Chapter 2 would be |
| this: |
| |
| @node Chapter 2, Chapter 3, Chapter 1, Top |
| @comment node-name, next, previous, up |
| |
| This '@node' line says that the name of this node is "Chapter 2", the |
| name of the 'Next' node is "Chapter 3", the name of the 'Previous' node |
| is "Chapter 1", and the name of the 'Up' node is "Top". You can (and |
| should) omit writing out these node names if your document is |
| hierarchically organized (*note makeinfo Pointer Creation::), but the |
| pointer relationships still obtain. |
| |
| Note: 'Next' and 'Previous' refer to nodes at the _same |
| hierarchical level_ in the manual, not necessarily to the next node |
| within the Texinfo file. In the Texinfo file, the subsequent node |
| may be at a lower level--a section-level node 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.) |
| |
| To go to Sections 2.1 and 2.2 using Info, you need a menu inside |
| Chapter 2. (*Note Menus::.) You would write the menu just before the |
| beginning of Section 2.1, like this: |
| |
| @menu |
| * Sect. 2.1:: Description of this section. |
| * Sect. 2.2:: Description. |
| @end menu |
| |
| Using explicit pointers, the node for Sect. 2.1 is written like this: |
| |
| @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 |
| @comment node-name, next, previous, up |
| |
| 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 |
| *note Cross References::.) |
| |
| A '@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 '@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 '@node' line followed by an '@chapter' |
| line, and then by indexing lines. |
| |
| @node Ending a File |
| @chapter Ending a Texinfo File |
| @cindex Ending a Texinfo file |
| @cindex Texinfo file ending |
| @cindex File ending |
| |
| An earlier version of the manual used explicit node pointers. Here |
| is the beginning of the same chapter for that case. This shows an |
| '@node' line followed by a comment line, a '@chapter' line, and then by |
| indexing lines. |
| |
| @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 |
| ... |
| |
| |
| File: texinfo.info, Node: makeinfo Pointer Creation, Next: Menus, Prev: Node Menu Illustration, Up: Nodes |
| |
| 4.8 'makeinfo' Pointer Creation |
| =============================== |
| |
| The 'makeinfo' program can automatically determine node pointers for a |
| hierarchically organized document. This implicit node pointer creation |
| feature in 'makeinfo' relieves you from the need to update menus and |
| pointers manually or with Texinfo mode commands. (*Note Updating Nodes |
| and Menus::.) We highly recommend taking advantage of this. |
| |
| To do so, write your '@node' lines with just the name of the node: |
| |
| @node My Node |
| |
| You do not need to write out the 'Next', 'Previous', and 'Up' pointers. |
| |
| Then, you must write a sectioning command, such as '@chapter' or |
| '@section', on the line immediately following each truncated '@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' '@node' line with a line beginning |
| with '@top' to mark the top-level node in the file. *Note @top |
| Command::. |
| |
| If you use a detailed menu in your master menu (*note Master Menu |
| Parts::), mark it with the '@detailmenu ... @end detailmenu' |
| environment, or '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. |
| |
| |
| File: texinfo.info, Node: Menus, Prev: makeinfo Pointer Creation, Up: Nodes |
| |
| 4.9 Menus |
| ========= |
| |
| "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. |
| |
| * Menu: |
| |
| * Writing a Menu:: What is a menu? |
| * Menu Example:: Two and three part menu entries. |
| * Menu Location:: Menus go at the ends of nodes. |
| * Menu Parts:: A menu entry has three parts. |
| * Less Cluttered Menu Entry:: Two part menu entry. |
| * Other Info Files:: How to refer to a different Info file. |
| |
| |
| File: texinfo.info, Node: Writing a Menu, Next: Menu Example, Up: Menus |
| |
| 4.9.1 Writing a Menu |
| -------------------- |
| |
| A menu consists of a '@menu' command on a line by itself, followed by |
| menu entry lines or menu comment lines, and then followed by an '@end |
| menu' command on a line by itself. |
| |
| A menu looks like this: |
| |
| @menu |
| Larger Units of Text |
| |
| * Files:: All about handling files. |
| * Multiples: Buffers. Multiple buffers; editing |
| several files at once. |
| @end menu |
| |
| In a menu, every line that begins with an '* ' is a "menu entry". |
| (Note the space after the asterisk.) |
| |
| A line that does not start with an '* ' may also appear in a menu. |
| Such a line is not a menu entry but rather a "menu comment" line that |
| appears in the Info file. In the example above, the line 'Larger Units |
| of Text' is such a menu comment line; the two lines starting with '* ' |
| are menu entries. |
| |
| 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 'makeinfo' implicit pointer creation |
| feature (*note makeinfo Pointer Creation::) and GNU Emacs 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. |
| |
| 'makeinfo' can automatically generate menus in nodes for Info and |
| HTML output, based on the chapter structure of the document. To specify |
| that you want it to do this, place the line '@validatemenus off' near |
| the beginning of the document. |
| |
| In Info, a user selects a node with the 'm' ('Info-menu') command. |
| The menu entry name is what the user types after the 'm' command. In |
| the HTML output from 'makeinfo', the 'accesskey' attribute is used with |
| the values '1'...'9' for the first nine entries. This allows people |
| using web browsers to follow the first menu entries using (typically) |
| 'M-DIGIT', e.g., 'M-1' for the first entry. |
| |
| |
| File: texinfo.info, Node: Menu Example, Next: Menu Location, Prev: Writing a Menu, Up: Menus |
| |
| 4.9.2 A Menu Example |
| -------------------- |
| |
| A menu looks like this in Texinfo: |
| |
| @menu |
| * menu entry name: Node name. A short description. |
| * Node name:: This form is preferred. |
| @end menu |
| |
| This produces: |
| |
| * menu: |
| |
| * menu entry name: Node name. A short description. |
| * Node name:: This form is preferred. |
| |
| Here is an example as you might see it in a Texinfo file: |
| |
| @menu |
| Larger Units of Text |
| |
| * Files:: All about handling files. |
| * Multiples: Buffers. Multiple buffers; editing |
| several files at once. |
| @end menu |
| |
| This produces: |
| |
| * menu: |
| Larger Units of Text |
| |
| * Files:: All about handling files. |
| * Multiples: Buffers. Multiple buffers; editing |
| several files at once. |
| |
| In this example, the menu has two entries. 'Files' is both a menu |
| entry name and the name of the node referred to by that name. |
| 'Multiples' is the menu entry name; it refers to the node named |
| 'Buffers'. The line '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 'Files' or 'Buffers', |
| they must be the names of nodes in the same Info file (*note Referring |
| to Other Info Files: Other Info Files.). |
| |
| |
| File: texinfo.info, Node: Menu Location, Next: Menu Parts, Prev: Menu Example, Up: Menus |
| |
| 4.9.3 Menu Location |
| ------------------- |
| |
| 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 '@end menu' and the beginning of the next node. |
| |
| 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 '* ' will likely be |
| incorrectly handled. |
| |
| 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. |
| |
| |
| File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Menu Location, Up: Menus |
| |
| 4.9.4 The Parts of a Menu |
| ------------------------- |
| |
| A menu entry has three parts, only the second of which is required: |
| |
| 1. The menu entry name (optional). |
| |
| 2. The name of the node (required). |
| |
| 3. A description of the item (optional). |
| |
| The template for a generic menu entry looks like this (but see the |
| next section for one more possibility): |
| |
| * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION |
| |
| 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 |
| ('. '). |
| |
| 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. |
| |
| Space characters in a menu are preserved as-is in the Info output; |
| this allows you to format the menu as you wish. Unfortunately you must |
| type node names without any extra spaces or some versions of some Info |
| readers will not find the node (*note Node Line Requirements::). |
| |
| '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 'INFO_SPECIAL_CHARS_WARNING' to '0' |
| (*note Other Customization Variables::). |
| |
| |
| File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Other Info Files, Prev: Menu Parts, Up: Menus |
| |
| 4.9.5 Less Cluttered 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. |
| |
| For example, write |
| |
| * Name:: DESCRIPTION |
| |
| instead of |
| |
| * Name: Name. DESCRIPTION |
| |
| We recommend using the node name for the menu entry name whenever |
| possible, since it reduces visual clutter in the menu. |
| |
| |
| File: texinfo.info, Node: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus |
| |
| 4.9.6 Referring to Other Info Files |
| ----------------------------------- |
| |
| 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: |
| |
| @menu |
| * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION |
| * (FILENAME)SECOND-NODE:: DESCRIPTION |
| @end menu |
| |
| For example, to refer directly to the 'Outlining' and 'Rebinding' |
| nodes in the 'Emacs Manual', you could write a menu like this: |
| |
| @menu |
| * Outlining: (emacs)Outline Mode. The major mode for |
| editing outlines. |
| * (emacs)Rebinding:: How to redefine the |
| meaning of a key. |
| @end menu |
| |
| 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: |
| |
| * Info: (info). Documentation browsing system. |
| * (emacs):: The extensible, self-documenting |
| text editor. |
| |
| The GNU Emacs Texinfo mode menu updating commands only work with |
| nodes within the current buffer, so you cannot use them to create menus |
| that refer to other files. You must write such menus by hand. |
| |
| |
| File: texinfo.info, Node: Chapter Structuring, Next: Cross References, Prev: Nodes, Up: Top |
| |
| 5 Chapter Structuring |
| ********************* |
| |
| Texinfo's "chapter structuring" commands 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 (*note |
| Generating a Table of Contents: Contents.). |
| |
| Normally you put a '@node' command immediately before each chapter |
| structuring command. *Note Nodes::. |
| |
| * Menu: |
| |
| * Tree Structuring:: A manual is like an upside down tree ... |
| * Structuring Command Types:: How to divide a manual into parts. |
| * @chapter:: Chapter structuring. |
| * @unnumbered @appendix:: |
| * @majorheading @chapheading:: |
| * @section:: |
| * @unnumberedsec @appendixsec @heading:: |
| * @subsection:: |
| * @unnumberedsubsec @appendixsubsec @subheading:: |
| * @subsubsection:: Commands for the lowest level sections. |
| * @part:: Collections of chapters. |
| * Raise/lower sections:: How to change commands' hierarchical level. |
| |
| |
| File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Up: Chapter Structuring |
| |
| 5.1 Tree Structure of Sections |
| ============================== |
| |
| 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. |
| |
| 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 |
| |
| |
| In a Texinfo file that has this structure, the beginning of Chapter 2 |
| would be written like this: |
| |
| @node Chapter 2 |
| @chapter Chapter 2 |
| |
| For purposes of example, here is how it would be written with explicit |
| node pointers: |
| |
| @node Chapter 2, Chapter 3, Chapter 1, Top |
| @chapter Chapter 2 |
| |
| The chapter structuring commands are described in the sections that |
| follow; the '@node' command is described in the previous chapter (*note |
| Nodes::). |
| |
| |
| File: texinfo.info, Node: Structuring Command Types, Next: @chapter, Prev: Tree Structuring, Up: Chapter Structuring |
| |
| 5.2 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 '@chapter' series, the |
| '@unnumbered' series, the '@appendix' series, and the '@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: |
| |
| * The '@chapter' and '@appendix' series of commands produce numbered |
| or lettered entries both in the body of a document and in its table |
| of contents. |
| |
| * The '@unnumbered' series of commands produce unnumbered entries |
| both in the body of a document and in its table of contents. The |
| '@top' command, which has a special use, is a member of this series |
| (*note @top Command::). An '@unnumbered' section is a normal part |
| of the document structure. |
| |
| * The '@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. |
| |
| When a '@setchapternewpage' command says to do so, the '@chapter', |
| '@unnumbered', and '@appendix' commands start new pages in the printed |
| manual; the '@heading' commands do not. *Note @setchapternewpage::. |
| |
| Here is a summary: |
| |
| No new page |
| Numbered Unnumbered Lettered/numbered Unnumbered |
| In contents In contents In contents Not in |
| contents |
| '@top' '@majorheading' |
| '@chapter' '@unnumbered' '@appendix' '@chapheading' |
| '@section' '@unnumberedsec' '@appendixsec' '@heading' |
| '@subsection' '@unnumberedsubsec' '@appendixsubsec' '@subheading' |
| '@subsubsection''@unnumberedsubsubsec''@appendixsubsubsec' '@subsubheading' |
| |
| |
| File: texinfo.info, Node: @chapter, Next: @unnumbered @appendix, Prev: Structuring Command Types, Up: Chapter Structuring |
| |
| 5.3 '@chapter': Chapter Structuring |
| =================================== |
| |
| '@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 1. |
| |
| For example, the present chapter in this manual is entitled |
| "'@chapter': Chapter Structuring"; the '@chapter' line looks like this: |
| |
| @chapter @code{@@chapter}: Chapter Structuring |
| |
| In TeX, the '@chapter' command produces a chapter heading in the |
| document. |
| |
| In Info and plain text output, the '@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: |
| |
| 5 Chapter Structuring |
| ********************* |
| |
| In HTML, the '@chapter' command produces an '<h2>'-level header by |
| default (controlled by the 'CHAPTER_HEADER_LEVEL' customization |
| variable, *note Other Customization Variables::). |
| |
| In the XML and Docbook output, a '<chapter>' element is produced that |
| includes all the following sections, up to the next chapter. |
| |
| |
| File: texinfo.info, Node: @unnumbered @appendix, Next: @majorheading @chapheading, Prev: @chapter, Up: Chapter Structuring |
| |
| 5.4 '@unnumbered', '@appendix': Chapters with Other Labeling |
| ============================================================ |
| |
| Use the '@unnumbered' command to start a chapter-level element that |
| appears without chapter numbers of any kind. Use the '@appendix' |
| command to start an appendix that is labeled by letter ('A', 'B', ...) |
| instead of by number; appendices are also at the chapter level of |
| structuring. |
| |
| Write an '@appendix' or '@unnumbered' command at the beginning of a |
| line and follow it on the same line by the title, just as with |
| '@chapter'. |
| |
| Texinfo also provides a command '@centerchap', which is analogous to |
| '@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. |
| |
| With '@unnumbered', if the name of the associated node is one of |
| these English words (case-insensitive): |
| |
| Acknowledgements Colophon Dedication Preface |
| |
| then the Docbook output uses corresponding special tags ('<preface>', |
| etc.) instead of the default '<chapter>'. The argument to '@unnumbered' |
| itself can be anything, and is output as the following '<title>' text as |
| usual. |
| |
| |
| File: texinfo.info, Node: @majorheading @chapheading, Next: @section, Prev: @unnumbered @appendix, Up: Chapter Structuring |
| |
| 5.5 '@majorheading', '@chapheading': Chapter-level Headings |
| =========================================================== |
| |
| The '@majorheading' and '@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, a '@majorheading' command generates a larger vertical |
| whitespace before the heading than a '@chapheading' command but is |
| otherwise the same. |
| |
| In Info and plain text, the '@majorheading' and '@chapheading' |
| commands produce the same output as '@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. *Note @chapter::. |
| |
| |
| File: texinfo.info, Node: @section, Next: @unnumberedsec @appendixsec @heading, Prev: @majorheading @chapheading, Up: Chapter Structuring |
| |
| 5.6 '@section': Sections Below Chapters |
| ======================================= |
| |
| An '@section' command identifies a section within a chapter unit, |
| whether created with '@chapter', '@unnumbered', or '@appendix', |
| following the numbering scheme of the chapter-level command. Thus, |
| within a '@chapter' chapter numbered '1', the sections are numbered |
| '1.1', '1.2', etc.; within an '@appendix' "chapter" labeled 'A', the |
| sections are numbered 'A.1', 'A.2', etc.; within an '@unnumbered' |
| chapter, the section gets no number. The output is underlined with '=' |
| in Info and plain text. |
| |
| To make a section, write the '@section' command at the beginning of a |
| line and follow it on the same line by the section title. For example, |
| |
| @section This is a section |
| |
| might produce the following in Info: |
| |
| 5.7 This is a section |
| ===================== |
| |
| 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"; *note @chapter::. |
| |
| |
| File: texinfo.info, Node: @unnumberedsec @appendixsec @heading, Next: @subsection, Prev: @section, Up: Chapter Structuring |
| |
| 5.7 '@unnumberedsec', '@appendixsec', '@heading' |
| ================================================ |
| |
| The '@unnumberedsec', '@appendixsec', and '@heading' commands are, |
| respectively, the unnumbered, appendix-like, and heading-like |
| equivalents of the '@section' command (see the previous section). |
| |
| '@unnumberedsec' and '@appendixsec' do not need to be used in |
| ordinary circumstances, because '@section' may also be used within |
| '@unnumbered' and '@appendix' chapters; again, see the previous section. |
| |
| '@unnumberedsec' |
| The '@unnumberedsec' command may be used within an unnumbered |
| chapter or within a regular chapter or appendix to produce an |
| unnumbered section. |
| |
| '@appendixsec' |
| '@appendixsection' |
| '@appendixsection' is a longer spelling of the '@appendixsec' |
| command; the two are synonymous. |
| |
| Conventionally, the '@appendixsec' or '@appendixsection' command is |
| used only within appendices. |
| |
| '@heading' |
| You may use the '@heading' command (almost) anywhere for a |
| section-style heading that will not appear in the table of |
| contents. The '@heading'-series commands can appear inside most |
| environments, for example, though pathological and useless |
| locations such as inside '@titlepage', as an argument to another |
| command, etc., are not allowed. |
| |
| |
| File: texinfo.info, Node: @subsection, Next: @unnumberedsubsec @appendixsubsec @subheading, Prev: @unnumberedsec @appendixsec @heading, Up: Chapter Structuring |
| |
| 5.8 '@subsection': Subsections Below Sections |
| ============================================= |
| |
| Subsections are to sections as sections are to chapters; *note |
| @section::. In Info and plain text, subsection titles are underlined |
| with '-'. For example, |
| |
| @subsection This is a subsection |
| |
| might produce |
| |
| 1.2.3 This is a subsection |
| -------------------------- |
| |
| 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"; *note @chapter::. |
| |
| |
| File: texinfo.info, Node: @unnumberedsubsec @appendixsubsec @subheading, Next: @subsubsection, Prev: @subsection, Up: Chapter Structuring |
| |
| 5.9 The '@subsection'-like Commands |
| =================================== |
| |
| The '@unnumberedsubsec', '@appendixsubsec', and '@subheading' commands |
| are, respectively, the unnumbered, appendix-like, and heading-like |
| equivalents of the '@subsection' command. (*Note @subsection::.) |
| |
| '@unnumberedsubsec' and '@appendixsubsec' do not need to be used in |
| ordinary circumstances, because '@subsection' may also be used within |
| sections of '@unnumbered' and '@appendix' chapters (*note @section::). |
| |
| An '@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 '@unnumberedsubsec' command produces an |
| unnumbered heading like that of a subsection and an '@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 '@subsection'-like |
| commands generate a title underlined with hyphens. |
| |
| |
| File: texinfo.info, Node: @subsubsection, Next: @part, Prev: @unnumberedsubsec @appendixsubsec @subheading, Up: Chapter Structuring |
| |
| 5.10 '@subsection' and Other Subsub Commands |
| ============================================ |
| |
| The fourth and lowest level sectioning commands in Texinfo are the |
| 'subsub' commands. They are: |
| |
| '@subsubsection' |
| Subsubsections are to subsections as subsections are to sections. |
| (*Note @subsection::.) Subsubsection titles appear in the table of |
| contents. |
| |
| '@unnumberedsubsubsec' |
| Unnumbered subsubsection titles appear in the table of contents, |
| but lack numbers. Otherwise, unnumbered subsubsections are the |
| same as subsubsections. |
| |
| '@appendixsubsubsec' |
| Conventionally, appendix commands are used only for appendices and |
| are lettered and numbered appropriately. They also appear in the |
| table of contents. |
| |
| '@subsubheading' |
| The '@subsubheading' command may be used anywhere that you want a |
| small heading that will not appear in the table of contents. |
| |
| As with subsections, '@unnumberedsubsubsec' and '@appendixsubsubsec' |
| do not need to be used in ordinary circumstances, because |
| '@subsubsection' may also be used within subsections of '@unnumbered' |
| and '@appendix' chapters (*note @section::). |
| |
| In Info, 'subsub' titles are underlined with periods. For example, |
| |
| @subsubsection This is a subsubsection |
| |
| might produce |
| |
| 1.2.3.4 This is a subsubsection |
| ............................... |
| |
| The TeX, HTML, Docbook, and XML output is all analogous to the |
| chapter-level output, just "three levels down"; *note @chapter::. |
| |
| |
| File: texinfo.info, Node: @part, Next: Raise/lower sections, Prev: @subsubsection, Up: Chapter Structuring |
| |
| 5.11 '@part': Groups of Chapters |
| ================================ |
| |
| The final sectioning command is '@part', to mark a "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 '@node' command is associated with '@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: |
| |
| @part Part I:@* The beginning |
| |
| As can be inferred from this example, no automatic numbering or |
| labeling of the '@part' text is done. The text is taken as-is. |
| |
| Because parts are not associated with nodes, no general text can |
| follow the '@part' line. To produce the intended output, it must be |
| followed by a chapter-level command (including its node). Thus, to |
| continue the example: |
| |
| @part Part I:@* The beginning |
| |
| @node Introduction |
| @chapter Introduction |
| ... |
| |
| In the TeX output, the '@part' text is included in both the normal |
| and short tables of contents (*note 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 '@part' text. In the |
| example above, the '@*' 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 (*note @setchapternewpage::). |
| |
| In the HTML output, the '@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 '<part>' element includes all the |
| following chapters, up to the next '<part>'. A '<part>' containing |
| chapters is also closed at an appendix. |
| |
| In the Info and plain text output, '@part' has no effect. |
| |
| '@part' is ignored when raising or lowering sections (see next |
| section). That is, it is never lowered and nothing can be raised to it. |
| |
| |
| File: texinfo.info, Node: Raise/lower sections, Prev: @part, Up: Chapter Structuring |
| |
| 5.12 Raise/lower Sections: '@raisesections' and '@lowersections' |
| ================================================================ |
| |
| The '@raisesections' and '@lowersections' commands implicitly raise and |
| lower the hierarchical level of following chapters, sections and the |
| other sectioning commands (excluding parts). |
| |
| That is, the '@raisesections' command changes sections to chapters, |
| subsections to sections, and so on. Conversely, the '@lowersections' |
| command changes chapters to sections, sections to subsections, and so |
| on. Thus, a '@lowersections' command cancels a '@raisesections' |
| command, and vice versa. |
| |
| You can use '@lowersections' to include text written as an outer or |
| standalone Texinfo file in another Texinfo file as an inner, included |
| file (*note Include Files::). Typical usage looks like this: |
| |
| @lowersections |
| @include somefile.texi |
| @raisesections |
| |
| (Without the '@raisesections', all the subsequent sections in the main |
| file would also be lowered.) |
| |
| If the included file being lowered has a '@top' node, you'll need to |
| conditionalize its inclusion with a flag (*note @set @value::). |
| |
| As a practical matter, you generally only want to raise or lower |
| large chunks, usually in external files as shown above. The final |
| result has to have menus that take the raising and lowering into |
| account, so you cannot just arbitrarily sprinkle '@raisesections' and |
| '@lowersections' commands throughout the document. |
| |
| 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 'makeinfo''s |
| feature of implicitly determining node pointers, since the menu |
| structure cannot be represented correctly. |
| |
| Write each '@raisesections' and '@lowersections' command on a line of |
| its own. |
| |
| |
| File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Chapter Structuring, Up: Top |
| |
| 6 Cross-references |
| ****************** |
| |
| "Cross-references" are used to refer the reader to other parts of the |
| same or different Texinfo files. |
| |
| * Menu: |
| |
| * References:: What cross-references are for. |
| * Cross Reference Commands:: A summary of the different commands. |
| * Cross Reference Parts:: A cross-reference has several parts. |
| * @xref:: Begin a reference with 'See' ... |
| * Referring to a Manual as a Whole:: Refer to an entire manual. |
| * @ref:: A reference for the last part of a sentence. |
| * @pxref:: How to write a parenthetical cross-reference. |
| * @anchor:: Defining arbitrary cross-reference targets |
| * @inforef:: How to refer to an Info-only file. |
| * @url:: How to refer to a uniform resource locator. |
| * @cite:: How to refer to books not in the Info system. |
| |
| |
| File: texinfo.info, Node: References, Next: Cross Reference Commands, Up: Cross References |
| |
| 6.1 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 'f' command. (*Note |
| Following cross-references: (info)Help-Xref.) In HTML, a |
| cross-reference results in an hyperlink. |
| |
| The various cross-reference commands use nodes (or anchors, *note |
| @anchor::) to define cross-reference locations. TeX needs nodes to |
| define cross-reference locations. 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 '@node' lines |
| in order to name the places to which you make cross-references. |
| |
| |
| File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References |
| |
| 6.2 Different Cross-reference Commands |
| ====================================== |
| |
| There are three different cross-reference commands: |
| |
| '@xref' |
| Used to start a sentence in the printed manual and in HTML with |
| 'See ...' or an Info cross-reference saying '*Note NAME: NODE.'. |
| |
| '@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 '@xref' for Info). |
| |
| '@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 |
| '*note' in Info. ('p' is for 'parenthesis'.) |
| |
| Additionally, there are commands to produce references to documents |
| outside the Texinfo system. The '@cite' command is used to make |
| references to books and manuals. '@url' produces a URL, for example a |
| reference to a page on the World Wide Web. '@inforef' is used to make a |
| reference to an Info file for which there is no printed manual. |
| |
| |
| File: texinfo.info, Node: Cross Reference Parts, Next: @xref, Prev: Cross Reference Commands, Up: Cross References |
| |
| 6.3 Parts of a Cross-reference |
| ============================== |
| |
| A cross-reference command requires only one argument, which is the name |
| of the node to which it refers. Here is a simple example: |
| |
| @xref{Node name}. |
| |
| In Info output, this produces |
| |
| *Note Node name::. |
| |
| In a printed manual, the output is |
| |
| See Section NNN [Node name], page PPP. |
| |
| 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 (*note |
| Referring to a Manual as a Whole::). |
| |
| Here is an example of a full five-part cross-reference: |
| |
| @xref{Node name, Online Label, Printed Label, |
| info-file-name, A Printed Manual}, for details. |
| |
| which produces |
| |
| *Note Online Label: (info-file-name)Node name, |
| for details. |
| |
| in Info and |
| |
| See section "Printed Label" in A Printed Manual, for details. |
| |
| in a printed book. |
| |
| The five possible arguments for a cross-reference are: |
| |
| 1. 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. Use |
| '@node' to define the node (*note Writing a Node::), or '@anchor' |
| (*note @anchor::). |
| |
| Write a node name in a cross-reference in exactly the same way as |
| in the '@node' line, including the same capitalization; otherwise, |
| the formatters may not find the reference. |
| |
| 2. A label for online output. 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. |
| |
| 3. A label for printed output. Often, this is the title or topic of |
| the section. This is used as the name of the reference in the |
| printed manual. If omitted, the node name is used. |
| |
| 4. 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. |
| |
| 5. The name of a printed manual from a different Texinfo file. |
| |
| The template for a full five argument cross-reference looks like |
| this: |
| |
| @xref{NODE-NAME, ONLINE-LABEL, PRINTED-LABEL, |
| INFO-FILE-NAME, PRINTED-MANUAL-TITLE} |
| |
| Whitespace before and after the commas separating these arguments is |
| ignored. To include a comma in one of the arguments, use '@comma{}' |
| (*note Inserting a Comma::). |
| |
| When processing with TeX, a comma is automatically inserted after the |
| page number for cross-references to within the same manual, unless the |
| closing brace of the argument is followed by non-whitespace (such as a |
| comma or period). This gives you the choice of whether to have a comma |
| there in Info or HTML output. For example, |
| |
| @xref{Another Section} for more information |
| |
| produces 'See Another Section, page PPP, for more information' in the |
| printed output, and '*Note Another Section:: for more information' in |
| the Info output. |
| |
| If an unwanted comma is added, follow the argument with a command |
| such as '@:'. For example, '@xref{Hurricanes}@: --- for the details' |
| produces |
| |
| See Hurricanes, page PPP -- for the details |
| |
| instead of 'See Hurricanes, page PPP, -- for the details'. |
| |
| Cross-references with one, two, three, four, and five arguments are |
| described separately following the description of '@xref'. |
| |
| '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 'INFO_SPECIAL_CHARS_WARNING' to '0' |
| (*note Other Customization Variables::). |
| |
| |
| File: texinfo.info, Node: @xref, Next: Referring to a Manual as a Whole, Prev: Cross Reference Parts, Up: Cross References |
| |
| 6.4 '@xref' |
| =========== |
| |
| The '@xref' command generates a cross-reference for the beginning of a |
| sentence. |
| |
| * Menu: |
| |
| * One Argument:: '@xref' with one argument. |
| * Two Arguments:: '@xref' with two arguments. |
| * Three Arguments:: '@xref' with three arguments. |
| * Four and Five Arguments:: '@xref' with four and five arguments. |
| |
| |
| File: texinfo.info, Node: One Argument, Next: Two Arguments, Up: @xref |
| |
| 6.4.1 '@xref' with One Argument |
| ------------------------------- |
| |
| The simplest form of '@xref' takes one argument, the name of another |
| node in the same Texinfo file. |
| |
| For example, |
| |
| @xref{Tropical Storms}. |
| |
| produces |
| |
| *Note Tropical Storms::. |
| |
| in Info and |
| |
| See Section 3.1 [Tropical Storms], page 24. |
| |
| in a printed manual. |
| |
| |
| File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: @xref |
| |
| 6.4.2 '@xref' with Two Arguments |
| -------------------------------- |
| |
| With two arguments, the second is used as a label for the online output. |
| |
| The template is like this: |
| |
| @xref{NODE-NAME, ONLINE-LABEL}. |
| |
| For example, |
| |
| @xref{Electrical Effects, Lightning}. |
| |
| produces: |
| |
| *Note Lightning: Electrical Effects. |
| |
| in Info and |
| |
| See Section 5.2 [Electrical Effects], page 57. |
| |
| in a printed manual, where the node name is printed. |
| |
| The second argument to cross-references must observe some of the |
| restrictions for node names (*note Node Line Requirements::). The most |
| common issue is that colons cannot be used, since that interferes with |
| the parsing of the Info file. |
| |
| |
| File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: @xref |
| |
| 6.4.3 '@xref' with Three Arguments |
| ---------------------------------- |
| |
| A third argument replaces the node name in the TeX output. The third |
| argument should be the name of the section in the printed output, or |
| else state the topic discussed by that section. |
| |
| The template is like this: |
| |
| @xref{NODE-NAME, ONLINE-LABEL, PRINTED-LABEL}. |
| |
| For example, |
| |
| @xref{Electrical Effects, Lightning, Thunder and Lightning}, |
| for details. |
| |
| produces |
| |
| *Note Lightning: Electrical Effects, for details. |
| |
| in Info and |
| |
| See Section 5.2 [Thunder and Lightning], page 57, for details. |
| |
| 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.) |
| |
| @xref{Electrical Effects, , Thunder and Lightning}, |
| for details. |
| |
| produces |
| |
| *Note Thunder and Lightning: Electrical Effects, for details. |
| |
| in Info and |
| |
| See Section 5.2 [Thunder and Lightning], page 57, for details. |
| |
| in a printed manual. |
| |
| The third argument to cross-references must observe some of the |
| restrictions for node names (*note 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. |
| |
| 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): |
| |
| @xrefautomaticsectiontitle on |
| |
| 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 |
| ('@xrefautomaticsectiontitle off'), for example, if you're including |
| some other sub-document that doesn't have suitable section names. |
| |
| |
| File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: @xref |
| |
| 6.4.4 '@xref' with Four and Five Arguments |
| ------------------------------------------ |
| |
| In a cross-reference, a fourth argument specifies the name of another |
| Info file, different from the file in which the reference appears, and a |
| fifth argument specifies its title as a printed manual. |
| |
| The full template is: |
| |
| @xref{NODE-NAME, ONLINE-LABEL, PRINTED-LABEL, |
| INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. |
| |
| For example, |
| |
| @xref{Electrical Effects, Lightning, Thunder and Lightning, |
| weather, An Introduction to Meteorology}. |
| |
| produces this output in Info: |
| |
| *Note Lightning: (weather)Electrical Effects. |
| |
| As you can see, the name of the Info file is enclosed in parentheses and |
| precedes the name of the node. |
| |
| In a printed manual, the reference looks like this: |
| |
| See section "Thunder and Lightning" in 'An Introduction to |
| Meteorology'. |
| |
| The title of the printed manual is typeset like '@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 '@xref'. In this case, the third argument, the |
| topic description, will be used as the cross-reference name in Info. |
| For example, |
| |
| @xref{Electrical Effects, , Thunder and Lightning, |
| weather, An Introduction to Meteorology}. |
| |
| produces |
| |
| *Note Thunder and Lightning: (weather)Electrical Effects. |
| |
| in Info and |
| |
| See section "Thunder and Lightning" in 'An Introduction to |
| Meteorology'. |
| |
| 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, |
| |
| @xref{Electrical Effects,,, |
| weather, An Introduction to Meteorology}. |
| |
| produces |
| |
| *Note (weather)Electrical Effects::. |
| |
| in Info and |
| |
| See section "Electrical Effects" in 'An Introduction to |
| Meteorology'. |
| |
| 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 _except_ |
| the fourth and fifth, to refer to another manual as a whole. See the |
| next section. |
| |
| |
| File: texinfo.info, Node: Referring to a Manual as a Whole, Next: @ref, Prev: @xref, Up: Cross References |
| |
| 6.5 Referring to a Manual as a Whole |
| ==================================== |
| |
| 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 (*note Four and Five |
| Arguments::), if the first argument is either '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 'Top' if it was given.) For example, |
| |
| @xref{Top,,, make, The GNU Make Manual}. |
| |
| produces |
| |
| *Note (make)Top::. |
| |
| and |
| |
| See 'The GNU Make Manual'. |
| |
| 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 '@xref' command. Using this idiom, to make a |
| cross-reference to 'The GNU Make Manual', you would write: |
| |
| @xref{Top,, Overview, make, The GNU Make Manual}. |
| |
| which produces |
| |
| *Note Overview: (make)Top. |
| |
| in Info and |
| |
| See section "Overview" in 'The GNU Make Manual'. |
| |
| in a printed manual. |
| |
| In this example, 'Top' is the name of the first node, and '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. |
| |
| |
| File: texinfo.info, Node: @ref, Next: @pxref, Prev: Referring to a Manual as a Whole, Up: Cross References |
| |
| 6.6 '@ref' |
| ========== |
| |
| '@ref' is nearly the same as '@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. |
| |
| For example, |
| |
| For more information, @pxref{This}, and @ref{That}. |
| |
| produces in Info: |
| |
| For more information, *note This::, and *note That::. |
| |
| and in printed output: |
| |
| For more information, see Section 1.1 [This], page 1, and Section |
| 1.2 [That], page 2. |
| |
| The '@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: |
| |
| Sea surges are described in @ref{Hurricanes}. |
| |
| looks ok in the printed output: |
| |
| Sea surges are described in Section 6.7 [Hurricanes], page 72. |
| |
| but is awkward to read in Info, "note" being a verb: |
| |
| Sea surges are described in *note Hurricanes::. |
| |
| |
| File: texinfo.info, Node: @pxref, Next: @anchor, Prev: @ref, Up: Cross References |
| |
| 6.7 '@pxref' |
| ============ |
| |
| The parenthetical reference command, '@pxref', is nearly the same as |
| '@xref', but it is best used at the end of a sentence or before a |
| closing parenthesis. The command differs from '@xref' in that TeX |
| typesets the reference for the printed manual with a lowercase 'see' |
| rather than an uppercase 'See'. |
| |
| With one argument, a parenthetical cross-reference looks like this: |
| |
| ... storms cause flooding (@pxref{Hurricanes}) ... |
| |
| which produces |
| |
| ... storms cause flooding (*note Hurricanes::) ... |
| |
| in Info and |
| |
| ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) |
| ... |
| |
| in a printed manual. |
| |
| With two arguments, a parenthetical cross-reference has this |
| template: |
| |
| ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ... |
| |
| which produces |
| |
| ... (*note CROSS-REFERENCE-NAME: NODE-NAME.) ... |
| |
| in Info and |
| |
| ... (see Section NNN [NODE-NAME], page PPP) ... |
| |
| in a printed manual. |
| |
| '@pxref' can be used with up to five arguments, just like '@xref' |
| (*note @xref::). |
| |
| In past versions of Texinfo, it was not allowed to write punctuation |
| after a '@pxref', so it could be used _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: |
| |
| ... For more information, @pxref{More}. |
| |
| which outputs (in Info): |
| |
| ... For more information, *note More::. |
| |
| As a matter of style, '@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. |
| |
| |
| File: texinfo.info, Node: @anchor, Next: @inforef, Prev: @pxref, Up: Cross References |
| |
| 6.8 '@anchor': Defining Arbitrary Cross-reference Targets |
| ========================================================= |
| |
| An "anchor" is a position in your document, labelled so that |
| cross-references can refer to it, just as they can to nodes. You create |
| an anchor with the '@anchor' command, and give the label as a normal |
| brace-delimited argument. For example: |
| |
| This marks the @anchor{x-spot}spot. |
| ... |
| @xref{x-spot,,the spot}. |
| |
| produces: |
| |
| This marks the spot. |
| ... |
| See [the spot], page 1. |
| |
| As you can see, the '@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 '@xref' or other cross reference |
| command, as shown (*note Cross References::). |
| |
| It is best to put '@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 '@anchor' command on |
| a line by itself if that helps readability of the source. Whitespace |
| (including newlines) is ignored after '@anchor'. |
| |
| Anchor names and node names may not conflict. Anchors and nodes are |
| given similar treatment in some ways; for example, the 'goto-node' |
| command takes either an anchor name or a node name as an argument. |
| (*Note (info)Go to node::.) |
| |
| Also like node names, anchor names cannot include some characters |
| (*note Node Line Requirements::). |
| |
| Because of this duality, when you delete or rename a node, it is |
| usually a good idea to define an '@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 |
| 'RENAMED_NODES_FILE' feature of 'makeinfo' (*note 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. |
| |
| |
| File: texinfo.info, Node: @inforef, Next: @url, Prev: @anchor, Up: Cross References |
| |
| 6.9 '@inforef': Cross-references to Info-only Material |
| ====================================================== |
| |
| '@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 '@ifinfo' text (*note 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: |
| |
| 1. The node name. |
| |
| 2. The cross-reference name (optional). |
| |
| 3. The Info file name. |
| |
| The template is: |
| |
| @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME} |
| |
| For example, |
| |
| @inforef{Advanced, Advanced Info commands, info}, |
| for more information. |
| |
| produces (in Info): |
| |
| *Note Advanced Info commands: (info)Advanced, |
| for more information. |
| |
| and (in the printed output): |
| |
| See Info file 'info', node 'Advanced', for more information. |
| |
| (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 '@inforef' is '@cite', which is used to refer to |
| printed works for which no Info form exists. *Note @cite::. |
| |
| |
| File: texinfo.info, Node: @url, Next: @cite, Prev: @inforef, Up: Cross References |
| |
| 6.10 '@url', '@uref{URL[, TEXT][, REPLACEMENT]}' |
| ================================================ |
| |
| '@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 and PDF output, '@uref' |
| produces a link you can follow. (To merely indicate a url without |
| creating a link people can follow, use '@indicateurl', *note |
| @indicateurl::.) |
| |
| '@url' is a synonym for '@uref'. (Originally, '@url' had the meaning |
| of '@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, DVI, and PDF output, but not in |
| HTML output, the url is output in addition to this text. |
| |
| 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. Also, if the |
| third argument is given, the second argument is ignored. |
| |
| * Menu: |
| |
| * @url Examples:: Examples of using all the forms of '@url'. |
| * URL Line Breaking:: How lines are broken within '@url' text. |
| * @url PDF Output Format:: A special option to hide links in PDF output. |
| * PDF Colors:: Colorizing urls and other links in PDF output. |
| |
| |
| File: texinfo.info, Node: @url Examples, Next: URL Line Breaking, Up: @url |
| |
| 6.10.1 '@url' Examples |
| ---------------------- |
| |
| First, here is an example of the simplest form of '@url', with just one |
| argument. The given url is both the target and the visible text of the |
| link: |
| |
| The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}. |
| |
| produces: |
| The official GNU ftp site is <http://ftp.gnu.org/gnu>. |
| |
| Two-argument form of '@url' |
| ........................... |
| |
| Here is an example of the two-argument form: |
| The official @uref{http://ftp.gnu.org/gnu, GNU ftp site} |
| holds programs and texts. |
| |
| which produces: |
| The official GNU ftp site (http://ftp.gnu.org/gnu) |
| holds programs and texts. |
| |
| that is, the Info (and TeX, etc.) output is this: |
| The official GNU ftp site (http://ftp.gnu.org/gnu) |
| holds programs and texts. |
| |
| while the HTML output is this: |
| The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a> |
| holds programs and texts. |
| |
| Three-argument form of '@url' |
| ............................. |
| |
| Finally, an example of the three-argument form: |
| The @uref{/man.cgi/1/ls,,ls} program ... |
| |
| which, except for HTML, produces: |
| The ls program ... |
| |
| but with HTML: |
| The <a href="/man.cgi/1/ls">ls</a> program ... |
| |
| By the way, some people prefer to display urls in the unambiguous |
| format: |
| |
| <URL:http://HOST/PATH> |
| |
| You can use this form in the input file if you wish. We feel it's not |
| necessary to include the '<URL:' and '>' in the output, since to be |
| useful any software that tries to detect urls in text already has to |
| detect them without the '<URL:'. |
| |
| |
| File: texinfo.info, Node: URL Line Breaking, Next: @url PDF Output Format, Prev: @url Examples, Up: @url |
| |
| 6.10.2 URL Line Breaking |
| ------------------------ |
| |
| TeX allows line breaking within urls at only a few characters (which are |
| special in urls): '&', '.', '#', '?', and '/' (but not between two '/' |
| 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 '@/' as needed (*note Line Breaks::). |
| |
| By default, in TeX any such breaks at special characters will occur |
| after the character. Some people prefer such breaks to happen before |
| the special character. This can be controlled with the |
| '@urefbreakstyle' command (this command has effect only in TeX): |
| |
| @urefbreakstyle HOW |
| |
| where the argument HOW is one of these words: |
| |
| 'after' |
| (the default) Potentially break after the special characters. |
| 'before' |
| Potentially break before the special characters. |
| 'none' |
| Do not consider breaking at the special characters at all; any |
| potential breaks must be manually inserted. |
| |
| |
| File: texinfo.info, Node: @url PDF Output Format, Next: PDF Colors, Prev: URL Line Breaking, Up: @url |
| |
| 6.10.3 '@url' PDF Output Format |
| ------------------------------- |
| |
| If the ultimate purpose of a PDF is only to be viewed online, perhaps |
| similar to HTML in some inchoate way, you may not want the urls to be |
| included in the visible text (just as urls are not visible to readers of |
| web pages). Texinfo provides a PDF-specific option for this, which must |
| be used inside '@tex': |
| |
| @tex |
| \global\urefurlonlylinktrue |
| @end tex |
| |
| The result is that '@url{http://www.gnu.org, GNU}' has the visible |
| output of just 'GNU', with a link target of <http://www.gnu.org>. |
| Ordinarily, the visible output would include both the label and the url: |
| 'GNU (<http://www.gnu.org>)'. |
| |
| This option only has effect when the PDF output is produced with the |
| pdfTeX program, not with other ways of getting from Texinfo to PDF |
| (e.g., TeX to DVI to PDF). Consequently, it is ok to specify this |
| option unconditionally within '@tex', as shown above. It is ignored |
| when DVI is being produced. |
| |
| |
| File: texinfo.info, Node: PDF Colors, Prev: @url PDF Output Format, Up: @url |
| |
| 6.10.4 PDF Colors |
| ----------------- |
| |
| By default, urls and cross-reference links are printed in black in PDF |
| output. Very occasionally, however, you may want to highlight such |
| "live" links with a different color, as is commonly done on web pages. |
| Texinfo provides a PDF-specific option for specifying these colors, |
| which must be used inside '@tex': |
| |
| @tex |
| \global\def\linkcolor{1 0 0} % red |
| \global\def\urlcolor{0 1 0} % green |
| @end tex |
| |
| '\urlcolor' changes the color of '@url' output (both the actual url |
| and any textual label), while '\linkcolor' changes the color for |
| cross-references to nodes, etc. They are independent. |
| |
| The three given values must be numbers between 0 and 1, specifying |
| the amount of red, green, and blue respectively. |
| |
| These definitions only have an effect when the PDF output is produced |
| with the pdfTeX program, not with other ways of getting from Texinfo to |
| PDF (e.g., TeX to DVI to PDF). Consequently, it is ok to specify this |
| option unconditionally within '@tex', as shown above. It is ignored |
| when DVI is being produced. |
| |
| We do not recommend colorizing just for fun; unless you have a |
| specific reason to use colors, best to skip it. |
| |
| |
| File: texinfo.info, Node: @cite, Prev: @url, Up: Cross References |
| |
| 6.11 '@cite'{REFERENCE} |
| ======================= |
| |
| Use the '@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. *Note @xref::. |
| |
| |
| File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top |
| |
| 7 Marking Text, Words and Phrases |
| ********************************* |
| |
| 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. |
| |
| |
| File: texinfo.info, Node: Indicating, Next: Emphasis, Up: Marking Text |
| |
| 7.1 Indicating Definitions, Commands, etc. |
| ========================================== |
| |
| Texinfo has commands for indicating just what kind of object a piece of |
| text refers to. For example, email addresses are marked by '@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. |
| * @code:: Indicating program code. |
| * @kbd:: Showing keyboard input. |
| * @key:: Specifying keys. |
| * @samp:: Indicating a literal sequence of characters. |
| * @verb:: Indicating a verbatim sequence of characters. |
| * @var:: Indicating metasyntactic variables. |
| * @env:: Indicating environment variables. |
| * @file:: Indicating file names. |
| * @command:: Indicating command names. |
| * @option:: Indicating option names. |
| * @dfn:: Specifying definitions. |
| * @abbr:: Indicating abbreviations. |
| * @acronym:: Indicating acronyms. |
| * @indicateurl:: Indicating an example url. |
| * @email:: Indicating an electronic mail address. |
| |
| |
| File: texinfo.info, Node: Useful Highlighting, Next: @code, Up: Indicating |
| |
| 7.1.1 Highlighting Commands are Useful |
| -------------------------------------- |
| |
| The commands serve a variety of purposes: |
| |
| '@code{SAMPLE-CODE}' |
| Indicate text that is a literal example of a piece of a program. |
| *Note @code::. |
| |
| '@kbd{KEYBOARD-CHARACTERS}' |
| Indicate keyboard input. *Note @kbd::. |
| |
| '@key{KEY-NAME}' |
| Indicate the conventional name for a key on a keyboard. *Note |
| @key::. |
| |
| '@samp{TEXT}' |
| Indicate text that is a literal example of a sequence of |
| characters. *Note @samp::. |
| |
| '@verb{TEXT}' |
| Write a verbatim sequence of characters. *Note @verb::. |
| |
| '@var{METASYNTACTIC-VARIABLE}' |
| Indicate a metasyntactic variable. *Note @var::. |
| |
| '@env{ENVIRONMENT-VARIABLE}' |
| Indicate an environment variable. *Note @env::. |
| |
| '@file{FILE-NAME}' |
| Indicate the name of a file. *Note @file::. |
| |
| '@command{COMMAND-NAME}' |
| Indicate the name of a command. *Note @command::. |
| |
| '@option{OPTION}' |
| Indicate a command-line option. *Note @option::. |
| |
| '@dfn{TERM}' |
| Indicate the introductory or defining use of a term. *Note @dfn::. |
| |
| '@cite{REFERENCE}' |
| Indicate the name of a book. *Note @cite::. |
| |
| '@abbr{ABBREVIATION}' |
| Indicate an abbreviation, such as 'Comput.'. |
| |
| '@acronym{ACRONYM}' |
| Indicate an acronym. *Note @acronym::. |
| |
| '@indicateurl{UNIFORM-RESOURCE-LOCATOR}' |
| Indicate an example (that is, nonfunctional) uniform resource |
| locator. *Note @indicateurl::. (Use '@url' (*note @url::) for |
| live urls.) |
| |
| '@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}' |
| Indicate an electronic mail address. *Note @email::. |
| |
| |
| File: texinfo.info, Node: @code, Next: @kbd, Prev: Useful Highlighting, Up: Indicating |
| |
| 7.1.2 '@code'{SAMPLE-CODE} |
| -------------------------- |
| |
| Use the '@code' command to indicate text that is a piece of a program |
| and which consists of entire syntactic tokens. Enclose the text in |
| braces. |
| |
| Thus, you should use '@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' for command names in languages that resemble programming |
| languages, such as Texinfo. For example, '@code' and '@samp' are |
| produced by writing '@code{@@code}' and '@code{@@samp}' in the Texinfo |
| source, respectively. |
| |
| It is incorrect to alter the case of a word inside a '@code' command |
| when it appears at the beginning of a sentence. Most computer languages |
| are case sensitive. In C, for example, 'Printf' is different from the |
| identifier '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' results in single quotation marks around |
| the text. In other formats, '@code' argument is typeset in a typewriter |
| (monospace) font. For example, |
| |
| The function returns @code{nil}. |
| |
| produces this: |
| |
| The function returns 'nil'. |
| |
| Here are some cases for which it is preferable _not_ to use '@code': |
| |
| * For shell command names such as 'ls' (use '@command'). |
| |
| * For environment variable such as 'TEXINPUTS' (use '@env'). |
| |
| * For shell options such as '-c' when such options stand alone (use |
| '@option'). |
| |
| * An entire shell command often looks better if written using '@samp' |
| rather than '@code'. In this case, the rule is to choose the more |
| pleasing format. |
| |
| * For a string of characters shorter than a syntactic token. For |
| example, if you are writing about 'goto-ch', which is just a part |
| of the name for the 'goto-char' Emacs Lisp function, you should use |
| '@samp'. |
| |
| * In general, when writing about the characters used in a token; for |
| example, do not use '@code' when you are explaining what letters or |
| printable symbols can be used in the names of functions. (Use |
| '@samp'.) Also, you should not use '@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' for the keystroke commands of GNU Emacs (use |
| '@kbd' instead) although you may use '@code' for the names of the |
| Emacs Lisp functions that the keystroke commands invoke. |
| |
| By default, TeX will consider breaking lines at '-' and '_' |
| characters within '@code' and related commands. This can be controlled |
| with '@allowcodebreaks' (*note @allowcodebreaks::). The HTML output |
| attempts to respect this for '-', 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' command |
| and related commands (e.g., '@kbd', '@command'), in typewriter-like |
| contexts such as the '@example' environment (*note @example::) and |
| '@code' itself, etc. |
| |
| To control which quoting characters are implicitly inserted by |
| Texinfo processors in the output of '@code', etc., see the |
| 'OPEN_QUOTE_SYMBOL' and 'CLOSE_QUOTE_SYMBOL' customization variables |
| (*note Other Customization Variables::). This is separate from how |
| actual quotation characters in the input document are handled (*note |
| Inserting Quote Characters::). |
| |
| |
| File: texinfo.info, Node: @kbd, Next: @key, Prev: @code, Up: Indicating |
| |
| 7.1.3 '@kbd'{KEYBOARD-CHARACTERS} |
| --------------------------------- |
| |
| Use the '@kbd' command for characters of input to be typed by users. |
| For example, to refer to the characters 'M-a', write: |
| |
| @kbd{M-a} |
| |
| and to refer to the characters 'M-x shell', write: |
| |
| @kbd{M-x shell} |
| |
| By default, the '@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. |
| |
| Since the usage of '@kbd' varies from manual to manual, you can |
| control the font switching with the '@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: |
| |
| 'code' |
| Always use the same font for '@kbd' as '@code'. |
| 'example' |
| Use the distinguishing font for '@kbd' only in '@example' and |
| similar environments. |
| 'distinct' |
| (the default) Always use the distinguishing font for '@kbd'. |
| |
| You can embed another @-command inside the braces of a '@kbd' |
| command. Here, for example, is the way to describe a command that would |
| be described more verbosely as "press the 'r' key and then press the |
| <RETURN> key": |
| |
| @kbd{r @key{RET}} |
| |
| This produces: 'r <RET>'. (The present manual uses the default for |
| '@kbdinputstyle'.) |
| |
| You also use the '@kbd' command if you are spelling out the letters |
| you type; for example: |
| |
| To give the @code{logout} command, |
| type the characters @kbd{l o g o u t @key{RET}}. |
| |
| This produces: |
| |
| To give the 'logout' command, type the characters 'l o g o u t |
| <RET>'. |
| |
| (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 '@key{SPC}' for it.) |
| |
| |
| File: texinfo.info, Node: @key, Next: @samp, Prev: @kbd, Up: Indicating |
| |
| 7.1.4 '@key'{KEY-NAME} |
| ---------------------- |
| |
| Use the '@key' command for the conventional name for a key on a |
| keyboard, as in: |
| |
| @key{RET} |
| |
| You can use the '@key' command within the argument of an '@kbd' |
| command when the sequence of characters to be typed includes one or more |
| keys that are described by name. |
| |
| For example, to produce 'C-x <ESC>' and 'M-<TAB>' you would type: |
| |
| @kbd{C-x @key{ESC}} |
| @kbd{M-@key{TAB}} |
| |
| Here is a list of the recommended names for keys: |
| |
| SPC |
| Space |
| RET |
| Return |
| LFD |
| Linefeed (however, since most keyboards nowadays do not have a |
| Linefeed key, it might be better to call this character 'C-j') |
| TAB |
| Tab |
| BS |
| Backspace |
| ESC |
| Escape |
| DELETE |
| Delete |
| SHIFT |
| Shift |
| CTRL |
| Control |
| META |
| Meta |
| |
| 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 'Meta-a', use the '@kbd' command alone; do |
| not use the '@key' command; but when you are referring to the modifier |
| key in isolation, use the '@key' command. For example, write |
| '@kbd{Meta-a}' to produce 'Meta-a' and '@key{META}' to produce <META>. |
| |
| As a convention in GNU manuals, '@key' should not be used in index |
| entries. |
| |
| |
| File: texinfo.info, Node: @samp, Next: @verb, Prev: @key, Up: Indicating |
| |
| 7.1.5 '@samp'{TEXT} |
| ------------------- |
| |
| Use the '@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. |
| |
| To match @samp{foo} at the end of the line, |
| use the regexp @samp{foo$}. |
| |
| produces |
| |
| To match 'foo' at the end of the line, use the regexp 'foo$'. |
| |
| Any time you are referring to single characters, you should use |
| '@samp' unless '@kbd' or '@key' is more appropriate. Also, you may use |
| '@samp' for entire statements in C and for entire shell commands--in |
| this case, '@samp' often looks better than '@code'. Basically, '@samp' |
| is a catchall for whatever is not covered by '@code', '@kbd', '@key', |
| '@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: |
| |
| In English, the vowels are @samp{a}, @samp{e}, |
| @samp{i}, @samp{o}, @samp{u}, and sometimes |
| @samp{y}. |
| |
| This produces: |
| |
| In English, the vowels are 'a', 'e', 'i', 'o', 'u', and sometimes |
| 'y'. |
| |
| |
| File: texinfo.info, Node: @verb, Next: @var, Prev: @samp, Up: Indicating |
| |
| 7.1.6 '@verb'{CHARTEXTCHAR} |
| --------------------------- |
| |
| Use the '@verb' command to print a verbatim sequence of characters. |
| |
| Like LaTeX's '\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: |
| |
| How many @verb{|@|}-escapes does one need to print this |
| @verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this? |
| |
| produces |
| |
| How many @-escapes does one need to print this |
| @a @b.@c string or @'e?`{}!`\ this? |
| |
| This is in contrast to '@samp' (see the previous section), '@code', |
| and similar commands; in those cases, the argument is normal Texinfo |
| text, where the three characters '@{}' are special, as usual. With |
| '@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, '@verb{...}' prints a single |
| (fixed-width) period. |
| |
| It is not reliable to use '@verb' inside other Texinfo constructs. |
| In particular, it does not work to use '@verb' in anything related to |
| cross-referencing, such as section titles or figure captions. |
| |
| |
| File: texinfo.info, Node: @var, Next: @env, Prev: @verb, Up: Indicating |
| |
| 7.1.7 '@var'{METASYNTACTIC-VARIABLE} |
| ------------------------------------ |
| |
| Use the '@var' command to indicate metasyntactic variables. A |
| "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 '@var' for the names of normal variables in computer |
| programs. These are specific names, so '@code' is correct for them |
| ('@code'). For example, the Emacs Lisp variable 'texinfo-tex-command' |
| is not a metasyntactic variable; it is properly formatted using '@code'. |
| |
| Do not use '@var' for environment variables either; '@env' is correct |
| for them (see the next section). |
| |
| The effect of '@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. |
| |
| For example, |
| |
| To delete file @var{filename}, |
| type @samp{rm @var{filename}}. |
| |
| produces |
| |
| To delete file FILENAME, type 'rm FILENAME'. |
| |
| (Note that '@var' may appear inside '@code', '@samp', '@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: |
| |
| \input texinfo |
| @@settitle @var{name-of-manual} |
| |
| This produces: |
| |
| \input texinfo |
| @settitle NAME-OF-MANUAL |
| |
| In some documentation styles, metasyntactic variables are shown with |
| angle brackets, for example: |
| |
| ..., type rm <filename> |
| |
| However, that is not the style that Texinfo uses. |
| |
| |
| File: texinfo.info, Node: @env, Next: @file, Prev: @var, Up: Indicating |
| |
| 7.1.8 '@env'{ENVIRONMENT-VARIABLE} |
| ---------------------------------- |
| |
| Use the '@env' command to indicate environment variables, as used by |
| many operating systems, including GNU. Do not use it for |
| _meta_syntactic variables; use '@var' for those (see the previous |
| section). |
| |
| '@env' is equivalent to '@code' in its effects. For example: |
| |
| The @env{PATH} environment variable ... |
| produces |
| The 'PATH' environment variable ... |
| |
| |
| File: texinfo.info, Node: @file, Next: @command, Prev: @env, Up: Indicating |
| |
| 7.1.9 '@file'{FILE-NAME} |
| ------------------------ |
| |
| Use the '@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 '@file' for symbols |
| in a programming language; use '@code'. |
| |
| '@file' is equivalent to 'code' in its effects. For example, |
| |
| The @file{.el} files are in |
| the @file{/usr/local/emacs/lisp} directory. |
| |
| produces |
| |
| The '.el' files are in the '/usr/local/emacs/lisp' directory. |
| |
| |
| File: texinfo.info, Node: @command, Next: @option, Prev: @file, Up: Indicating |
| |
| 7.1.10 '@command'{COMMAND-NAME} |
| ------------------------------- |
| |
| Use the '@command' command to indicate command names, such as 'ls' or |
| 'cc'. |
| |
| '@command' is equivalent to '@code' in its effects. For example: |
| |
| The command @command{ls} lists directory contents. |
| produces |
| The command 'ls' lists directory contents. |
| |
| You should write the name of a program in the ordinary text font, |
| rather than using '@command', if you regard it as a new English word, |
| such as 'Emacs' or 'Bison'. |
| |
| When writing an entire shell command invocation, as in 'ls -l', you |
| should use either '@samp' or '@code' at your discretion. |
| |
| |
| File: texinfo.info, Node: @option, Next: @dfn, Prev: @command, Up: Indicating |
| |
| 7.1.11 '@option'{OPTION-NAME} |
| ----------------------------- |
| |
| Use the '@option' command to indicate a command-line option; for |
| example, '-l' or '--version' or '--output=FILENAME'. |
| |
| '@option' is equivalent to '@code' in its effects. For example: |
| |
| The option @option{-l} produces a long listing. |
| produces |
| The option '-l' produces a long listing. |
| |
| |
| File: texinfo.info, Node: @dfn, Next: @abbr, Prev: @option, Up: Indicating |
| |
| 7.1.12 '@dfn'{TERM} |
| ------------------- |
| |
| Use the '@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 '@dfn'. The command generates italics in the printed manual, |
| and double quotation marks in the Info file. For example: |
| |
| Getting rid of a file is called @dfn{deleting} it. |
| |
| produces |
| |
| Getting rid of a file is called "deleting" it. |
| |
| 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. |
| |
| |
| File: texinfo.info, Node: @abbr, Next: @acronym, Prev: @dfn, Up: Indicating |
| |
| 7.1.13 '@abbr'{ABBREVIATION[, MEANING]} |
| --------------------------------------- |
| |
| You can use the '@abbr' command for general abbreviations. The |
| abbreviation is given as the single argument in braces, as in |
| '@abbr{Comput.}'. As a matter of style, or for particular |
| abbreviations, you may prefer to omit periods, as in '@abbr{Mr} |
| Stallman'. |
| |
| '@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 '@.' command (*note Ending a Sentence::) to get the correct |
| spacing. However, you do not have to use '@.' within the abbreviation |
| itself; Texinfo automatically assumes periods within the abbreviation do |
| not end a sentence. |
| |
| 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 '<abbr>' tag is used; in Docbook, the |
| '<abbrev>' tag is used. For instance: |
| |
| @abbr{Comput. J., Computer Journal} |
| |
| produces: |
| |
| Comput. J. (Computer Journal) |
| |
| For abbreviations consisting of all capital letters, you may prefer |
| to use the '@acronym' command instead. See the next section for more on |
| the usage of these two commands. |
| |
| |
| File: texinfo.info, Node: @acronym, Next: @indicateurl, Prev: @abbr, Up: Indicating |
| |
| 7.1.14 '@acronym'{ACRONYM[, MEANING]} |
| ------------------------------------- |
| |
| You can use the '@acronym' command for abbreviations written in all |
| capital letters, such as 'NASA'. The abbreviation is given as the |
| single argument in braces, as in '@acronym{NASA}'. As a matter of |
| style, or for particular acronyms, you may prefer to use periods, as in |
| '@acronym{N.A.S.A.}'. |
| |
| '@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 '@.' or similar command (*note Ending a |
| Sentence::) to get the correct spacing. |
| |
| 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 '<acronym>' tag is used. |
| |
| For instance (since GNU is a recursive acronym, we use '@acronym' |
| recursively): |
| |
| @acronym{GNU, @acronym{GNU}'s Not Unix} |
| |
| produces: |
| |
| GNU (GNU's Not Unix) |
| |
| In some circumstances, it is conventional to print family names in |
| all capitals. Don't use '@acronym' for this, since a name is not an |
| acronym. Use '@sc' instead (*note Smallcaps::). |
| |
| '@abbr' and '@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. |
| |
| - In common English usage, acronyms are a subset of abbreviations: |
| they include pronounceable words like 'NATO', 'radar', and 'snafu'; |
| some sources also include syllable acronyms like 'Usenet', hybrids |
| like 'SIGGRAPH', and unpronounceable initialisms like 'FBI'. |
| |
| - In Texinfo, an acronym (but not an abbreviation) should consist |
| only of capital letters and periods, no lowercase. |
| |
| - In TeX, an acronym (but not an abbreviation) is printed in a |
| slightly smaller font. |
| |
| - Some browsers place a dotted bottom border under abbreviations but |
| not acronyms. |
| |
| - It usually turns out to be quite difficult and/or time-consuming to |
| consistently use '@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 '@acronym' and just typeset |
| everything as normal text in all capitals: 'GNU', producing the |
| output 'GNU'. |
| |
| - In general, it's not essential to use either of these commands for |
| all abbreviations; use your judgment. Text is perfectly readable |
| without them. |
| |
| |
| File: texinfo.info, Node: @indicateurl, Next: @email, Prev: @acronym, Up: Indicating |
| |
| 7.1.15 '@indicateurl'{UNIFORM-RESOURCE-LOCATOR} |
| ----------------------------------------------- |
| |
| Use the '@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 '@url' or '@uref' command for |
| that, *note @url::). '@indicateurl' is useful for urls which do not |
| actually exist. For example: |
| |
| For example, the url might be @indicateurl{http://example.org/path}. |
| |
| which produces: |
| |
| For example, the url might be 'http://example.org/path'. |
| |
| The output from '@indicateurl' is more or less like that of '@samp' |
| (*note @samp::). |
| |
| |
| File: texinfo.info, Node: @email, Prev: @indicateurl, Up: Indicating |
| |
| 7.1.16 '@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]} |
| ------------------------------------------------ |
| |
| Use the '@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). |
| |
| 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, '@email' produces a 'mailto' link that usually brings up a mail |
| composition window. For example: |
| |
| Send bug reports to @email{bug-texinfo@@gnu.org}, |
| suggestions to the @email{bug-texinfo@@gnu.org, same place}. |
| |
| produces |
| |
| Send bug reports to <bug-texinfo@gnu.org>, |
| suggestions to the same place <bug-texinfo@gnu.org>. |
| |
| |
| File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text |
| |
| 7.2 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' 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 '@r' command, has any regular |
| use. |
| |
| * Menu: |
| |
| * @emph @strong:: How to emphasize text in Texinfo. |
| * Smallcaps:: How to use the small caps font. |
| * Fonts:: Various font commands for printed output. |
| |
| |
| File: texinfo.info, Node: @emph @strong, Next: Smallcaps, Up: Emphasis |
| |
| 7.2.1 '@emph'{TEXT} and '@strong'{TEXT} |
| --------------------------------------- |
| |
| The '@emph' and '@strong' commands are for emphasis; '@strong' is |
| stronger. In printed output, '@emph' produces _italics_ and '@strong' |
| produces *bold*. In the Info output, '@emph' surrounds the text with |
| underscores ('_'), and '@strong' puts asterisks around the text. |
| |
| For example, |
| |
| @strong{Caution:} @samp{rm *} |
| removes @emph{all} normal files. |
| |
| produces the following: |
| |
| *Caution*: 'rm * .[^.]*' removes _all_ normal files. |
| |
| The '@strong' command is seldom used except to mark what is, in |
| effect, a typographical element, such as the word 'Caution' in the |
| preceding example. |
| |
| Caution: Do not use '@strong' with the word 'Note' followed by a |
| space; Info will mistake the combination for a cross-reference. |
| Use a phrase such as *Please notice* or *Caution* instead, or the |
| optional argument to '@quotation'--'Note' is allowable there. |
| |
| |
| File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: @emph @strong, Up: Emphasis |
| |
| 7.2.2 '@sc'{TEXT}: The Small Caps Font |
| -------------------------------------- |
| |
| Use the '@sc' command to set text in A SMALL CAPS FONT (where possible). |
| Write the text you want to be in small caps between braces in lowercase, |
| like this: |
| |
| Richard @sc{Stallman} commence' GNU. |
| |
| This produces: |
| |
| Richard STALLMAN commence' GNU. |
| |
| As shown here, we recommend reserving '@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. |
| |
| TeX typesets any uppercase letters between the braces of an '@sc' |
| command in full-size capitals; only lowercase letters are printed in the |
| small caps font. In the Info output, the argument to '@sc' is printed |
| in all uppercase. In HTML, the argument is uppercased and the output |
| marked with the '<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. |
| |
| |
| File: texinfo.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis |
| |
| 7.2.3 Fonts for Printing |
| ------------------------ |
| |
| Texinfo provides one command to change the size of the main body font in |
| the TeX output for a document: '@fonttextsize'. It has no effect in |
| other output. It takes a single argument on the remainder of the line, |
| which must be either '10' or '11'. For example: |
| |
| @fonttextsize 10 |
| |
| The effect is to reduce the body font to a 10pt size (the default is |
| 11pt). Fonts for other elements, such as sections and chapters, are |
| reduced accordingly. This should only be used in conjunction with |
| '@smallbook' (*note @smallbook::) or similar, since 10pt 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. |
| |
| '@b' |
| selects bold face; |
| |
| '@i' |
| selects an italic font; |
| |
| '@r' |
| selects a roman font, which is the usual font in which text is |
| printed. It may or may not be seriffed. |
| |
| '@sansserif' |
| selects a sans serif font; |
| |
| '@slanted' |
| selects a slanted font; |
| |
| '@t' |
| selects the fixed-width, typewriter-style font used by '@code'; |
| |
| (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.) |
| |
| The '@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 '<lineannotation>' |
| tag in Docbook output. |
| |
| For example, |
| |
| @lisp |
| (+ 2 2) ; @r{Add two plus two.} |
| @end lisp |
| |
| produces |
| |
| (+ 2 2) ; Add two plus two. |
| |
| The '@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: '@t{foo}' produces foo, cf. |
| '@code{foo}' producing 'foo'. |
| |
| 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. |
| |
| |
| File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top |
| |
| 8 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. |
| |
| 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 |
| '@end' command that is also at the beginning of a line by itself. For |
| instance, you begin an example by writing '@example' by itself at the |
| beginning of a line and end the example by writing '@end example' on a |
| line by itself, at the beginning of that line, and with only one space |
| between the '@end' and the 'example'. |
| |
| * Menu: |
| |
| * Block Enclosing Commands:: Different constructs for different purposes. |
| * @quotation:: Writing a quotation. |
| * @indentedblock:: Block of text indented on left. |
| * @example:: Writing an example in a fixed-width font. |
| * @verbatim:: Writing a verbatim example. |
| * @lisp:: Illustrating Lisp code. |
| * @display:: Writing an example in the current font. |
| * @format:: Writing an example without narrowed margins. |
| * @exdent:: Undo indentation on a line. |
| * @flushleft @flushright:: Pushing text flush left or flush right. |
| * @raggedright:: Avoiding justification on the right. |
| * @noindent:: Preventing paragraph indentation. |
| * @indent:: Forcing paragraph indentation. |
| * @cartouche:: Drawing rounded rectangles around text. |
| * @small...:: Examples in a smaller font. |
| |
| |
| File: texinfo.info, Node: Block Enclosing Commands, Next: @quotation, Up: Quotations and Examples |
| |
| 8.1 Block Enclosing Commands |
| ============================ |
| |
| Here is a summary of commands that enclose blocks of text, also known as |
| "environments". They're explained further in the following sections. |
| |
| '@quotation' |
| Indicate text that is quoted. The text is filled, indented (from |
| both margins), and printed in a roman font by default. |
| |
| '@indentedblock' |
| Like '@quotation', but the text is indented only on the left. |
| |
| '@example' |
| Illustrate code, commands, and the like. The text is printed in a |
| fixed-width font, and indented but not filled. |
| |
| '@lisp' |
| Like '@example', but specifically for illustrating Lisp code. The |
| text is printed in a fixed-width font, and indented but not filled. |
| |
| '@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 |
| '@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. |
| |
| '@display' |
| Display illustrative text. The text is indented but not filled, |
| and no font is selected (so, by default, the font is roman). |
| |
| '@format' |
| Like '@display' (the text is not filled and no font is selected), |
| but the text is not indented. |
| |
| '@smallquotation' |
| '@smallindentedblock' |
| '@smallexample' |
| '@smalllisp' |
| '@smalldisplay' |
| '@smallformat' |
| These '@small...' commands are just like their non-small |
| counterparts, except that they output text in a smaller font size, |
| where possible. |
| |
| '@flushleft' |
| '@flushright' |
| Text is not filled, but is set flush with the left or right margin, |
| respectively. |
| |
| '@raggedright' |
| Text is filled, but only justified on the left, leaving the right |
| margin ragged. |
| |
| '@cartouche' |
| Highlight text, often an example or quotation, by drawing a box |
| with rounded corners around it. |
| |
| The '@exdent' command is used within the above constructs to undo the |
| indentation of a line. |
| |
| The '@noindent' command may be used after one of the above constructs |
| (or at the beginning of any paragraph) to prevent the following text |
| from being indented as a new paragraph. |
| |
| |
| File: texinfo.info, Node: @quotation, Next: @indentedblock, Prev: Block Enclosing Commands, Up: Quotations and Examples |
| |
| 8.2 '@quotation': Block Quotations |
| ================================== |
| |
| The text of a quotation is processed like normal text (regular font, |
| text is filled) except that: |
| |
| * both the left and right margins are closer to the center of the |
| page, so the whole of the quotation is indented; |
| |
| * the first lines of paragraphs are indented no more than other |
| lines; and |
| |
| * an '@author' command may be given to specify the author of the |
| quotation. |
| |
| This is an example of text written between a '@quotation' command |
| and an '@end quotation' command. A '@quotation' command is most |
| often used to indicate text that is excerpted from another (real or |
| hypothetical) printed work. |
| |
| Write a '@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 '@end quotation'. The '@end |
| quotation' line will likewise disappear from the output. |
| |
| '@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 ':'. For |
| example: |
| |
| @quotation Note |
| This is |
| a foo. |
| @end quotation |
| |
| produces |
| |
| Note: This is a foo. |
| |
| If the '@quotation' argument is one of these English words |
| (case-insensitive): |
| |
| Caution Important Note Tip Warning |
| |
| then the Docbook output uses corresponding special tags ('<note>', etc.) |
| instead of the default '<blockquote>'. HTML output always uses |
| '<blockquote>'. |
| |
| If the author of the quotation is specified in the '@quotation' block |
| with the '@author' command, a line with the author name is displayed |
| after the quotation: |
| |
| @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 |
| |
| produces |
| |
| 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. |
| |
| -- _Richard Stallman_ |
| |
| Texinfo also provides a command '@smallquotation', which is just like |
| '@quotation' but uses a smaller font size where possible. *Note |
| @small...::. |
| |
| |
| File: texinfo.info, Node: @indentedblock, Next: @example, Prev: @quotation, Up: Quotations and Examples |
| |
| 8.3 '@indentedblock': Indented text blocks |
| ========================================== |
| |
| The '@indentedblock' environment is similar to '@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: |
| |
| This is an example of text written between an '@indentedblock' |
| command and an '@end indentedblock' command. The '@indentedblock' |
| environment can contain any text or other commands desired. |
| |
| This is written in the Texinfo source as: |
| |
| @indentedblock |
| This is an example ... |
| @end indentedblock |
| |
| Texinfo also provides a command '@smallindentedblock', which is just |
| like '@indentedblock' but uses a smaller font size where possible. |
| *Note @small...::. |
| |
| |
| File: texinfo.info, Node: @example, Next: @verbatim, Prev: @indentedblock, Up: Quotations and Examples |
| |
| 8.4 '@example': Example Text |
| ============================ |
| |
| The '@example' environment is used to indicate an example that is not |
| part of the running text, such as computer input or output. Write an |
| '@example' command at the beginning of a line by itself. Mark the end |
| of the example with an '@end example' command, also written at the |
| beginning of a line by itself. |
| |
| An '@example' environment has the following characteristics: |
| |
| * Each line in the input file is a line in the output; that is, the |
| source text is not filled as it normally is. |
| * Extra spaces and blank lines are significant. |
| * The output is indented. |
| * The output uses a fixed-width font. |
| * Texinfo commands _are_ expanded; if you want the output to be the |
| input verbatim, use the '@verbatim' environment instead (*note |
| @verbatim::). |
| |
| For example, |
| |
| @example |
| cp foo @var{dest1}; \ |
| cp foo @var{dest2} |
| @end example |
| |
| produces |
| |
| cp foo DEST1; \ |
| cp foo DEST2 |
| |
| The lines containing '@example' and '@end example' will disappear |
| from the output. To make the output look good, you should put a blank |
| line before the '@example' and another blank line after the '@end |
| example'. Blank lines inside the beginning '@example' and the ending |
| '@end example', on the other hand, do appear in the output. |
| |
| Caution: Do not use tabs in the lines of an example! (Or anywhere |
| else in Texinfo, except in verbatim environments.) TeX treats tabs |
| as single spaces, and that is not what they look like. In Emacs, |
| you can use 'M-x untabify' to convert tabs in a region to multiple |
| spaces. |
| |
| 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 '@noindent' command prevents a |
| piece of text from being indented as if it were a new paragraph (*note |
| @noindent::. |
| |
| If you want to embed code fragments within sentences, instead of |
| displaying them, use the '@code' command or its relatives (*note |
| @code::). |
| |
| If you wish to write a "comment" on a line of an example in the |
| normal roman font, you can use the '@r' command (*note Fonts::). |
| |
| |
| File: texinfo.info, Node: @verbatim, Next: @lisp, Prev: @example, Up: Quotations and Examples |
| |
| 8.5 '@verbatim': Literal Text |
| ============================= |
| |
| Use the '@verbatim' environment for printing of text that may contain |
| special characters or commands that should not be interpreted, such as |
| computer input or output ('@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 a '@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 '@end verbatim' command, also written at the beginning of |
| a line by itself. The '@end verbatim' will also disappear from the |
| output. |
| |
| For example: |
| |
| @verbatim |
| { |
| <TAB>@command with strange characters: @'e |
| expand<TAB>me |
| } |
| @end verbatim |
| |
| This produces: |
| |
| { |
| @command with strange characters: @'e |
| expand me |
| } |
| |
| Since the lines containing '@verbatim' and '@end verbatim' produce no |
| output, typically you should put a blank line before the '@verbatim' and |
| another blank line after the '@end verbatim'. Blank lines between the |
| beginning '@verbatim' and the ending '@end verbatim' will appear in the |
| output. |
| |
| You can get a "small" verbatim by enclosing the '@verbatim' in an |
| '@smallformat' environment, as shown here: |
| |
| @smallformat |
| @verbatim |
| ... still verbatim, but in a smaller font ... |
| @end verbatim |
| @end smallformat |
| |
| Finally, a word of warning: it is not reliable to use '@verbatim' |
| inside other Texinfo constructs. |
| |
| See also *note @verbatiminclude::. |
| |
| |
| File: texinfo.info, Node: @lisp, Next: @display, Prev: @verbatim, Up: Quotations and Examples |
| |
| 8.6 '@lisp': Marking a Lisp Example |
| =================================== |
| |
| The '@lisp' command is used for Lisp code. It is synonymous with the |
| '@example' command. |
| |
| This is an example of text written between an |
| @lisp command and an @end lisp command. |
| |
| Use '@lisp' instead of '@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. Mark the end of |
| '@lisp' with '@end lisp' on a line by itself. |
| |
| |
| File: texinfo.info, Node: @display, Next: @format, Prev: @lisp, Up: Quotations and Examples |
| |
| 8.7 '@display': Examples Using the Text Font |
| ============================================ |
| |
| The '@display' command begins another kind of environment, where the |
| font is left unchanged, not switched to typewriter as with '@example'. |
| Each line of input still produces a line of output, and the output is |
| still indented. |
| |
| This is an example of text written between a '@display' command |
| and an '@end display' command. The '@display' command |
| indents the text, but does not fill it. |
| |
| Texinfo also provides the environment '@smalldisplay', which is like |
| '@display' but uses a smaller font size. *Note @small...::. |
| |
| |
| File: texinfo.info, Node: @format, Next: @exdent, Prev: @display, Up: Quotations and Examples |
| |
| 8.8 '@format': Examples Using the Full Line Width |
| ================================================= |
| |
| The '@format' command is similar to '@display', except it leaves the |
| text unindented. Like '@display', it does not select the fixed-width |
| font. |
| |
| This is an example of text written between a '@format' command |
| and an '@end format' command. As you can see |
| from this example, |
| the '@format' command does not fill the text. |
| |
| Texinfo also provides the environment '@smallformat', which is like |
| '@format' but uses a smaller font size. *Note @small...::. |
| |
| |
| File: texinfo.info, Node: @exdent, Next: @flushleft @flushright, Prev: @format, Up: Quotations and Examples |
| |
| 8.9 '@exdent': Undoing a Line's Indentation |
| =========================================== |
| |
| The '@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 '@exdent' |
| line is printed in the roman font. |
| |
| '@exdent' is usually used within examples. Thus, |
| |
| @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 |
| |
| produces |
| |
| This line follows an @example command. |
| This line is exdented. |
| This line follows the exdented line. |
| The @end example comes on the next line. |
| |
| In practice, the '@exdent' command is rarely used. Usually, you |
| un-indent text by ending the example and returning the page to its |
| normal width. |
| |
| '@exdent' has no effect in HTML output. |
| |
| |
| File: texinfo.info, Node: @flushleft @flushright, Next: @raggedright, Prev: @exdent, Up: Quotations and Examples |
| |
| 8.10 '@flushleft' and '@flushright' |
| =================================== |
| |
| The '@flushleft' and '@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 |
| '@flushleft' and '@flushright' commands are ended by '@end flushleft' |
| and '@end flushright' commands on lines of their own. |
| |
| For example, |
| |
| @flushleft |
| This text is |
| written flushleft. |
| @end flushleft |
| |
| produces |
| |
| This text is |
| written flushleft. |
| |
| '@flushright' produces the type of indentation often used in the |
| return address of letters. For example, |
| |
| @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 |
| |
| produces |
| |
| Here is an example of text written |
| flushright. The '@flushright' command |
| right justifies every line but leaves the |
| left end ragged. |
| |
| |
| File: texinfo.info, Node: @raggedright, Next: @noindent, Prev: @flushleft @flushright, Up: Quotations and Examples |
| |
| 8.11 '@raggedright': Ragged Right Text |
| ====================================== |
| |
| The '@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 '@raggedright' command is ended by |
| '@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 '@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. |
| |
| An example (from elsewhere in this manual): |
| |
| @raggedright |
| Commands for double and single angle quotation marks: |
| @code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}}, |
| @code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}}, |
| @code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}. |
| @end raggedright |
| |
| produces |
| |
| Commands for double and single angle quotation marks: |
| '@guillemetleft{}', '@guillemetright{}', '@guillemotleft{}', |
| '@guillemotright{}', '@guilsinglleft{}', '@guilsinglright{}'. |
| |
| |
| File: texinfo.info, Node: @noindent, Next: @indent, Prev: @raggedright, Up: Quotations and Examples |
| |
| 8.12 '@noindent': Omitting Indentation |
| ====================================== |
| |
| 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 |
| '@noindent' at the beginning of a line, preceding the continuation text. |
| You can also disable indentation for all paragraphs globally with |
| '@paragraphindent' (*note @paragraphindent::). |
| |
| Here is an example showing how to eliminate the normal indentation of |
| the text after an '@example', a common situation: |
| |
| @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. |
| |
| produces: |
| |
| This is an example |
| |
| 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. |
| |
| The standard usage of '@indent' is just as above: at the beginning of |
| what would otherwise be a paragraph, to eliminate the indentation that |
| normally happens there. It can either be followed by text or be on a |
| line by itself. There is no reason to use it in other contexts, such as |
| in the middle of a paragraph or inside an environment (*note Quotations |
| and Examples::). |
| |
| You can control the number of blank lines in the Info file output by |
| adjusting the input as desired: a line containing just '@noindent' does |
| not generate a blank line, and neither does an '@end' line for an |
| environment. |
| |
| Do not put braces after a '@noindent' command; they are not used, |
| since '@noindent' is a command used outside of paragraphs (*note Command |
| Syntax::). |
| |
| |
| File: texinfo.info, Node: @indent, Next: @cartouche, Prev: @noindent, Up: Quotations and Examples |
| |
| 8.13 '@indent': Forcing Indentation |
| =================================== |
| |
| To complement the '@noindent' command (see the previous section), |
| Texinfo provides the '@indent' command to force a paragraph to be |
| indented. For instance, this paragraph (the first in this section) is |
| indented using an '@indent' command. |
| |
| And indeed, the first paragraph of a section is the most likely place |
| to use '@indent', to override the normal behavior of no indentation |
| there (*note @paragraphindent::). It can either be followed by text or |
| be on a line by itself. |
| |
| As a special case, when '@indent' is used in an environment where |
| text is not filled, it produces a paragraph indentation space in the TeX |
| output. (These environments are where a line of input produces a line |
| of output, such as '@example' and '@display'; for a summary of all |
| environments, *note Block Enclosing Commands::.) |
| |
| Do not put braces after an '@indent' command; they are not used, |
| since '@indent' is a command used outside of paragraphs (*note Command |
| Syntax::). |
| |
| |
| File: texinfo.info, Node: @cartouche, Next: @small..., Prev: @indent, Up: Quotations and Examples |
| |
| 8.14 '@cartouche': Rounded Rectangles |
| ===================================== |
| |
| In a printed manual, the '@cartouche' command draws a box with rounded |
| corners around its contents. In HTML, a normal rectangle is drawn. |
| '@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, |
| |
| @cartouche |
| @example |
| % pwd |
| /usr/local/share/emacs |
| @end example |
| @end cartouche |
| |
| 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 '@cartouche' had no effect): |
| |
| % pwd |
| /usr/local/info |
| |
| '@cartouche' also implies '@group' (*note @group::). |
| |
| |
| File: texinfo.info, Node: @small..., Prev: @cartouche, Up: Quotations and Examples |
| |
| 8.15 '@small...' Block Commands |
| =============================== |
| |
| In addition to the regular '@example' and similar commands, Texinfo has |
| "small" example-style commands. These are '@smallquotation', |
| '@smallindentedblock', '@smalldisplay', '@smallexample', '@smallformat', |
| and '@smalllisp'. |
| |
| In Info output, the '@small...' commands are equivalent to their |
| non-small companion commands. |
| |
| In TeX, however, the '@small...' 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 XML transliteration. |
| |
| Mark the end of a '@small...' block with a corresponding '@end |
| small...'. For example, pair '@smallexample' with '@end smallexample'. |
| |
| Here is an example of the font used by the '@smallexample' command |
| (in Info, the output will be the same as usual): |
| |
| ... 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. |
| |
| The '@small...' commands use the same font style as their normal |
| counterparts: '@smallexample' and '@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) '@example' or '@smallexample' consistently within |
| a chapter. |
| |
| |
| File: texinfo.info, Node: Lists and Tables, Next: Special Displays, Prev: Quotations and Examples, Up: Top |
| |
| 9 Lists and Tables |
| ****************** |
| |
| Texinfo has several ways of making lists and tables. Lists can be |
| bulleted or numbered; two-column tables can highlight the items in the |
| first column; multi-column tables are also supported. |
| |
| * Menu: |
| |
| * Introducing Lists:: Texinfo formats lists for you. |
| * @itemize:: How to construct a simple list. |
| * @enumerate:: How to construct a numbered list. |
| * Two-column Tables:: How to construct a two-column table. |
| * Multi-column Tables:: How to construct generalized tables. |
| |
| |
| File: texinfo.info, Node: Introducing Lists, Next: @itemize, Up: Lists and Tables |
| |
| 9.1 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 '@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 '@enumerate' command |
| and end the list with an '@end enumerate' command. Begin an itemized |
| list with an '@itemize' command, followed on the same line by a |
| formatting command such as '@bullet', and end the list with an '@end |
| itemize' command. |
| |
| Precede each element of a list with an '@item' or '@itemx' command. |
| |
| |
| Here is an itemized list of the different kinds of table and lists: |
| |
| * Itemized lists with and without bullets. |
| |
| * Enumerated lists, using numbers or letters. |
| |
| * Two-column tables with highlighting. |
| |
| |
| Here is an enumerated list with the same items: |
| |
| 1. Itemized lists with and without bullets. |
| |
| 2. Enumerated lists, using numbers or letters. |
| |
| 3. Two-column tables with highlighting. |
| |
| |
| And here is a two-column table with the same items and their @-commands: |
| |
| '@itemize' |
| Itemized lists with and without bullets. |
| |
| '@enumerate' |
| Enumerated lists, using numbers or letters. |
| |
| '@table' |
| '@ftable' |
| '@vtable' |
| Two-column tables, optionally with indexing. |
| |
| |
| File: texinfo.info, Node: @itemize, Next: @enumerate, Prev: Introducing Lists, Up: Lists and Tables |
| |
| 9.2 '@itemize': Making an Itemized List |
| ======================================= |
| |
| The '@itemize' command produces a sequence of "items", each starting |
| with a bullet or other mark inside the left margin, and generally |
| indented. |
| |
| Begin an itemized list by writing '@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 '@bullet' |
| after '@itemize', but you can use '@minus', or any command or character |
| that results in a single character in the Info file. (When you write |
| the mark command such as '@bullet' after an '@itemize' command, you may |
| omit the '{}'.) If you don't specify a mark command, the default is |
| '@bullet'. If you don't want any mark at all, but still want logical |
| items, use '@w{}' (in this case the braces are required). |
| |
| After the '@itemize', write your items, each starting with '@item'. |
| Text can follow on the same line as the '@item'. The text of an item |
| can continue for more than one paragraph. |
| |
| There should be at least one '@item' inside the '@itemize' |
| environment. If none are present, 'makeinfo' gives a warning. If you |
| just want indented text and not a list of items, use '@indentedblock'; |
| *note @indentedblock::. |
| |
| Index entries and comments that are given before an '@item' including |
| the first, are automatically moved (internally) to after the '@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 '@itemize', followed by the output |
| it produces. '@bullet' produces an '*' in Info and a round dot in other |
| output formats. |
| |
| @itemize @bullet |
| @item |
| Some text for foo. |
| |
| @item |
| Some text |
| for bar. |
| @end itemize |
| |
| This produces: |
| |
| * Some text for foo. |
| |
| * Some text for bar. |
| |
| Itemized lists may be embedded within other itemized lists. Here is |
| a list marked with dashes embedded in a list marked with bullets: |
| |
| @itemize @bullet |
| @item |
| First item. |
| |
| @itemize @minus |
| @item |
| Inner item. |
| |
| @item |
| Second inner item. |
| @end itemize |
| |
| @item |
| Second outer item. |
| @end itemize |
| |
| This produces: |
| |
| * First item. |
| |
| - Inner item. |
| |
| - Second inner item. |
| |
| * Second outer item. |
| |
| |
| File: texinfo.info, Node: @enumerate, Next: Two-column Tables, Prev: @itemize, Up: Lists and Tables |
| |
| 9.3 '@enumerate': Making a Numbered or Lettered List |
| ==================================================== |
| |
| '@enumerate' is like '@itemize' (*note @itemize::), except that the |
| labels on the items are successive integers or letters instead of |
| bullets. |
| |
| Write the '@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, '@enumerate' starts the list |
| with the number '1'. With a numeric argument, such as '3', the command |
| starts the list with that number. With an upper- or lowercase letter, |
| such as 'a' or '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 '@item' at the beginning of each item |
| in the enumeration. It is ok to have text following the '@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. |
| |
| Here is an example of '@enumerate' without an argument: |
| |
| @enumerate |
| @item |
| Underlying causes. |
| |
| @item |
| Proximate causes. |
| @end enumerate |
| |
| This produces: |
| |
| 1. Underlying causes. |
| |
| 2. Proximate causes. |
| |
| Here is an example with an argument of '3': |
| |
| @enumerate 3 |
| @item |
| Predisposing causes. |
| |
| @item |
| Precipitating causes. |
| |
| @item |
| Perpetuating causes. |
| @end enumerate |
| |
| This produces: |
| |
| 3. Predisposing causes. |
| |
| 4. Precipitating causes. |
| |
| 5. Perpetuating causes. |
| |
| Here is a brief summary of the alternatives. The summary is |
| constructed using '@enumerate' with an argument of 'a'. |
| |
| a. '@enumerate' |
| |
| Without an argument, produce a numbered list, with the first item |
| numbered 1. |
| |
| b. '@enumerate UNSIGNED-INTEGER' |
| |
| With an (unsigned) numeric argument, start a numbered list with |
| that number. You can use this to continue a list that you |
| interrupted with other text. |
| |
| c. '@enumerate 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. |
| |
| d. '@enumerate 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. |
| |
| You can also nest enumerated lists, as in an outline. |
| |
| |
| File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: @enumerate, Up: Lists and Tables |
| |
| 9.4 Making a Two-column Table |
| ============================= |
| |
| '@table' is similar to '@itemize' (*note @itemize::), but allows you to |
| specify a name or heading line for each item. The '@table' command is |
| used to produce two-column tables, and is especially useful for |
| glossaries, explanatory exhibits, and command-line option summaries. |
| |
| * Menu: |
| |
| * @table:: How to construct a two-column table. |
| * @ftable @vtable:: Automatic indexing for two-column tables. |
| * @itemx:: How to put more entries in the first column. |
| |
| |
| File: texinfo.info, Node: @table, Next: @ftable @vtable, Up: Two-column Tables |
| |
| 9.4.1 Using the '@table' Command |
| -------------------------------- |
| |
| Use the '@table' command to produce a two-column table. This command is |
| typically used when you have a list of items and a brief text with each |
| one, such as a list of definitions. |
| |
| Write the '@table' command at the beginning of a line, after a blank |
| line, and follow it on the same line with an argument that is an |
| 'indicating" command, such as '@code', '@samp', '@var', '@option', or |
| '@kbd' (*note Indicating::). This command will be applied to the text |
| in the first column. For example, '@table @code' will cause the text in |
| the first column to be output as if it had been the argument to a |
| '@code' command. |
| |
| You may use the '@asis' command as an argument to '@table'. '@asis' |
| is a command that does nothing: if you use this command after '@table', |
| the first column entries are output without added highlighting ("as |
| is"). |
| |
| The '@table' command works with other commands besides those |
| explicitly mentioned here. However, you can only use predefined Texinfo |
| commands that take an argument in braces. You cannot reliably use a new |
| command defined with '@macro', although an '@alias' (for a suitable |
| predefined command) is acceptable. *Note Defining New Texinfo |
| Commands::. |
| |
| Begin each table entry with an '@item' command at the beginning of a |
| line. Write the text for the first column on the same line as the |
| '@item' command. Write the text for the second column on the line |
| following the '@item' line and on subsequent lines. 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 '@item' will be placed in the |
| first column (including any footnotes). You do not need to type |
| anything for an empty second column. |
| |
| Normally, you should put a blank line before an '@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 '@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. |
| |
| For example, the following table highlights the text in the first |
| column with the '@samp' command: |
| |
| @table @samp |
| @item foo |
| This is the text for |
| @samp{foo}. |
| |
| @item bar |
| Text for @samp{bar}. |
| @end table |
| |
| This produces: |
| |
| 'foo' |
| This is the text for 'foo'. |
| 'bar' |
| Text for 'bar'. |
| |
| If you want to list two or more named items with a single block of |
| text, use the '@itemx' command. (*Note @itemx::.) |
| |
| The '@table' command (*note @table::) is not supported inside |
| '@display'. Since '@display' is line-oriented, it doesn't make sense to |
| use them together. If you want to indent a table, try '@quotation' |
| (*note @quotation::) or '@indentedblock' (*note @indentedblock::). |
| |
| |
| File: texinfo.info, Node: @ftable @vtable, Next: @itemx, Prev: @table, Up: Two-column Tables |
| |
| 9.4.2 '@ftable' and '@vtable' |
| ----------------------------- |
| |
| The '@ftable' and '@vtable' commands are the same as the '@table' |
| command except that '@ftable' automatically enters each of the items in |
| the first column of the table into the index of functions and '@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 '@item' or '@itemx' |
| commands are indexed, and they are indexed in exactly the form that they |
| appear on that line. *Note Indices::, for more information about |
| indices. |
| |
| Begin a two-column table using '@ftable' or '@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', exactly as you would |
| for a '@table' command; and end the table with an '@end ftable' or '@end |
| vtable' command on a line by itself. |
| |
| See the example for '@table' in the previous section. |
| |
| |
| File: texinfo.info, Node: @itemx, Prev: @ftable @vtable, Up: Two-column Tables |
| |
| 9.4.3 '@itemx': Second and Subsequent Items |
| ------------------------------------------- |
| |
| Use the '@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 '@item' for the first entry, and '@itemx' for all subsequent |
| entries; '@itemx' must always follow an '@item' command, with no blank |
| line intervening. |
| |
| The '@itemx' command works exactly like '@item' except that it does |
| not generate extra vertical space above the first column text. If you |
| have multiple consecutive '@itemx' commands, do not insert any blank |
| lines between them. |
| |
| For example, |
| |
| @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 |
| |
| This produces: |
| |
| 'upcase' |
| 'downcase' |
| These two functions accept a character or a string as argument, and |
| return the corresponding uppercase (lowercase) character or string. |
| |
| (Note also that this example illustrates multi-line supporting text in a |
| two-column table.) |
| |
| |
| File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables |
| |
| 9.5 '@multitable': Multi-column Tables |
| ====================================== |
| |
| '@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 '@multitable' line itself, and |
| write each row of the actual table following an '@item' command, with |
| columns separated by a '@tab' command. Finally, '@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. |
| |
| |
| File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Up: Multi-column Tables |
| |
| 9.5.1 Multitable Column Widths |
| ------------------------------ |
| |
| 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 '@multitable' command. |
| |
| 1. To specify column widths as fractions of the line length, write |
| '@columnfractions' and the decimal numbers (presumably less than 1; |
| a leading zero is allowed and ignored) after the '@multitable' |
| command, as in: |
| |
| @multitable @columnfractions .33 .33 .33 |
| |
| 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. |
| |
| 2. To specify a prototype row, write the longest entry for each column |
| enclosed in braces after the '@multitable' command. For example: |
| |
| @multitable {some text for column one} {for column two} |
| |
| 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' are |
| particularly likely to be useful. |
| |
| |
| File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables |
| |
| 9.5.2 Multitable Rows |
| --------------------- |
| |
| After the '@multitable' command defining the column widths (see the |
| previous section), you begin each row in the body of a multitable with |
| '@item', and separate the column entries with '@tab'. Line breaks are |
| not special within the table body, and you may break input lines in your |
| source file as necessary. |
| |
| You can also use '@headitem' instead of '@item' to produce a "heading |
| row". The TeX output for such a row is in bold, and the HTML and |
| Docbook output uses the '<thead>' tag. In Info, the heading row is |
| followed by a separator line made of dashes ('-' characters). |
| |
| The command '@headitemfont' can be used in templates when the entries |
| in a '@headitem' row need to be used in a template. It is a synonym for |
| '@b', but using '@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 |
| 'The GNU Emacs Manual', *note Splitting Windows: (emacs)Split Window.): |
| |
| @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 |
| |
| produces: |
| |
| Key Command Description |
| --------------------------------------------------------------------------- |
| C-x 2 'split-window-vertically' Split the selected window |
| into two windows, with one |
| above the other. |
| C-x 3 'split-window-horizontally' Split the selected window |
| into two windows positioned |
| side by side. |
| C-Mouse-2 In the mode line or scroll |
| bar of a window, split that |
| window. |
| |
| |
| File: texinfo.info, Node: Special Displays, Next: Indices, Prev: Lists and Tables, Up: Top |
| |
| 10 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. |
| |
| |
| File: texinfo.info, Node: Floats, Next: Images, Up: Special Displays |
| |
| 10.1 Floats |
| =========== |
| |
| A "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. |
| |
| 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 |
| '@group' (*note @group::). |
| |
| * Menu: |
| |
| * @float:: Producing floating material. |
| * @caption @shortcaption:: Specifying descriptions for floats. |
| * @listoffloats:: A table of contents for floats. |
| |
| |
| File: texinfo.info, Node: @float, Next: @caption @shortcaption, Up: Floats |
| |
| 10.1.1 '@float' [TYPE][,LABEL]: Floating Material |
| ------------------------------------------------- |
| |
| To produce floating material, enclose the material you want to be |
| displayed separate between '@float' and '@end float' commands, on lines |
| by themselves. |
| |
| Floating material often uses '@image' to display an already-existing |
| graphic (*note Images::), or '@multitable' to display a table (*note |
| Multi-column Tables::). However, the contents of the float can be |
| anything. Here's an example with simple text: |
| |
| @float Figure,fig:ex1 |
| This is an example float. |
| @end float |
| |
| And the output: |
| |
| This is an example float. |
| |
| Figure 10.1 |
| |
| As shown in the example, '@float' takes two arguments (separated by a |
| comma), TYPE and LABEL. Both are optional. |
| |
| TYPE |
| Specifies the sort of float this is; typically a word such as |
| "Figure", "Table", etc. If this is not given, and LABEL is, any |
| cross-referencing will simply use a bare number. |
| |
| LABEL |
| Specifies a cross-reference label for this float. If given, this |
| float is automatically given a number, and will appear in any |
| '@listoffloats' output (*note @listoffloats::). Cross references |
| to LABEL are allowed. |
| |
| On the other hand, if LABEL is not given, then the float will not |
| be numbered and consequently will not appear in the '@listoffloats' |
| output or be cross-referenceable. |
| |
| Ordinarily, you specify both TYPE and LABEL, to get a labeled and |
| numbered float. |
| |
| 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, ..., and is reset at each chapter. Each float |
| type is counted independently. |
| |
| Floats within an '@unnumbered', or outside of any chapter, are simply |
| numbered consecutively from 1. |
| |
| These numbering conventions are not, at present, changeable. |
| |
| |
| File: texinfo.info, Node: @caption @shortcaption, Next: @listoffloats, Prev: @float, Up: Floats |
| |
| 10.1.2 '@caption' & '@shortcaption' |
| ----------------------------------- |
| |
| You may write a '@caption' anywhere within a '@float' environment, to |
| define a caption for the float. It is not allowed in any other context. |
| '@caption' takes a single argument, enclosed in braces. Here's an |
| example: |
| |
| @float |
| An example float, with caption. |
| @caption{Caption for example float.} |
| @end float |
| |
| The output is: |
| |
| An example float, with caption. |
| |
| Caption for example float. |
| |
| '@caption' can appear anywhere within the float; it is not processed |
| until the '@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 '@float' command (see the previous section). |
| |
| The '@shortcaption' command likewise may be used only within |
| '@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: |
| |
| @float |
| ... as above ... |
| @shortcaption{Text for list of floats.} |
| @end float |
| |
| The text for '@shortcaption' may not contain comments ('@c'), |
| verbatim text ('@verb'), environments such as '@example', footnotes |
| ('@footnote') or other complex constructs. The same constraints apply |
| to '@caption' unless there is a '@shortcaption'. |
| |
| |
| File: texinfo.info, Node: @listoffloats, Prev: @caption @shortcaption, Up: Floats |
| |
| 10.1.3 '@listoffloats': Tables of Contents for Floats |
| ----------------------------------------------------- |
| |
| You can write a '@listoffloats' command to generate a list of floats for |
| a given float type (*note @float::), analogous to the document's overall |
| table of contents. Typically, it is written in its own '@unnumbered' |
| node to provide a heading and structure, rather like '@printindex' |
| (*note Printing Indices & Menus::). |
| |
| '@listoffloats' takes one optional argument, the float type. Here's |
| an example: |
| |
| @node List of Figures |
| @unnumbered List of Figures |
| @listoffloats Figure |
| |
| And here's what the output from '@listoffloats' looks like, given the |
| example figure earlier in this chapter (the Info output is formatted as |
| a menu): |
| |
| * Figure 12.1: fig:ex1. |
| |
| Without any argument, '@listoffloats' generates a list of floats for |
| which no float type was specified, i.e., no first argument to the |
| '@float' command (*note @float::). |
| |
| Each line in the list of floats contains the float type (if any), the |
| float number, and the caption, if any--the '@shortcaption' argument, if |
| it was specified, else the '@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. |
| |
| |
| File: texinfo.info, Node: Images, Next: Footnotes, Prev: Floats, Up: Special Displays |
| |
| 10.2 Inserting Images |
| ===================== |
| |
| You can insert an image given in an external file with the '@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:: |
| |
| |
| File: texinfo.info, Node: Image Syntax, Next: Image Scaling, Up: Images |
| |
| 10.2.1 Image Syntax |
| ------------------- |
| |
| Here is the synopsis of the '@image' command: |
| |
| @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]} |
| |
| The FILENAME argument is mandatory, and must not have an extension, |
| because the different processors support different formats: |
| |
| * TeX (DVI output) reads the file 'FILENAME.eps' (Encapsulated |
| PostScript format). |
| |
| * pdfTeX reads 'FILENAME.pdf', 'FILENAME.png', 'FILENAME.jpg', or |
| '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. |
| |
| * For Info, 'makeinfo' includes 'FILENAME.txt' verbatim (more or less |
| as if it were in '@verbatim'). The Info output may also include a |
| reference to 'FILENAME.png' or 'FILENAME.jpg'. (See below.) |
| |
| * For HTML, 'makeinfo' outputs a reference to 'FILENAME.png', |
| 'FILENAME.jpg', 'FILENAME.jpeg' or 'FILENAME.gif' (in that order). |
| If none of those exist, it gives an error, and outputs a reference |
| to 'FILENAME.jpg' anyway. |
| |
| * For Docbook, 'makeinfo' outputs references to 'FILENAME.eps', |
| 'FILENAME.gif' 'FILENAME.jpeg', 'FILENAME.jpg', 'FILENAME.pdf', |
| 'FILENAME.png' and 'FILENAME.svg', for every file found. Also, |
| 'FILENAME.txt' is included verbatim, if present. (The subsequent |
| Docbook processor is supposed to choose the appropriate one.) |
| |
| * For Info and HTML output, 'makeinfo' uses the optional fifth |
| argument EXTENSION to '@image' for the filename extension, if it is |
| specified and the file is found. Any leading period should be |
| included in EXTENSION. For example: |
| |
| @image{foo,,,,.xpm} |
| |
| If you want to install image files for use by Info readers too, we |
| recommend putting them in a subdirectory like 'FOO-figures' for a |
| package FOO. Copying the files into '$(infodir)/FOO-figures/' should be |
| done in your 'Makefile'. |
| |
| The WIDTH and 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 '@center' (*note @titlefont @center @sp::). |
| |
| For HTML output, 'makeinfo' sets the "alt attribute" for inline |
| images to the optional ALTTEXT (fourth) argument to '@image', if |
| supplied. If not supplied, 'makeinfo' uses the full file name of the |
| image being displayed. The ALTTEXT is processed as Texinfo text, so |
| special characters such as '"' and '<' and '&' are escaped in the HTML |
| output; also, you can get an empty 'alt' string with '@-' (a command |
| that produces no output; *note @- @hyphenation::). |
| |
| For Info output, the 'alt' string is also processed as Texinfo text |
| and output. In this case, '\' is escaped as '\\' and '"' as '\"'; no |
| other escapes are done. |
| |
| In Info output, 'makeinfo' writes a reference to the binary image |
| file (trying FILENAME suffixed with 'EXTENSION', '.EXTENSION', '.png', |
| or '.jpg', in that order) if one exists. It also literally includes the |
| '.txt' file if one exists. This way, Info readers which can display |
| images (such as the Emacs 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. |
| |
| The implementation of this is to put the following construct into the |
| Info output: |
| |
| ^@^H[image src="BINARYFILE" text="TXTFILE" |
| alt="ALTTEXT ... ^@^H] |
| |
| where '^@' and '^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. |
| |
| |
| File: texinfo.info, Node: Image Scaling, Prev: Image Syntax, Up: Images |
| |
| 10.2.2 Image Scaling |
| -------------------- |
| |
| The optional WIDTH and HEIGHT arguments to the '@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. |
| |
| The WIDTH and HEIGHT may be specified using any valid TeX dimension, |
| namely: |
| |
| pt |
| point (72.27pt = 1in) |
| pc |
| pica (1pc = 12pt) |
| bp |
| big point (72bp = 1in) |
| in |
| inch |
| cm |
| centimeter (2.54cm = 1in) |
| mm |
| millimeter (10mm = 1cm) |
| dd |
| dido^t point (1157dd = 1238pt) |
| cc |
| cicero (1cc = 12dd) |
| sp |
| scaled point (65536sp = 1pt) |
| |
| For example, the following will scale a file 'ridt.eps' to one inch |
| vertically, with the width scaled proportionately: |
| |
| @image{ridt,,1in} |
| |
| For '@image' to work with TeX, the file 'epsf.tex' must be installed |
| somewhere that TeX can find it. (The standard location is |
| 'TEXMF/tex/generic/dvips/epsf.tex', where TEXMF is a root of your TeX |
| directory tree.) This file is included in the Texinfo distribution and |
| is also available from <ftp://tug.org/tex/epsf.tex>, among other places. |
| |
| '@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. |
| |
| |
| File: texinfo.info, Node: Footnotes, Prev: Images, Up: Special Displays |
| |
| 10.3 Footnotes |
| ============== |
| |
| A "footnote" is for a reference that documents or elucidates the primary |
| text.(1) |
| |
| Footnotes are distracting; use them sparingly at most, and it is best |
| to avoid them completely. Standard bibliographical references are |
| usually 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. |
| |
| ---------- Footnotes ---------- |
| |
| (1) 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 'The Chicago Manual |
| of Style', which is published by the University of Chicago Press. |
| |
| |
| File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Up: Footnotes |
| |
| 10.3.1 Footnote Commands |
| ------------------------ |
| |
| In Texinfo, footnotes are created with the '@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: |
| |
| ordinary text@footnote{TEXT OF FOOTNOTE} |
| |
| As shown here, the '@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(1); in the |
| Texinfo source, it looks like this: |
| |
| ...a sample footnote@footnote{Here is the sample |
| footnote.}; in the Texinfo source... |
| |
| As you can see, this source includes two punctuation marks next to |
| each other; in this case, '.};' 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. (Another style, perfectly |
| acceptable, is to put the footnote after punctuation belonging to the |
| sentence, as in ';@footnote{...'.) |
| |
| 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: '(1)'. The reference |
| mark is followed by a cross-reference link to the footnote text if |
| footnotes are put in separate nodes (*note 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. |
| |
| Footnotes cannot be nested, and cannot appear in section headings of |
| any kind or other "unusual" places. |
| |
| A final tip: footnotes in the argument of an '@item' command for an |
| '@table' must be entirely on the same line as the '@item' (as usual). |
| *Note Two-column Tables::. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Here is the sample footnote. |
| |
| |
| File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes |
| |
| 10.3.2 Footnote Styles |
| ---------------------- |
| |
| Info has two footnote styles, which determine where the text of the |
| footnote is located: |
| |
| * 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 'Footnotes' |
| within it. Each footnote begins with an '(N)' reference mark. |
| |
| Here is an example of the Info output for a single footnote in the |
| end-of-node style: |
| |
| --------- Footnotes --------- |
| |
| (1) Here is a sample footnote. |
| |
| * 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 '(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 |
| '-Footnotes' to the name of the node that contains the footnotes. |
| (Consequently, the footnotes' node for the 'Footnotes' node is |
| 'Footnotes-Footnotes'!) The footnotes' node has an 'Up' node |
| pointer that leads back to its parent node. |
| |
| Here is how the first footnote in this manual looks after being |
| formatted for Info in the separate node style: |
| |
| File: texinfo.info Node: Overview-Footnotes, Up: Overview |
| |
| (1) The first syllable of "Texinfo" is pronounced like "speck", not |
| "hex". ... |
| |
| Unless your document has long and important footnotes (as in, say, |
| Gibbon's 'Decline and Fall ...'), we recommend the 'end' style, as it is |
| simpler for readers to follow. |
| |
| Use the '@footnotestyle' command to specify an Info file's footnote |
| style. Write this command at the beginning of a line followed by an |
| argument, either 'end' for the end node style or 'separate' for the |
| separate node style. |
| |
| For example, |
| |
| @footnotestyle end |
| or |
| @footnotestyle separate |
| |
| Write a '@footnotestyle' command before or shortly after the |
| end-of-header line at the beginning of a Texinfo file. (You should |
| include any '@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 'end', or if the output is not |
| split, footnotes are put at the end of the output. If set to |
| 'separate', and the output is split, they are placed in a separate file. |
| |
| |
| File: texinfo.info, Node: Indices, Next: Insertions, Prev: Special Displays, Up: Top |
| |
| 11 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. |
| |
| * Menu: |
| |
| * Predefined Indices:: Use different indices for different kinds |
| of entries. |
| * Indexing Commands:: How to make an index entry. |
| * Index Entries:: Choose different words for index entries. |
| * Printing Indices & Menus:: How to print an index in hardcopy and |
| generate index menus in Info. |
| * Combining Indices:: How to combine indices. |
| * New Indices:: How to define your own indices. |
| |
| |
| File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Up: Indices |
| |
| 11.1 Predefined Indices |
| ======================= |
| |
| Texinfo provides six predefined indices. Here are their nominal |
| meanings, abbreviations, and the corresponding index entry commands: |
| |
| 'cp' |
| ('@cindex') concept index, for general concepts. |
| 'fn' |
| ('@findex') function index, for function and function-like names |
| (such as entry points of libraries). |
| 'ky' |
| ('@kindex') keystroke index, for keyboard commands. |
| 'pg' |
| ('@pindex') program index, for names of programs. |
| 'tp' |
| ('@tindex') data type index, for type names (such as structures |
| defined in header files). |
| 'vr' |
| ('@vindex') variable index, for variable names (such as global |
| variables of libraries). |
| |
| 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 '@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 (*note 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 '@synindex' or '@syncodeindex' commands |
| (*note Combining Indices::). |
| |
| |
| File: texinfo.info, Node: Indexing Commands, Next: Index Entries, Prev: Predefined Indices, Up: Indices |
| |
| 11.2 Defining the Entries of an Index |
| ===================================== |
| |
| 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: |
| |
| @cindex Defining indexing entries |
| @cindex Index entries, defining |
| @cindex Entries for an index |
| @cindex Specifying index entries |
| @cindex Creating index entries |
| |
| Each predefined index has its own indexing command--'@cindex' for the |
| concept index, '@findex' for the function index, and so on, as listed in |
| the previous section. |
| |
| Index entries should precede the visible material that is being |
| indexed. For instance: |
| |
| @cindex hello |
| Hello, there! |
| |
| Among other reasons, that way following indexing links (in whatever |
| context) ends up before the material, where readers want to be, instead |
| of after. |
| |
| 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' |
| font. You may change the way part of an entry is printed with the usual |
| Texinfo commands, such as '@file' for file names (*note Marking Text::), |
| and '@r' for the normal roman font (*note Fonts::). |
| |
| For the printed output, you may specify an explicit sort key for an |
| index entry using '@sortas' immediately following the index command. |
| For example: '@findex @sortas{\} \ @r{(literal \ in @code{@@math})' |
| sorts the index entry this produces under backslash. |
| |
| To reduce the quantity of sort keys you need to provide explicitly, |
| you may choose to ignore certain characters in index entries for the |
| purposes of sorting. The characters that you can currently choose to |
| ignore are '\', '-', '<' and '@', which are ignored by giving as an |
| argument to the '@set' command, respectively, 'txiindexbackslashignore', |
| 'txiindexhyphenignore', 'txiindexlessthanignore' and |
| 'txiindexatsignignore'. For example, specifying '@set |
| txiindexbackslashignore' causes the '\mathopsup' entry in the index for |
| this manual to be sorted as if it were 'mathopsup', so that it appears |
| among the other entries beginning 'M'. |
| |
| 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. *Note Menu Parts::, for more |
| information about the structure of a menu entry. |
| |
| |
| File: texinfo.info, Node: Index Entries, Next: Printing Indices & Menus, Prev: Indexing Commands, Up: Indices |
| |
| 11.3 Making 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. |
| |
| 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. |
| |
| When you are making index entries, it is good practice to think of |
| the different ways people may look for something. Different people _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. |
| |
| |
| File: texinfo.info, Node: Printing Indices & Menus, Next: Combining Indices, Prev: Index Entries, Up: Indices |
| |
| 11.4 Printing Indices and Menus |
| =============================== |
| |
| 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 '@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 '@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 |
| 'texindex' (*note 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. *Note 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 '@printindex' command. |
| |
| '@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 '@printindex' command does not generate a chapter heading for the |
| index, since different manuals have different needs. Consequently, you |
| should precede the '@printindex' command with a suitable section or |
| chapter command (usually '@appendix' or '@unnumbered') to supply the |
| chapter heading and put the index into the table of contents. Precede |
| the chapter heading with an '@node' line as usual. |
| |
| For example: |
| |
| @node Variable Index |
| @unnumbered Variable Index |
| |
| @printindex vr |
| |
| @node Concept Index |
| @unnumbered Concept Index |
| |
| @printindex cp |
| |
| If you have more than one index, we recommend placing the concept |
| index last. |
| |
| * In printed output, '@printindex' produces a traditional two-column |
| index, with dot leaders between the index terms and page numbers. |
| |
| * In Info output, '@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: |
| |
| * First index entry: Top. (line 7) |
| |
| 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. |
| |
| * In plain text output, '@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. |
| |
| * In HTML output, '@printindex' produces links to the index entries. |
| |
| * In XML and Docbook output, it simply records the index to be |
| printed. |
| |
| |
| File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Printing Indices & Menus, Up: Indices |
| |
| 11.5 Combining Indices |
| ====================== |
| |
| 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 '@cindex' |
| commands for them instead of '@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'. |
| |
| * Menu: |
| |
| * @syncodeindex:: How to merge two indices, using '@code' |
| font for the merged-from index. |
| * @synindex:: How to merge two indices, using the |
| roman font for the merged-from index. |
| |
| |
| File: texinfo.info, Node: @syncodeindex, Next: @synindex, Up: Combining Indices |
| |
| 11.5.1 '@syncodeindex': Combining indices using '@code' |
| ------------------------------------------------------- |
| |
| When you want to combine functions and concepts into one index, you |
| should index the functions with '@findex' and index the concepts with |
| '@cindex', and use the '@syncodeindex' command to redirect the function |
| index entries into the concept index. |
| |
| The '@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: |
| |
| @syncodeindex FROM TO |
| |
| For this purpose, the indices are given two-letter names: |
| |
| 'cp' |
| concept index |
| 'fn' |
| function index |
| 'vr' |
| variable index |
| 'ky' |
| key index |
| 'pg' |
| program index |
| 'tp' |
| data type index |
| |
| Write a '@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: |
| |
| @syncodeindex fn cp |
| |
| 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: |
| |
| @syncodeindex vr cp |
| @syncodeindex fn cp |
| |
| The '@syncodeindex' command puts all the entries from the 'from' |
| index (the redirected index) into the '@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' font as |
| you would expect. |
| |
| |
| File: texinfo.info, Node: @synindex, Prev: @syncodeindex, Up: Combining Indices |
| |
| 11.5.2 '@synindex': Combining indices |
| ------------------------------------- |
| |
| The '@synindex' command is nearly the same as the '@syncodeindex' |
| command, except that it does not put the 'from' index entries into the |
| '@code' font; rather it puts them in the roman font. Thus, you use |
| '@synindex' when you merge a concept index into a function index. |
| |
| *Note Printing Indices & Menus::, for information about printing an |
| index at the end of a book or creating an index menu in an Info file. |
| |
| |
| File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices |
| |
| 11.6 Defining New Indices |
| ========================= |
| |
| In addition to the predefined indices (*note Predefined Indices::), you |
| may use the '@defindex' and '@defcodeindex' commands to define new |
| indices. These commands create new indexing @-commands with which you |
| mark index entries. The '@defindex' command is used like this: |
| |
| @defindex NAME |
| |
| New index names are usually two-letter words, such as 'au'. For |
| example: |
| |
| @defindex au |
| |
| This defines a new index, called the 'au' index. At the same time, |
| it creates a new indexing command, '@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 'au' index entries. |
| |
| @section Cognitive Semantics |
| @cindex kinesthetic image schemas |
| @auindex Johnson, Mark |
| @auindex Lakoff, George |
| |
| (Evidently, 'au' serves here as an abbreviation for "author".) |
| |
| Texinfo constructs the new indexing command by concatenating the name |
| of the index with 'index'; thus, defining an 'xy' index leads to the |
| automatic creation of an '@xyindex' command. |
| |
| Use the '@printindex' command to print the index, as you do with the |
| predefined indices. For example: |
| |
| @node Author Index |
| @unnumbered Author Index |
| |
| @printindex au |
| |
| The '@defcodeindex' is like the '@defindex' command, except that, in |
| the printed output, it prints entries in an '@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 '@synindex' or '@syncodeindex' |
| commands (*note Texinfo File Header::). |
| |
| As mentioned earlier (*note 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 (*note Names of index files::). Therefore you should |
| avoid using index names that collide with extensions used for other |
| purposes, such as '.aux' or '.xml'. 'makeinfo' already reports an error |
| if a new index conflicts well-known extension name. |
| |
| |
| File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top |
| |
| 12 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. |
| |
| * 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 Subscripts and Superscripts:: Inserting sub/superscripts. |
| * 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. |
| * Inserting Unicode:: Inserting a Unicode character by code point. |
| |
| |
| File: texinfo.info, Node: Special Characters, Next: Inserting Quote Characters, Up: Insertions |
| |
| 12.1 Special Characters: Inserting @ {} , \ # |
| ============================================= |
| |
| '@' and curly braces are the basic special characters in Texinfo. To |
| insert these characters so they appear in text, you must put an '@' 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:: '@@', '@atchar{}'. |
| * Inserting Braces:: '@{ @}', '@l rbracechar{}'. |
| * Inserting a Comma:: , and '@comma{}'. |
| * Inserting a Backslash:: \ and '@backslashchar{}'. |
| * Inserting a Hashsign:: # and '@hashchar{}'. |
| |