| 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: Inserting an Atsign, Next: Inserting Braces, Up: Special Characters |
| |
| 12.1.1 Inserting '@' with '@@' and '@atchar{}' |
| ---------------------------------------------- |
| |
| '@@' produces a single '@' character in the output. Do not put braces |
| after an '@@' command. |
| |
| '@atchar{}' also produces a single '@' character in the output. It |
| does need following braces, as usual for alphabetic commands. In inline |
| conditionals (*note Inline Conditionals::), it can be necessary to avoid |
| using the literal '@' character in the source (and may be clearer in |
| other contexts). |
| |
| |
| File: texinfo.info, Node: Inserting Braces, Next: Inserting a Comma, Prev: Inserting an Atsign, Up: Special Characters |
| |
| 12.1.2 Inserting '{ '}' with '@{ @}' and '@l rbracechar{}' |
| ---------------------------------------------------------- |
| |
| '@{' produces a single '{' in the output, and '@}' produces a single |
| '}'. Do not put braces after either an '@{' or an '@}' command. |
| |
| '@lbracechar{}' and '@rbracechar{}' also produce single '{' and '}' |
| characters in the output. They do need following braces, as usual for |
| alphabetic commands. In inline conditionals (*note Inline |
| Conditionals::), it can be necessary to avoid using literal brace |
| characters in the source (and may be clearer in other contexts). |
| |
| |
| File: texinfo.info, Node: Inserting a Comma, Next: Inserting a Backslash, Prev: Inserting Braces, Up: Special Characters |
| |
| 12.1.3 Inserting ',' with '@comma{}' |
| ------------------------------------ |
| |
| Ordinarily, a comma ',' is a normal character that can be simply typed |
| in your input where you need it. |
| |
| However, Texinfo uses the comma as a special character only in one |
| context: to separate arguments to those Texinfo commands, such as |
| '@acronym' (*note @acronym::) and '@xref' (*note Cross References::), as |
| well as user-defined macros (*note Defining Macros::), which take more |
| than one argument. |
| |
| Since a comma character would confuse Texinfo's parsing for these |
| commands, you must use the command '@comma{}' instead if you want to |
| pass an actual comma. Here are some examples: |
| |
| @acronym{ABC, A Bizarre @comma{}} |
| @xref{Comma,, The @comma{} symbol} |
| @mymac{One argument@comma{} containing a comma} |
| |
| Although '@comma{}' can be used nearly anywhere, there is no need for |
| it anywhere except in this unusual case. |
| |
| (Incidentally, the name '@comma' lacks the 'char' suffix used in its |
| companion commands only for historical reasons. It didn't seem |
| important enough to define a synonym.) |
| |
| |
| File: texinfo.info, Node: Inserting a Backslash, Next: Inserting a Hashsign, Prev: Inserting a Comma, Up: Special Characters |
| |
| 12.1.4 Inserting '\' with '@backslashchar{}' |
| -------------------------------------------- |
| |
| Ordinarily, a backslash '\' is a normal character in Texinfo that can be |
| simply typed in your input where you need it. The result is to typeset |
| the backslash from the typewriter font. |
| |
| However, Texinfo uses the backslash as a special character in one |
| restricted context: to delimit formal arguments in the bodies of |
| user-defined macros (*note Defining Macros::). |
| |
| Due to the vagaries of macro argument parsing, it is more reliable to |
| pass an alphabetic command that produces a backslash instead of using a |
| literal \. Hence '@backslashchar{}'. Here is an example macro call: |
| |
| @mymac{One argument@backslashchar{} with a backslash} |
| |
| Texinfo documents may also use \ as a command character inside |
| '@math' (*note Inserting Math::). In this case, '@\' or '\backslash' |
| produces a "math" backslash (from the math symbol font), while |
| '@backslashchar{}' produces a typewriter backslash as usual. |
| |
| Although '@backslashchar{}' can be used nearly anywhere, there is no |
| need for it except in these unusual cases. |
| |
| |
| File: texinfo.info, Node: Inserting a Hashsign, Prev: Inserting a Backslash, Up: Special Characters |
| |
| 12.1.5 Inserting '#' with '@hashchar{}' |
| --------------------------------------- |
| |
| Ordinarily, a hash '#' is a normal character in Texinfo that can be |
| simply typed in your input where you need it. The result is to typeset |
| the hash character from the current font. |
| |
| This character has many other names, varying by locale, such as |
| "number sign", "pound", and "octothorp". It is also sometimes called |
| "sharp" or "sharp sign" since it vaguely resembles the musical symbol by |
| that name. In situations where Texinfo is used, "hash" is the most |
| common in our experience. |
| |
| However, Texinfo uses the hash character as a special character in |
| one restricted context: to introduce the so-called '#line' directive and |
| variants (*note External Macro Processors::). |
| |
| So, in order to typeset an actual hash character in such a place (for |
| example, in a program that needs documentation about '#line'), it's |
| necessary to use '@hashchar{}' or some other construct. Here's an |
| example: |
| |
| @hashchar{} 10 "example.c" |
| |
| Although '@hashchar{}' can be used nearly anywhere, there is no need |
| for it anywhere except this unusual case. |
| |
| |
| File: texinfo.info, Node: Inserting Quote Characters, Next: Inserting Space, Prev: Special Characters, Up: Insertions |
| |
| 12.2 Inserting Quote Characters |
| =============================== |
| |
| As explained in the early section on general Texinfo input conventions |
| (*note Conventions::), Texinfo source files use the ASCII character '`' |
| (96 decimal) to produce a left quote ('), and ASCII ''' (39 decimal) to |
| produce a right quote ('). Doubling these input characters ('``' and |
| '''') produces double quotes (" and "). These are the conventions used |
| by TeX. |
| |
| This works all right for text. However, in examples of computer |
| code, readers are especially likely to cut and paste the text |
| verbatim--and, unfortunately, some document viewers will mangle these |
| characters. (The free PDF reader 'xpdf' works fine, but other PDF |
| readers, both free and nonfree, have problems.) |
| |
| If this is a concern for you, Texinfo provides these two commands: |
| |
| '@codequoteundirected ON-OFF' |
| causes the output for the ''' character in code environments to be |
| the undirected single quote, like this: '''. |
| |
| '@codequotebacktick ON-OFF' |
| causes the output for the '`' character in code environments to be |
| the backtick character (standalone grave accent), like this: '`'. |
| |
| If you want these settings for only part of the document, |
| '@codequote... off' will restore the normal behavior, as in |
| '@codequoteundirected off'. |
| |
| These settings affect '@code', '@example', '@kbd', '@samp', '@verb', |
| and '@verbatim'. *Note Useful Highlighting::. |
| |
| This feature used to be controlled by using '@set' to change the |
| values of the corresponding variables 'txicodequoteundirected' and |
| 'txicodequotebacktick'; they are still supported, but the command |
| interface is preferred. |
| |
| |
| File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Inserting Quote Characters, Up: Insertions |
| |
| 12.3 Inserting Space |
| ==================== |
| |
| The following sections describe commands that control spacing of various |
| kinds within and after sentences. |
| |
| * Menu: |
| |
| * Multiple Spaces:: Inserting multiple spaces. |
| * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. |
| * Ending a Sentence:: Sometimes it does. |
| * @frenchspacing:: Specifying end-of-sentence spacing. |
| * @dmn:: Formatting a dimension. |
| |
| |
| File: texinfo.info, Node: Multiple Spaces, Next: Not Ending a Sentence, Up: Inserting Space |
| |
| 12.3.1 Multiple Spaces |
| ---------------------- |
| |
| Ordinarily, multiple whitespace characters (space, tab, and newline) are |
| collapsed into a single space. |
| |
| Occasionally, you may want to produce several consecutive spaces, |
| either for purposes of example (e.g., what your program does with |
| multiple spaces as input), or merely for purposes of appearance in |
| headings or lists. Texinfo supports three commands: '@SPACE', '@TAB', |
| and '@NL', all of which insert a single space into the output. (Here, |
| '@SPACE' represents an '@' character followed by a space, i.e., '@ ', |
| 'TAB' represents an actual tab character, and '@NL' represents an '@' |
| character and end-of-line, i.e., when '@' is the last character on a |
| line.) |
| |
| For example, |
| Spacey@ @ @ @ |
| example. |
| |
| produces |
| |
| Spacey example. |
| |
| Other possible uses of '@SPACE' have been subsumed by '@multitable' |
| (*note Multi-column Tables::). |
| |
| Do not follow any of these commands with braces. |
| |
| To produce a non-breakable space, see *note @tie::. |
| |
| |
| File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Multiple Spaces, Up: Inserting Space |
| |
| 12.3.2 Not Ending a Sentence |
| ---------------------------- |
| |
| When a period, exclamation point or question mark is at the end of a |
| sentence, slightly more space is inserted after it in a typeset manual. |
| |
| Usually, Texinfo can determine automatically when a period ends a |
| sentence. However, special commands are needed in some circumstances. |
| Use the '@:' command after a period, question mark, exclamation mark or |
| colon that should not be followed by extra space. This is necessary in |
| the following situations: |
| |
| 1. After a period that ends a lowercase abbreviation which is not at |
| the end of a sentences. |
| |
| 2. When a parenthetical remark in the middle of a sentence (like this |
| one!) ends with a period, exclamation point or question mark, '@:' |
| should be used after the right parenthesis. Similarly for right |
| brackets and right quotes (both single and double). |
| |
| For example: |
| |
| 'foo vs.@: bar (or?)@: baz', |
| |
| The first line below shows the output, and for comparison, the second |
| line shows the spacing when the '@:' commands were not used. |
| |
| foo vs. bar (or?) baz |
| foo vs. bar (or?) baz |
| |
| It may help you to remember what '@:' does by imagining that it |
| stands for an invisible lower-case character that stops a word ending in |
| a period. |
| |
| A few Texinfo commands force normal interword spacing, so that you |
| don't have to insert '@:' where you otherwise would. These are the |
| code-like highlighting commands, '@var', '@abbr', and '@acronym' (*note |
| Useful Highlighting::). For example, in '@code{foo. bar}' the period is |
| not considered to be the end of a sentence, and no extra space is |
| inserted. |
| |
| '@:' has no effect on the HTML or Docbook output. |
| |
| |
| File: texinfo.info, Node: Ending a Sentence, Next: @frenchspacing, Prev: Not Ending a Sentence, Up: Inserting Space |
| |
| 12.3.3 Ending a Sentence |
| ------------------------ |
| |
| As mentioned above, Texinfo normally inserts additional space after the |
| end of a sentence. It uses the same heuristic for this as TeX: a |
| sentence ends with a period, exclamation point, or question mark, either |
| preceded or followed by optional closing punctuation, and then |
| whitespace, and _not_ preceded by a capital letter. |
| |
| Use '@.' instead of a period, '@!' instead of an exclamation point, |
| and '@?' instead of a question mark at the end of a sentence that does |
| end with a capital letter. Do not put braces after any of these |
| commands. For example: |
| |
| Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@. |
| Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. |
| |
| The output follows. In printed output and Info, you can see the desired |
| extra whitespace after the 'W' in the first line. |
| |
| Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. |
| Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. |
| |
| In the HTML output, '@.' is equivalent to a simple '.'; likewise for |
| '@!' and '@?'. |
| |
| The "closing punctuation" mentioned above is defined as a right |
| parenthesis (')', right bracket (']'), or right quote, either single or |
| double (''' and ''''; the many possible additional Unicode right quotes |
| are not included). These characters can be thought of as invisible with |
| respect to whether a given period ends a sentence. (This is the same |
| rule as TeX.) For instance, the periods in 'foo.) Bar' and 'foo.'' Bar' |
| do end sentences. |
| |
| The meanings of '@:' and '@.', etc. in Texinfo are designed to work |
| well with the Emacs sentence motion commands (*note (emacs)Sentences::). |
| It may help to imagine that the '@' in '@.', etc., is an invisible |
| lower-case letter 'a' which makes an upper-case letter before it |
| immaterial for the purposes of deciding whether the period ends the |
| sentence. |
| |
| A few Texinfo commands are not considered as being an abbreviation, |
| even though they may end with a capital letter when expanded, so that |
| you don't have to insert '@.' and companions. Notably, this is the case |
| for code-like highlighting commands, '@var' arguments ending with a |
| capital letter, '@LaTeX', and '@TeX'. For example, that sentence ended |
| with '... @code{@@TeX}.'; '@.' was not needed. Similarly, in '... |
| @var{VARNAME}. Text' the period after VARNAME ends the sentence; there |
| is no need to use '@.'. |
| |
| |
| File: texinfo.info, Node: @frenchspacing, Next: @dmn, Prev: Ending a Sentence, Up: Inserting Space |
| |
| 12.3.4 '@frenchspacing' VAL: Control Sentence Spacing |
| ----------------------------------------------------- |
| |
| In American typography, it is traditional and correct to put extra space |
| at the end of a sentence. This is the default in Texinfo (implemented |
| in Info and printed output; for HTML, we don't try to override the |
| browser). In French typography (and others), this extra space is wrong; |
| all spaces are uniform. |
| |
| Therefore Texinfo provides the '@frenchspacing' command to control |
| the spacing after punctuation. It reads the rest of the line as its |
| argument, which must be the single word 'on' or 'off' (always these |
| words, regardless of the language of the document). Here is an example: |
| |
| @frenchspacing on |
| This is text. Two sentences. Three sentences. French spacing. |
| |
| @frenchspacing off |
| This is text. Two sentences. Three sentences. Non-French spacing. |
| |
| produces: |
| |
| This is text. Two sentences. Three sentences. French spacing. |
| |
| This is text. Two sentences. Three sentences. Non-French spacing. |
| |
| '@frenchspacing' also affects the output after '@.', '@!', and '@?' |
| (*note Ending a Sentence::). |
| |
| '@frenchspacing' has no effect on the HTML or Docbook output; for |
| XML, it outputs a transliteration of itself (*note Output Formats::). |
| |
| |
| File: texinfo.info, Node: @dmn, Prev: @frenchspacing, Up: Inserting Space |
| |
| 12.3.5 '@dmn'{DIMENSION}: Format a Dimension |
| -------------------------------------------- |
| |
| You can use the '@dmn' command to format a dimension with a little extra |
| space in the printed output. That is, on seeing '@dmn', TeX inserts |
| just enough space for proper typesetting; in other output formats, the |
| formatting commands insert no space at all. |
| |
| To use the '@dmn' command, write the number and then follow it |
| immediately, with no intervening space, by '@dmn', and then by the |
| dimension within braces. For example, |
| |
| A4 paper is 8.27@dmn{in} wide. |
| |
| produces |
| |
| A4 paper is 8.27in wide. |
| |
| Not everyone uses this style. Some people prefer '8.27 in.' or |
| '8.27 inches'. In these cases, however, you need to use '@tie' (*note |
| @tie::) or '@w' (*note @w::) so that no line break can occur between the |
| number and the dimension. Also, if you write a period after an |
| abbreviation within a sentence (as with the 'in.' above), you should |
| write '@:' after the period to prevent TeX from inserting extra |
| whitespace, as shown here. *Note Not Ending a Sentence::. |
| |
| |
| File: texinfo.info, Node: Inserting Accents, Next: Inserting Quotation Marks, Prev: Inserting Space, Up: Insertions |
| |
| 12.4 Inserting Accents |
| ====================== |
| |
| Here is a table with the commands Texinfo provides for inserting |
| floating accents. They all need an argument, the character to accent, |
| which can either be given in braces as usual ('@'{e}'), or, as a special |
| case, the braces can be omitted, in which case the argument is the next |
| character ('@'e'). This is to make the source as convenient as possible |
| to type and read, since accented characters are very common in some |
| languages. |
| |
| If the command is alphabetic, such as '@dotaccent', then there must |
| be a space between the command name and argument if braces are not used. |
| If the command is non-alphabetic, such as '@'', then there must _not_ be |
| a space; the argument is the very next character. |
| |
| Exception: the argument to '@tieaccent' must be enclosed in braces |
| (since it is two characters instead of one). |
| |
| To get the true accented characters output in Info, not just the |
| ASCII transliterations, it is necessary to specify '@documentencoding' |
| with an encoding which supports the required characters (*note |
| @documentencoding::). In this case, you can also use non-ASCII (e.g., |
| pre-accented) characters in the source file. |
| |
| Command Output What |
| ------------------------------------------------------ |
| @"o o" umlaut accent |
| @'o o' acute accent |
| @,{c} c, cedilla accent |
| @=o o= macron/overbar accent |
| @^o o^ circumflex accent |
| @`o o` grave accent |
| @~o o~ tilde accent |
| @dotaccent{o} o. overdot accent |
| @H{o} o'' long Hungarian umlaut |
| @ogonek{a} a; ogonek |
| @ringaccent{o} o* ring accent |
| @tieaccent{oo} oo[ tie-after accent |
| @u{o} o( breve accent |
| @ubaraccent{o} o_ underbar accent |
| @udotaccent{o} .o underdot accent |
| @v{o} o< caron/hacek/check accent |
| |
| This table lists the Texinfo commands for inserting other characters |
| commonly used in languages other than English. |
| |
| @exclamdown{} ! upside-down ! |
| @questiondown{} ? upside-down ? |
| @aa{} @AA{} aa AA a,A with circle |
| @ae{} @AE{} ae AE ae,AE ligatures |
| @dh{} @DH{} d D Icelandic eth |
| @dotless{i} i dotless i |
| @dotless{j} j dotless j |
| @l{} @L{} /l /L suppressed-L,l |
| @o{} @O{} /o /O O,o with slash |
| @oe{} @OE{} oe OE oe,OE ligatures |
| @ordf{} @ordm{} a o Spanish ordinals |
| @ss{} ss es-zet or sharp S |
| @th{} @TH{} th TH Icelandic thorn |
| |
| |
| File: texinfo.info, Node: Inserting Quotation Marks, Next: Inserting Subscripts and Superscripts, Prev: Inserting Accents, Up: Insertions |
| |
| 12.5 Inserting Quotation Marks |
| ============================== |
| |
| Use doubled single-quote characters to begin and end quotations: |
| ``...''. TeX converts two single quotes to left- and right-hand doubled |
| quotation marks, and Info converts doubled single-quote characters to |
| ASCII double-quotes: ``...'' becomes "...". |
| |
| You may occasionally need to produce two consecutive single quotes; |
| for example, in documenting a computer language such as Maxima where '' |
| is a valid command. You can do this with the input '@w{}'; the empty |
| '@w' command stops the combination into the double-quote characters. |
| |
| The left quote character (`, ASCII code 96) used in Texinfo is a |
| grave accent in ANSI and ISO character set standards. We use it as a |
| quote character because that is how TeX is set up, by default. |
| |
| Texinfo supports several other quotation marks used in languages |
| other than English. Below is a table with the commands Texinfo provides |
| for inserting quotation marks. |
| |
| In order to get the symbols for the quotation marks in encoded Info |
| output, it is necessary to specify '@documentencoding UTF-8'. (*Note |
| @documentencoding::.) Double guillemets are also present in ISO 8859-1 |
| (aka Latin 1) and ISO 8859-15 (aka Latin 9). |
| |
| The standard TeX fonts support the usual quotation marks used in |
| English (the ones produced with single and doubled ASCII single-quotes). |
| For the other quotation marks, TeX uses European Computer Modern (EC) |
| fonts ('ecrm1000' and other variants). These fonts are freely |
| available, of course; you can download them from |
| <http://ctan.org/pkg/ec>, among other places. |
| |
| The free EC fonts are bitmap fonts created with Metafont. Especially |
| for on-line viewing, Type 1 (vector) versions of the fonts are |
| preferable; these are available in the CM-Super font package |
| (<http://ctan.org/pkg/cm-super>). |
| |
| Both distributions include installation instructions. |
| |
| Command Glyph Unicode name (point) |
| ---------------------------------------------------------------------- |
| @quotedblleft{} `` `` Left double quotation mark (U+201C) |
| @quotedblright{} '' '' Right double quotation mark (U+201D) |
| @quoteleft{} ` ` Left single quotation mark (U+2018) |
| @quoteright{} ' ' Right single quotation mark (U+2019) |
| @quotedblbase{} ,, Double low-9 quotation mark (U+201E) |
| @quotesinglbase{} , Single low-9 quotation mark (U+201A) |
| @guillemetleft{} << Left-pointing double angle quotation |
| mark (U+00AB) |
| @guillemetright{} >> Right-pointing double angle quotation |
| mark (U+00BB) |
| @guilsinglleft{} < Single left-pointing angle quotation |
| mark (U+2039) |
| @guilsinglright{} > Single right-pointing angle quotation |
| mark (U+203A) |
| |
| For the double angle quotation marks, Adobe and LaTeX glyph names are |
| also supported: '@guillemotleft' and '@guillemotright'. These names are |
| incorrect; a "guillemot" is a bird species (a type of auk). |
| |
| Traditions for quotation mark usage vary to a great extent between |
| languages (<http://en.wikipedia.org/wiki/Quotation_mark>). Texinfo does |
| not provide commands or configurations for typesetting quotation marks |
| according to the numerous traditions. Therefore, you have to choose the |
| commands appropriate for the language of your manual. Sometimes aliases |
| (*note @alias::) can simplify the usage and make the source code more |
| readable. For example, in German, '@quotedblbase' is used for the left |
| double quote, and the right double quote is the glyph produced by |
| '@quotedblleft', which is counter-intuitive. Thus, in this case the |
| following aliases would be convenient: |
| |
| @alias lgqq = quotedblbase |
| @alias rgqq = quotedblleft |
| |
| |
| File: texinfo.info, Node: Inserting Subscripts and Superscripts, Next: Inserting Math, Prev: Inserting Quotation Marks, Up: Insertions |
| |
| 12.6 '@sub' and '@sup': Inserting Subscripts and Superscripts |
| ============================================================= |
| |
| You can insert subscripts and superscripts, in either text or math, with |
| the '@sub' and '@sup' commands. (For other mathematical expressions, |
| see the next section.) For example, here is a purely textual subscript |
| and superscript: |
| |
| here@sub{below}@sup{above} |
| |
| produces: |
| |
| here_{below}^{above} |
| |
| Inside '@math', '@sub' and '@sup' produce mathematical subscripts and |
| superscripts. This uses a different font in the TeX output (math italic |
| instead of text italic); it makes no difference in the other output |
| formats. Here's an example: |
| |
| @math{e@sup{x}} |
| |
| produces: |
| |
| e^{x} |
| |
| In Info and plain text, regardless of being used inside '@math', |
| '@sub{TEXT}' is output as '_{TEXT}' and '@sup{TEXT}' as '^{TEXT}', |
| including the literal braces (to mark the beginning and end of the |
| "script" text to the reader). |
| |
| When the output format (and display program) permit (TeX math, HTML), |
| the superscript is set above the subscript when both commands are given |
| consecutively. |
| |
| |
| File: texinfo.info, Node: Inserting Math, Next: Glyphs for Text, Prev: Inserting Subscripts and Superscripts, Up: Insertions |
| |
| 12.7 '@math': Inserting Mathematical Expressions |
| ================================================ |
| |
| You can write a short mathematical expression with the '@math' command. |
| Write the mathematical expression between braces, like this: |
| |
| @math{(a + b) = (b + a)} |
| |
| This produces the following in Info and HTML: |
| |
| (a + b) = (b + a) |
| |
| The '@math' command has no special effect on the Info and HTML |
| output. 'makeinfo' expands any @-commands as usual, but it does not try |
| to use produce good mathematical formatting in any way (no use of |
| MathML, etc.). The HTML output is enclosed by '<em>...</em>', but |
| nothing more. |
| |
| However, as far as the TeX output is concerned, plain TeX |
| mathematical commands are allowed in '@math', starting with '\'. In |
| essence, '@math' switches into plain TeX math mode. (Exception: the |
| plain TeX command '\sup', which typesets the mathematical operator name |
| 'sup', must be accessed as '\mathopsup', due to the conflict with |
| Texinfo's '@sup' command.) |
| |
| This allows you to use all the plain TeX math control sequences for |
| symbols, functions, and so on, and thus get proper formatting in the TeX |
| output, at least. |
| |
| The '@sub' and '@sup' commands described in the previous section |
| produce subscripts and superscripts in HTML output as well as TeX; the |
| plain TeX characters '_' and '^' for subscripts and superscripts are |
| recognized by TeX inside '@math', but do nothing special in HTML or |
| other output formats. |
| |
| It's best to use '\' instead of '@' for any such mathematical |
| commands; otherwise, 'makeinfo' will complain. On the other hand, |
| 'makeinfo' does allow input with matching (but unescaped) braces, such |
| as 'k_{75}'; it complains about such bare braces in regular input. |
| |
| Here's an example: |
| |
| @math{\sin 2\pi \equiv \cos 3\pi} |
| |
| which looks like the input in Info and HTML: |
| \sin 2\pi \equiv \cos 3\pi |
| |
| Since '\' is an escape character inside '@math', you can use '@\' to |
| get a literal backslash ('\\' will work in TeX, but you'd get the |
| literal two characters '\\' in Info). '@\' is not defined outside of |
| '@math', since a '\' ordinarily produces a literal (typewriter) '\'. |
| You can also use '@backslashchar{}' in any mode to get a typewriter |
| backslash. *Note Inserting a Backslash::. |
| |
| For displayed equations, you must at present use TeX directly (*note |
| Raw Formatter Commands::). |
| |
| |
| File: texinfo.info, Node: Glyphs for Text, Next: Glyphs for Programming, Prev: Inserting Math, Up: Insertions |
| |
| 12.8 Glyphs for Text |
| ==================== |
| |
| Texinfo has support for a few additional glyphs that are commonly used |
| in printed text but not available in ASCII. Of course, there are many |
| thousands more. It is possible to use Unicode characters as-is as far |
| as 'makeinfo' is concerned, but TeX is not so lucky. |
| |
| * Menu: |
| |
| * @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. |
| |
| |
| File: texinfo.info, Node: @TeX @LaTeX, Next: @copyright, Up: Glyphs for Text |
| |
| 12.8.1 '@TeX'{} (TeX) and '@LaTeX'{} (LaTeX) |
| -------------------------------------------- |
| |
| Use the '@TeX{}' command to generate 'TeX'. In a printed manual, this |
| is a special logo that is different from three ordinary letters. In |
| Info, it just looks like 'TeX'. |
| |
| Similarly, use the '@LaTeX{}' command to generate 'LaTeX', which is |
| even more special in printed manuals (and different from the incorrect |
| 'La@TeX{}'. In Info, the result is just 'LaTeX'. (LaTeX is another |
| macro package built on top of TeX, very loosely analogous to Texinfo in |
| that it emphasizes logical structure, but much (much) larger.) |
| |
| The spelling of these commands are unusual for Texinfo, in that they |
| use both uppercase and lowercase letters. |
| |
| |
| File: texinfo.info, Node: @copyright, Next: @registeredsymbol, Prev: @TeX @LaTeX, Up: Glyphs for Text |
| |
| 12.8.2 '@copyright{}' ((C)) |
| --------------------------- |
| |
| Use the '@copyright{}' command to generate the copyright symbol, '(C)'. |
| Where possible, this is a 'c' inside a circle; in Info, this is '(C)'. |
| |
| Legally, it's not necessary to use the copyright symbol; the English |
| word 'Copyright' suffices, according to international treaty. |
| |
| |
| File: texinfo.info, Node: @registeredsymbol, Next: @dots, Prev: @copyright, Up: Glyphs for Text |
| |
| 12.8.3 '@registeredsymbol{}' ((R)) |
| ---------------------------------- |
| |
| Use the '@registeredsymbol{}' command to generate the registered symbol, |
| '(R)'. Where possible, this is an 'R' inside a circle; in Info, this is |
| '(R)'. |
| |
| |
| File: texinfo.info, Node: @dots, Next: @bullet, Prev: @registeredsymbol, Up: Glyphs for Text |
| |
| 12.8.4 '@dots' (...) and '@enddots' (...) |
| ----------------------------------------- |
| |
| An "ellipsis" (a sequence of dots) would be spaced wrong when typeset as |
| a string of periods, so a special command is used in Texinfo: use the |
| '@dots{}' command to generate a normal ellipsis, which is three dots in |
| a row, appropriately spaced ... like so. To emphasize: do not simply |
| write three periods in the input file; that would work for the Info file |
| output, but would produce the wrong amount of space between the periods |
| in the printed manual. |
| |
| The '@enddots{}' command generates an end-of-sentence ellipsis, which |
| also has three dots, but with different spacing afterwards, ... Look |
| closely to see the difference. |
| |
| Here is an ellipsis: ... Here are three periods in a row: ... |
| |
| In printed (and usually HTML) output, the three periods in a row are |
| much closer together than the dots in the ellipsis. |
| |
| |
| File: texinfo.info, Node: @bullet, Next: @euro, Prev: @dots, Up: Glyphs for Text |
| |
| 12.8.5 '@bullet' (*) |
| -------------------- |
| |
| Use the '@bullet{}' command to generate a large round dot, or the |
| closest possible thing to one. In Info, an asterisk is used. Here is a |
| bullet: * |
| |
| When you use '@bullet' in '@itemize', you do not need to type the |
| braces, because '@itemize' supplies them. (*note @itemize::). |
| |
| |
| File: texinfo.info, Node: @euro, Next: @pounds, Prev: @bullet, Up: Glyphs for Text |
| |
| 12.8.6 '@euro' (Euro): Euro Currency Symbol |
| ------------------------------------------- |
| |
| Use the '@euro{}' command to generate 'Euro'. Where possible, this is |
| the symbol for the Euro currency. Otherwise, the word 'Euro' is used. |
| |
| Texinfo cannot magically synthesize support for the Euro symbol where |
| the underlying system (fonts, software, whatever) does not support it. |
| Therefore, you may find it preferable to use the word "Euro". (In |
| banking contexts, the abbreviation for the Euro is EUR.) |
| |
| In order to get the Euro symbol in encoded Info output, for example, |
| it is necessary to specify '@documentencoding ISO-8859-15' or |
| '@documentencoding UTF-8' (*Note @documentencoding::.) The Euro symbol |
| is in ISO 8859-15 (aka Latin 9), and is _not_ in the more widely-used |
| ISO 8859-1 (Latin 1). |
| |
| The Euro symbol does not exist in the standard TeX fonts (which were |
| designed before the Euro was legislated into existence). Therefore, TeX |
| uses an additional font, named 'feymr10' (along with other variables). |
| It is freely available, of course; you can download it from |
| <http://ctan.org/pkg/eurosym>, among other places. The distribution |
| includes installation instructions. |
| |
| |
| File: texinfo.info, Node: @pounds, Next: @textdegree, Prev: @euro, Up: Glyphs for Text |
| |
| 12.8.7 '@pounds' (#): Pounds Sterling |
| ------------------------------------- |
| |
| Use the '@pounds{}' command to generate '#'. Where possible, this is |
| the symbol for the pounds sterling British currency. Otherwise, it is |
| '#'. |
| |
| |
| File: texinfo.info, Node: @textdegree, Next: @minus, Prev: @pounds, Up: Glyphs for Text |
| |
| 12.8.8 '@textdegree' (o): Degrees Symbol |
| ---------------------------------------- |
| |
| Use the '@textdegree{}' command to generate 'o'. Where possible, this |
| is the normal symbol for degrees. Otherwise, it is an 'o'. |
| |
| |
| File: texinfo.info, Node: @minus, Next: @geq @leq, Prev: @textdegree, Up: Glyphs for Text |
| |
| 12.8.9 '@minus' (-): Inserting a Minus Sign |
| ------------------------------------------- |
| |
| Use the '@minus{}' command to generate a minus sign. In a fixed-width |
| font, this is a single hyphen, but in a proportional font, the symbol is |
| the customary length for a minus sign--a little longer than a hyphen, |
| shorter than an em-dash: |
| |
| '-' is a minus sign generated with '@minus{}', |
| |
| '-' is a hyphen generated with the character '-', |
| |
| '--' is an em-dash for text. |
| |
| In the fixed-width font used by Info, '@minus{}' is the same as a |
| hyphen. |
| |
| You should not use '@minus{}' inside '@code' or '@example' because |
| the width distinction is not made in the fixed-width font they use. |
| |
| When you use '@minus' to specify the mark beginning each entry in an |
| itemized list, you do not need to type the braces (*note @itemize::). |
| |
| If you actually want to typeset some math that does a subtraction, it |
| is better to use '@math'. Then the regular '-' character produces a |
| minus sign, as in '@math{a-b}' (*note Inserting Math::). |
| |
| |
| File: texinfo.info, Node: @geq @leq, Prev: @minus, Up: Glyphs for Text |
| |
| 12.8.10 '@geq' (>=) and '@leq' (<=): Inserting Relations |
| -------------------------------------------------------- |
| |
| Use the '@geq{}' and '@leq{}' commands to generate greater-than-or-equal |
| and less-than-equal-signs, '>=' and '<='. When those symbols are not |
| available, the ASCII sequences '>=' and '<=' are output. |
| |
| |
| File: texinfo.info, Node: Glyphs for Programming, Next: Inserting Unicode, Prev: Glyphs for Text, Up: Insertions |
| |
| 12.9 Glyphs for Programming |
| =========================== |
| |
| In Texinfo, code is often illustrated in examples that are delimited by |
| '@example' and '@end example', or by '@lisp' and '@end lisp'. In such |
| examples, you can indicate the results of evaluation or an expansion |
| using '=>' or '==>'. Likewise, there are commands to insert glyphs to |
| indicate printed output, error messages, equivalence of expressions, the |
| location of point in an editor, and GUI operation sequences. |
| |
| The glyph-insertion commands do not need to be used within an |
| example, but most often they are. All glyph-insertion commands are |
| followed by empty braces. |
| |
| * Menu: |
| |
| * Glyphs Summary:: |
| * @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. |
| |
| |
| File: texinfo.info, Node: Glyphs Summary, Next: @result, Up: Glyphs for Programming |
| |
| 12.9.1 Glyphs Summary |
| --------------------- |
| |
| Here is a summary of the glyph commands: |
| |
| => |
| '@result{}' indicates the result of an expression. |
| |
| ==> |
| '@expansion{}' indicates the results of a macro expansion. |
| |
| -| |
| '@print{}' indicates printed output. |
| |
| error-> |
| '@error{}' indicates the following text is an error message. |
| |
| == |
| '@equiv{}' indicates the exact equivalence of two forms. |
| |
| -!- |
| '@point{}' shows the location of point. |
| |
| A -> B |
| '@clicksequence{A @click{} B' indicates a GUI operation sequence: |
| first A, then clicking B, or choosing B from a menu, or otherwise |
| selecting it. |
| |
| |
| File: texinfo.info, Node: @result, Next: @expansion, Prev: Glyphs Summary, Up: Glyphs for Programming |
| |
| 12.9.2 '@result{}' (=>): Result of an Expression |
| ------------------------------------------------ |
| |
| Use the '@result{}' command to indicate the result of evaluating an |
| expression. |
| |
| The '@result{}' command is displayed as '=>', either a double stemmed |
| arrow or (when that is not available) the ASCII sequence '=>'. |
| |
| Thus, the following, |
| |
| (cdr '(1 2 3)) |
| => (2 3) |
| |
| may be read as "'(cdr '(1 2 3))' evaluates to '(2 3)'". |
| |
| |
| File: texinfo.info, Node: @expansion, Next: @print, Prev: @result, Up: Glyphs for Programming |
| |
| 12.9.3 '@expansion{}' (==>): Indicating an Expansion |
| ---------------------------------------------------- |
| |
| When an expression is a macro call, it expands into a new expression. |
| You can indicate the result of the expansion with the '@expansion{}' |
| command. |
| |
| The '@expansion{}' command is displayed as '==>', either a long arrow |
| with a flat base or (when that is not available) the ASCII sequence |
| '==>'. |
| |
| For example, the following |
| |
| @lisp |
| (third '(a b c)) |
| @expansion{} (car (cdr (cdr '(a b c)))) |
| @result{} c |
| @end lisp |
| |
| produces |
| |
| (third '(a b c)) |
| ==> (car (cdr (cdr '(a b c)))) |
| => c |
| |
| which may be read as: |
| |
| '(third '(a b c))' expands to '(car (cdr (cdr '(a b c))))'; the |
| result of evaluating the expression is 'c'. |
| |
| Often, as in this case, an example looks better if the '@expansion{}' |
| and '@result{}' commands are indented. |
| |
| |
| File: texinfo.info, Node: @print, Next: @error, Prev: @expansion, Up: Glyphs for Programming |
| |
| 12.9.4 '@print{}' (-|): Indicating Generated Output |
| --------------------------------------------------- |
| |
| Sometimes an expression will generate output during its execution. You |
| can indicate such displayed output with the '@print{}' command. |
| |
| The '@print{}' command is displayed as '-|', either a horizontal dash |
| butting against a vertical bar or (when that is not available) the ASCII |
| sequence '-|'. |
| |
| In the following example, the printed text is indicated with '-|', |
| and the value of the expression follows on the last line. |
| |
| (progn (print 'foo) (print 'bar)) |
| -| foo |
| -| bar |
| => bar |
| |
| In a Texinfo source file, this example is written as follows: |
| |
| @lisp |
| (progn (print 'foo) (print 'bar)) |
| @print{} foo |
| @print{} bar |
| @result{} bar |
| @end lisp |
| |
| |
| File: texinfo.info, Node: @error, Next: @equiv, Prev: @print, Up: Glyphs for Programming |
| |
| 12.9.5 '@error{}' (error->): Indicating an Error Message |
| -------------------------------------------------------- |
| |
| A piece of code may cause an error when you evaluate it. You can |
| designate the error message with the '@error{}' command. |
| |
| The '@error{}' command is displayed as 'error->', either the word |
| 'error' in a box in the printed output, the word error followed by an |
| arrow in other formats or (when no arrow is available) 'error-->'. |
| |
| Thus, |
| |
| @lisp |
| (+ 23 'x) |
| @error{} Wrong type argument: integer-or-marker-p, x |
| @end lisp |
| |
| produces |
| |
| (+ 23 'x) |
| error-> Wrong type argument: integer-or-marker-p, x |
| |
| This indicates that the following error message is printed when you |
| evaluate the expression: |
| |
| Wrong type argument: integer-or-marker-p, x |
| |
| The word 'error->' itself is not part of the error message. |
| |
| |
| File: texinfo.info, Node: @equiv, Next: @point, Prev: @error, Up: Glyphs for Programming |
| |
| 12.9.6 '@equiv{}' (==): Indicating Equivalence |
| ---------------------------------------------- |
| |
| Sometimes two expressions produce identical results. You can indicate |
| the exact equivalence of two forms with the '@equiv{}' command. The |
| '@equiv{}' command is displayed as '==', either a standard mathematical |
| equivalence sign (three parallel horizontal lines) or (when that is not |
| available) as the ASCII sequence '=='. |
| |
| Thus, |
| |
| @lisp |
| (make-sparse-keymap) @equiv{} (list 'keymap) |
| @end lisp |
| |
| produces |
| |
| (make-sparse-keymap) == (list 'keymap) |
| |
| This indicates that evaluating '(make-sparse-keymap)' produces identical |
| results to evaluating '(list 'keymap)'. |
| |
| |
| File: texinfo.info, Node: @point, Next: Click Sequences, Prev: @equiv, Up: Glyphs for Programming |
| |
| 12.9.7 '@point{}' (-!-): Indicating Point in a Buffer |
| ----------------------------------------------------- |
| |
| Sometimes you need to show an example of text in an Emacs buffer. In |
| such examples, the convention is to include the entire contents of the |
| buffer in question between two lines of dashes containing the buffer |
| name. |
| |
| You can use the '@point{}' command to show the location of point in |
| the text in the buffer. (The symbol for point, of course, is not part |
| of the text in the buffer; it indicates the place _between_ two |
| characters where point is located.) |
| |
| The '@point{}' command is displayed as '-!-', either a pointed star |
| or (when that is not available) the ASCII sequence '-!-'. |
| |
| The following example shows the contents of buffer 'foo' before and |
| after evaluating a Lisp command to insert the word 'changed'. |
| |
| ---------- Buffer: foo ---------- |
| This is the -!-contents of foo. |
| ---------- Buffer: foo ---------- |
| |
| |
| (insert "changed ") |
| => nil |
| ---------- Buffer: foo ---------- |
| This is the changed -!-contents of foo. |
| ---------- Buffer: foo ---------- |
| |
| |
| In a Texinfo source file, the example is written like this: |
| |
| @example |
| ---------- Buffer: foo ---------- |
| This is the @point{}contents of foo. |
| ---------- Buffer: foo ---------- |
| |
| (insert "changed ") |
| @result{} nil |
| ---------- Buffer: foo ---------- |
| This is the changed @point{}contents of foo. |
| ---------- Buffer: foo ---------- |
| @end example |
| |
| |
| File: texinfo.info, Node: Click Sequences, Prev: @point, Up: Glyphs for Programming |
| |
| 12.9.8 Click Sequences |
| ---------------------- |
| |
| When documenting graphical interfaces, it is necessary to describe |
| sequences such as 'Click on 'File', then choose 'Open', then ...'. |
| Texinfo offers commands '@clicksequence' and 'click' to represent this, |
| typically used like this: |
| |
| ... @clicksequence{File @click{} Open} ... |
| |
| which produces: |
| |
| ... File -> Open ... |
| |
| The '@click' command produces a right arrow by default; this glyph is |
| also available independently via the command '@arrow{}'. |
| |
| You can change the glyph produced by '@click' with the command |
| '@clickstyle', which takes a command name as its single argument on the |
| rest of the line, much like '@itemize' and friends (*note @itemize::). |
| The command should produce a glyph, and the usual empty braces '{}' are |
| omitted. Here's an example: |
| |
| @clickstyle @result |
| ... @clicksequence{File @click{} Open} ... |
| |
| now produces: |
| |
| ... File => Open ... |
| |
| |
| File: texinfo.info, Node: Inserting Unicode, Prev: Glyphs for Programming, Up: Insertions |
| |
| 12.10 Inserting Unicode: '@U' |
| ============================= |
| |
| The command '@U{HEX}' inserts a representation of the Unicode character |
| U+HEX. For example, '@U{0132}' inserts the Dutch 'IJ' ligature (poorly |
| shown here as simply the two letters 'I' and 'J'). |
| |
| The HEX value should be at least four hex digits; leading zeros are |
| _not_ added. In general, HEX must specify a valid normal Unicode |
| character; e.g., U+10FFFF (the very last code point) is invalid by |
| definition, and thus cannot be inserted this way. |
| |
| '@U' is useful for inserting occasional glyphs for which Texinfo has |
| no dedicated command, while allowing the Texinfo source to remain purely |
| 7-bit ASCII for maximum portability. |
| |
| This command has many limitations--the same limitations as inserting |
| Unicode characters in UTF-8 or another binary form. First and most |
| importantly, TeX knows nothing about most of Unicode. Supporting |
| specific additional glyphs upon request is possible, but it's not viable |
| for 'texinfo.tex' to support whole additional scripts (Japanese, Urdu, |
| ...). The '@U' command does nothing to change this. If the specified |
| character is not supported in TeX, an error is given. (*Note |
| @documentencoding::.) |
| |
| In HTML, XML, and Docbook, the output from '@U' is always an entity |
| reference of the form '&#xHEX;', as in 'IJ' for the example above. |
| This should work even when an HTML document uses some other encoding |
| (say, Latin 1) and the given character is not supported in that |
| encoding. |
| |
| In Info and plain text, if the document encoding is specified |
| explicitly to be UTF-8, the output will be the UTF-8 representation of |
| the character U+HEX (presuming it's a valid character). In all other |
| cases, the output is the ASCII sequence 'U+HEX', as in the six ASCII |
| characters 'U+0132' for the example above. |
| |
| That's all. No magic! |
| |
| |
| File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top |
| |
| 13 Forcing and Preventing Breaks |
| ******************************** |
| |
| Line and page breaks can sometimes occur in the 'wrong' place in one or |
| another form of output. It's up to you to ensure that text looks right |
| in all the output formats. |
| |
| For example, in a printed manual, page breaks may occur awkwardly in |
| the middle of an example; to prevent this, you can hold text together |
| using a grouping command that keeps the text from being split across two |
| pages. Conversely, you may want to force a page break where none would |
| occur normally. |
| |
| You can use the break, break prevention, or pagination commands to |
| fix problematic line and page breaks. |
| |
| * Menu: |
| |
| * Break Commands:: Summary of break-related commands. |
| * Line Breaks:: Forcing line breaks. |
| * @- @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. |
| |
| |
| File: texinfo.info, Node: Break Commands, Next: Line Breaks, Up: Breaks |
| |
| 13.1 Break Commands |
| =================== |
| |
| The break commands create or allow line and paragraph breaks: |
| |
| '@*' |
| Force a line break. |
| |
| '@sp N' |
| Skip N blank lines. |
| |
| '@-' |
| Insert a discretionary hyphen. |
| |
| '@hyphenation{HY-PHEN-A-TED WORDS}' |
| Define hyphen points in HY-PHEN-A-TED WORDS. |
| |
| These commands hold text together on a single line: |
| |
| '@w{TEXT}' |
| Prevent TEXT from being split and hyphenated across two lines. |
| |
| '@tie{}' |
| Insert a normal interword space at which a line break may not |
| occur. |
| |
| The pagination commands apply only to printed output, since other |
| output formats do not have pages. |
| |
| '@page' |
| Start a new page. |
| |
| '@group' |
| Hold text together that must appear on one page. |
| |
| '@need MILS' |
| Start a new page if not enough space on this one. |
| |
| |
| File: texinfo.info, Node: Line Breaks, Next: @- @hyphenation, Prev: Break Commands, Up: Breaks |
| |
| 13.2 '@*' and '@/': Generate and Allow Line Breaks |
| ================================================== |
| |
| The '@*' command forces a line break in all output formats. The '@/' |
| command allows a line break (printed manual only). |
| |
| Here is an example with '@*': |
| |
| This sentence is broken @*into two lines. |
| |
| produces |
| |
| This sentence is broken |
| into two lines. |
| |
| The '@/' command can be useful within long urls or other identifiers |
| where TeX can't find a good place to break. TeX will automatically |
| break urls at the natural places (*note URL Line Breaking::), so only |
| use '@/' if you need it. '@/' has no effect in the other output format. |
| |
| |
| File: texinfo.info, Node: @- @hyphenation, Next: @allowcodebreaks, Prev: Line Breaks, Up: Breaks |
| |
| 13.3 '@-' and '@hyphenation': Helping TeX Hyphenate |
| =================================================== |
| |
| Although TeX's hyphenation algorithm is generally pretty good, it does |
| miss useful hyphenation points from time to time. (Or, far more rarely, |
| insert an incorrect hyphenation.) So, for documents with an unusual |
| vocabulary or when fine-tuning for a printed edition, you may wish to |
| help TeX out. Texinfo supports two commands for this: |
| |
| '@-' |
| Insert a discretionary hyphen, i.e., a place where TeX can (but |
| does not have to) hyphenate. This is especially useful when you |
| notice an overfull hbox is due to TeX missing a hyphenation (*note |
| Overfull hboxes::). TeX will not insert any hyphenation points |
| itself into a word containing '@-'. |
| |
| '@hyphenation{HY-PHEN-A-TED WORDS}' |
| Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put a |
| '-' at each hyphenation point. For example: |
| @hyphenation{man-u-script man-u-scripts} |
| TeX only uses the specified hyphenation points when the words match |
| exactly, so give all necessary variants, such as plurals. |
| |
| Info, HTML, and other non-TeX output is not hyphenated, so none of |
| these commands have any effect there. |
| |
| |
| File: texinfo.info, Node: @allowcodebreaks, Next: @w, Prev: @- @hyphenation, Up: Breaks |
| |
| 13.4 '@allowcodebreaks': Control Line Breaks in '@code' |
| ======================================================= |
| |
| Ordinarily, TeX considers breaking lines at '-' and '_' characters |
| within '@code' and related commands (*note @code::), more or less as if |
| they were "empty" hyphenation points. |
| |
| This is necessary since many manuals, especially for Lisp-family |
| languages, must document very long identifiers. On the other hand, some |
| manuals don't have this problems, and you may not wish to allow a line |
| break at the underscore in, for example, 'SIZE_MAX', or even worse, |
| after any of the four underscores in '__typeof__'. |
| |
| So Texinfo provides this command: |
| |
| @allowcodebreaks false |
| |
| to prevent from breaking at '-' or '_' within '@code'. You can go back |
| to allowing such breaks with '@allowcodebreaks true'. Write these |
| commands on lines by themselves. |
| |
| These commands can be given anywhere in the document. For example, |
| you may have just one problematic paragraph where you need to turn off |
| the breaks, but want them in general, or vice versa. |
| |
| This command has no effect except in HTML and TeX output. |
| |
| |
| File: texinfo.info, Node: @w, Next: @tie, Prev: @allowcodebreaks, Up: Breaks |
| |
| 13.5 '@w'{TEXT}: Prevent Line Breaks |
| ==================================== |
| |
| '@w{TEXT}' outputs TEXT, while prohibiting line breaks within TEXT. |
| |
| Thus, you can use '@w' to produce a non-breakable space, fixed at the |
| width of a normal interword space: |
| |
| @w{ } @w{ } @w{ } indentation. |
| |
| produces: |
| |
| indentation. |
| |
| The space from '@w{ }', as well as being non-breakable, also will not |
| stretch or shrink. Sometimes that is what you want, for instance if |
| you're doing manual indenting. However, usually you want a normal |
| interword space that does stretch and shrink (in the printed output); |
| for that, see the '@tie' command in the next section. |
| |
| You can also use the '@w' command to prevent TeX from automatically |
| hyphenating a long name or phrase that happens to fall near the end of a |
| line. 'makeinfo' does not ever hyphenate words. |
| |
| You can also use '@w' to avoid unwanted keyword expansion in source |
| control systems. For example, to literally write $Id$ in your document, |
| use '@w{$}Id$'. This trick isn't effective in Info or plain text |
| output, though. |
| |
| |
| File: texinfo.info, Node: @tie, Next: @sp, Prev: @w, Up: Breaks |
| |
| 13.6 '@tie{}': Inserting an Unbreakable Space |
| ============================================= |
| |
| The '@tie{}' command produces a normal interword space at which a line |
| break may not occur. Always write it with following (empty) braces, as |
| usual for commands used within a paragraph. Here's an example: |
| |
| @TeX{} was written by Donald E.@tie{}Knuth. |
| |
| produces: |
| |
| TeX was written by Donald E. Knuth. |
| |
| There are two important differences between '@tie{}' and '@w{ }': |
| |
| * The space produced by '@tie{}' will stretch and shrink slightly |
| along with the normal interword spaces in the paragraph; the space |
| produced by '@w{ }' will not vary. |
| |
| * '@tie{}' allows hyphenation of the surrounding words, while '@w{ }' |
| inhibits hyphenation of those words (for TeXnical reasons, namely |
| that it produces an '\hbox'). |
| |
| |
| File: texinfo.info, Node: @sp, Next: @page, Prev: @tie, Up: Breaks |
| |
| 13.7 '@sp' N: Insert Blank Lines |
| ================================ |
| |
| A line beginning with and containing only '@sp N' generates N blank |
| lines of space in both the printed manual and the Info file. '@sp' also |
| forces a paragraph break. For example, |
| |
| @sp 2 |
| |
| generates two blank lines. |
| |
| The '@sp' command is most often used in the title page. |
| |
| |
| File: texinfo.info, Node: @page, Next: @group, Prev: @sp, Up: Breaks |
| |
| 13.8 '@page': Start a New Page |
| ============================== |
| |
| A line containing only '@page' starts a new page in a printed manual. |
| In other formats, without the concept of pages, it starts a new |
| paragraph. A '@page' command is often used in the '@titlepage' section |
| of a Texinfo file to start the copyright page. |
| |
| |
| File: texinfo.info, Node: @group, Next: @need, Prev: @page, Up: Breaks |
| |
| 13.9 '@group': Prevent Page Breaks |
| ================================== |
| |
| The '@group' command (on a line by itself) is used inside an '@example' |
| or similar construct to begin an unsplittable vertical group, which will |
| appear entirely on one page in the printed output. The group is |
| terminated by a line containing only '@end group'. These two lines |
| produce no output of their own, and in the Info file output they have no |
| effect at all. |
| |
| Although '@group' would make sense conceptually in a wide variety of |
| contexts, its current implementation works reliably only within |
| '@example' and variants, and within '@display', '@format', '@flushleft' |
| and '@flushright'. *Note Quotations and Examples::. (What all these |
| commands have in common is that each line of input produces a line of |
| output.) In other contexts, '@group' can cause anomalous vertical |
| spacing. |
| |
| This formatting requirement means that you should write: |
| |
| @example |
| @group |
| ... |
| @end group |
| @end example |
| |
| with the '@group' and '@end group' commands inside the '@example' and |
| '@end example' commands. |
| |
| The '@group' command is most often used to hold an example together |
| on one page. In this Texinfo manual, more than 100 examples contain |
| text that is enclosed between '@group' and '@end group'. |
| |
| If you forget to end a group, you may get strange and unfathomable |
| error messages when you run TeX. This is because TeX keeps trying to |
| put the rest of the Texinfo file onto the one page and does not start to |
| generate error messages until it has processed considerable text. It is |
| a good rule of thumb to look for a missing '@end group' if you get |
| incomprehensible error messages in TeX. |
| |
| |
| File: texinfo.info, Node: @need, Prev: @group, Up: Breaks |
| |
| 13.10 '@need MILS': Prevent Page Breaks |
| ======================================= |
| |
| A line containing only '@need N' starts a new page in a printed manual |
| if fewer than N mils (thousandths of an inch) remain on the current |
| page. Do not use braces around the argument N. The '@need' command has |
| no effect on other output formats since they are not paginated. |
| |
| This paragraph is preceded by a '@need' command that tells TeX to |
| start a new page if fewer than 800 mils (eight-tenths inch) remain on |
| the page. It looks like this: |
| |
| @need 800 |
| This paragraph is preceded by ... |
| |
| The '@need' command is useful for preventing orphans: single lines at |
| the bottoms of printed pages. |
| |
| |
| File: texinfo.info, Node: Definition Commands, Next: Internationalization, Prev: Breaks, Up: Top |
| |
| 14 Definition Commands |
| ********************** |
| |
| The '@deffn' command and the other "definition commands" enable you to |
| describe functions, variables, macros, commands, user options, special |
| forms and other such artifacts in a uniform format. |
| |
| In the Info file, a definition causes the entity |
| category--'Function', 'Variable', or whatever--to appear at the |
| beginning of the first line of the definition, followed by the entity's |
| name and arguments. In the printed manual, the command causes TeX to |
| print the entity's name and its arguments on the left margin and print |
| the category next to the right margin. In both output formats, the body |
| of the definition is indented. Also, the name of the entity is entered |
| into the appropriate index: '@deffn' enters the name into the index of |
| functions, '@defvr' enters it into the index of variables, and so on |
| (*note Predefined Indices::). |
| |
| A manual need not and should not contain more than one definition for |
| a given name. An appendix containing a summary should use '@table' |
| rather than the definition commands. |
| |
| * Menu: |
| |
| * Def Cmd Template:: Writing descriptions using definition commands. |
| * Def Cmd Continuation Lines:: Continuing the heading over source lines. |
| * Optional Arguments:: Handling optional and repeated arguments. |
| * @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. |
| |
| |
| File: texinfo.info, Node: Def Cmd Template, Next: Def Cmd Continuation Lines, Up: Definition Commands |
| |
| 14.1 The Template for a Definition |
| ================================== |
| |
| The '@deffn' command is used for definitions of entities that resemble |
| functions. To write a definition using the '@deffn' command, write the |
| '@deffn' command at the beginning of a line and follow it on the same |
| line by the category of the entity, the name of the entity itself, and |
| its arguments (if any). Then write the body of the definition on |
| succeeding lines. (You may embed examples in the body.) Finally, end |
| the definition with an '@end deffn' command written on a line of its |
| own. |
| |
| The other definition commands follow the same format: a line with the |
| '@def...' command and whatever arguments are appropriate for that |
| command; the body of the definition; and a corresponding '@end' line. |
| |
| The template for a definition looks like this: |
| |
| @deffn CATEGORY NAME ARGUMENTS... |
| BODY-OF-DEFINITION |
| @end deffn |
| |
| For example, |
| |
| @deffn Command forward-word count |
| This command moves point forward @var{count} words |
| (or backward if @var{count} is negative). ... |
| @end deffn |
| |
| produces |
| |
| -- Command: forward-word count |
| This command moves point forward COUNT words (or backward if |
| COUNT is negative). ... |
| |
| Capitalize the category name like a title. If the name of the |
| category contains spaces, as in the phrase 'Interactive Command', |
| enclose it in braces. For example: |
| |
| @deffn {Interactive Command} isearch-forward |
| ... |
| @end deffn |
| |
| Otherwise, the second word will be mistaken for the name of the entity. |
| As a general rule, when any of the arguments in the heading line |
| _except_ the last one are more than one word, you need to enclose them |
| in braces. This may also be necessary if the text contains commands, |
| for example, '{declaraci@'on}' if you are writing in Spanish. |
| |
| Some of the definition commands are more general than others. The |
| '@deffn' command, for example, is the general definition command for |
| functions and the like--for entities that may take arguments. When you |
| use this command, you specify the category to which the entity belongs. |
| Three predefined, specialized variations ('@defun', '@defmac', and |
| '@defspec') specify the category for you: "Function", "Macro", and |
| "Special Form" respectively. (In Lisp, a special form is an entity much |
| like a function.) Similarly, the general '@defvr' command is |
| accompanied by several specialized variations for describing particular |
| kinds of variables. |
| |
| *Note Sample Function Definition::, for a detailed example of a |
| function definition, including the use of '@example' inside the |
| definition. |
| |
| |
| File: texinfo.info, Node: Def Cmd Continuation Lines, Next: Optional Arguments, Prev: Def Cmd Template, Up: Definition Commands |
| |
| 14.2 Definition Command Continuation Lines |
| ========================================== |
| |
| The heading line of a definition command can get very long. Therefore, |
| Texinfo has a special syntax allowing them to be continued over multiple |
| lines of the source file: a lone '@' at the end of each line to be |
| continued. Here's an example: |
| |
| @defun fn-name @ |
| arg1 arg2 arg3 |
| This is the basic continued defun. |
| @end defun |
| |
| produces: |
| |
| -- Function: fn-name arg1 arg2 arg3 |
| This is the basic continued defun. |
| |
| As you can see, the continued lines are combined, as if they had been |
| typed on one source line. |
| |
| Although this example only shows a one-line continuation, |
| continuations may extend over any number of lines, in the same way; put |
| an '@' at the end of each line to be continued. |
| |
| In general, any number of spaces or tabs before the '@' continuation |
| character are collapsed into a single space. There is one exception: |
| the Texinfo processors will not fully collapse whitespace around a |
| continuation inside braces. For example: |
| |
| @deffn {Category @ |
| Name} ... |
| |
| The output (not shown) has excess space between 'Category' and 'Name'. |
| To avoid this, elide the unwanted whitespace in your input, or put the |
| continuation '@' outside braces. |
| |
| '@' does not function as a continuation character in _any_ other |
| context. Ordinarily, '@' followed by a whitespace character (space, |
| tab, newline) produces a normal interword space (*note Multiple |
| Spaces::). |
| |
| |
| File: texinfo.info, Node: Optional Arguments, Next: @deffnx, Prev: Def Cmd Continuation Lines, Up: Definition Commands |
| |
| 14.3 Optional and Repeated Arguments |
| ==================================== |
| |
| Some entities take optional or repeated arguments, conventionally |
| specified by using square brackets and ellipses: an argument enclosed |
| within square brackets is optional, and an argument followed by an |
| ellipsis is optional and may be repeated more than once. |
| |
| Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional and |
| REPEATED-ARGS'...' stands for zero or more arguments. Parentheses are |
| used when several arguments are grouped into additional levels of list |
| structure in Lisp. |
| |
| Here is the '@defspec' line of an example of an imaginary |
| (complicated) special form: |
| |
| -- Special Form: foobar (var [from to [inc]]) body... |
| |
| In this example, the arguments FROM and TO are optional, but must both |
| be present or both absent. If they are present, INC may optionally be |
| specified as well. These arguments are grouped with the argument VAR |
| into a list, to distinguish them from BODY, which includes all remaining |
| elements of the form. |
| |
| In a Texinfo source file, this '@defspec' line is written like this: |
| |
| @defspec foobar (var [from to [inc]]) body@dots{} |
| |
| The function is listed in the Command and Variable Index under 'foobar'. |
| |
| |
| File: texinfo.info, Node: @deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands |
| |
| 14.4 '@deffnx', et al.: Two or More 'First' Lines |
| ================================================= |
| |
| To create two or more 'first' or header lines for a definition, follow |
| the first '@deffn' line by a line beginning with '@deffnx'. The |
| '@deffnx' command works exactly like '@deffn' except that it does not |
| generate extra vertical white space between it and the preceding line. |
| |
| For example, |
| |
| @deffn {Interactive Command} isearch-forward |
| @deffnx {Interactive Command} isearch-backward |
| These two search commands are similar except ... |
| @end deffn |
| |
| produces |
| |
| -- Interactive Command: isearch-forward |
| -- Interactive Command: isearch-backward |
| These two search commands are similar except ... |
| |
| Each definition command has an 'x' form: '@defunx', '@defvrx', |
| '@deftypefunx', etc. |
| |
| The 'x' forms work similarly to '@itemx' (*note @itemx::). |
| |
| |
| File: texinfo.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: @deffnx, Up: Definition Commands |
| |
| 14.5 The Definition Commands |
| ============================ |
| |
| Texinfo provides more than a dozen definition commands, all of which are |
| described in this section. |
| |
| The definition commands automatically enter the name of the entity in |
| the appropriate index: for example, '@deffn', '@defun', and '@defmac' |
| enter function names in the index of functions; '@defvr' and '@defvar' |
| enter variable names in the index of variables. |
| |
| Although the examples that follow mostly illustrate Lisp, the |
| commands can be used for other programming languages. |
| |
| * Menu: |
| |
| * Functions Commands:: Commands for functions and similar entities. |
| * Variables Commands:: Commands for variables and similar entities. |
| * Typed Functions:: Commands for functions in typed languages. |
| * Typed Variables:: Commands for variables in typed languages. |
| * Data Types:: The definition command for data types. |
| * Abstract Objects:: Commands for object-oriented programming. |
| |
| |
| File: texinfo.info, Node: Functions Commands, Next: Variables Commands, Up: Def Cmds in Detail |
| |
| 14.5.1 Functions and Similar Entities |
| ------------------------------------- |
| |
| This section describes the commands for describing functions and similar |
| entities: |
| |
| '@deffn CATEGORY NAME ARGUMENTS...' |
| The '@deffn' command is the general definition command for |
| functions, interactive commands, and similar entities that may take |
| arguments. You must choose a term to describe the category of |
| entity being defined; for example, "Function" could be used if the |
| entity is a function. The '@deffn' command is written at the |
| beginning of a line and is followed on the same line by the |
| category of entity being described, the name of this particular |
| entity, and its arguments, if any. Terminate the definition with |
| '@end deffn' on a line of its own. |
| |
| For example, here is a definition: |
| |
| @deffn Command forward-char nchars |
| Move point forward @var{nchars} characters. |
| @end deffn |
| |
| This shows a rather terse definition for a "command" named |
| 'forward-char' with one argument, NCHARS. |
| |
| '@deffn' prints argument names such as NCHARS in slanted type in |
| the printed output, because we think of these names as |
| metasyntactic variables--they stand for the actual argument values. |
| Within the text of the description, however, write an argument name |
| explicitly with '@var' to refer to the value of the argument. In |
| the example above, we used '@var{nchars}' in this way. |
| |
| In the extremely unusual case when an argument name contains '--', |
| or another character sequence which is treated specially (*note |
| Conventions::), use '@code' around the special characters. This |
| avoids the conversion to typographic en-dashes and em-dashes. |
| |
| The template for '@deffn' is: |
| |
| @deffn CATEGORY NAME ARGUMENTS... |
| BODY-OF-DEFINITION |
| @end deffn |
| |
| '@defun NAME ARGUMENTS...' |
| The '@defun' command is the definition command for functions. |
| '@defun' is equivalent to '@deffn Function ...'. Terminate the |
| definition with '@end defun' on a line of its own. Thus, the |
| template is: |
| |
| @defun FUNCTION-NAME ARGUMENTS... |
| BODY-OF-DEFINITION |
| @end defun |
| |
| '@defmac NAME ARGUMENTS...' |
| The '@defmac' command is the definition command for macros. |
| '@defmac' is equivalent to '@deffn Macro ...' and works like |
| '@defun'. |
| |
| '@defspec NAME ARGUMENTS...' |
| The '@defspec' command is the definition command for special forms. |
| (In Lisp, a special form is an entity much like a function; *note |
| (elisp)Special Forms::.) '@defspec' is equivalent to '@deffn |
| {Special Form} ...' and works like '@defun'. |
| |
| All these commands create entries in the index of functions. |
| |
| |
| File: texinfo.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail |
| |
| 14.5.2 Variables and Similar Entities |
| ------------------------------------- |
| |
| Here are the commands for defining variables and similar entities: |
| |
| '@defvr CATEGORY NAME' |
| The '@defvr' command is a general definition command for something |
| like a variable--an entity that records a value. You must choose a |
| term to describe the category of entity being defined; for example, |
| "Variable" could be used if the entity is a variable. Write the |
| '@defvr' command at the beginning of a line and follow it on the |
| same line by the category of the entity and the name of the entity. |
| |
| We recommend capitalizing the category name like a title. If the |
| name of the category contains spaces, as in the name "User Option", |
| enclose it in braces. Otherwise, the second word will be mistaken |
| for the name of the entity. For example, |
| |
| @defvr {User Option} fill-column |
| This buffer-local variable specifies |
| the maximum width of filled lines. |
| ... |
| @end defvr |
| |
| Terminate the definition with '@end defvr' on a line of its own. |
| |
| The template is: |
| |
| @defvr CATEGORY NAME |
| BODY-OF-DEFINITION |
| @end defvr |
| |
| '@defvr' creates an entry in the index of variables for NAME. |
| |
| '@defvar NAME' |
| The '@defvar' command is the definition command for variables. |
| '@defvar' is equivalent to '@defvr Variable ...'. |
| |
| For example: |
| |
| @defvar kill-ring |
| ... |
| @end defvar |
| |
| The template is: |
| |
| @defvar NAME |
| BODY-OF-DEFINITION |
| @end defvar |
| |
| '@defvar' creates an entry in the index of variables for NAME. |
| |
| '@defopt NAME' |
| The '@defopt' command is the definition command for "user options", |
| i.e., variables intended for users to change according to taste; |
| Emacs has many such (*note (emacs)Variables::). '@defopt' is |
| equivalent to '@defvr {User Option} ...' and works like '@defvar'. |
| It creates an entry in the index of variables. |
| |
| |
| File: texinfo.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail |
| |
| 14.5.3 Functions in Typed Languages |
| ----------------------------------- |
| |
| The '@deftypefn' command and its variations are for describing functions |
| in languages in which you must declare types of variables and functions, |
| such as C and C++. |
| |
| '@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...' |
| The '@deftypefn' command is the general definition command for |
| functions and similar entities that may take arguments and that are |
| typed. The '@deftypefn' command is written at the beginning of a |
| line and is followed on the same line by the category of entity |
| being described, the type of the returned value, the name of this |
| particular entity, and its arguments, if any. |
| |
| For example, |
| |
| @deftypefn {Library Function} int foobar @ |
| (int @var{foo}, float @var{bar}) |
| ... |
| @end deftypefn |
| |
| produces: |
| |
| -- Library Function: int foobar (int FOO, float BAR) |
| ... |
| |
| This means that 'foobar' is a "library function" that returns an |
| 'int', and its arguments are FOO (an 'int') and BAR (a 'float'). |
| |
| Since in typed languages, the actual names of the arguments are |
| typically scattered among data type names and keywords, Texinfo |
| cannot find them without help. You can either (a) write everything |
| as straight text, and it will be printed in slanted type; (b) use |
| '@var' for the variable names, which will uppercase the variable |
| names in Info and use the slanted typewriter font in printed |
| output; (c) use '@var' for the variable names and '@code' for the |
| type names and keywords, which will be dutifully obeyed. |
| |
| The template for '@deftypefn' is: |
| |
| @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ... |
| BODY-OF-DESCRIPTION |
| @end deftypefn |
| |
| Note that if the CATEGORY or DATA TYPE is more than one word then |
| it must be enclosed in braces to make it a single argument. |
| |
| If you are describing a procedure in a language that has packages, |
| such as Ada, you might consider using '@deftypefn' in a manner |
| somewhat contrary to the convention described in the preceding |
| paragraphs. For example: |
| |
| @deftypefn stacks private push @ |
| (@var{s}:in out stack; @ |
| @var{n}:in integer) |
| ... |
| @end deftypefn |
| |
| (In these examples the '@deftypefn' arguments are shown using |
| continuations (*note Def Cmd Continuation Lines::), but could be on |
| a single line.) |
| |
| In this instance, the procedure is classified as belonging to the |
| package 'stacks' rather than classified as a 'procedure' and its |
| data type is described as 'private'. (The name of the procedure is |
| 'push', and its arguments are S and N.) |
| |
| '@deftypefn' creates an entry in the index of functions for NAME. |
| |
| '@deftypefun DATA-TYPE NAME ARGUMENTS...' |
| The '@deftypefun' command is the specialized definition command for |
| functions in typed languages. The command is equivalent to |
| '@deftypefn Function ...'. The template is: |
| |
| @deftypefun TYPE NAME ARGUMENTS... |
| BODY-OF-DESCRIPTION |
| @end deftypefun |
| |
| '@deftypefun' creates an entry in the index of functions for NAME. |
| |
| Ordinarily, the return type is printed on the same line as the |
| function name and arguments, as shown above. In source code, GNU style |
| is to put the return type on a line by itself. So Texinfo provides an |
| option to do that: '@deftypefnnewline on'. |
| |
| This affects typed functions only--not untyped functions, not typed |
| variables, etc.. Specifically, it affects the commands in this section, |
| and the analogous commands for object-oriented languages, namely |
| '@deftypeop' and '@deftypemethod' (*note Object-Oriented Methods::). |
| |
| Specifying '@deftypefnnewline off' reverts to the default. |
| |
| |
| File: texinfo.info, Node: Typed Variables, Next: Data Types, Prev: Typed Functions, Up: Def Cmds in Detail |
| |
| 14.5.4 Variables in Typed Languages |
| ----------------------------------- |
| |
| Variables in typed languages are handled in a manner similar to |
| functions in typed languages. *Note Typed Functions::. The general |
| definition command '@deftypevr' corresponds to '@deftypefn' and the |
| specialized definition command '@deftypevar' corresponds to |
| '@deftypefun'. |
| |
| '@deftypevr CATEGORY DATA-TYPE NAME' |
| The '@deftypevr' command is the general definition command for |
| something like a variable in a typed language--an entity that |
| records a value. You must choose a term to describe the category |
| of the entity being defined; for example, "Variable" could be used |
| if the entity is a variable. |
| |
| The '@deftypevr' command is written at the beginning of a line and |
| is followed on the same line by the category of the entity being |
| described, the data type, and the name of this particular entity. |
| |
| For example: |
| |
| @deftypevr {Global Flag} int enable |
| ... |
| @end deftypevr |
| |
| produces the following: |
| |
| -- Global Flag: int enable |
| ... |
| |
| The template is: |
| |
| @deftypevr CATEGORY DATA-TYPE NAME |
| BODY-OF-DESCRIPTION |
| @end deftypevr |
| |
| '@deftypevar DATA-TYPE NAME' |
| The '@deftypevar' command is the specialized definition command for |
| variables in typed languages. '@deftypevar' is equivalent to |
| '@deftypevr Variable ...'. The template is: |
| |
| @deftypevar DATA-TYPE NAME |
| BODY-OF-DESCRIPTION |
| @end deftypevar |
| |
| These commands create entries in the index of variables. |
| |
| |
| File: texinfo.info, Node: Data Types, Next: Abstract Objects, Prev: Typed Variables, Up: Def Cmds in Detail |
| |
| 14.5.5 Data Types |
| ----------------- |
| |
| Here is the command for data types: |
| |
| '@deftp CATEGORY NAME ATTRIBUTES...' |
| The '@deftp' command is the generic definition command for data |
| types. The command is written at the beginning of a line and is |
| followed on the same line by the category, by the name of the type |
| (which is a word like 'int' or 'float'), and then by names of |
| attributes of objects of that type. Thus, you could use this |
| command for describing 'int' or 'float', in which case you could |
| use 'data type' as the category. (A data type is a category of |
| certain objects for purposes of deciding which operations can be |
| performed on them.) |
| |
| In Lisp, for example, "pair" names a particular data type, and an |
| object of that type has two slots called the CAR and the CDR. Here |
| is how you would write the first line of a definition of 'pair'. |
| |
| @deftp {Data type} pair car cdr |
| ... |
| @end deftp |
| |
| The template is: |
| |
| @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES... |
| BODY-OF-DEFINITION |
| @end deftp |
| |
| '@deftp' creates an entry in the index of data types. |
| |
| |
| File: texinfo.info, Node: Abstract Objects, Prev: Data Types, Up: Def Cmds in Detail |
| |
| 14.5.6 Object-Oriented Programming |
| ---------------------------------- |
| |
| Here are the commands for formatting descriptions about abstract |
| objects, such as are used in object-oriented programming. A class is a |
| defined type of abstract object. An instance of a class is a particular |
| object that has the type of the class. An instance variable is a |
| variable that belongs to the class but for which each instance has its |
| own value. |
| |
| * Menu: |
| |
| * Variables: Object-Oriented Variables. |
| * Methods: Object-Oriented Methods. |
| |
| |
| File: texinfo.info, Node: Object-Oriented Variables, Next: Object-Oriented Methods, Up: Abstract Objects |
| |
| 14.5.6.1 Object-Oriented Variables |
| .................................. |
| |
| These commands allow you to define different sorts of variables in |
| object-oriented programming languages. |
| |
| '@defcv CATEGORY CLASS NAME' |
| The '@defcv' command is the general definition command for |
| variables associated with classes in object-oriented programming. |
| The '@defcv' command is followed by three arguments: the category |
| of thing being defined, the class to which it belongs, and its |
| name. For instance: |
| |
| @defcv {Class Option} Window border-pattern |
| ... |
| @end defcv |
| |
| produces: |
| -- Class Option of Window: border-pattern |
| ... |
| |
| '@defcv' creates an entry in the index of variables. |
| |
| '@deftypecv CATEGORY CLASS DATA-TYPE NAME' |
| The '@deftypecv' command is the definition command for typed class |
| variables in object-oriented programming. It is analogous to |
| '@defcv' with the addition of the DATA-TYPE parameter to specify |
| the type of the instance variable. Ordinarily, the data type is a |
| programming language construct that should be marked with '@code'. |
| For instance: |
| |
| @deftypecv {Class Option} Window @code{int} border-pattern |
| ... |
| @end deftypecv |
| |
| produces: |
| |
| -- Class Option of Window: 'int' border-pattern |
| ... |
| |
| '@deftypecv' creates an entry in the index of variables. |
| |
| '@defivar CLASS NAME' |
| The '@defivar' command is the definition command for instance |
| variables in object-oriented programming. '@defivar' is equivalent |
| to '@defcv {Instance Variable} ...'. For instance: |
| |
| @defivar Window border-pattern |
| ... |
| @end defivar |
| |
| produces: |
| |
| -- Instance Variable of Window: border-pattern |
| ... |
| |
| '@defivar' creates an entry in the index of variables. |
| |
| '@deftypeivar CLASS DATA-TYPE NAME' |
| The '@deftypeivar' command is the definition command for typed |
| instance variables in object-oriented programming. It is analogous |
| to '@defivar' with the addition of the DATA-TYPE parameter to |
| specify the type of the instance variable. Ordinarily, the data |
| type is a programming language construct that should be marked with |
| '@code'. For instance: |
| |
| @deftypeivar Window @code{int} border-pattern |
| ... |
| @end deftypeivar |
| |
| produces: |
| |
| -- Instance Variable of Window: 'int' border-pattern |
| ... |
| |
| '@deftypeivar' creates an entry in the index of variables. |
| |
| |
| File: texinfo.info, Node: Object-Oriented Methods, Prev: Object-Oriented Variables, Up: Abstract Objects |
| |
| 14.5.6.2 Object-Oriented Methods |
| ................................ |
| |
| These commands allow you to define different sorts of function-like |
| entities resembling methods in object-oriented programming languages. |
| These entities take arguments, as functions do, but are associated with |
| particular classes of objects. |
| |
| '@defop CATEGORY CLASS NAME ARGUMENTS...' |
| The '@defop' command is the general definition command for these |
| method-like entities. |
| |
| For example, some systems have constructs called "wrappers" that |
| are associated with classes as methods are, but that act more like |
| macros than like functions. You could use '@defop Wrapper' to |
| describe one of these. |
| |
| Sometimes it is useful to distinguish methods and "operations". |
| You can think of an operation as the specification for a method. |
| Thus, a window system might specify that all window classes have a |
| method named 'expose'; we would say that this window system defines |
| an 'expose' operation on windows in general. Typically, the |
| operation has a name and also specifies the pattern of arguments; |
| all methods that implement the operation must accept the same |
| arguments, since applications that use the operation do so without |
| knowing which method will implement it. |
| |
| Often it makes more sense to document operations than methods. For |
| example, window application developers need to know about the |
| 'expose' operation, but need not be concerned with whether a given |
| class of windows has its own method to implement this operation. |
| To describe this operation, you would write: |
| |
| @defop Operation windows expose |
| |
| The '@defop' command is written at the beginning of a line and is |
| followed on the same line by the overall name of the category of |
| operation, the name of the class of the operation, the name of the |
| operation, and its arguments, if any. |
| |
| The template is: |
| @defop CATEGORY CLASS NAME ARGUMENTS... |
| BODY-OF-DEFINITION |
| @end defop |
| |
| '@defop' creates an entry, such as ''expose' on 'windows'', in the |
| index of functions. |
| |
| '@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' |
| The '@deftypeop' command is the definition command for typed |
| operations in object-oriented programming. It is similar to |
| '@defop' with the addition of the DATA-TYPE parameter to specify |
| the return type of the method. '@deftypeop' creates an entry in |
| the index of functions. |
| |
| '@defmethod CLASS NAME ARGUMENTS...' |
| The '@defmethod' command is the definition command for methods in |
| object-oriented programming. A method is a kind of function that |
| implements an operation for a particular class of objects and its |
| subclasses. |
| |
| '@defmethod' is equivalent to '@defop Method ...'. The command is |
| written at the beginning of a line and is followed by the name of |
| the class of the method, the name of the method, and its arguments, |
| if any. |
| |
| For example: |
| @defmethod bar-class bar-method argument |
| ... |
| @end defmethod |
| |
| illustrates the definition for a method called 'bar-method' of the |
| class 'bar-class'. The method takes an argument. |
| |
| '@defmethod' creates an entry in the index of functions. |
| |
| '@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...' |
| The '@deftypemethod' command is the definition command for methods |
| in object-oriented typed languages, such as C++ and Java. It is |
| similar to the '@defmethod' command with the addition of the |
| DATA-TYPE parameter to specify the return type of the method. |
| '@deftypemethod' creates an entry in the index of functions. |
| |
| The typed commands are affected by the '@deftypefnnewline' option |
| (*note Functions in Typed Languages: Typed Functions.). |
| |
| |
| File: texinfo.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands |
| |
| 14.6 Conventions for Writing Definitions |
| ======================================== |
| |
| When you write a definition using '@deffn', '@defun', or one of the |
| other definition commands, please take care to use arguments that |
| indicate the meaning, as with the COUNT argument to the 'forward-word' |
| function. Also, if the name of an argument contains the name of a type, |
| such as INTEGER, take care that the argument actually is of that type. |
| |
| |
| File: texinfo.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands |
| |
| 14.7 A Sample Function Definition |
| ================================= |
| |
| A function definition uses the '@defun' and '@end defun' commands. The |
| name of the function follows immediately after the '@defun' command and |
| it is followed, on the same line, by the parameter list. |
| |
| Here is a definition from *note (elisp)Calling Functions::. |
| |
| -- Function: apply function &rest arguments |
| 'apply' calls FUNCTION with ARGUMENTS, just like 'funcall' but |
| with one difference: the last of ARGUMENTS is a list of |
| arguments to give to FUNCTION, rather than a single argument. |
| We also say that this list is "appended" to the other |
| arguments. |
| |
| 'apply' returns the result of calling FUNCTION. As with |
| 'funcall', FUNCTION must either be a Lisp function or a |
| primitive function; special forms and macros do not make sense |
| in 'apply'. |
| |
| (setq f 'list) |
| => list |
| (apply f 'x 'y 'z) |
| error-> Wrong type argument: listp, z |
| (apply '+ 1 2 '(3 4)) |
| => 10 |
| (apply '+ '(1 2 3 4)) |
| => 10 |
| |
| (apply 'append '((a b c) nil (x y z) nil)) |
| => (a b c x y z) |
| |
| An interesting example of using 'apply' is found in the |
| description of 'mapcar'. |
| |
| In the Texinfo source file, this example looks like this: |
| |
| @defun apply function &rest arguments |
| @code{apply} calls @var{function} with |
| @var{arguments}, just like @code{funcall} but with one |
| difference: the last of @var{arguments} is a list of |
| arguments to give to @var{function}, rather than a single |
| argument. We also say that this list is @dfn{appended} |
| to the other arguments. |
| |
| @code{apply} returns the result of calling |
| @var{function}. As with @code{funcall}, |
| @var{function} must either be a Lisp function or a |
| primitive function; special forms and macros do not make |
| sense in @code{apply}. |
| |
| @example |
| (setq f 'list) |
| @result{} list |
| (apply f 'x 'y 'z) |
| @error{} Wrong type argument: listp, z |
| (apply '+ 1 2 '(3 4)) |
| @result{} 10 |
| (apply '+ '(1 2 3 4)) |
| @result{} 10 |
| |
| (apply 'append '((a b c) nil (x y z) nil)) |
| @result{} (a b c x y z) |
| @end example |
| |
| An interesting example of using @code{apply} is found |
| in the description of @code{mapcar}. |
| @end defun |
| |
| In this manual, this function is listed in the Command and Variable |
| Index under 'apply'. |
| |
| Ordinary variables and user options are described using a format like |
| that for functions except that variables do not take arguments. |
| |
| |
| File: texinfo.info, Node: Internationalization, Next: Conditionals, Prev: Definition Commands, Up: Top |
| |
| 15 Internationalization |
| *********************** |
| |
| Texinfo has some support for writing in languages other than English, |
| although this area still needs considerable work. (If you are yourself |
| helping to translate the fixed strings written to documents, *note |
| Internationalization of Document Strings::.) |
| |
| For a list of the various accented and special characters Texinfo |
| supports, see *note Inserting Accents::. |
| |
| * Menu: |
| |
| * @documentlanguage:: Declaring the current language. |
| * @documentencoding:: Declaring the input encoding. |
| |
| |
| File: texinfo.info, Node: @documentlanguage, Next: @documentencoding, Up: Internationalization |
| |
| 15.1 '@documentlanguage LL[_CC]': Set the Document Language |
| =========================================================== |
| |
| The '@documentlanguage' command declares the current document locale. |
| Write it on a line by itself, near the beginning of the file. |
| |
| @documentlanguage LL[_CC] |
| |
| Include a two-letter ISO 639-2 language code (LL) following the |
| command name, optionally followed by an underscore and two-letter |
| ISO 3166 two-letter country code (CC). If you have a multilingual |
| document, the intent is to be able to use this command multiple times, |
| to declare each language change. If the command is not used at all, the |
| default is 'en_US' for US English. |
| |
| As with GNU Gettext (*note (gettext)Top::), if the country code is |
| omitted, the main dialect is assumed where possible. For example, 'de' |
| is equivalent to 'de_DE' (German as spoken in Germany). |
| |
| For Info and other online output, this command changes the |
| translation of various "document strings" such as "see" in |
| cross-references (*note Cross References::), "Function' in defuns (*note |
| Definition Commands::), and so on. Some strings, such as "Node:", |
| "Next:", "Menu:", etc., are keywords in Info output, so are not |
| translated there; they are translated in other output formats. |
| |
| For TeX, this command causes a file 'txi-LOCALE.tex' to be read (if |
| it exists). If '@documentlanguage' argument contains the optional '_CC' |
| suffix, this is tried first. For example, with '@documentlanguage |
| de_DE', TeX first looks for 'txi-de_DE.tex', then 'txi-de.tex'. |
| |
| Such a 'txi-*' file is intended to redefine the various English words |
| used in TeX output, such as 'Chapter', 'See', and so on. We are aware |
| that individual words like these cannot always be translated in |
| isolation, and that a very different strategy would be required for |
| ideographic (among other) scripts. Help in improving Texinfo's language |
| support is welcome. |
| |
| '@documentlanguage' also changes TeX's current hyphenation patterns, |
| if the TeX program being run has the necessary support included. This |
| will generally not be the case for 'tex' itself, but will usually be the |
| case for up-to-date distributions of the extended TeX programs 'etex' |
| (DVI output) and 'pdftex' (PDF output). 'texi2dvi' will use the |
| extended TeXs if they are available (*note Format with texi2dvi::). |
| |
| In September 2006, the W3C Internationalization Activity released a |
| new recommendation for specifying languages: |
| <http://www.rfc-editor.org/rfc/bcp/bcp47.txt>. When Gettext supports |
| this new scheme, Texinfo will too. |
| |
| Since the lists of language codes and country codes are updated |
| relatively frequently, we don't attempt to list them here. The valid |
| language codes are on the official home page for ISO 639, |
| <http://www.loc.gov/standards/iso639-2/>. The country codes and the |
| official web site for ISO 3166 can be found via |
| <http://en.wikipedia.org/wiki/ISO_3166>. |
| |
| |
| File: texinfo.info, Node: @documentencoding, Prev: @documentlanguage, Up: Internationalization |
| |
| 15.2 '@documentencoding ENC': Set Input Encoding |
| ================================================ |
| |
| The '@documentencoding' command declares the input document encoding, |
| and can also affect the encoding of the output. Write it on a line by |
| itself, with a valid encoding specification following, near the |
| beginning of the file. |
| |
| @documentencoding ENC |
| |
| Texinfo supports these encodings: |
| |
| 'US-ASCII' |
| This has no particular effect, but it's included for completeness. |
| |
| 'UTF-8' |
| The vast global character encoding, expressed in 8-bit bytes. |
| |
| 'ISO-8859-1' |
| 'ISO-8859-15' |
| 'ISO-8859-2' |
| These specify the standard encodings for Western European (the |
| first two) and Eastern European languages (the third), |
| respectively. ISO 8859-15 replaces some little-used characters |
| from 8859-1 (e.g., precomposed fractions) with more commonly needed |
| ones, such as the Euro symbol (Euro). |
| |
| A full description of the encodings is beyond our scope here; one |
| useful reference is <http://czyborra.com/charsets/iso8859.html>. |
| |
| 'koi8-r' |
| This is the commonly used encoding for the Russian language. |
| |
| 'koi8-u' |
| This is the commonly used encoding for the Ukrainian language. |
| |
| Specifying an encoding ENC has the following effects: |
| |
| In Info output, a so-called 'Local Variables' section (*note |
| (emacs)File Variables::) is output including ENC. This allows Info |
| readers to set the encoding appropriately. It looks like this: |
| |
| Local Variables: |
| coding: ENC |
| End: |
| |
| Also, in Info and plain text output, unless the option |
| '--disable-encoding' is given to 'makeinfo', accent constructs and |
| special characters, such as '@'e', are output as the actual 8-bit or |
| UTF-8 character in the given encoding where possible. |
| |
| In HTML output, a '<meta>' tag is output, in the '<head>' section of |
| the HTML, that specifies ENC. Web servers and browsers cooperate to use |
| this information so the correct encoding is used to display the page, if |
| supported by the system. That looks like this: |
| |
| <meta http-equiv="Content-Type" content="text/html; |
| charset=ENC"> |
| |
| In XML and Docbook output, UTF-8 is always used for the output, |
| according to the conventions of those formats. |
| |
| In TeX output, the characters which are supported in the standard |
| Computer Modern fonts are output accordingly. For example, this means |
| using constructed accents rather than precomposed glyphs. Using a |
| missing character generates a warning message, as does specifying an |
| unimplemented encoding. |
| |
| Although modern TeX systems support nearly every script in use in the |
| world, this wide-ranging support is not available in 'texinfo.tex', and |
| it's not feasible to duplicate or incorporate all that effort. (Our |
| plan to support other scripts is to create a LaTeX back-end to |
| 'texi2any', where the support is already present.) |
| |
| For maximum portability of Texinfo documents across the many |
| different user environments in the world, we recommend sticking to 7-bit |
| ASCII in the input unless your particular manual needs a substantial |
| amount of non-ASCII, e.g., it's written in German. You can use the '@U' |
| command to insert an occasional needed character (*note Inserting |
| Unicode::). |
| |
| |
| File: texinfo.info, Node: Conditionals, Next: Defining New Texinfo Commands, Prev: Internationalization, Up: Top |
| |
| 16 Conditionally Visible Text |
| ***************************** |
| |
| The "conditional commands" allow you to use different text for different |
| output formats, or for general conditions that you define. For example, |
| you can use them to specify different text for the printed manual and |
| the Info output. |
| |
| The conditional commands comprise the following categories. |
| |
| * Commands specific to an output format (Info, TeX, HTML, ...). |
| |
| * Commands specific to any output format _excluding_ a given one |
| (e.g., not Info, not TeX, ...). |
| |
| * 'Raw' formatter text for any output format, passed straight through |
| with minimal (but not zero) interpretation of @-commands. |
| |
| * Format-independent variable substitutions, and testing if a |
| variable is set or clear. |
| |
| * Menu: |
| |
| * Conditional Commands:: Text for a given format. |
| * Conditional Not Commands:: Text for any format other than a given one. |
| * Raw Formatter Commands:: Using raw formatter commands. |
| * Inline Conditionals:: Brace-delimited conditional text. |
| * @set @clear @value:: Variable tests and substitutions. |
| * Testing for Texinfo Commands:: Testing if a Texinfo command is available. |
| * Conditional Nesting:: Using conditionals inside conditionals. |
| |
| |
| File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals |
| |
| 16.1 Conditional Commands |
| ========================= |
| |
| Texinfo has an '@ifFORMAT' environment for each output format, to allow |
| conditional inclusion of text for a particular output format. |
| |
| '@ifinfo' begins segments of text that should be ignored by TeX when |
| it typesets the printed manual, and by 'makeinfo' when not producing |
| Info output. The segment of text appears only in the Info file and, for |
| historical compatibility, the plain text output. |
| |
| The environments for the other formats are analogous: |
| |
| '@ifdocbook ... @end ifdocbook' |
| Text to appear only in the Docbook output. |
| |
| '@ifhtml ... @end ifhtml' |
| Text to appear only in the HTML output. |
| |
| '@ifplaintext ... @end ifplaintext' |
| Text to appear only in the plain text output. |
| |
| '@iftex ... @end iftex' |
| Text to appear only in the printed manual. |
| |
| '@ifxml ... @end ifxml' |
| Text to appear only in the XML output. |
| |
| The '@if...' and '@end if...' commands must appear on lines by |
| themselves in your source file. The newlines following the commands are |
| (more or less) treated as whitespace, so that the conditional text is |
| flowed normally into a surrounding paragraph. |
| |
| The '@if...' constructs are intended to conditionalize normal Texinfo |
| source; *note Raw Formatter Commands::, for using underlying format |
| commands directly. |
| |
| Here is an example showing all these conditionals: |
| |
| @iftex |
| This text will appear only in the printed manual. |
| @end iftex |
| @ifinfo |
| However, this text will appear only in Info and plain text. |
| @end ifinfo |
| @ifhtml |
| And this text will only appear in HTML. |
| @end ifhtml |
| @ifplaintext |
| Whereas this text will only appear in plain text. |
| @end ifplaintext |
| @ifxml |
| Notwithstanding that this will only appear in XML. |
| @end ifxml |
| @ifdocbook |
| Nevertheless, this will only appear in Docbook. |
| @end ifdocbook |
| |
| The preceding example produces the following line: |
| |
| However, this text will appear only in Info and plain text. |
| |
| Notice that you only see one of the input lines, depending on which |
| version of the manual you are reading. |
| |
| In complex documents, you may want Texinfo to issue an error message |
| in some conditionals that should not ever be processed. The |
| '@errormsg{TEXT}' command will do this; it takes one argument, the text |
| of the error message, which is expanded more or less as if it were Info |
| text. |
| |
| We mention '@errormsg{}' here even though it is not strictly related |
| to conditionals, since in practice it is most likely to be useful in |
| that context. Technically, it can be used anywhere. *Note External |
| Macro Processors::, for a caveat regarding the line numbers which |
| '@errormsg' emits in TeX. |
| |
| |
| File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals |
| |
| 16.2 Conditional Not Commands |
| ============================= |
| |
| You can specify text to be included in any output format _other_ than a |
| given one with the '@ifnot...' environments: |
| |
| @ifnotdocbook ... @end ifnotdocbook |
| @ifnothtml ... @end ifnothtml |
| @ifnotinfo ... @end ifnotinfo |
| @ifnotplaintext ... @end ifnotplaintext |
| @ifnottex ... @end ifnottex |
| @ifnotxml ... @end ifnotxml |
| |
| The '@ifnot...' command and the '@end' command must appear on lines by |
| themselves in your actual source file. |
| |
| If the output file is being made in the given format, the region is |
| _ignored_. Otherwise, it is included. |
| |
| There is one exception (for historical compatibility): '@ifnotinfo' |
| text is omitted for both Info and plain text output, not just Info. To |
| specify text which appears only in Info and not in plain text, use |
| '@ifnotplaintext', like this: |
| |
| @ifinfo |
| @ifnotplaintext |
| This will be in Info, but not plain text. |
| @end ifnotplaintext |
| @end ifinfo |
| |
| The regions delimited by these commands are ordinary Texinfo source |
| as with '@iftex', not raw formatter source as with '@tex' (*note Raw |
| Formatter Commands::). |
| |
| |
| File: texinfo.info, Node: Raw Formatter Commands, Next: Inline Conditionals, Prev: Conditional Not Commands, Up: Conditionals |
| |
| 16.3 Raw Formatter Commands |
| =========================== |
| |
| The '@if...' conditionals just described must be used only with normal |
| Texinfo source. For instance, most features of plain TeX will not work |
| within '@iftex'. The purpose of '@if...' is to provide conditional |
| processing for Texinfo source, not provide access to underlying |
| formatting features. For that, Texinfo provides so-called "raw |
| formatter commands". They should only be used when truly required (most |
| documents do not need them). |
| |
| The first raw formatter command is '@tex'. You can enter plain TeX |
| completely, and use '\' in the TeX commands, by delineating a region |
| with the '@tex' and '@end tex' commands. All plain TeX commands and |
| category codes are restored within a '@tex' region. The sole exception |
| is that the '@' character still introduces a command, so that '@end tex' |
| can be recognized. Texinfo processors will not output material in such |
| a region, unless TeX output is being produced. |
| |
| In complex cases, you may wish to define new TeX macros within |
| '@tex'. You must use '\gdef' to do this, not '\def', because '@tex' |
| regions are processed in a TeX group. If you need to make several |
| definitions, you may wish to set '\globaldefs=1' (its value will be |
| restored to zero as usual when the group ends at '@end tex', so it won't |
| cause problems with the rest of the document). |
| |
| As an example, here is a displayed equation written in plain TeX: |
| |
| @tex |
| $$ \chi^2 = \sum_{i=1}^N |
| \left (y_i - (a + b x_i) |
| \over \sigma_i\right)^2 $$ |
| @end tex |
| |
| The output of this example will appear only in a printed manual. If you |
| are reading this in a format not generated by TeX, you will not see the |
| equation that appears in the printed manual. |
| |
| Analogously, you can use '@ifhtml ... @end ifhtml' to delimit Texinfo |
| source to be included in HTML output only, and '@html ... @end html' for |
| a region of raw HTML. |
| |
| Likewise, you can use '@ifxml ... @end ifxml' to delimit Texinfo |
| source to be included in XML output only, and '@xml ... @end xml' for a |
| region of raw XML. Regions of raw text in other formats will also be |
| present in the XML output, but with protection of XML characters and |
| within corresponding elements. For example, the raw HTML text: |
| |
| @html |
| <br /> |
| @end html |
| |
| will be included in the XML output as: |
| |
| <html> |
| <br /> |
| </html> |
| |
| Again likewise, you can use '@ifdocbook ... @end ifdocbook' to |
| delimit Texinfo source to be included in Docbook output only, and |
| '@docbook ... @end docbook' for a region of raw Docbook. |
| |
| The behavior of newlines in raw regions is unspecified. |
| |
| In all cases, in raw processing, '@' retains the same meaning as in |
| the remainder of the document. Thus, the Texinfo processors must |
| recognize and even execute, to some extent, the contents of the raw |
| regions, regardless of the final output format. Therefore, specifying |
| changes that globally affect the document inside a raw region leads to |
| unpredictable and generally undesirable behavior. For example, using |
| the '@kbdinputstyle' command inside a raw region is undefined. |
| |
| The remedy is simple: don't do that. Use the raw formatter commands |
| for their intended purpose, of providing material directly in the |
| underlying format. When you simply want to give different Texinfo |
| specifications for different output formats, use the '@if...' |
| conditionals and stay in Texinfo syntax. |
| |
| |
| File: texinfo.info, Node: Inline Conditionals, Next: @set @clear @value, Prev: Raw Formatter Commands, Up: Conditionals |
| |
| 16.4 Inline Conditionals: '@inline', '@inlineifelse', '@inlineraw' |
| ================================================================== |
| |
| Texinfo provides a set of conditional commands with arguments given |
| within braces: |
| |
| '@inlinefmt{FORMAT, TEXT}' |
| Process the Texinfo TEXT if FORMAT output is being generated. |
| |
| '@inlinefmtifelse{FORMAT, THEN-TEXT, ELSE-TEXT}' |
| Process the Texinfo THEN-TEXT if FORMAT output is being generated; |
| otherwise, process ELSE-TEXT. |
| |
| '@inlineraw{FORMAT, TEXT}' |
| Similar, but for raw TEXT (*note Raw Formatter Commands::). |
| |
| The supported FORMAT names are: |
| |
| docbook html info plaintext tex xml |
| |
| For example, |
| |
| @inlinefmt{html, @emph{HTML-only text}} |
| |
| is nearly equivalent to |
| |
| @ifhtml |
| @emph{HTML-only text} |
| @end ifhtml |
| |
| except that no whitespace is added, as happens in the latter |
| (environment) case. |
| |
| In these commands, whitespace is ignored after the comma separating |
| the arguments, as usual, but is _not_ ignored at the end of TEXT. |
| |
| To insert a literal at sign, left brace, or right brace in one of the |
| arguments, you must use the alphabetic commands '@atchar{}' (*note |
| Inserting an Atsign::), and '@lbracechar{}' or '@rbracechar{}' (*note |
| Inserting Braces::), or the parsing will become confused. |
| |
| With '@inlinefmtifelse', it is also necessary to use '@comma{}' to |
| avoid mistaking a ',' in the text for the delimiter. With '@inlinefmt' |
| and '@inlineraw', '@comma{}' is not required (though it's fine to use |
| it), since these commands always have exactly two arguments. |
| |
| For TeX, the processed TEXT cannot contain newline-delimited |
| commands. Text to be ignored (i.e., for non-TeX) can, though. |
| |
| Two other '@inline...' conditionals complement the '@ifset' and |
| '@ifclear' commands; see the next section. |
| |
| |
| File: texinfo.info, Node: @set @clear @value, Next: Testing for Texinfo Commands, Prev: Inline Conditionals, Up: Conditionals |
| |
| 16.5 Flags: '@set', '@clear', conditionals, and '@value' |
| ======================================================== |
| |
| You can direct the Texinfo formatting commands to format or ignore parts |
| of a Texinfo file with the '@set', '@clear', '@ifset', and '@ifclear' |
| commands. |
| |
| Here are brief descriptions of these commands, see the following |
| sections for more details: |
| |
| '@set FLAG [VALUE]' |
| Set the variable FLAG, to the optional VALUE if specified. |
| |
| '@clear FLAG' |
| Undefine the variable FLAG, whether or not it was previously |
| defined. |
| |
| '@ifset FLAG' |
| If FLAG is set, text through the next '@end ifset' command is |
| formatted. If FLAG is clear, text through the following '@end |
| ifset' command is ignored. |
| |
| '@inlineifset{FLAG, TEXT}' |
| Brace-delimited version of '@ifset'. |
| |
| '@ifclear FLAG' |
| If FLAG is set, text through the next '@end ifclear' command is |
| ignored. If FLAG is clear, text through the following '@end |
| ifclear' command is formatted. |
| |
| '@inlineifclear{FLAG, TEXT}' |
| Brace-delimited version of '@ifclear'. |
| |
| * Menu: |
| |
| * @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. |
| |
| |
| File: texinfo.info, Node: @set @value, Next: @ifset @ifclear, Up: @set @clear @value |
| |
| 16.5.1 '@set' and '@value' |
| -------------------------- |
| |
| You use the '@set' command to specify a value for a flag, which is later |
| expanded by the '@value' command. |
| |
| A "flag" (aka "variable") name is an identifier starting with an |
| alphanumeric, '-', or '_'. Subsequent characters, if any, may not be |
| whitespace, '@', braces, angle brackets, or any of '~`^+|'; other |
| characters, such as '%', may work. However, it is best to use only |
| letters and numerals in a flag name, not '-' or '_' or others--they will |
| work in some contexts, but not all, due to limitations in TeX. |
| |
| The value is the remainder of the input line, and can contain |
| anything. However, unlike most other commands which take the rest of |
| the line as a value, '@set' need not appear at the beginning of a line. |
| |
| Write the '@set' command like this: |
| |
| @set foo This is a string. |
| |
| This sets the value of the flag 'foo' to "This is a string.". |
| |
| The Texinfo formatters then replace a '@value{FLAG}' command with the |
| string to which FLAG is set. Thus, when 'foo' is set as shown above, |
| the Texinfo formatters convert this: |
| |
| @value{foo} |
| to this: |
| This is a string. |
| |
| You can write a '@value' command within a paragraph; but you must |
| write a '@set' command on a line of its own. |
| |
| If you write the '@set' command like this: |
| |
| @set foo |
| |
| without specifying a string, the value of 'foo' is the empty string. |
| |
| If you clear a previously set flag with '@clear FLAG', a subsequent |
| '@value{flag}' command will report an error. |
| |
| For example, if you set 'foo' as follows: |
| |
| @set howmuch very, very, very |
| |
| then the formatters transform |
| |
| It is a @value{howmuch} wet day. |
| into |
| It is a very, very, very wet day. |
| |
| If you write |
| |
| @clear howmuch |
| |
| then the formatters transform |
| |
| It is a @value{howmuch} wet day. |
| into |
| It is a {No value for "howmuch"} wet day. |
| |
| '@value' cannot be reliably used as the argument to an accent command |
| (*note Inserting Accents::). For example, this fails: |
| |
| @set myletter a |
| @'@value{myletter} |
| |
| |
| File: texinfo.info, Node: @ifset @ifclear, Next: @inlineifset @inlineifclear, Prev: @set @value, Up: @set @clear @value |
| |
| 16.5.2 '@ifset' and '@ifclear' |
| ------------------------------ |
| |
| When a FLAG is set, the Texinfo formatting commands format text between |
| subsequent pairs of '@ifset FLAG' and '@end ifset' commands. When the |
| FLAG is cleared, the Texinfo formatting commands do _not_ format the |
| text. '@ifclear' operates analogously. |
| |
| Write the conditionally formatted text between '@ifset FLAG' and |
| '@end ifset' commands, like this: |
| |
| @ifset FLAG |
| CONDITIONAL-TEXT |
| @end ifset |
| |
| For example, you can create one document that has two variants, such |
| as a manual for a 'large' and 'small' model: |
| |
| You can use this machine to dig up shrubs |
| without hurting them. |
| |
| @set large |
| |
| @ifset large |
| It can also dig up fully grown trees. |
| @end ifset |
| |
| Remember to replant promptly ... |
| |
| In the example, the formatting commands will format the text between |
| '@ifset large' and '@end ifset' because the 'large' flag is set. |
| |
| When FLAG is cleared, the Texinfo formatting commands do _not_ format |
| the text between '@ifset FLAG' and '@end ifset'; that text is ignored |
| and does not appear in either printed or Info output. |
| |
| For example, if you clear the flag of the preceding example by |
| writing an '@clear large' command after the '@set large' command (but |
| before the conditional text), then the Texinfo formatting commands |
| ignore the text between the '@ifset large' and '@end ifset' commands. |
| In the formatted output, that text does not appear; in both printed and |
| Info output, you see only the lines that say, "You can use this machine |
| to dig up shrubs without hurting them. Remember to replant promptly |
| ...". |
| |
| If a flag is cleared with a '@clear FLAG' command, then the |
| formatting commands format text between subsequent pairs of '@ifclear' |
| and '@end ifclear' commands. But if the flag is set with '@set FLAG', |
| then the formatting commands do _not_ format text between an '@ifclear' |
| and an '@end ifclear' command; rather, they ignore that text. An |
| '@ifclear' command looks like this: |
| |
| @ifclear FLAG |
| |
| |
| File: texinfo.info, Node: @inlineifset @inlineifclear, Next: @value Example, Prev: @ifset @ifclear, Up: @set @clear @value |
| |
| 16.5.3 '@inlineifset' and '@inlineifclear' |
| ------------------------------------------ |
| |
| '@inlineifset' and '@inlineifclear' provide brace-delimited alternatives |
| to the '@ifset' and '@ifclear' forms, similar to the other '@inline...' |
| Commands (*note Inline Conditionals::). The same caveats about argument |
| parsing given there apply here too. |
| |
| '@inlineifset{VAR, TEXT}' |
| Process the Texinfo TEXT if the flag VAR is defined. |
| |
| '@inlineifclear{VAR, TEXT}' |
| Process the Texinfo TEXT if the flag VAR is not defined. |
| |
| Except for the syntax, their general behavior and purposes is the |
| same as with '@ifset' and '@ifclear', described in the previous section. |
| |
| |
| File: texinfo.info, Node: @value Example, Prev: @inlineifset @inlineifclear, Up: @set @clear @value |
| |
| 16.5.4 '@value' Example |
| ----------------------- |
| |
| You can use the '@value' command to minimize the number of places you |
| need to change when you record an update to a manual. *Note GNU Sample |
| Texts::, for the full text of an example of using this to work with |
| Automake distributions. |
| |
| This example is adapted from *note (make)Top::. |
| |
| 1. Set the flags: |
| |
| @set EDITION 0.35 Beta |
| @set VERSION 3.63 Beta |
| @set UPDATED 14 August 1992 |
| @set UPDATE-MONTH August 1992 |
| |
| 2. Write text for the '@copying' section (*note @copying::): |
| |
| @copying |
| This is Edition @value{EDITION}, |
| last updated @value{UPDATED}, |
| of @cite{The GNU Make Manual}, |
| for @code{make}, version @value{VERSION}. |
| |
| Copyright ... |
| |
| Permission is granted ... |
| @end copying |
| |
| 3. Write text for the title page, for people reading the printed |
| manual: |
| |
| @titlepage |
| @title GNU Make |
| @subtitle A Program for Directing Recompilation |
| @subtitle Edition @value{EDITION}, ... |
| @subtitle @value{UPDATE-MONTH} |
| @page |
| @insertcopying |
| ... |
| @end titlepage |
| |
| (On a printed cover, a date listing the month and the year looks |
| less fussy than a date listing the day as well as the month and |
| year.) |
| |
| 4. Write text for the Top node, for people reading the Info file: |
| |
| @ifnottex |
| @node Top |
| @top Make |
| |
| This is Edition @value{EDITION}, |
| last updated @value{UPDATED}, |
| of @cite{The GNU Make Manual}, |
| for @code{make}, version @value{VERSION}. |
| @end ifnottex |
| |
| After you format the manual, the '@value' constructs have been |
| expanded, so the output contains text like this: |
| |
| This is Edition 0.35 Beta, last updated 14 August 1992, |
| of `The GNU Make Manual', for `make', Version 3.63 Beta. |
| |
| When you update the manual, you change only the values of the flags; |
| you do not need to edit the three sections. |
| |
| |
| File: texinfo.info, Node: Testing for Texinfo Commands, Next: Conditional Nesting, Prev: @set @clear @value, Up: Conditionals |
| |
| 16.6 Testing for Texinfo Commands: '@ifcommanddefined', '@ifcommandnotdefined' |
| ============================================================================== |
| |
| Occasionally, you may want to arrange for your manual to test if a given |
| Texinfo command is available and (presumably) do some sort of fallback |
| formatting if not. There are conditionals '@ifcommanddefined' and |
| '@ifcommandnotdefined' to do this. For example: |
| |
| @ifcommanddefined node |
| Good, @samp{@@node} is defined. |
| @end ifcommanddefined |
| |
| will output the expected 'Good, '@node' is defined.'. |
| |
| This conditional will also consider true any new commands defined by |
| the document via '@macro', '@alias', '@definfoenclose', and |
| '@def(code)index' (*note Defining New Texinfo Commands::). Caveat: the |
| TeX implementation reports internal TeX commands, in addition to all the |
| Texinfo commands, as being "defined"; the 'makeinfo' implementation is |
| reliable in this regard, however. |
| |
| You can check the 'NEWS' file in the Texinfo source distribution and |
| linked from the Texinfo home page |
| (<http://www.gnu.org/software/texinfo>) to see when a particular command |
| was added. |
| |
| These command-checking conditionals themselves were added in |
| Texinfo 5.0, released in 2013--decades after Texinfo's inception. In |
| order to test if they themselves are available, the predefined flag |
| 'txicommandconditionals' can be tested, like this: |
| |
| @ifset txicommandconditionals |
| @ifcommandnotdefined foobarnode |
| (Good, @samp{@@foobarnode} is not defined.) |
| @end ifcommandnotdefined |
| @end ifset |
| |
| Since flags (see the previous section) were added early in the |
| existence of Texinfo, there is no problem with assuming they are |
| available. |
| |
| We recommend avoiding these tests whenever possible--which is usually |
| the case. For many software packages, it is reasonable for all |
| developers to have a given version of Texinfo (or newer) installed, and |
| thus no reason to worry about older versions. (It is straightforward |
| for anyone to download and install the Texinfo source; it does not have |
| any problematic dependencies.) |
| |
| The issue of Texinfo versions does not generally arise for end-users. |
| With properly distributed packages, users need not process the Texinfo |
| manual simply to build and install the package; they can use |
| preformatted Info (or other) output files. This is desirable in |
| general, to avoid unnecessary dependencies between packages (*note |
| (standards)Releases::). |
| |
| |
| File: texinfo.info, Node: Conditional Nesting, Prev: Testing for Texinfo Commands, Up: Conditionals |
| |
| 16.7 Conditional Nesting |
| ======================== |
| |
| Conditionals can be nested; however, the details are a little tricky. |
| The difficulty comes with failing conditionals, such as '@ifhtml' when |
| HTML is not being produced, where the included text is to be ignored. |
| However, it is not to be _completely_ ignored, since it is useful to |
| have one '@ifset' inside another, for example--that is a way to include |
| text only if two conditions are met. Here's an example: |
| |
| @ifset somevar |
| @ifset anothervar |
| Both somevar and anothervar are set. |
| @end ifset |
| @ifclear anothervar |
| Somevar is set, anothervar is not. |
| @end ifclear |
| @end ifset |
| |
| Technically, Texinfo requires that for a failing conditional, the |
| ignored text must be properly nested with respect to that failing |
| conditional. Unfortunately, it's not always feasible to check that |
| _all_ conditionals are properly nested, because then the processors |
| could have to fully interpret the ignored text, which defeats the |
| purpose of the command. Here's an example illustrating these rules: |
| |
| @ifset a |
| @ifset b |
| @ifclear ok - ok, ignored |
| @end junky - ok, ignored |
| @end ifset |
| @c WRONG - missing @end ifset. |
| |
| Finally, as mentioned above, all conditional commands must be on |
| lines by themselves, with no text (even spaces) before or after. |
| Otherwise, the processors cannot reliably determine which commands to |
| consider for nesting purposes. |
| |
| |
| File: texinfo.info, Node: Defining New Texinfo Commands, Next: Include Files, Prev: Conditionals, Up: Top |
| |
| 17 Defining New Texinfo Commands |
| ******************************** |
| |
| Texinfo provides several ways to define new commands (in all cases, it's |
| not recommended to try redefining existing commands): |
| |
| * A Texinfo "macro" allows you to define a new Texinfo command as any |
| sequence of text and/or existing commands (including other macros). |
| The macro can have any number of "parameters"--text you supply each |
| time you use the macro. |
| |
| Incidentally, these macros have nothing to do with the '@defmac' |
| command, which is for documenting macros in the subject area of the |
| manual (*note Def Cmd Template::). |
| |
| * '@alias' is a convenient way to define a new name for an existing |
| command. |
| |
| * '@definfoenclose' allows you to define new commands with customized |
| output for all non-TeX output formats. |
| |
| Most generally of all (not just for defining new commands), it is |
| possible to invoke any external macro processor and have Texinfo |
| recognize so-called '#line' directives for error reporting. |
| |
| If you want to do simple text substitution, '@set' and '@value' is |
| the simplest approach (*note @set @clear @value::). |
| |
| * Menu: |
| |
| * Defining Macros:: Defining and undefining new commands. |
| * Invoking Macros:: Using a macro, once you've defined it. |
| * Macro Details:: Limitations of Texinfo macros. |
| * @alias:: Command aliases. |
| * @definfoenclose:: Customized highlighting. |
| * External Macro Processors:: '#line' directives. |
| |
| |
| File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands |
| |
| 17.1 Defining Macros |
| ==================== |
| |
| You use the Texinfo '@macro' command to define a macro, like this: |
| |
| @macro MACRONAME{PARAM1, PARAM2, ...} |
| TEXT ... \PARAM1\ ... |
| @end macro |
| |
| The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied |
| when the macro is subsequently used in the document (described in the |
| next section). |
| |
| For a macro to work consistently with TeX, MACRONAME must consist |
| entirely of letters: no digits, hyphens, underscores, or other special |
| characters. So, we recommend using only letters. However, 'makeinfo' |
| will accept anything consisting of alphanumerics, and (except as the |
| first character) '-'. The '_' character is excluded so that macros can |
| be called inside '@math' without a following space (*note Inserting |
| Math::). |
| |
| If a macro needs no parameters, you can define it either with an |
| empty list ('@macro foo {}') or with no braces at all ('@macro foo'). |
| |
| The definition or "body" of the macro can contain most Texinfo |
| commands, including macro invocations. However, a macro definition that |
| defines another macro does not work in TeX due to limitations in the |
| design of '@macro'. |
| |
| In the macro body, instances of a parameter name surrounded by |
| backslashes, as in '\PARAM1\' in the example above, are replaced by the |
| corresponding argument from the macro invocation. You can use parameter |
| names any number of times in the body, including zero. |
| |
| To get a single '\' in the macro expansion, use '\\'. Any other use |
| of '\' in the body yields a warning. |
| |
| The newline characters after the '@macro' line and before the '@end |
| macro' line are ignored, that is, not included in the macro body. All |
| other whitespace is treated according to the usual Texinfo rules. |
| |
| To allow a macro to be used recursively, that is, in an argument to a |
| call to itself, you must define it with '@rmacro', like this: |
| |
| @rmacro rmac {arg} |
| a\arg\b |
| @end rmacro |
| ... |
| @rmac{1@rmac{text}2} |
| |
| This produces the output 'a1atextb2b'. With '@macro' instead of |
| '@rmacro', an error message is given. |
| |
| You can undefine a macro FOO with '@unmacro FOO'. It is not an error |
| to undefine a macro that is already undefined. For example: |
| |
| @unmacro foo |
| |
| |
| File: texinfo.info, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands |
| |
| 17.2 Invoking Macros |
| ==================== |
| |
| After a macro is defined (see the previous section), you can "invoke" |
| (use) it in your document like this: |
| |
| @MACRONAME {ARG1, ARG2, ...} |
| |
| and the result will be more or less as if you typed the body of |
| MACRONAME at that spot. For example: |
| |
| @macro foo {p, q} |
| Together: \p\ & \q\. |
| @end macro |
| @foo{a, b} |
| |
| produces: |
| |
| Together: a & b. |
| |
| Thus, the arguments and parameters are separated by commas and |
| delimited by braces; any whitespace after (but not before) a comma is |
| ignored. The braces are required in the invocation even when the macro |
| takes no arguments, consistent with other Texinfo commands. For |
| example: |
| |
| @macro argless {} |
| No arguments here. |
| @end macro |
| @argless{} |
| |
| produces: |
| |
| No arguments here. |
| |
| Passing macro arguments containing commas requires care, since commas |
| also separate the arguments. To include a comma character in an |
| argument, the most reliable method is to use the '@comma{}' command. |
| For 'makeinfo', you can also prepend a backslash character, as in '\,', |
| but this does not work with TeX. |
| |
| It's not always necessary to worry about commas. To facilitate use |
| of macros, 'makeinfo' implements two rules for "automatic quoting" in |
| some circumstances: |
| |
| 1. If a macro takes only one argument, all commas in its invocation |
| are quoted by default. For example: |
| |
| @macro TRYME{text} |
| @strong{TRYME: \text\} |
| @end macro |
| |
| @TRYME{A nice feature, though it can be dangerous.} |
| |
| will produce the following output |
| |
| *TRYME: A nice feature, though it can be dangerous.* |
| |
| And indeed, it can. Namely, 'makeinfo' does not control the number |
| of arguments passed to one-argument macros, so be careful when you |
| invoke them. |
| |
| 2. If a macro invocation includes another command (including a |
| recursive invocation of itself), any commas in the nested command |
| invocation(s) are quoted by default. For example, in |
| |
| @say{@strong{Yes, I do}, person one} |
| |
| the comma after 'Yes' is implicitly quoted. Here's another |
| example, with a recursive macro: |
| |
| @rmacro cat{a,b} |
| \a\\b\ |
| @end rmacro |
| |
| @cat{@cat{foo, bar}, baz} |
| |
| will produce the string 'foobarbaz'. |
| |
| 3. Otherwise, a comma should be explicitly quoted, as above, for it to |
| be treated as a part of an argument. |
| |
| The backslash itself can be quoted in macro arguments with another |
| backslash. For example: |
| |
| @MACNAME {\\bleh} |
| |
| will pass the argument '\bleh' to MACNAME. |
| |
| 'makeinfo' also recognizes '\{' and '\}' sequences for curly braces, |
| but these are not recognized by the implementation in TeX. There |
| should, however, rarely be a need for these, as they are only needed |
| when a macro argument contains unbalanced braces. |
| |
| If a macro is defined to take exactly one argument, it can be invoked |
| without any braces, taking all of the line after the macro name as the |
| argument. For example: |
| |
| @macro bar {p} |
| Twice: \p\ & \p\. |
| @end macro |
| @bar aah |
| |
| produces: |
| |
| Twice: aah & aah. |
| |
| In these arguments, there is no escaping of special characters, so each |
| '\' stands for itself. |
| |
| If a macro is defined to take more than one argument, but is called |
| with only one (in braces), the remaining arguments are set to the empty |
| string, and no error is given. For example: |
| |
| @macro addtwo {p, q} |
| Both: \p\\q\. |
| @end macro |
| @addtwo{a} |
| |
| produces simply: |
| |
| Both: a. |
| |
| |
| File: texinfo.info, Node: Macro Details, Next: @alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands |
| |
| 17.3 Macro Details and Caveats |
| ============================== |
| |
| By design, macro expansion does not happen in the following contexts in |
| 'makeinfo': |
| |
| * '@macro' and '@unmacro' lines; |
| |
| * '@if...' lines, including '@ifset' and similar; |
| |
| * '@set', '@clear', '@value'; |
| |
| * '@clickstyle' lines; |
| |
| * '@end' lines. |
| |
| Unfortunately, TeX may do some expansion in these situations, possibly |
| yielding errors. |
| |
| Also, quite a few macro-related constructs cause problems with TeX; |
| some of the caveats are listed below. Thus, if you get macro-related |
| errors when producing the printed version of a manual, you might try |
| expanding the macros with 'makeinfo' by invoking 'texi2dvi' with the |
| '-E' option (*note Format with texi2dvi::). Or, more reliably, eschew |
| Texinfo macros altogether and use a language designed for macro |
| processing, such as M4 (*note External Macro Processors::). |
| |
| * As mentioned earlier, macro names must consist entirely of letters. |
| |
| * It is not advisable to redefine any TeX primitive, plain, or |
| Texinfo command name as a macro. Unfortunately this is a large and |
| open-ended set of names, and the possible resulting errors are |
| unpredictable. |
| |
| * Arguments to macros taking more than one argument cannot cross |
| lines. |
| |
| * Macros containing a command which must be on a line by itself, such |
| as a conditional, cannot be invoked in the middle of a line. |
| Similarly, macros containing line-oriented commands or text, such |
| as '@example' environments, may behave unpredictably in TeX. |
| |
| * Texinfo commands in the expansion of a macro in the text of an |
| index entry may end up being typeset as literal text (including an |
| "@" sign), instead of being interpreted with their intended |
| meaning. |
| |
| * White space is ignored at the beginnings of lines. |
| |
| * Macros can't be reliably used in the argument to accent commands |
| (*note Inserting Accents::). |
| |
| * The backslash escape for commas in macro arguments does not work; |
| '@comma{}' must be used. |
| |
| * Likewise, if you want to pass an argument with the Texinfo command |
| '@,' (to produce a cedilla, see *note Inserting Accents::), you |
| have to use '@value' or another work-around. Otherwise, the comma |
| may be taken as separating the arguments. For example, |
| |
| @macro mactwo{argfirst, argsecond} |
| \argfirst\+\argsecond\. |
| @end macro |
| @set fc Fran@,cois |
| @mactwo{@value{fc},} |
| |
| produces: |
| |
| Franc,ois+. |
| |
| * Ending a macro body with '@c' may cause text following the macro |
| invocation to be ignored as a comment in 'makeinfo'. This is not |
| the case when processing with TeX (in case you really want to |
| comment out following text, use '@comment' instead). This was |
| often done to "comment out" an unwanted newline at the end of a |
| macro body, but this is not necessary any more, as the final |
| newline before '@end macro' is not included in the macro body |
| anyway. |
| |
| * In general, you can't arbitrarily substitute a macro (or '@value') |
| call for Texinfo command arguments, even when the text is the same. |
| Texinfo is not M4 (or even plain TeX). It might work with some |
| commands, it fails with others. Best not to do it at all. For |
| instance, this fails: |
| |
| @macro offmacro |
| off |
| @end macro |
| @headings @offmacro |
| |
| This looks equivalent to '@headings off', but for TeXnical reasons, |
| it fails with a mysterious error message (namely, 'Paragraph ended |
| before @headings was complete'). |
| |
| * Macros cannot define macros in the natural way. To do this, you |
| must use conditionals and raw TeX. For example: |
| |
| @ifnottex |
| @macro ctor {name, arg} |
| @macro \name\ |
| something involving \arg\ somehow |
| @end macro |
| @end macro |
| @end ifnottex |
| @tex |
| \gdef\ctor#1{\ctorx#1,} |
| \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}} |
| @end tex |
| |
| The 'makeinfo' implementation also has the following limitations (by |
| design): |
| |
| * '@verbatim' and macros do not mix; for instance, you can't start a |
| verbatim block inside a macro and end it outside (*note |
| @verbatim::). Starting any environment inside a macro and ending |
| it outside may or may not work, for that matter. |
| |
| * Macros that completely define macros are ok, but it's not possible |
| to have incompletely nested macro definitions. That is, '@macro' |
| and '@end macro' (likewise for '@rmacro') must be correctly paired. |
| For example, you cannot start a macro definition within a macro, |
| and then end that nested definition outside the macro. |
| |
| In the 'makeinfo' implementation before Texinfo 5.0, ends of lines |
| from expansion of a '@macro' definition did not end an @-command |
| line-delimited argument ('@chapter', '@center', etc.). This is no |
| longer the case. For example: |
| |
| @macro twolines{} |
| aaa |
| bbb |
| @end macro |
| @center @twolines{} |
| |
| In the current 'makeinfo', this is equivalent to: |
| |
| @center aaa |
| bbb |
| |
| with just 'aaa' as the argument to '@center'. In the earlier |
| implementation, it would have been parsed as this: |
| |
| @center aaa bbb |
| |
| |
| File: texinfo.info, Node: @alias, Next: @definfoenclose, Prev: Macro Details, Up: Defining New Texinfo Commands |
| |
| 17.4 '@alias NEW=EXISTING' |
| ========================== |
| |
| The '@alias' command defines a new command to be just like an existing |
| one. This is useful for defining additional markup names, thus |
| preserving additional semantic information in the input even though the |
| output result may be the same. |
| |
| Write the '@alias' command on a line by itself, followed by the new |
| command name, an equals sign, and the existing command name. Whitespace |
| around the equals sign is optional and ignored if present. Thus: |
| |
| @alias NEW = EXISTING |
| |
| For example, if your document contains citations for both books and |
| some other media (movies, for example), you might like to define a macro |
| '@moviecite{}' that does the same thing as an ordinary '@cite{}' but |
| conveys the extra semantic information as well. You'd do this as |
| follows: |
| |
| @alias moviecite = cite |
| |
| Macros do not always have the same effect as aliases, due to vagaries |
| of argument parsing. Also, aliases are much simpler to define than |
| macros. So the command is not redundant. |
| |
| Unfortunately, it's not possible to alias Texinfo environments; for |
| example, '@alias lang=example' is an error. |
| |
| Aliases must not be recursive, directly or indirectly. |
| |
| It is not advisable to redefine any TeX primitive, plain TeX, or |
| Texinfo command name as an alias. Unfortunately this is a very large |
| set of names, and the possible resulting errors from TeX are |
| unpredictable. |
| |
| 'makeinfo' will accept the same identifiers for aliases as it does |
| for macro names, that is, alphanumerics and (except as the first |
| character) '-'. |
| |
| |
| File: texinfo.info, Node: @definfoenclose, Next: External Macro Processors, Prev: @alias, Up: Defining New Texinfo Commands |
| |
| 17.5 '@definfoenclose': Customized Highlighting |
| =============================================== |
| |
| An '@definfoenclose' command may be used to define a highlighting |
| command for all the non-TeX output formats. A command defined using |
| '@definfoenclose' marks text by enclosing it in strings that precede and |
| follow the text. You can use this to get closer control of your output. |
| |
| Presumably, if you define a command with '@definfoenclose', you will |
| create a corresponding command for TeX, either in 'texinfo.tex', |
| 'texinfo.cnf', or within an '@iftex' or '@tex' in your document. |
| |
| Write a '@definfoenclose' command at the beginning of a line followed |
| by three comma-separated arguments. The first argument to |
| '@definfoenclose' is the @-command name (without the '@'); the second |
| argument is the start delimiter string; and the third argument is the |
| end delimiter string. The latter two arguments enclose the highlighted |
| text in the output. |
| |
| A delimiter string may contain spaces. Neither the start nor end |
| delimiter is required. If you do not want a start delimiter but do want |
| an end delimiter, you must follow the command name with two commas in a |
| row; otherwise, the end delimiter string you intended will naturally be |
| (mis)interpreted as the start delimiter string. |
| |
| If you do a '@definfoenclose' on the name of a predefined command |
| (such as '@emph', '@strong', '@t', or '@i'), the enclosure definition |
| will override the built-in definition. We don't recommend this. |
| |
| An enclosure command defined this way takes one argument in braces, |
| since it is intended for new markup commands (*note Marking Text::). |
| |
| For example, you can write: |
| |
| @definfoenclose phoo,//,\\ |
| |
| near the beginning of a Texinfo file to define '@phoo' as an Info |
| formatting command that inserts '//' before and '\\' after the argument |
| to '@phoo'. You can then write '@phoo{bar}' wherever you want '//bar\\' |
| highlighted in Info. |
| |
| For TeX formatting, you could write |
| |
| @iftex |
| @global@let@phoo=@i |
| @end iftex |
| |
| to define '@phoo' as a command that causes TeX to typeset the argument |
| to '@phoo' in italics. |
| |
| Each definition applies to its own formatter: one for TeX, the other |
| for everything else. The raw TeX commands need to be in '@iftex'. |
| '@definfoenclose' command need not be within '@ifinfo', unless you want |
| to use different definitions for different output formats. |
| |
| Here is another example: write |
| |
| @definfoenclose headword, , : |
| |
| near the beginning of the file, to define '@headword' as an Info |
| formatting command that inserts nothing before and a colon after the |
| argument to '@headword'. |
| |
| '@definfoenclose' definitions must not be recursive, directly or |
| indirectly. |
| |
| |
| File: texinfo.info, Node: External Macro Processors, Prev: @definfoenclose, Up: Defining New Texinfo Commands |
| |
| 17.6 External Macro Processors: Line Directives |
| =============================================== |
| |
| Texinfo macros (and its other text substitution facilities) work fine in |
| straightforward cases. If your document needs unusually complex |
| processing, however, their fragility and limitations can be a problem. |
| In this case, you may want to use a different macro processor |
| altogether, such as M4 (*note (m4)Top::) or CPP (*note (cpp)Top::). |
| |
| With one exception, Texinfo does not need to know whether its input |
| is "original" source or preprocessed from some other source file. |
| Therefore, you can arrange your build system to invoke whatever programs |
| you like to handle macro expansion or other preprocessing needs. |
| Texinfo does not offer built-in support for any particular preprocessor, |
| since no one program seemed likely to suffice for the requirements of |
| all documents. |
| |
| The one exception is line numbers in error messages. In that case, |
| the line number should refer to the original source file, whatever it |
| may be. There's a well-known mechanism for this: the so-called '#line' |
| directive. Texinfo supports this. |
| |
| * Menu: |
| |
| * #line Directive:: |
| * TeX: #line and TeX. |
| * Syntax: #line Syntax Details. |
| |
| |
| File: texinfo.info, Node: #line Directive, Next: #line and TeX, Up: External Macro Processors |
| |
| 17.6.1 '#line' Directive |
| ------------------------ |
| |
| An input line such as this: |
| |
| #line 100 "foo.ptexi" |
| |
| indicates that the next line was line 100 of the file 'foo.ptexi', and |
| so that's what an error message should refer to. Both M4 (*note |
| (m4)Preprocessor features::) and CPP (*note (cpp)Line Control::, and |
| *note (cpp)Preprocessor Output::) can generate such lines. |
| |
| The 'makeinfo' program recognizes these lines by default, except |
| within '@verbatim' blocks (*note @verbatim::. Their recognition can be |
| turned off completely with 'CPP_LINE_DIRECTIVES' (*note Other |
| Customization Variables::), though there is normally no reason to do so. |
| |
| For those few programs (M4, CPP, Texinfo) which need to document |
| '#line' directives and therefore have examples which would otherwise |
| match the pattern, the command '@hashchar{}' can be used (*note |
| Inserting a Hashsign::). The example line above looks like this in the |
| source for this manual: |
| |
| @hashchar{}line 100 "foo.ptexi" |
| |
| The '@hashchar' command was added to Texinfo in 2013. If you don't |
| want to rely on it, you can also use '@set' and '@value' to insert the |
| literal '#': |
| |
| @set hash # |
| @value{hash}line 1 "example.c" |
| |
| Or, if suitable, a '@verbatim' environment can be used instead of |
| '@example'. As mentioned above, '#line'-recognition is disabled inside |
| verbatim blocks. |
| |
| |
| File: texinfo.info, Node: #line and TeX, Next: #line Syntax Details, Prev: #line Directive, Up: External Macro Processors |
| |
| 17.6.2 '#line' and TeX |
| ---------------------- |
| |
| As mentioned, 'makeinfo' recognizes the '#line' directives described in |
| the previous section. However, 'texinfo.tex' does not and cannot. |
| Therefore, such a line will be incorrectly typeset verbatim if TeX sees |
| it. The solution is to use 'makeinfo''s macro expansion options before |
| running TeX. There are three approaches: |
| |
| * If you run 'texi2dvi' or its variants (*note Format with |
| texi2dvi::), you can pass '-E' and 'texi2dvi' will run 'makeinfo' |
| first to expand macros and eliminate '#line'. |
| |
| * If you run 'makeinfo' or its variants (*note Generic Translator |
| texi2any::), you can specify '--no-ifinfo --iftex -E somefile.out', |
| and then give 'somefile.out' to 'texi2dvi' in a separate command. |
| |
| * Or you can run 'makeinfo --dvi --Xopt -E'. (Or '--pdf' instead of |
| '--dvi'.) 'makeinfo' will then call 'texi2dvi -E'. |
| |
| One last caveat regarding use with TeX: since the '#line' directives |
| are not recognized, the line numbers emitted by the '@errormsg{}' |
| command (*note Conditional Commands::), or by TeX itself, are the |
| (incorrect) line numbers from the derived file which TeX is reading, |
| rather than the preprocessor-specified line numbers. This is another |
| example of why we recommend running 'makeinfo' for the best diagnostics |
| (*note makeinfo Advantages::). |
| |
| |
| File: texinfo.info, Node: #line Syntax Details, Prev: #line and TeX, Up: External Macro Processors |
| |
| 17.6.3 '#line' Syntax Details |
| ----------------------------- |
| |
| Syntax details for the '#line' directive: the '#' character can be |
| preceded or followed by whitespace, the word 'line' is optional, and the |
| file name can be followed by a whitespace-separated list of integers |
| (these are so-called "flags" output by CPP in some cases). For those |
| who like to know the gory details, the actual (Perl) regular expression |
| which is matched is this: |
| |
| /^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/ |
| |
| As far as we've been able to tell, the trailing integer flags only |
| occur in conjunction with a filename, so that is reflected in the |
| regular expression. |
| |
| As an example, the following is a syntactically valid '#line' |
| directive, meaning line 1 of '/usr/include/stdio.h': |
| |
| # 1 "/usr/include/stdio.h" 2 3 4 |
| |
| Unfortunately, the quoted filename ('"..."') has to be optional, |
| because M4 (especially) can often generate '#line' directives within a |
| single file. Since the 'line' is also optional, the result is that |
| lines might match which you wouldn't expect, e.g., |
| |
| # 1 |
| |
| The possible solutions are described above (*note #line Directive::). |
| |
| |
| File: texinfo.info, Node: Include Files, Next: Hardcopy, Prev: Defining New Texinfo Commands, Up: Top |
| |
| 18 Include Files |
| **************** |
| |
| When a Texinfo processor sees an '@include' command in a Texinfo file, |
| it processes the contents of the file named by the '@include' and |
| incorporates them into the output files being created. Include files |
| thus let you keep a single large document as a collection of |
| conveniently small parts. |
| |
| * Menu: |
| |
| * Using Include Files:: How to use the '@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. |
| * @verbatiminclude:: Including a file verbatim. |
| * Include Files Evolution:: How use of the '@include' command |
| has changed over time. |
| |
| |
| File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Up: Include Files |
| |
| 18.1 How to Use Include Files |
| ============================= |
| |
| To include another file within a Texinfo file, write the '@include' |
| command at the beginning of a line and follow it on the same line by the |
| name of a file to be included. For example: |
| |
| @include buffers.texi |
| |
| @-commands are expanded in file names. The one most likely to be |
| useful is '@value' (*note @set @value::), and even then only in |
| complicated situations. |
| |
| An included file should simply be a segment of text that you expect |
| to be included as is into the overall or "outer" Texinfo file; it should |
| not contain the standard beginning and end parts of a Texinfo file. In |
| particular, you should not start an included file with a line saying |
| '\input texinfo'; if you do, that text is inserted into the output file |
| literally. Likewise, you should not end an included file with a '@bye' |
| command; nothing after '@bye' is formatted. |
| |
| In the long-ago past, you were required to write an '@setfilename' |
| line at the beginning of an included file, but no longer. Now, it does |
| not matter whether you write such a line. If an '@setfilename' line |
| exists in an included file, it is ignored. |
| |
| |
| File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include Files Requirements, Prev: Using Include Files, Up: Include Files |
| |
| 18.2 'texinfo-multiple-files-update' |
| ==================================== |
| |
| GNU Emacs Texinfo mode provides the 'texinfo-multiple-files-update' |
| command. This command creates or updates 'Next', 'Previous', and 'Up' |
| pointers of included files as well as those in the outer or overall |
| Texinfo file, and it creates or updates a main menu in the outer file. |
| Depending on whether you call it with optional arguments, the command |
| updates only the pointers in the first '@node' line of the included |
| files or all of them: |
| |
| 'M-x texinfo-multiple-files-update' |
| Called without any arguments: |
| |
| - Create or update the 'Next', 'Previous', and 'Up' pointers of |
| the first '@node' line in each file included in an outer or |
| overall Texinfo file. |
| |
| - Create or update the 'Top' level node pointers of the outer or |
| overall file. |
| |
| - Create or update a main menu in the outer file. |
| |
| 'C-u M-x texinfo-multiple-files-update' |
| Called with 'C-u' as a prefix argument: |
| |
| - Create or update pointers in the first '@node' line in each |
| included file. |
| |
| - Create or update the 'Top' level node pointers of the outer |
| file. |
| |
| - Create and insert a master menu in the outer file. The master |
| menu is made from all the menus in all the included files. |
| |
| 'C-u 8 M-x texinfo-multiple-files-update' |
| Called with a numeric prefix argument, such as 'C-u 8': |
| |
| - Create or update _all_ the 'Next', 'Previous', and 'Up' |
| pointers of all the included files. |
| |
| - Create or update _all_ the menus of all the included files. |
| |
| - Create or update the 'Top' level node pointers of the outer or |
| overall file. |
| |
| - And then create a master menu in the outer file. This is |
| similar to invoking 'texinfo-master-menu' with an argument |
| when you are working with just one file. |
| |
| Note the use of the prefix argument in interactive use: with a |
| regular prefix argument, just 'C-u', the 'texinfo-multiple-files-update' |
| command inserts a master menu; with a numeric prefix argument, such as |
| 'C-u 8', the command updates _every_ pointer and menu in _all_ the files |
| and then inserts a master menu. |
| |
| |
| File: texinfo.info, Node: Include Files Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files |
| |
| 18.3 Include Files Requirements |
| =============================== |
| |
| If you plan to use the 'texinfo-multiple-files-update' command, the |
| outer Texinfo file that lists included files within it should contain |
| nothing but the beginning and end parts of a Texinfo file, and a number |
| of '@include' commands listing the included files. It should not even |
| include indices, which should be listed in an included file of their |
| own. |
| |
| Moreover, each of the included files must contain exactly one highest |
| level node (conventionally, '@chapter' or equivalent), and this node |
| must be the first node in the included file. Furthermore, each of these |
| highest level nodes in each included file must be at the same |
| hierarchical level in the file structure. Usually, each is a |
| '@chapter', an '@appendix', or an '@unnumbered' node. Thus, normally, |
| each included file contains one, and only one, chapter or |
| equivalent-level node. |
| |
| The outer file should contain only _one_ node, the 'Top' node. It |
| should _not_ contain any nodes besides the single 'Top' node. The |
| 'texinfo-multiple-files-update' command will not process them. |
| |
| |
| File: texinfo.info, Node: Sample Include File, Next: @verbatiminclude, Prev: Include Files Requirements, Up: Include Files |
| |
| 18.4 Sample File with '@include' |
| ================================ |
| |
| Here is an example of an outer Texinfo file with '@include' files within |
| it before running 'texinfo-multiple-files-update', which would insert a |
| main or master menu: |
| |
| \input texinfo @c -*-texinfo-*- |
| @settitle Include Example |
| |
| ... *Note Sample Texinfo Files::, for |
| examples of the rest of the frontmatter ... |
| |
| @ifnottex |
| @node Top |
| @top Include Example |
| @end ifnottex |
| |
| @include foo.texinfo |
| @include bar.texinfo |
| @include concept-index.texinfo |
| @bye |
| |
| An included file, such as 'foo.texinfo', might look like this: |
| |
| @node First |
| @chapter First Chapter |
| |
| Contents of first chapter ... |
| |
| The full contents of 'concept-index.texinfo' might be as simple as |
| this: |
| |
| @node Concept Index |
| @unnumbered Concept Index |
| |
| @printindex cp |
| |
| The outer Texinfo source file for 'The GNU Emacs Lisp Reference |
| Manual' is named 'elisp.texi'. This outer file contains a master menu |
| with 417 entries and a list of 41 '@include' files. |
| |
| |
| File: texinfo.info, Node: @verbatiminclude, Next: Include Files Evolution, Prev: Sample Include File, Up: Include Files |
| |
| 18.5 '@verbatiminclude' FILE: Include a File Verbatim |
| ===================================================== |
| |
| You can include the exact contents of a file in the document with the |
| '@verbatiminclude' command: |
| |
| @verbatiminclude FILENAME |
| |
| The contents of FILENAME is printed in a verbatim environment (*note |
| @verbatim::). Generally, the file is printed exactly as it is, with all |
| special characters and white space retained. No indentation is added; |
| if you want indentation, enclose the '@verbatiminclude' within |
| '@example' (*note @example::). |
| |
| The name of the file is taken literally, with a single exception: |
| '@value{VAR}' references are expanded. This makes it possible to |
| include files in other directories within a distribution, for instance: |
| |
| @verbatiminclude @value{top_srcdir}/NEWS |
| |
| (You still have to get 'top_srcdir' defined in the first place.) |
| |
| For a method on printing the file contents in a smaller font size, |
| see the end of the section on '@verbatim'. |
| |
| |
| File: texinfo.info, Node: Include Files Evolution, Prev: @verbatiminclude, Up: Include Files |
| |
| 18.6 Evolution of Include Files |
| =============================== |
| |
| When Info was first created, it was customary to create many small Info |
| files on one subject. Each Info file was formatted from its own Texinfo |
| source file. This custom meant that Emacs did not need to make a large |
| buffer to hold the whole of a large Info file when someone wanted |
| information; instead, Emacs allocated just enough memory for the small |
| Info file that contained the particular information sought. This way, |
| Emacs could avoid wasting memory. |
| |
| References from one file to another were made by referring to the |
| file name as well as the node name. (*Note Referring to Other Info |
| Files: Other Info Files. Also, see *note '@xref' with Four and Five |
| Arguments: Four and Five Arguments.) |
| |
| Include files were designed primarily as a way to create a single, |
| large printed manual out of several smaller Info files. In a printed |
| manual, all the references were within the same document, so TeX could |
| automatically determine the references' page numbers. The Info |
| formatting commands used include files only for creating joint indices; |
| each of the individual Texinfo files had to be formatted for Info |
| individually. (Each, therefore, required its own '@setfilename' line.) |
| |
| However, because large Info files are now split automatically, it is |
| no longer necessary to keep them small. |
| |
| Nowadays, multiple Texinfo files are used mostly for large documents, |
| such as 'The GNU Emacs Lisp Reference Manual', and for projects in which |
| several different people write different sections of a document |
| simultaneously. |
| |
| In addition, the Info formatting commands have been extended to work |
| with the '@include' command so as to create a single large Info file |
| that is split into smaller files if necessary. This means that you can |
| write menus and cross-references without naming the different Texinfo |
| files. |
| |
| |
| File: texinfo.info, Node: Hardcopy, Next: Generic Translator texi2any, Prev: Include Files, Up: Top |
| |
| 19 Formatting and Printing Hardcopy |
| *********************************** |
| |
| Running the 'texi2dvi' or 'texi2pdf' command is the simplest way to |
| create printable output. These commands are installed as part of the |
| Texinfo package. |
| |
| In more detail, three major shell commands are used to print |
| formatted output from a Texinfo manual: one converts the Texinfo source |
| into something printable, a second sorts indices, and a third actually |
| prints the formatted document. When you use the shell commands, you can |
| either work directly in the operating system shell or work within a |
| shell inside GNU Emacs (or some other computing environment). |
| |
| If you are using GNU Emacs, you can use commands provided by Texinfo |
| mode instead of shell commands. In addition to the three commands to |
| format a file, sort the indices, and print the result, Texinfo mode |
| offers key bindings for commands to recenter the output buffer, show the |
| print queue, and delete a job from the print queue. |
| |
| Details are in the following sections. |
| |
| * Menu: |
| |
| * Use TeX:: Use TeX to format for hardcopy. |
| * Format with 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. |
| |
| |
| File: texinfo.info, Node: Use TeX, Next: Format with texi2dvi, Up: Hardcopy |
| |
| 19.1 Use TeX |
| ============ |
| |
| The typesetting program called TeX is used to format a Texinfo document |
| for printable output. TeX is a very powerful typesetting program and, |
| when used correctly, does an exceptionally good job. |
| |
| *Note Obtaining TeX::, for information on how to obtain TeX. It is |
| not included in the Texinfo package, being a vast suite of software in |
| itself. |
| |
| |
| File: texinfo.info, Node: Format with texi2dvi, Next: Format with tex/texindex, Prev: Use TeX, Up: Hardcopy |
| |
| 19.2 Format with 'texi2dvi' |
| =========================== |
| |
| The 'texi2dvi' program takes care of all the steps for producing a TeX |
| DVI file from a Texinfo document. Similarly, 'texi2pdf' produces a PDF |
| file. |
| |
| To run 'texi2dvi' or 'texi2pdf' on an input file 'foo.texi', do this |
| (where 'prompt$ ' is your shell prompt): |
| |
| prompt$ texi2dvi foo.texi |
| prompt$ texi2pdf foo.texi |
| |
| As shown in this example, the input filenames to 'texi2dvi' and |
| 'texi2pdf' must include any extension, such as '.texi'. (Under MS-DOS |
| and perhaps in other circumstances, you may need to run 'sh texi2dvi |
| foo.texi' instead of relying on the operating system to invoke the shell |
| on the 'texi2dvi' script.) |
| |
| For a list of all the options, run 'texi2dvi --help'. Some of the |
| options are discussed below. |
| |
| With the '--pdf' option, 'texi2dvi' produces PDF output instead of |
| DVI (*note PDF Output::), by running 'pdftex' instead of 'tex'. |
| Alternatively, the command 'texi2pdf' is an abbreviation for running |
| 'texi2dvi --pdf'. The command 'pdftexi2dvi' is also provided as a |
| convenience for AUC-TeX (*note (auctex)Top::, as it prefers to merely |
| prepend 'pdf' to DVI producing tools to have PDF producing tools. |
| |
| With the '--dvipdf' option, 'texi2dvi' produces PDF output by running |
| TeX and then a DVI-to-PDF program: if the 'DVIPDF' environment variable |
| is set, that value is used, else the first program extant among |
| 'dvipdfmx', 'dvipdfm', 'dvipdf', 'dvi2pdf', 'dvitopdf'. This method |
| generally supports CJK typesetting better than 'pdftex'. |
| |
| With the '--ps' option, 'texi2dvi' produces PostScript instead of |
| DVI, by running 'tex' and then 'dvips' (*note (dvips)Top::). (Or the |
| value of the 'DVIPS' environment variable, if set.) |
| |
| 'texi2dvi' can also be used to process LaTeX files. Normally |
| 'texi2dvi' is able to guess the input file language by its contents and |
| file name extension; however, if it guesses wrong you can explicitly |
| specify the input language using '--language=LANG' command line option, |
| where LANG is either 'latex' or 'texinfo'. |
| |
| One useful option to 'texi2dvi' is '--command=CMD'. This inserts CMD |
| on a line by itself, after a '@setfilename' line in a temporary copy of |
| the input file, before running TeX. With this, you can specify |
| different printing formats, such as '@smallbook' (*note @smallbook::), |
| '@afourpaper' (*note A4 Paper::), or '@pagesizes' (*note @pagesizes::), |
| without actually changing the document source. (You can also do this on |
| a site-wide basis with 'texinfo.cnf'; *note Preparing for TeX::). |
| |
| The option '-E' (equivalently, '-e' and '--expand') does Texinfo |
| macro expansion using 'makeinfo' instead of the TeX implementation |
| (*note Macro Details::). Each implementation has its own limitations |
| and advantages. If this option is used, no line in the source file may |
| begin with the string '@c _texi2dvi' or the string '@c (_texi2dvi)'. |
| |
| 'texi2dvi' takes the '--build=MODE' option to specify where the TeX |
| compilation takes place, and, as a consequence, how auxiliary files are |
| treated. The build mode can also be set using the environment variable |
| 'TEXI2DVI_BUILD_MODE'. The valid values for MODE are: |
| |
| 'local' |
| Compile in the current directory, leaving all the auxiliary files |
| around. This is the traditional TeX use. |
| |
| 'tidy' |
| Compile in a local '*.t2d' directory, where the auxiliary files are |
| left. Output files are copied back to the original file. |
| |
| Using the 'tidy' mode brings several advantages: |
| - the current directory is not cluttered with plethora of |
| temporary files. |
| - clutter can be even further reduced using '--build-dir=dir': |
| all the '*.t2d' directories are stored there. |
| - clutter can be reduced to zero using, e.g., |
| '--build-dir=/tmp/\$USER.t2d' or '--build-dir=\$HOME/.t2d'. |
| - the output file is updated after every successful TeX run, for |
| sake of concurrent visualization of the output. In a 'local' |
| build the viewer stops during the whole TeX run. |
| - if the compilation fails, the previous state of the output |
| file is preserved. |
| - PDF and DVI compilation are kept in separate subdirectories |
| preventing any possibility of auxiliary file incompatibility. |
| |
| On the other hand, because 'tidy' compilation takes place in |
| another directory, occasionally TeX won't be able to find some |
| files (e.g., when using '\graphicspath'): in that case, use '-I' to |
| specify the additional directories to consider. |
| |
| 'clean' |
| Same as 'tidy', but remove the auxiliary directory afterwards. |
| Every compilation therefore requires the full cycle. |
| |
| 'texi2dvi' will use 'etex' (or 'pdfetex') if it is available, because |
| it runs faster in some cases, and provides additional tracing |
| information when debugging 'texinfo.tex'. Nevertheless, this extended |
| version of TeX is not required, and the DVI output is identical. (These |
| days, 'pdftex' and 'pdfetex' are exactly the same, but we still run |
| 'pdfetex' to cater to ancient TeX installations.) |
| |
| 'texi2dvi' attempts to detect auxiliary files output by TeX, either |
| by using the '-recorder' option, or by scanning for '\openout' in the |
| log file that a run of TeX produces. You may control how 'texi2dvi' |
| does this with the 'TEXI2DVI_USE_RECORDER' environment variable. Valid |
| values are: |
| |
| 'yes' |
| use the '-recorder' option, no checks. |
| |
| 'no' |
| scan for '\openout' in the log file, no checks. |
| |
| 'yesmaybe' |
| check whether '-recorder' option is supported, and if yes use it, |
| otherwise check for tracing '\openout' in the log file is |
| supported, and if yes use it, else it is an error. |
| |
| 'nomaybe' |
| same as 'yesmaybe', except that the '\openout' trace in log file is |
| checked first. |
| |
| The default is 'nomaybe'. This environment variable is provided for |
| troubleshooting purposes, and may change or disappear in the future. |
| |
| |
| File: texinfo.info, Node: Format with tex/texindex, Next: Print with lpr, Prev: Format with texi2dvi, Up: Hardcopy |
| |
| 19.3 Format with 'tex'/'texindex' |
| ================================= |
| |
| You can do the basic formatting of a Texinfo file with the shell command |
| 'tex' followed by the name of the Texinfo file. For example: |
| |
| tex foo.texi |
| |
| TeX will produce a "DVI file" as well as several auxiliary files |
| containing information for indices, cross-references, etc. The DVI file |
| (for "DeVice Independent" file) can be printed on virtually any device, |
| perhaps after a further conversion (see the previous section). |
| |
| The 'tex' formatting command itself does not sort the indices; it |
| writes an output file of unsorted index data. To generate a printed |
| index after running the 'tex' command, you first need a sorted index to |
| work from. The 'texindex' command sorts indices. ('texi2dvi', |
| described in the previous section, runs 'tex' and 'texindex' as |
| necessary.) |
| |
| 'tex' outputs unsorted index files under names following a standard |
| convention: the name of your main input file with any '.texi' or similar |
| extension replaced by the two letter index name. For example, the raw |
| index output files for the input file 'foo.texi' would be, by default, |
| 'foo.cp', 'foo.vr', 'foo.fn', 'foo.tp', 'foo.pg' and 'foo.ky'. Those |
| are exactly the arguments to give to 'texindex'. |
| |
| Instead of specifying all the unsorted index file names explicitly, |
| it's typical to use '??' as shell wildcards and give the command in this |
| form: |
| |
| texindex foo.?? |
| |
| This command will run 'texindex' on all the unsorted index files, |
| including any two letter indices that you have defined yourself using |
| '@defindex' or '@defcodeindex'. You can safely run 'texindex foo.??' |
| even if there are files with two letter extensions that are not index |
| files, such as 'foo.el'. The 'texindex' command reports but otherwise |
| ignores such files. |
| |
| For each file specified, 'texindex' generates a sorted index file |
| whose name is made by appending 's' to the input file name; for example, |
| 'foo.cps' is made from 'foo.cp'. The '@printindex' command looks for a |
| file with that name (*note Printing Indices & Menus::). TeX does not |
| read the raw index output file, and 'texindex' does not alter it. |
| |
| After you have sorted the indices, you need to rerun 'tex' on the |
| Texinfo file. This regenerates the output file, this time with |
| up-to-date index entries. |
| |
| Finally, you may need to run 'tex' one more time, to get the page |
| numbers in the cross-references correct. |
| |
| To summarize, this is a five step process. (Alternatively, it's a |
| one-step process: run 'texi2dvi'; see the previous section.) |
| |
| 1. Run 'tex' on your Texinfo file. This generates a DVI file (with |
| undefined cross-references and no indices), and the raw index files |
| (with two letter extensions). |
| |
| 2. Run 'texindex' on the raw index files. This creates the |
| corresponding sorted index files (with three letter extensions). |
| |
| 3. Run 'tex' again on your Texinfo file. This regenerates the DVI |
| file, this time with indices and defined cross-references, but with |
| page numbers for the cross-references from the previous run, |
| generally incorrect. |
| |
| 4. Sort the indices again, with 'texindex'. |
| |
| 5. Run 'tex' one last time. This time the correct page numbers are |
| written for the cross-references. |
| |
| * Menu: |
| |
| * Formatting Partial Documents:: |
| * Details of texindex:: |
| |
| |
| File: texinfo.info, Node: Formatting Partial Documents, Next: Details of texindex, Up: Format with tex/texindex |
| |
| 19.3.1 Formatting Partial Documents |
| ----------------------------------- |
| |
| Sometimes you may wish to print a document while you know it is |
| incomplete, or to print just one chapter of a document. In such a case, |
| the usual auxiliary files that TeX creates and warnings TeX gives about |
| undefined cross-references are just nuisances. You can avoid them with |
| the '@novalidate' command, which you must give _before_ any sectioning |
| or cross-reference commands. |
| |
| Thus, the beginning of your file would look approximately like this: |
| |
| \input texinfo |
| @novalidate |
| ... |
| |
| '@novalidate' also turns off validation in 'makeinfo', just like its |
| '--no-validate' option (*note Pointer Validation::). |
| |
| Furthermore, you need not run 'texindex' each time after you run |
| 'tex'. The 'tex' formatting command simply uses whatever sorted index |
| files happen to exist from a previous use of 'texindex'. If those are |
| out of date, that is usually ok while you are creating or debugging a |
| document. |
| |
| |
| File: texinfo.info, Node: Details of texindex, Prev: Formatting Partial Documents, Up: Format with tex/texindex |
| |
| 19.3.2 Details of 'texindex' |
| ---------------------------- |
| |
| In Texinfo version 6, released in 2015, the 'texindex' program was |
| completely reimplemented. The principal functional difference is that |
| index entries beginning with a left brace or right brace ('{' resp. '}') |
| can work properly. For example, these simple index entries are |
| processed correctly, including the "index initial" shown in the index: |
| |
| @cindex @{ |
| @cindex @} |
| ... |
| @printindex cp |
| |
| However, to enable this behavior, it's necessary (for the time being) |
| to give a special option to TeX early in a source document: |
| |
| @tex |
| \global\usebracesinindexestrue |
| @end tex |
| |
| This is because the previous 'texindex' implementation aborted with |
| an incorrect error message ('No page number in \entry...') on such index |
| entries when handled in the normal way. Therefore TeX wrote out an |
| incorrect "sort string" using the '|' character; this did not affect the |
| text of the entry, but the index initial was the incorrect '|', and |
| sorting was not perfect. |
| |
| Because of that fatal error, and because relatively few documents |
| have index entries beginning with braces, we want to provide some |
| transition time for installations to have the new 'texindex'. At some |
| point in the future, we'll make '\usebracesinindexes' true by default |
| (the above TeX code will continue to work fine). |
| |
| Although not a matter of functionality, readers may be interested to |
| know that the new 'texindex' is a literate program |
| (<http://en.wikipedia.org/wiki/Literate_programming>) using Texinfo for |
| documentation and (portable) 'awk' for code. A single source file, |
| 'texindex/ti.twjr' in this case, produces the runnable program, a |
| printable document, and an online document. |
| |
| The system is called TexiWeb Jr. and was created by Arnold Robbins, |
| who also wrote the new 'texindex'. Not coincidentally, he is also the |
| long-time maintainer of 'gawk' (GNU Awk, *note (gawk)Top::). The file |
| 'texindex/Makefile.am' shows example usage of the system. |
| |
| |
| File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with tex/texindex, Up: Hardcopy |
| |
| 19.4 Print with 'lpr' from Shell |
| ================================ |
| |
| The way to print a DVI file depends on your system installation. Two |
| common ones are 'dvips foo.dvi -o' to make a PostScript file first and |
| then print that, and 'lpr -d foo.dvi' to print a DVI file directly. |
| |
| For example, the following commands will (probably) suffice to sort |
| the indices, format, and print this manual using the 'texi2dvi' shell |
| script (*note Format with texi2dvi::). |
| |
| texi2dvi texinfo.texi |
| dvips texinfo.dvi -o |
| lpr texinfo.ps |
| |
| Depending on the 'lpr' setup on your machine, you might able to |
| combine the last two steps into 'lpr -d texinfo.dvi'. |
| |
| You can also generate a PDF file by running 'texi2pdf' instead of |
| 'texi2dvi'; a PDF is often directly printable. Or you can generate a |
| PCL file by using 'dvilj' instead of 'dvips', if you have a printer that |
| prefers that format. |
| |
| 'lpr' is a standard program on Unix systems, but it is usually absent |
| on MS-DOS/MS-Windows. If so, just create a PostScript or PDF or PCL |
| file, whatever is most convenient, and print that in the usual way for |
| your machine (e.g., by sending to the appropriate port, usually 'PRN'). |
| |
| |
| File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Hardcopy |
| |
| 19.5 Printing From an Emacs Shell |
| ================================= |
| |
| You can give formatting and printing commands from a shell within GNU |
| Emacs, just like any other shell command. To create a shell within |
| Emacs, type 'M-x shell' (*note (emacs)Shell::). In this shell, you can |
| format and print the document. *Note Format and Print Hardcopy: |
| Hardcopy, for details. |
| |
| You can switch to and from the shell buffer while 'tex' is running |
| and do other editing. If you are formatting a long document on a slow |
| machine, this can be very convenient. |
| |
| For example, you can use 'texi2dvi' from an Emacs shell. Here is one |
| way to use 'texi2pdf' to format and print 'Using and Porting GNU CC' |
| from a shell within Emacs: |
| |
| texi2pdf gcc.texi |
| lpr gcc.pdf |
| |
| See the next section for more information about formatting and |
| printing in Texinfo mode. |
| |
| |
| File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Hardcopy |
| |
| 19.6 Formatting and Printing in Texinfo Mode |
| ============================================ |
| |
| Texinfo mode provides several predefined key commands for TeX formatting |
| and printing. These include commands for sorting indices, looking at |
| the printer queue, killing the formatting job, and recentering the |
| display of the buffer in which the operations occur. |
| |
| 'C-c C-t C-b' |
| 'M-x texinfo-tex-buffer' |
| Run 'texi2dvi' on the current buffer. |
| |
| 'C-c C-t C-r' |
| 'M-x texinfo-tex-region' |
| Run TeX on the current region. |
| |
| 'C-c C-t C-i' |
| 'M-x texinfo-texindex' |
| Sort the indices of a Texinfo file formatted with |
| 'texinfo-tex-region'. |
| |
| 'C-c C-t C-p' |
| 'M-x texinfo-tex-print' |
| Print a DVI file that was made with 'texinfo-tex-region' or |
| 'texinfo-tex-buffer'. |
| |
| 'C-c C-t C-q' |
| 'M-x tex-show-print-queue' |
| Show the print queue. |
| |
| 'C-c C-t C-d' |
| 'M-x texinfo-delete-from-print-queue' |
| Delete a job from the print queue; you will be prompted for the job |
| number shown by a preceding 'C-c C-t C-q' command |
| ('texinfo-show-tex-print-queue'). |
| |
| 'C-c C-t C-k' |
| 'M-x tex-kill-job' |
| Kill the currently running TeX job started by either |
| 'texinfo-tex-region' or 'texinfo-tex-buffer', or any other process |
| running in the Texinfo shell buffer. |
| |
| 'C-c C-t C-x' |
| 'M-x texinfo-quit-job' |
| Quit a TeX formatting job that has stopped because of an error by |
| sending an <x> to it. When you do this, TeX preserves a record of |
| what it did in a '.log' file. |
| |
| 'C-c C-t C-l' |
| 'M-x tex-recenter-output-buffer' |
| Redisplay the shell buffer in which the TeX printing and formatting |
| commands are run to show its most recent output. |
| |
| Thus, the usual sequence of commands for formatting a buffer is as |
| follows (with comments to the right): |
| |
| C-c C-t C-b Run 'texi2dvi' on the buffer. |
| C-c C-t C-p Print the DVI file. |
| C-c C-t C-q Display the printer queue. |
| |
| The Texinfo mode TeX formatting commands start a subshell in Emacs |
| called the '*tex-shell*'. The 'texinfo-tex-command', |
| 'texinfo-texindex-command', and 'tex-dvi-print-command' commands are all |
| run in this shell. |
| |
| You can watch the commands operate in the '*tex-shell*' buffer, and |
| you can switch to and from and use the '*tex-shell*' buffer as you would |
| any other shell buffer. |
| |
| The formatting and print commands depend on the values of several |
| variables. The default values are: |
| |
| Variable Default value |
| |
| texinfo-texi2dvi-command "texi2dvi" |
| texinfo-tex-command "tex" |
| texinfo-texindex-command "texindex" |
| texinfo-delete-from-print-queue-command "lprm" |
| texinfo-tex-trailer "@bye" |
| tex-start-of-header "%**start" |
| tex-end-of-header "%**end" |
| tex-dvi-print-command "lpr -d" |
| tex-show-queue-command "lpq" |
| |
| You can change the values of these variables with the 'M-x |
| set-variable' command (*note Examining and Setting Variables: |
| (emacs)Examining.), or with your '.emacs' initialization file (*note |
| (emacs)Init File::). |
| |
| Beginning with version 20, GNU Emacs offers a user-friendly |
| interface, called "Customize", for changing values of user-definable |
| variables. *Note Easy Customization Interface: (emacs)Easy |
| Customization, for more details about this. The Texinfo variables can |
| be found in the 'Development/Docs/Texinfo' group, once you invoke the |
| 'M-x customize' command. |
| |
| |
| File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Hardcopy |
| |
| 19.7 Using the Local Variables List |
| =================================== |
| |
| Yet another way to apply the TeX formatting command to a Texinfo file is |
| to put that command in a "local variables list" at the end of the |
| Texinfo file. You can then specify the 'tex' or 'texi2dvi' commands as |
| a 'compile-command' and have Emacs run it by typing 'M-x compile'. This |
| creates a special shell called the '*compilation*' buffer in which Emacs |
| runs the compile command. For example, at the end of the 'gdb.texi' |
| file, after the '@bye', you could put the following: |
| |
| Local Variables: |
| compile-command: "texi2dvi gdb.texi" |
| End: |
| |
| This technique is most often used by programmers who also compile |
| programs this way; see *note (emacs)Compilation::. |
| |
| |
| File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Hardcopy |
| |
| 19.8 TeX Formatting Requirements Summary |
| ======================================== |
| |
| Every Texinfo file that is to be input to TeX must begin with a '\input' |
| command: |
| |
| \input texinfo |
| |
| This instructs TeX to load the macros it needs to process a Texinfo |
| file. |
| |
| Every Texinfo file must end with a line that terminates TeX's |
| processing and forces out unfinished pages: |
| |
| @bye |
| |
| Strictly speaking, these two lines are all a Texinfo file needs to be |
| processed successfully by TeX. |
| |
| Usually, however, the beginning includes a '@settitle' command to |
| define the title of the printed manual, a title page, a copyright page, |
| permissions, and a table of contents. Besides '@bye', the end of a file |
| usually includes indices. (Not to mention that most manuals contain a |
| body of text as well.) |
| |
| For more information, see: |
| |
| * *note @settitle::. |
| * *note @setchapternewpage::. |
| * *note Headings::. |
| * *note Titlepage & Copyright Page::. |
| * *note Printing Indices & Menus::. |
| * *note Contents::. |
| |
| |
| File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Hardcopy |
| |
| 19.9 Preparing for TeX |
| ====================== |
| |
| TeX needs to know where to find the 'texinfo.tex' file that the '\input |
| texinfo' command on the first line reads. The 'texinfo.tex' file tells |
| TeX how to handle @-commands; it is included in all standard GNU |
| distributions. The latest version released for general use is available |
| from the usual GNU servers and mirrors: |
| |
| <http://ftp.gnu.org/gnu/texinfo/texinfo.tex> |
| <http://ftpmirror.gnu.org/texinfo/texinfo.tex> |
| |
| The latest development version is available from the Texinfo source |
| repository: |
| <http://svn.savannah.gnu.org/viewvc/trunk/doc/texinfo.tex?root=texinfo&view=log> |
| |
| 'texinfo.tex' is essentially a standalone file, and compatibility is |
| of utmost concern; so, if you need or want to try a newer version than |
| came with your system, it nearly always suffices to download it and put |
| it anywhere that TeX will find it (first). You can replace any existing |
| 'texinfo.tex' with a newer version (of course saving the original in |
| case of disaster). |
| |
| Also, you should install 'epsf.tex', if it is not already installed |
| from another distribution. More details are at the end of the |
| description of the '@image' command (*note Images::). |
| |
| To use quotation marks other than those used in English, you'll need |
| to have the European Computer Modern fonts (e.g., 'ecrm1000') and (for |
| PDF output) CM-Super fonts (*note Inserting Quotation Marks::). |
| |
| To use the '@euro' command, you'll need the 'feym*' fonts (e.g., |
| 'feymr10'). *Note @euro::. |
| |
| All of the above files (and a whole lot more) should be installed by |
| default in a reasonable TeX installation. |
| |
| Optionally, you may create a file 'texinfo.cnf' for site |
| configuration. This file is read by TeX at the beginning of a Texinfo |
| file. You can put any commands you like there, according to local |
| site-wide conventions. They will be read by TeX when processing any |
| Texinfo document. For example, if 'texinfo.cnf' contains the line |
| '@afourpaper' (*note A4 Paper::), then all Texinfo documents will be |
| processed with that page size in effect. If you have nothing to put in |
| 'texinfo.cnf', you do not need to create it. |
| |
| If neither of the above locations for these system files suffice, you |
| can specify the directories explicitly. For 'texinfo.tex', you can do |
| this by writing the complete path for the file after the '\input' |
| command. Another way, that works for both 'texinfo.tex' and |
| 'texinfo.cnf' (and any other file TeX might read), is to set the |
| 'TEXINPUTS' environment variable in your '.profile' or '.cshrc' file. |
| |
| Whether you use '.profile' or '.cshrc' depends on whether you use a |
| Bourne shell-compatible ('sh', 'bash', 'ksh', ...) or C shell-compatible |
| ('csh', 'tcsh') command interpreter, respeictvely. |
| |
| In a '.profile' file, you could use the following 'sh' command |
| sequence: |
| |
| TEXINPUTS=.:/home/me/mylib: |
| export TEXINPUTS |
| |
| While in a '.cshrc' file, you could use the following 'csh' command |
| sequence: |
| |
| setenv TEXINPUTS .:/home/me/mylib: |
| |
| On MS-DOS/MS-Windows, you'd do this (note the use of the ';' |
| character as directory separator, instead of ':'): |
| |
| set TEXINPUTS=.;d:/home/me/mylib;c: |
| |
| It is customary for DOS/Windows users to put such commands in the |
| 'autoexec.bat' file, or in the Windows registry. |
| |
| These settings would cause TeX to look for '\input' file first in the |
| current directory, indicated by the '.', then in a hypothetical user |
| 'me''s 'mylib' directory, and finally in the system directories. (A |
| leading, trailing, or doubled ':' indicates searching the system |
| directories at that point.) |
| |
| |
| File: texinfo.info, Node: Overfull hboxes, Next: @smallbook, Prev: Preparing for TeX, Up: Hardcopy |
| |
| 19.10 Overfull "hboxes" |
| ======================= |
| |
| TeX is sometimes unable to typeset a line within the normal margins. |
| This most often occurs when TeX comes upon what it interprets as a long |
| word that it cannot hyphenate, such as an electronic mail network |
| address or a very long identifier. When this happens, TeX prints an |
| error message like this: |
| |
| Overfull @hbox (20.76302pt too wide) |
| |
| (In TeX, lines are in "horizontal boxes", hence the term, "hbox". |
| '@hbox' is a TeX primitive not used in the Texinfo language.) |
| |
| TeX also provides the line number in the Texinfo source file and the |
| text of the offending line, which is marked at all the places that TeX |
| considered hyphenation. *Note Debugging with TeX::, for more |
| information about typesetting errors. |
| |
| If the Texinfo file has an overfull hbox, you can rewrite the |
| sentence so the overfull hbox does not occur, or you can decide to leave |
| it. A small excursion into the right margin often does not matter and |
| may not even be noticeable. |
| |
| If you have many overfull boxes and/or an antipathy to rewriting, you |
| can coerce TeX into greatly increasing the allowable interword spacing, |
| thus (if you're lucky) avoiding many of the bad line breaks, like this: |
| |
| @tex |
| \global\emergencystretch = .9\hsize |
| @end tex |
| |
| (You should adjust the fraction as needed.) This huge value for |
| '\emergencystretch' cannot be the default, since then the typeset output |
| would generally be of noticeably lower quality; its default value is |
| '.15\hsize'. '\hsize' is the TeX dimension containing the current line |
| width. |
| |
| For any overfull boxes you do have, TeX will print a large, ugly, |
| black rectangle beside the line that contains the overfull hbox unless |
| told otherwise. This is so you will notice the location of the problem |
| if you are correcting a draft. |
| |
| To prevent such a monstrosity from marring your final printout, write |
| the following in the beginning of the Texinfo file on a line of its own, |
| before the '@titlepage' command: |
| |
| @finalout |
| |
| |
| File: texinfo.info, Node: @smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Hardcopy |
| |
| 19.11 '@smallbook': Printing "Small" Books |
| ========================================== |
| |
| By default, TeX typesets pages for printing in an 8.5 by 11 inch format. |
| However, you can direct TeX to typeset a document in a 7 by 9.25 inch |
| format that is suitable for bound books by inserting the following |
| command on a line by itself at the beginning of the Texinfo file, before |
| the title page: |
| |
| @smallbook |
| |
| (Since many books are about 7 by 9.25 inches, this command might better |
| have been called the '@regularbooksize' command, but it came to be |
| called the '@smallbook' command by comparison to the 8.5 by 11 inch |
| format.) |
| |
| If you write the '@smallbook' command between the start-of-header and |
| end-of-header lines, the Texinfo mode TeX region formatting command, |
| 'texinfo-tex-region', will format the region in "small" book size (*note |
| Start of Header::). |
| |
| *Note @small...::, for information about commands that make it easier |
| to produce examples for a smaller manual. |
| |
| *Note Format with texi2dvi::, and *note Preparing for TeX::, for |
| other ways to format with '@smallbook' that do not require changing the |
| source file. |
| |
| |
| File: texinfo.info, Node: A4 Paper, Next: @pagesizes, Prev: @smallbook, Up: Hardcopy |
| |
| 19.12 Printing on A4 Paper |
| ========================== |
| |
| You can tell TeX to format a document for printing on European size A4 |
| paper (or A5) with the '@afourpaper' (or '@afivepaper') command. Write |
| the command on a line by itself near the beginning of the Texinfo file, |
| before the title page. For example, this is how you would write the |
| header for this manual: |
| |
| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @settitle Texinfo |
| @afourpaper |
| @c %**end of header |
| |
| *Note Format with texi2dvi::, and *note Preparing for TeX::, for |
| other ways to format for different paper sizes that do not require |
| changing the source file. |
| |
| You may or may not prefer the formatting that results from the |
| command '@afourlatex'. There's also '@afourwide' for A4 paper in wide |
| format. |
| |
| |
| File: texinfo.info, Node: @pagesizes, Next: Cropmarks and Magnification, Prev: A4 Paper, Up: Hardcopy |
| |
| 19.13 '@pagesizes' [WIDTH][, HEIGHT]: Custom Page Sizes |
| ======================================================= |
| |
| You can explicitly specify the height and (optionally) width of the main |
| text area on the page with the '@pagesizes' command. Write this on a |
| line by itself near the beginning of the Texinfo file, before the title |
| page. The height comes first, then the width if desired, separated by a |
| comma. Examples: |
| |
| @pagesizes 200mm,150mm |
| and |
| @pagesizes 11.5in |
| |
| This would be reasonable for printing on B5-size paper. To |
| emphasize, this command specifies the size of the _text area_, not the |
| size of the paper (which is 250mm by 177mm for B5, 14in by 8.5in for |
| legal). |
| |
| To make more elaborate changes, such as changing any of the page |
| margins, you must define a new command in 'texinfo.tex' or |
| 'texinfo.cnf'. |
| |
| *Note Format with texi2dvi::, and *note Preparing for TeX::, for |
| other ways to specify '@pagesizes' that do not require changing the |
| source file. |
| |
| |
| File: texinfo.info, Node: Cropmarks and Magnification, Next: PDF Output, Prev: @pagesizes, Up: Hardcopy |
| |
| 19.14 Cropmarks and Magnification |
| ================================= |
| |
| You can (attempt to) direct TeX to print cropmarks at the corners of |
| pages with the '@cropmarks' command. Write the '@cropmarks' command on |
| a line by itself near the beginning of the Texinfo file, before the |
| title page, like this: |
| |
| @cropmarks |
| |
| This command is mainly for printers that typeset several pages on one |
| sheet of film; but you can attempt to use it to mark the corners of a |
| book set to 7 by 9.25 inches with the '@smallbook' command. (Printers |
| will not produce cropmarks for regular sized output that is printed on |
| regular sized paper.) Since different printing machines work in |
| different ways, you should explore the use of this command with a spirit |
| of adventure. You may have to redefine the command in 'texinfo.tex'. |
| |
| The '@cropmarks' command is recognized and ignored in non-TeX output |
| formats. |
| |
| You can attempt to direct TeX to typeset pages larger or smaller than |
| usual with the '\mag' TeX command. Everything that is typeset is scaled |
| proportionally larger or smaller. ('\mag' stands for "magnification".) |
| This is _not_ a Texinfo @-command, but is a raw TeX command that is |
| prefixed with a backslash. You have to write this command between |
| '@tex' and '@end tex' (*note Raw Formatter Commands::). |
| |
| Follow the '\mag' command with an '=' and then a number that is 1000 |
| times the magnification you desire. For example, to print pages at 1.2 |
| normal size, write the following near the beginning of the Texinfo file, |
| before the title page: |
| |
| @tex |
| \global\mag=1200 |
| @end tex |
| |
| With some printing technologies, you can print normal-sized copies |
| that look better than usual by giving a larger-than-normal master to |
| your print shop. They do the reduction, thus effectively increasing the |
| resolution. |
| |
| Depending on your system, DVI files prepared with a |
| nonstandard-'\mag' may not print or may print only with certain |
| magnifications. Be prepared to experiment. |
| |
| |
| File: texinfo.info, Node: PDF Output, Next: Obtaining TeX, Prev: Cropmarks and Magnification, Up: Hardcopy |
| |
| 19.15 PDF Output |
| ================ |
| |
| The simplest way to generate PDF output from Texinfo source is to run |
| the convenience script 'texi2pdf' (or 'pdftexi2dvi'); this executes the |
| 'texi2dvi' script with the '--pdf' option (*note Format with |
| texi2dvi::). If for some reason you want to process the document by |
| hand, you can run the 'pdftex' program instead of plain 'tex'. That is, |
| run 'pdftex foo.texi' instead of 'tex foo.texi'. |
| |
| "PDF" stands for 'Portable Document Format'. It was invented by |
| Adobe Systems some years ago for document interchange, based on their |
| PostScript language. Related links: |
| |
| * GNU GV, a Ghostscript-based PDF reader |
| (http://www.gnu.org/software/gv/). (It can also preview PostScript |
| documents.) |
| |
| * 'xpdf', a freely available standalone PDF reader |
| (http://www.foolabs.com/xpdf/) for the X window system. |
| |
| * PDF at Wikipedia |
| (https://en.wikipedia.org/wiki/Portable_Document_Format). |
| |
| At present, Texinfo does not provide '@ifpdf' or '@pdf' commands as |
| for the other output formats, since PDF documents contain many internal |
| low-level offsets and cross-references that would be hard or impossible |
| to specify at the Texinfo source level. |
| |
| PDF files require dedicated software to be displayed, unlike the |
| plain ASCII formats (Info, HTML) that Texinfo supports. They also tend |
| to be much larger than the DVI files output by TeX by default. |
| Nevertheless, a PDF file does define an actual typeset document in a |
| self-contained file, notably including all the fonts that are used, so |
| it has its place. |
| |
| |
| File: texinfo.info, Node: Obtaining TeX, Prev: PDF Output, Up: Hardcopy |
| |
| 19.16 Obtaining TeX |
| =================== |
| |
| TeX is a document formatter that is used by the FSF for its |
| documentation. It is the easiest way to get printed output (e.g., PDF |
| and PostScript) for Texinfo manuals. TeX is freely redistributable, and |
| you can get it over the Internet or on physical media. See |
| <http://tug.org/texlive>. |
| |
| |
| File: texinfo.info, Node: Generic Translator texi2any, Next: Creating and Installing Info Files, Prev: Hardcopy, Up: Top |
| |
| 20 'texi2any': The Generic Translator for Texinfo |
| ************************************************* |
| |
| 'texi2any' is the generic translator for Texinfo that can produce |
| different output formats and is highly customizable. It supports these |
| formats: |
| |
| Info (by default, or with '--info'), |
| |
| HTML (with '--html'), |
| |
| plain text (with '--plaintext'), |
| |
| Docbook (with '--docbook'), |
| |
| Texinfo XML (with '--xml'). |
| |
| 'makeinfo' is an alias for 'texi2any'. By default, both 'texi2any' |
| and 'makeinfo' generate Info output; indeed, there are no differences in |
| behavior based on the name. |
| |
| Beside these default formats, command line options to 'texi2any' can |
| change many aspects of the output. Beyond that, initialization files |
| provide even more control over the final output--nearly anything not |
| specified in the Texinfo input file. Initialization files are written |
| in Perl, like the main program, and anything which can be specified on |
| the command line can also be specified within a initialization file. |
| |
| The rest of this chapter goes into the details. |
| |
| * Menu: |
| |
| * Reference Implementation:: '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'. |
| |
| |
| File: texinfo.info, Node: Reference Implementation, Next: Invoking texi2any, Up: Generic Translator texi2any |
| |
| 20.1 'texi2any': A Texinfo Reference Implementation |
| =================================================== |
| |
| Above, we called 'texi2any' "the" translator for Texinfo instead of just |
| "a" translator, even though (of course) it's technically and legally |
| possible for other implementations to be written. The reason is that |
| alternative implementations are very likely to have subtle, or |
| not-so-subtle, differences in behavior, and thus Texinfo documents would |
| become dependent on the processor. Therefore, it is important to have a |
| reference implementation that defines parts of the language not fully |
| specified by the manual (often intentionally so). It is equally |
| important to have consistent command-line options and other behavior for |
| all processors. |
| |
| For this reason, the once-independent 'texi2html' Perl Texinfo |
| processor was made compatible with the C implementation of 'makeinfo', |
| to avoid continuing with two different implementations (*note |
| History::). The current implementation, 'texi2any', serves as the |
| reference implementation. It inherited the design of customization and |
| other features from 'texi2html' (for more on 'texi2html' compatibility, |
| *note texi2html::). However, 'texi2any' is a full reimplementation: it |
| constructs a tree-based representation of the input document for all |
| back-ends to work from. |
| |
| Extensive tests of the language were developed at the same time as |
| 'texi2any'; we plead with anyone thinking of writing a program to parse |
| Texinfo input to at least make use of these tests. |
| |
| The 'texi2html' wrapper script (*note texi2html::) provides a very |
| simple example of calling 'texi2any' from a shell script; it's in |
| 'util/texi2html' in the Texinfo sources. More consequentially, |
| 'texi-elements-by-size' is an example Perl script using the |
| 'Texinfo::Parser' module interface; it's also in the 'util' source |
| directory. (Its functionality may also be useful to authors; *note |
| texi-elements-by-size::.) |
| |
| With the release of 'texi2any' as the reference implementation, |
| development of both the C implementation of 'makeinfo' and 'texi2html' |
| has been halted. Going forward, we ask authors of Texinfo documents to |
| use only 'texi2any'. |
| |
| |
| File: texinfo.info, Node: Invoking texi2any, Next: texi2any Printed Output, Prev: Reference Implementation, Up: Generic Translator texi2any |
| |
| 20.2 Invoking 'texi2any'/'makeinfo' from a Shell |
| ================================================ |
| |
| To process a Texinfo file, invoke 'texi2any' or 'makeinfo' (the two |
| names are synonyms for the same program; we'll use the names |
| interchangeably) followed by the name of the Texinfo file. Also select |
| the format you want to output with the appropriate command line option |
| (default is Info). Thus, to create the Info file for Bison, type the |
| following to the shell: |
| |
| texi2any --info bison.texinfo |
| |
| You can specify more than one input file name; each is processed in |
| turn. If an input file name is '-', standard input is read. |
| |
| The 'texi2any' program accept many options. Perhaps the most basic |
| are those that change the output format. By default, 'texi2any' outputs |
| Info. |
| |
| Each command line option is either a long name preceded by '--' or a |
| single letter preceded by '-'. You can use abbreviations for the long |
| option names as long as they are unique. |
| |
| For example, you could use the following shell command to create an |
| Info file for 'bison.texinfo' in which lines are filled to only 68 |
| columns: |
| |
| texi2any --fill-column=68 bison.texinfo |
| |
| You can write two or more options in sequence, like this: |
| |
| texi2any --no-split --fill-column=70 ... |
| |
| (This would keep the Info file together as one possibly very long file |
| and would also set the fill column to 70.) |
| |
| The options are (approximately in alphabetical order): |
| |
| '--commands-in-node-names' |
| This option now does nothing, but remains for compatibility. (It |
| used to ensure that @-commands in node names were expanded |
| throughout the document, especially '@value'. This is now done by |
| default.) |
| |
| '--conf-dir=PATH' |
| Prepend PATH to the directory search list for finding customization |
| files that may be loaded with '--init-file' (see below). The PATH |
| value can be a single directory, or a list of several directories |
| separated by the usual path separator character (':' on Unix-like |
| systems, ';' on Windows). |
| |
| '--css-include=FILE' |
| When producing HTML, literally include the contents of FILE, which |
| should contain W3C cascading style sheets specifications, in the |
| '<style>' block of the HTML output. If FILE is '-', read standard |
| input. *Note HTML CSS::. |
| |
| '--css-ref=URL' |
| When producing HTML, add a '<link>' tag to the output which |
| references a cascading style sheet at URL. This allows using |
| standalone style sheets. |
| |
| '-D VAR' |
| '-D 'VAR VALUE'' |
| Cause the Texinfo variable VAR to be defined. This is equivalent |
| to '@set VAR' in the Texinfo file (*note @set @clear @value::). |
| |
| The argument to the option is always one word to the shell; if it |
| contains internal whitespace, the first word is taken as the |
| variable name and the remainder as the value. For example, '-D |
| 'myvar someval'' is equivalent to '@set myvar someval'. |
| |
| '--disable-encoding' |
| '--enable-encoding' |
| By default, or with '--enable-encoding', output accented and |
| special characters in Info and plain text output based on |
| '@documentencoding'. With '--disable-encoding', 7-bit ASCII |
| transliterations are output. *Note @documentencoding::, and *note |
| Inserting Accents::. |
| |
| '--docbook' |
| Generate Docbook output (rather than Info). |
| |
| '--document-language=LANG' |
| Use LANG to translate Texinfo keywords which end up in the output |
| document. The default is the locale specified by the |
| '@documentlanguage' command if there is one, otherwise English |
| (*note @documentlanguage::). |
| |
| '--dvi' |
| Generate a TeX DVI file using 'texi2dvi', rather than Info (*note |
| texi2any Printed Output::). |
| |
| '--dvipdf' |
| Generate a PDF file using 'texi2dvi --dvipdf', rather than Info |
| (*note texi2any Printed Output::). |
| |
| '--error-limit=LIMIT' |
| '-e LIMIT' |
| Report LIMIT errors before aborting (on the assumption that |
| continuing would be useless); default 100. |
| |
| '--fill-column=WIDTH' |
| '-f WIDTH' |
| Specify the maximum number of columns in a line; this is the |
| right-hand edge of a line. Paragraphs that are filled will be |
| filled to this width. (Filling is the process of breaking up and |
| connecting lines so that lines are the same length as or shorter |
| than the number specified as the fill column. Lines are broken |
| between words.) The default value is 72. |
| |
| '--footnote-style=STYLE' |
| '-s STYLE' |
| Set the footnote style to STYLE: either 'end' for the end node |
| style (the default) or 'separate' for the separate node style. The |
| value set by this option overrides the value set in a Texinfo file |
| by a '@footnotestyle' command (*note Footnote Styles::). |
| |
| When the footnote style is 'separate', 'makeinfo' makes a new node |
| containing the footnotes found in the current node. When the |
| footnote style is 'end', 'makeinfo' places the footnote references |
| at the end of the current node. |
| |
| 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. |
| |
| '--force' |
| '-F' |
| Ordinarily, if the input file has errors, the output files are not |
| created. With this option, they are preserved. |
| |
| '--help' |
| '-h' |
| Print a message with available options and basic usage, then exit |
| successfully. |
| |
| '--html' |
| Generate HTML output (rather than Info). By default, the HTML |
| output is split into one output file per Texinfo source node, and |
| the split output is written into a subdirectory based on the name |
| of the top-level Info file. *Note Generating HTML::. |
| |
| '-I PATH' |
| Append PATH to the directory search list for finding files that are |
| included using the '@include' command. By default, 'texi2any' |
| searches only the current directory. If PATH is not given, the |
| current directory is appended. The PATH value can be a single |
| directory or a list of several directories separated by the usual |
| path separator character (':' on Unix-like systems, ';' on |
| Windows). |
| |
| '--ifdocbook' |
| '--ifhtml' |
| '--ifinfo' |
| '--ifplaintext' |
| '--iftex' |
| '--ifxml' |
| For the given format, process '@ifFORMAT' and '@FORMAT' commands, |
| and do not process '@ifnotFORMAT', regardless of the format being |
| output. For instance, if '--iftex' is given, then '@iftex' and |
| '@tex' blocks will be read, and '@ifnottex' blocks will be ignored. |
| |
| '--info' |
| Generate Info output. By default, if the output file contains more |
| than about 300,000 bytes, it is split into shorter subfiles of |
| about that size. The name of the output file and any subfiles is |
| determined by '@setfilename' (*note @setfilename::). *Note Tag and |
| Split Files::. |
| |
| '--init-file=FILE' |
| Load FILE as code to modify the behavior and output of the |
| generated manual. It is customary to use the '.pm' or the '.init' |
| extensions for these customization files, but that is not enforced; |
| the FILE name can be anything. The '--conf-dir' option (see above) |
| can be used to add to the list of directories in which these |
| customization files are searched for. |
| |
| '--internal-links=FILE' |
| In HTML mode, output a tab-separated file containing three columns: |
| the internal link to an indexed item or item in the table of |
| contents, the name of the index (or table of contents) in which it |
| occurs, and the term which was indexed or entered. The items are |
| in the natural sorting order for the given element. This dump can |
| be useful for post-processors. |
| |
| '--macro-expand=FILE' |
| '-E FILE' |
| Output the Texinfo source, with all Texinfo macros expanded, to |
| FILE. Normally, the result of macro expansion is used internally |
| by 'makeinfo' and then discarded. |
| |
| '--no-headers' |
| Do not include menus or node separator lines in the output. |
| |
| When generating Info, this is the same as using '--plaintext', |
| resulting in a simple plain text file. Furthermore, '@setfilename' |
| is ignored, and output is to standard output unless overridden with |
| '-o'. (This behavior is for backward compatibility.) |
| |
| When generating HTML, and output is split, also output navigation |
| links only at the beginning of each file. If output is not split, |
| do not include navigation links at the top of each node at all. |
| *Note Generating HTML::. |
| |
| '--no-ifdocbook' |
| '--no-ifhtml' |
| '--no-ifinfo' |
| '--no-ifplaintext' |
| '--no-iftex' |
| '--no-ifxml' |
| For the given format, do not process '@ifFORMAT' and '@FORMAT' |
| commands, and do process '@ifnotFORMAT', regardless of the format |
| being output. For instance, if '--no-ifhtml' is given, then |
| '@ifhtml' and '@html' blocks will not be read, and '@ifnothtml' |
| blocks will be. |
| |
| '--no-node-files' |
| '--node-files' |
| When generating HTML, create redirection files for anchors and any |
| nodes not already output with the file name corresponding to the |
| node name (*note HTML Xref Node Name Expansion::). This makes it |
| possible for section- and chapter-level cross-manual references to |
| succeed (*note HTML Xref Configuration::). |
| |
| If the output is split, this is enabled by default. If the output |
| is not split, '--node-files' enables the creation of the |
| redirection files, in addition to the monolithic main output file. |
| '--no-node-files' suppresses the creation of redirection files in |
| any case. This option has no effect with any output format other |
| than HTML. *Note Generating HTML::. |
| |
| '--no-number-footnotes' |
| Suppress automatic footnote numbering. By default, footnotes are |
| numbered sequentially within a node, i.e., the current footnote |
| number is reset to 1 at the start of each node. |
| |
| '--no-number-sections' |
| '--number-sections' |
| With '--number_sections' (the default), output chapter, section, |
| and appendix numbers as in printed manuals. This works only with |
| hierarchically-structured manuals. You should specify |
| '--no-number-sections' if your manual is not normally structured. |
| |
| '--no-pointer-validate' |
| '--no-validate' |
| Suppress the pointer-validation phase of 'makeinfo'--a dangerous |
| thing to do. This can also be done with the '@novalidate' command |
| (*note Use TeX::). Normally, consistency checks are made to ensure |
| that cross-references can be resolved, etc. *Note Pointer |
| Validation::. |
| |
| '--no-warn' |
| Suppress warning messages (but not error messages). |
| |
| '--output=FILE' |
| '-o FILE' |
| Specify that the output should be directed to FILE. This overrides |
| any file name specified in a '@setfilename' command found in the |
| Texinfo source. If neither '@setfilename' nor this option are |
| specified, the input file name is used to determine the output |
| name. *Note @setfilename::. |
| |
| If FILE is '-', output goes to standard output and '--no-split' is |
| implied. |
| |
| If FILE is a directory or ends with a '/' the usual rules are used |
| to determine the output file name (namely, use '@setfilename' or |
| the input file name) but the files are written to the FILE |
| directory. For example, 'makeinfo -o bar/ foo.texi', with or |
| without '--no-split', will write 'bar/foo.info', and possibly other |
| files, under 'bar/'. |
| |
| When generating HTML and output is split, FILE is used as the name |
| for the directory into which all files are written. For example, |
| 'makeinfo -o bar --html foo.texi' will write 'bar/index.html', |
| among other files. |
| |
| '--output-indent=VAL' |
| This option now does nothing, but remains for compatibility. (It |
| used to alter indentation in XML/Docbook output.) |
| |
| '-P PATH' |
| Prepend PATH to the directory search list for '@include'. If PATH |
| is not given, the current directory is prepended. See '-I' above. |
| |
| '--paragraph-indent=INDENT' |
| '-p INDENT' |
| Set the paragraph indentation style to INDENT. The value set by |
| this option overrides the value set in a Texinfo file by an |
| '@paragraphindent' command (*note @paragraphindent::). The value |
| of INDENT is interpreted as follows: |
| |
| 'asis' |
| Preserve any existing indentation (or lack thereof) at the |
| beginnings of paragraphs. |
| |
| '0' or 'none' |
| Delete any existing indentation. |
| |
| NUM |
| Indent each paragraph by NUM spaces. |
| |
| The default is to indent by two spaces, except for paragraphs |
| following a section heading, which are not indented. |
| |
| '--pdf' |
| Generate a PDF file using 'texi2dvi --pdf', rather than Info (*note |
| texi2any Printed Output::). |
| |
| '--plaintext' |
| Output a plain text file (rather than Info): do not include menus |
| or node separator lines in the output. This results in a |
| straightforward plain text file that you can (for example) send in |
| email without complications, or include in a distribution (for |
| example, an 'INSTALL' file). |
| |
| With this option, '@setfilename' is ignored and the output goes to |
| standard output by default; this can be overridden with '-o'. |
| |
| '--ps' |
| Generate a PostScript file using 'texi2dvi --ps', rather than Info |
| (*note texi2any Printed Output::). |
| |
| '--set-customization-variable VAR=VALUE' |
| '-c VAR=VALUE' |
| Set the customization variable VAR to VALUE. The '=' is optional, |
| but both VAR and VALUE must be quoted to the shell as necessary so |
| the result is a single word. Many aspects of 'texi2any' behavior |
| and output may be controlled by customization variables, beyond |
| what can be set in the document by @-commands and with other |
| command line switches. *Note Customization Variables::. |
| |
| '--split=HOW' |
| '--no-split' |
| When generating Info, by default large output files are split into |
| smaller subfiles, of approximately 300k bytes. When generating |
| HTML, by default each output file contains one node (*note |
| Generating HTML::). '--no-split' suppresses this splitting of the |
| output. |
| |
| Alternatively, '--split=HOW' may be used to specify at which level |
| the HTML output should be split. The possible values for HOW are: |
| |
| 'chapter' |
| The output is split at '@chapter' and other sectioning |
| @-commands at this level ('@appendix', etc.). |
| |
| 'section' |
| The output is split at '@section' and similar. |
| |
| 'node' |
| The output is split at every node. This is the default. |
| |
| Plain text output can be split similarly to HTML. This may be |
| useful for extracting sections from a Texinfo document and making |
| them available as separate files. |
| |
| '--split-size=NUM' |
| Keep Info files to at most NUM characters if possible; default is |
| 300,000. (However, a single node will never be split across Info |
| files.) |
| |
| '--transliterate-file-names' |
| Enable transliteration of 8-bit characters in node names for the |
| purpose of file name creation. *Note HTML Xref 8-bit Character |
| Expansion::. |
| |
| '-U VAR' |
| Cause VAR to be undefined. This is equivalent to '@clear VAR' in |
| the Texinfo file (*note @set @clear @value::). |
| |
| '--verbose' |
| Cause 'makeinfo' to display messages saying what it is doing. |
| Normally, 'makeinfo' only outputs messages if there are errors or |
| warnings. |
| |
| '--version' |
| '-V' |
| Print the version number, then exit successfully. |
| |
| '--Xopt STR' |
| Pass STR (a single shell word) to 'texi2dvi'; may be repeated |
| (*note texi2any Printed Output::). |
| |
| '--xml' |
| Generate Texinfo XML output (rather than Info). |
| |
| 'makeinfo' also reads the environment variable |
| 'TEXINFO_OUTPUT_FORMAT' to determine the output format, if not |
| overridden by a command line option. The value should be one of: |
| |
| docbook dvi dvipdf html info pdf plaintext ps xml |
| |
| If not set or otherwise specified, Info output is the default. |
| |
| The customization variable of the same name is also read; if set, |
| that overrides an environment variable setting, but not a command-line |
| option. *Note Customization Variables and Options::. |
| |
| |
| File: texinfo.info, Node: texi2any Printed Output, Next: Pointer Validation, Prev: Invoking texi2any, Up: Generic Translator texi2any |
| |
| 20.3 'texi2any' Printed Output |
| ============================== |
| |
| To justify the name Texinfo-to-_any_, 'texi2any' has basic support for |
| creating printed output in the various formats: TeX DVI, PDF, and |
| PostScript. This is done via the simple method of executing the |
| 'texi2dvi' program when those output formats are requested, after |
| checking the validity of the input to give users the benefit of |
| 'texi2any''s error checking. If you don't want such error checking, |
| perhaps because your manual plays advanced TeX tricks together with |
| 'texinfo.tex', just invoke 'texi2dvi' directly. |
| |
| The output format options for this are '--dvi', '--dvipdf', '--pdf', |
| and '--ps'. *Note Format with texi2dvi::, for more details on these |
| options and general 'texi2dvi' operation. In addition, the '--verbose', |
| '--silent', and '--quiet' options are passed on if specified; the '-I' |
| and '-o' options are likewise passed on with their arguments, and |
| '--debug' without its argument. |
| |
| The only option remaining that is related to the 'texi2dvi' |
| invocation is '--Xopt'. Here, just the argument is passed on and |
| multiple '--Xopt' options accumulate. This provides a way to construct |
| an arbitrary command line for 'texi2dvi'. For example, running |
| |
| texi2any --Xopt -t --Xopt @a4paper --pdf foo.texi |
| |
| is equivalent to running |
| |
| texi2dvi -t @a4paper --pdf foo.texi |
| |
| except for the validity check. |
| |
| Although one might wish that other options to 'texi2any' would take |
| effect, they don't. For example, running 'texi2any --no-number-sections |
| --dvi foo.texi' still results in a DVI file with numbered sections. |
| (Perhaps this could be improved in the future, if requests are |
| received.) |
| |
| The actual name of the command that is invoked is specified by the |
| 'TEXI2DVI' customization variable (*note Other Customization |
| Variables::). As you might guess, the default is 'texi2dvi'. |
| |
| 'texi2any' itself does not generate any normal output when it invokes |
| 'texi2dvi', only diagnostic messages. |
| |
| |
| File: texinfo.info, Node: Pointer Validation, Next: Customization Variables, Prev: texi2any Printed Output, Up: Generic Translator texi2any |
| |
| 20.4 Pointer Validation |
| ======================= |
| |
| If you do not suppress pointer validation with the '--no-validate' |
| option or the '@novalidate' command in the source file (*note Use |
| TeX::), 'makeinfo' will check the validity of the Texinfo file. |
| |
| Most validation checks are different depending on whether node |
| pointers are explicitly or implicitly determined. With explicit node |
| pointers, here is the list of what is checked: |
| |
| 1. If a 'Next', 'Previous', or 'Up' node reference is a reference to a |
| node in the current file and is not an external reference such as |
| to '(dir)', then the referenced node must exist. |
| |
| 2. Every node except the 'Top' node must have an 'Up' pointer. |
| |
| 3. The node referenced by an 'Up' pointer must itself reference the |
| current node through a menu item, unless the node referenced by |
| 'Up' has the form '(FILE)'. |
| |
| With implicit node pointers, the above error cannot occur, as such. |
| (Which is a major reason why we recommend using this feature of |
| 'makeinfo', and not specifying any node pointers yourself.) |
| |
| Instead, 'makeinfo' checks that the tree constructed from the |
| document's menus matches the tree constructed from the sectioning |
| commands. For example, if a chapter-level menu mentions nodes N1 and |
| N2, in that order, nodes N1 and N2 must be associated with '@section' |
| commands in the chapter. |
| |
| Finally, with both explicit and implicit node pointers, 'makeinfo' |
| checks that every node except the 'Top' node is referenced in a menu. |
| |
| |
| File: texinfo.info, Node: Customization Variables, Next: Internationalization of Document Strings, Prev: Pointer Validation, Up: Generic Translator texi2any |
| |
| 20.5 Customization Variables |
| ============================ |
| |
| Warning: These customization variable names and meanings may change |
| in any Texinfo release. We always try to avoid incompatible |
| changes, but we cannot absolutely promise, since needs change over |
| time. |
| |
| Many aspects of the behavior and output of 'texi2any' may be modified |
| by modifying so-called "customization variables". These fall into a few |
| general categories: |
| |
| * Those associated with @-commands; for example, '@documentlanguage'. |
| |
| * Those associated with command-line options; for example, the |
| customization variable 'SPLIT' is associated with the '--split' |
| command-line option, and 'TEXINFO_OUTPUT_FORMAT' allows specifying |
| the output format. |
| |
| * Those associated with customizing the HTML output. |
| |
| * Other ad hoc variables. |
| |
| Customization variables may set on the command line using |
| '--set-customization-variable 'VAR VALUE'' (quoting the variable/value |
| pair to the shell) or '--set-customization-variable VAR=VALUE' (using |
| '='). A special VALUE is 'undef', which sets the variable to this |
| special "undefined" Perl value. |
| |
| The sections below give the details for each of these. |
| |
| * Menu: |
| |
| * Commands: Customization Variables for @-Commands. |
| * Options: Customization Variables and Options. |
| * HTML: HTML Customization Variables. |
| * Other: Other Customization Variables. |
| |
| |
| File: texinfo.info, Node: Customization Variables for @-Commands, Next: Customization Variables and Options, Up: Customization Variables |
| |
| 20.5.1 Customization Variables for @-Commands |
| --------------------------------------------- |
| |
| Each of the following @-commands has an associated customization |
| variable with the same name (minus the leading '@'): |
| |
| @allowcodebreaks @clickstyle @codequotebacktick |
| @codequoteundirected @contents @deftypefnnewline |
| @documentdescription @documentencoding @documentlanguage |
| @evenfooting @evenfootingmarks |
| @evenheading @evenheadingmarks |
| @everyfooting @everyfootingmarks |
| @everyheading @everyheadingmarks |
| @exampleindent @firstparagraphindent |
| @fonttextsize @footnotestyle @frenchspacing @headings |
| @kbdinputstyle @novalidate |
| @oddfooting @oddfootingmarks |
| @oddheading @oddheadingmarks |
| @pagesizes @paragraphindent |
| @setchapternewpage @setcontentsaftertitlepage |
| @setfilename @setshortcontentsaftertitlepage @shortcontents |
| @urefbreakstyle @validatemenus @xrefautomaticsectiontitle |
| |
| Setting such a customization variable to a value 'foo' is similar to |
| executing '@CMD foo'. It is not exactly the same, though, since any |
| side effects of parsing the Texinfo source are not redone. Also, some |
| variables do not take Texinfo code when generating particular formats, |
| but an argument that is already formatted. This is the case, for |
| example, for HTML for 'documentdescription'. |
| |
| |
| File: texinfo.info, Node: Customization Variables and Options, Next: HTML Customization Variables, Prev: Customization Variables for @-Commands, Up: Customization Variables |
| |
| 20.5.2 Customization Variables and Options |
| ------------------------------------------ |
| |
| The following table gives the customization variables associated with |
| some command line options. *Note Invoking texi2any::, for the meaning |
| of the options. |
| |
| Option Variable |
| -------------------------------------------------------------------------- |
| '--enable-encoding' 'ENABLE_ENCODING' |
| '--document-language' 'documentlanguage' |
| '--error-limit' 'ERROR_LIMIT' |
| '--fill-column' 'FILLCOLUMN' |
| '--footnote-style' 'footnotestyle' |
| '--force' 'FORCE' |
| '--internal-links' 'INTERNAL_LINKS' |
| '--macro-expand' 'MACRO_EXPAND' |
| '--headers' 'HEADERS', 'SHOW_MENU' |
| '--no-warn' 'NO_WARN' |
| '--no-validate' 'novalidate' |
| '--number-footnotes' 'NUMBER_FOOTNOTES' |
| '--number-sections' 'NUMBER_SECTIONS' |
| '--node-files' 'NODE_FILES' |
| '--output' 'OUT', 'OUTFILE', 'SUBDIR' |
| '--paragraph-indent' 'paragraphindent' |
| '--silent' 'SILENT' |
| '--split' 'SPLIT' |
| '--split-size' 'SPLIT_SIZE' |
| '--transliterate-file-names' 'TRANSLITERATE_FILE_NAMES' |
| '--verbose' 'VERBOSE' |
| |
| Setting such a customization variable to a value 'foo' is essentially |
| the same as specifying the '--OPT=foo' if the option takes an argument, |
| or '--OPT' if not. |
| |
| In addition, the customization variable 'TEXINFO_OUTPUT_FORMAT' |
| allows specifying what 'makeinfo' outputs, either one of the usual |
| output formats that can be specified with options, or various other |
| forms: |
| |
| 'docbook' |
| 'dvi' |
| 'dvipdf' |
| 'html' |
| 'info' |
| 'pdf' |
| 'plaintext' |
| 'ps' |
| 'xml' |
| These correspond to the command-line options (and |
| 'TEXINFO_OUTPUT_FORMAT' environment variable values) of the same |
| name. *Note Invoking texi2any::. |
| |
| 'debugcount' |
| Instead of generating a regular output format, output the count of |
| bytes and lines obtained when converting to Info, and other |
| information. |
| |
| 'debugtree' |
| Instead of generating a regular output format, output a text |
| representation of the tree obtained by parsing the input texinfo |
| document. |
| |
| 'parse' |
| Do only Texinfo source parsing; there is no output. |
| |
| 'plaintexinfo' |
| Output the Texinfo source with all the macros, '@include' and |
| '@value{}' expanded. This is similar to setting '--macro-expand', |
| but instead of being output in addition to the normal conversion, |
| output of Texinfo is the main output. |
| |
| 'rawtext' |
| Output raw text, with minimal formatting. For example, footnotes |
| are ignored and there is no paragraph filling. This is used by the |
| parser for file names and copyright text in HTML comments, for |
| example. |
| |
| 'structure' |
| Do only Texinfo source parsing and determination of the document |
| structure; there is no output. |
| |
| 'texinfosxml' |
| Output the document in TexinfoSXML representation, a syntax for |
| writing XML data using Lisp S-expressions. |
| |
| 'textcontent' |
| Output the text content only, stripped of commands; this is useful |
| for spell checking or word counting, for example. The trivial |
| 'detexinfo' script setting this is in the 'util' directory of the |
| Texinfo source as an example. It's one line: |
| |
| exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@" |
| |
| |
| File: texinfo.info, Node: HTML Customization Variables, Next: Other Customization Variables, Prev: Customization Variables and Options, Up: Customization Variables |
| |
| 20.5.3 HTML Customization Variables |
| ----------------------------------- |
| |
| This table gives the customization variables which apply to HTML output |
| only. A few other customization variable apply to both HTML and other |
| output formats; those are given in the next section. |
| |
| 'AVOID_MENU_REDUNDANCY' |
| For HTML. If set, and the menu entry and menu description are the |
| same, then do not print the menu description; default false. |
| |
| 'AFTER_BODY_OPEN' |
| For HTML. If set, the corresponding text will appear at the |
| beginning of each HTML file; default unset. |
| |
| 'AFTER_ABOUT' |
| For HTML, when an About-element is output. If set, the |
| corresponding text will appear at the end of the About element; |
| default unset. |
| |
| 'AFTER_OVERVIEW' |
| 'AFTER_TOC_LINES' |
| For HTML. If set, the corresponding text is output after the short |
| table of contents for 'AFTER_OVERVIEW' and after the table of |
| contents for 'AFTER_TOC_LINES'; otherwise, a default string is |
| used. At the time of writing, a '</div>' element is closed. |
| |
| In general, you should set 'BEFORE_OVERVIEW' if 'AFTER_OVERVIEW' is |
| set, and you should set 'BEFORE_TOC_LINES' if 'AFTER_TOC_LINES' is |
| set. |
| |
| 'BASEFILENAME_LENGTH' |
| For HTML. The maximum length of the base filenames; default 245. |
| Changing this would make cross-manual references to such long node |
| names invalid (*note HTML Xref Link Basics::). |
| |
| 'BEFORE_OVERVIEW' |
| 'BEFORE_TOC_LINES' |
| For HTML. If set, the corresponding text is output before the |
| short table of contents for 'BEFORE_OVERVIEW' and before the table |
| of contents for 'BEFORE_TOC_LINES', otherwise a default string is |
| used. At the time of writing, a '<div ...>' element is opened. |
| |
| In general you should set 'AFTER_OVERVIEW' if 'BEFORE_OVERVIEW' is |
| set, and you should set 'AFTER_TOC_LINES' if 'BEFORE_TOC_LINES' is |
| set. |
| |
| 'BIG_RULE' |
| For HTML. Rule used after and before the top element and before |
| special elements, but not for footers and headers; default '<hr>'. |
| |
| 'BODYTEXT' |
| For HTML, the text appearing in '<body>'. By default, sets the |
| HTML 'lang' attribute to the document language (*note |
| @documentlanguage::). |
| |
| 'CASE_INSENSITIVE_FILENAMES' |
| For HTML. Construct output file names as if the filesystem were |
| case insensitive (*note HTML Splitting::); default false. |
| |
| 'CHAPTER_HEADER_LEVEL' |
| For HTML. Header formatting level used for chapter level |
| sectioning commands; default '2'. |
| |
| 'CHECK_HTMLXREF' |
| For HTML. Check that manuals which are the target of external |
| cross-references (*note Four and Five Arguments::) are present in |
| 'htmlxref.cnf' (*note HTML Xref Configuration::); default false. |
| |
| 'COMPLEX_FORMAT_IN_TABLE' |
| For HTML. If set, use tables for indentation of complex formats; |
| default false. |
| |
| 'CSS_LINES' |
| For HTML. CSS output, automatically determined by default (*note |
| HTML CSS::). |
| |
| 'DATE_IN_HEADER' |
| For HTML. Put the document generation date in the header; off by |
| default. |
| |
| 'DEF_TABLE' |
| For HTML. If set, a '<table>' construction for '@deffn' and |
| similar @-commands is used (looking more like the TeX output), |
| instead of definition lists; default false. |
| |
| 'DEFAULT_RULE' |
| For HTML. Rule used between element, except before and after the |
| top element, and before special elements, and for footers and |
| headers; default '<hr>'. |
| |
| 'DO_ABOUT' |
| For HTML. If set to 0 never do an About special element; if set to |
| 1 always do an About special element; default 0. |
| |
| 'EXTERNAL_DIR' |
| For HTML. Base directory for external manuals; default none. It |
| is better to use the general external cross-reference mechanism |
| (*note HTML Xref Configuration::) than this variable. |
| |
| 'EXTRA_HEAD' |
| For HTML. Additional text appearing within '<head>'; default |
| unset. |
| |
| 'FOOTNOTE_END_HEADER_LEVEL' |
| For HTML. Header formatting level used for the footnotes header |
| with the 'end' footnotestyle; default '4'. *Note Footnote |
| Styles::. |
| |
| 'FOOTNOTE_SEPARATE_HEADER_LEVEL' |
| For HTML. Header formatting level used for the footnotes header |
| with the 'separate' footnotestyle; default '4'. *Note Footnote |
| Styles::. |
| |
| 'FRAMES' |
| For HTML. If set, a file describing the frame layout is generated, |
| together with a file with the short table of contents; default |
| false. |
| |
| 'FRAMESET_DOCTYPE' |
| For HTML. Same as DOCTYPE, but for the file containing the frame |
| description. |
| |
| 'HEADER_IN_TABLE' |
| For HTML. Use tables for header formatting rather than a simple |
| '<div>' element; default false. |
| |
| 'ICONS' |
| For HTML. Use icons for the navigation panel; default false. |
| |
| 'IMAGE_LINK_PREFIX' |
| For HTML. If set, the associated value is prepended to the image |
| file links; default unset. |
| |
| 'INLINE_CONTENTS' |
| For HTML. If set, output the contents where the '@contents' and |
| similar @-commands are located; default true. This is ignored if |
| '@set*contentsaftertitlepage' is set (*note Contents::). |
| |
| 'INLINE_CSS_STYLE' |
| For HTML. Put CSS directly in HTML elements rather than at the |
| beginning of the output; default false. |
| |
| 'KEEP_TOP_EXTERNAL_REF' |
| For HTML. If set, do not ignore 'Top' as the first argument for an |
| external ref to a manual, as is done by default. *Note Referring |
| to a Manual as a Whole::. |
| |
| 'L2H' |
| For HTML. If set, 'latex2html' is used to convert '@math' and |
| '@tex' sections; default false. Best used with '--iftex'. |
| |
| 'L2H_CLEAN' |
| (Relevant only if 'L2H' is set.) If set, the intermediate files |
| generated in relation with 'latex2html' are removed; default true. |
| |
| 'L2H_FILE' |
| (Relevant only if 'L2H' is set.) If set, the given file is used as |
| 'latex2html''s init file; default unset. |
| |
| 'L2H_HTML_VERSION' |
| (Relevant only if 'L2H' is set.) The HTML version used in the |
| 'latex2html' call; default unset. |
| |
| 'L2H_L2H' |
| (Relevant only if 'L2H' is set.) The program invoked as |
| 'latex2html'; default is 'latex2html'. |
| |
| 'L2H_SKIP' |
| (Relevant only if 'L2H' is set.) If set to a true value, the |
| actual call to 'latex2html' is skipped; previously generated |
| content is reused instead. If set to 0, the cache is not used at |
| all. If set to 'undef', the cache is used for as many TeX |
| fragments as possible and for any remaining the command is run. |
| The default is 'undef'. |
| |
| 'L2H_TMP' |
| (Relevant only if 'L2H' is set.) Set the directory used for |
| temporary files. None of the file name components in this |
| directory name may start with '.'; otherwise, 'latex2html' will |
| fail (because of 'dvips'). The default is the empty string, which |
| means the current directory. |
| |
| 'MAX_HEADER_LEVEL' |
| For HTML. Maximum header formatting level used (higher header |
| formatting level numbers correspond to lower sectioning levels); |
| default '4'. |
| |
| 'MENU_SYMBOL' |
| For HTML. Symbol used in front of menu entries when node names are |
| used for menu entries formatting; default '•'. |
| |
| 'MONOLITHIC' |
| For HTML. Output only one file including the table of contents. |
| Set by default, but only relevant when the output is not split. |
| |
| 'NO_CSS' |
| For HTML. Do not use CSS; default false. *Note HTML CSS::. |
| |
| 'NODE_FILE_EXTENSION' |
| For HTML. Extension for node files if 'NODE_FILENAMES' is set; |
| default 'html'. |
| |
| 'PRE_ABOUT' |
| For HTML, when an About element is output. If set to a text |
| string, this text will appear at the beginning of the About |
| element. If set to a reference on a subroutine, the result of the |
| subroutine call will appear at the beginning of the About element. |
| If not set (the default), default text is used. |
| |
| 'PRE_BODY_CLOSE' |
| For HTML. If set, the given text will appear at the footer of each |
| HTML file; default unset. |
| |
| 'PROGRAM_NAME_IN_FOOTER' |
| For HTML. If set, output the program name and miscellaneous |
| related information in the page footers; default false. |
| |
| 'SHORTEXTN' |
| For HTML. If set, use '.htm' as extension; default false. |
| |
| 'SHOW_TITLE' |
| For HTML. If set, output the title at the beginning of the |
| document; default true. |
| |
| 'SIMPLE_MENU' |
| For HTML. If set, use a simple preformatted style for the menu, |
| instead of breaking down the different parts of the menu; default |
| false. *Note Menu Parts::. |
| |
| 'TOC_LINKS' |
| For HTML. If set, links from headings to toc entries are created; |
| default false. |
| |
| 'TOP_FILE' |
| This file name may be used for the top-level file. The extension |
| is set appropriately, if necessary. This is used to override the |
| default, and is, in general, only taken into account when output is |
| split, and for HTML. |
| |
| 'TOP_NODE_FILE' |
| For HTML. File name used for the Top node, if 'NODE_FILENAMES' is |
| set; default is 'index'. |
| |
| 'TOP_NODE_FILE_TARGET' |
| For HTML. File name used for the Top node in cross-references; |
| default is 'index'. |
| |
| 'TOP_NODE_UP_URL' |
| For HTML. A url used for '(dir)' references; the default is |
| 'undef', meaning that the normal rules apply, typically leading to |
| a link to 'dir.html' from an implicit or explicit reference to |
| '(dir)' (*note HTML Xref::). For more about the Top node pointers, |
| *note First Node::. For overriding the Up pointer in other |
| formats, see 'TOP_NODE_UP' in *note Other Customization |
| Variables::. |
| |
| 'USE_ACCESSKEY' |
| For HTML. Use 'accesskey' in cross-references; default true. |
| |
| 'USE_ISO' |
| For HTML. Use entities for doubled single-quote characters (*note |
| Inserting Quotation Marks::), and '---' and '--' (*note |
| Conventions::); default true. |
| |
| 'USE_LINKS' |
| For HTML. Generate '<link>' elements in the HTML '<head>' output; |
| default true. |
| |
| 'USE_REL_REV' |
| For HTML. Use 'rel' in cross-references; default true. |
| |
| 'VERTICAL_HEAD_NAVIGATION' |
| For HTML. If set, a vertical navigation panel is used; default |
| false. |
| |
| 'WORDS_IN_PAGE' |
| For HTML, with output split at nodes. Specifies the approximate |
| minimum page length at which a navigation panel is placed at the |
| bottom of a page. To avoid ever having the navigation buttons at |
| the bottom of a page, set this to a sufficiently large number. The |
| default is 300. |
| |
| 'XREF_USE_FLOAT_LABEL' |
| For HTML. If set, for the float name in cross-references, use the |
| float label instead of the type followed by the float number (*note |
| @float::). The default is off. |
| |
| 'XREF_USE_NODE_NAME_ARG' |
| For HTML. Only relevant for cross-reference commands with no cross |
| reference name (second argument). If set to 1, use the node name |
| (first) argument in cross-reference @-commands for the text |
| displayed as the hyperlink. If set to 0, use the node name if |
| 'USE_NODES' is set, otherwise the section name. If set to 'undef', |
| use the first argument in preformatted environments, otherwise use |
| the node name or section name depending on 'USE_NODES'. The |
| default is 'undef'. |
| |
| |
| File: texinfo.info, Node: Other Customization Variables, Prev: HTML Customization Variables, Up: Customization Variables |
| |
| 20.5.4 Other Customization Variables |
| ------------------------------------ |
| |
| This table gives the remaining customization variables, which apply to |
| multiple formats, or affect global behavior, or otherwise don't fit into |
| the categories of the previous sections. |
| |
| 'CLOSE_QUOTE_SYMBOL' |
| When a closing quote is needed, use this character; default |
| '’' in HTML, '’' in Docbook. The default for Info is |
| the same as 'OPEN_QUOTE_SYMBOL' (see below). |
| |
| 'CPP_LINE_DIRECTIVES' |
| Recognize '#line' directives in a "preprocessing" pass (*note |
| External Macro Processors::); on by default. |
| |
| 'DEBUG' |
| If set, debugging output is generated; default is off (zero). |
| |
| 'DOCTYPE' |
| For Docbook, HTML, XML. Specifies the 'SystemLiteral', the |
| entity's system identifier. This is a URI which may be used to |
| retrieve the entity, and identifies the canonical DTD for the |
| document. The default value is different for each of HTML, Docbook |
| and Texinfo XML. |
| |
| 'DUMP_TEXI' |
| For debugging. If set, no conversion is done, only parsing and |
| macro expansion. If the option '--macro-expand' is set, the |
| Texinfo source is also expanded to the corresponding file. Default |
| false. |
| |
| 'DUMP_TREE' |
| For debugging. If set, the tree constructed upon parsing a Texinfo |
| document is output to standard error; default false. |
| |
| 'ENABLE_ENCODING_USE_ENTITY' |
| For HTML, XML. If '--enable-encoding' is set, and there is an |
| entity corresponding with the letter or the symbol being output, |
| prefer the entity. Set by default for HTML, but not XML. |
| |
| 'EXTERNAL_CROSSREF_SPLIT' |
| For cross-references to other manuals, this determines if the other |
| manual is considered to be split or monolithic. By default, it is |
| set based on the value of 'SPLIT'. *Note HTML Xref::, and *note |
| HTML Xref Configuration::. |
| |
| 'EXTENSION' |
| The extension added to the output file name. The default is |
| different for each output format. |
| |
| 'FIX_TEXINFO' |
| For "plain Texinfo" (see the 'PLAINTEXINFO' item). If set to |
| false, the resulting Texinfo does not have all errors corrected, |
| such as missing '@end'; default true. This variable is only |
| relevant when expanding Texinfo; other converters always try to |
| output something sane even if the input is erroneous. |
| |
| 'IGNORE_BEFORE_SETFILENAME' |
| If set, begin outputting at '@setfilename', if '@setfilename' is |
| present; default true. |
| |
| 'IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME' |
| If set, spaces are ignored after an @-command that takes braces. |
| Default true, matching the TeX behavior. |
| |
| 'INDEX_ENTRY_COLON' |
| Symbol used between the index entry and the associated node or |
| section; default ':'. |
| |
| 'INDEX_SPECIAL_CHARS_WARNING' |
| If set, warn about ':' in index entry, as it leads to invalid |
| entries in index menus in output Info files. For Info and |
| plaintext only. |
| |
| 'INFO_SPECIAL_CHARS_QUOTE' |
| If set, whenever there are problematic characters for Info output |
| in places such as node names or menu items, surround the part of |
| the construct where they appear with quoting characters, as |
| described in *note Info Format Specification::. *Note Node Line |
| Requirements::. |
| |
| 'INFO_SPECIAL_CHARS_WARNING' |
| If set, warn about problematic constructs for Info output (such as |
| the string '::') in node names, menu items, and cross-references; |
| default true. Do not warn about index entries, since parsing |
| problems there don't prevent navigation; readers can still |
| relatively easily find their way to the node in question. |
| |
| 'INLINE_INSERTCOPYING' |
| If set, '@insertcopying' is replaced by the '@copying' content |
| (*note @copying::) as if '@insertcopying' were a user-defined |
| macro; default false. |
| |
| 'INPUT_ENCODING_NAME' |
| Normalized encoding name suitable for output. Should be a usable |
| charset name in HTML, typically one of the preferred IANA encoding |
| names. You should not need to use this variable, since it is set |
| by '@documentencoding' (*note @documentencoding::). |
| |
| 'INPUT_PERL_ENCODING' |
| Perl encoding used to process the Texinfo source. You should not |
| need to use that variable, since it is set by '@documentencoding' |
| (*note @documentencoding::). |
| |
| 'MACRO_BODY_IGNORES_LEADING_SPACE' |
| Ignore white space at the beginning of user defined macro body |
| line, mimicking a TeX limitation (*note Macro Details::). Default |
| off. |
| |
| 'MAX_MACRO_CALL_NESTING' |
| The maximal number of recursive calls of @-commands defined through |
| '@rmacro'; default 100000. The purpose of this variable is to |
| avoid infinite recursions. |
| |
| 'MENU_ENTRY_COLON' |
| Symbol used between the menu entry and the description; default |
| ':'. |
| |
| 'NO_USE_SETFILENAME' |
| If set, do not use '@setfilename' to set the document name; |
| instead, base the output document name only on the input file name. |
| The default is false. |
| |
| 'NODE_FILENAMES' |
| If set, node names are used to construct file names. By default, |
| it is set if the output is split by node, or if 'NODE_FILES' is set |
| and the output is split in any way. |
| |
| 'NODE_NAME_IN_INDEX' |
| If set, use node names in index entries, otherwise prefer section |
| names; default true. |
| |
| 'NODE_NAME_IN_MENU' |
| If set, use node names in menu entries, otherwise prefer section |
| names; default true. |
| |
| 'OPEN_QUOTE_SYMBOL' |
| When an opening quote is needed, e.g., for '@samp' output, use the |
| specified character; default '‘' for HTML, '‘' for |
| Docbook. For Info, the default depends on the enabled document |
| encoding (*note @documentencoding::); if no document encoding is |
| set, or the encoding is US-ASCII, etc., ''' is used. This |
| character usually appears as an undirected single quote on modern |
| systems. If the document encoding is Unicode, the Info output uses |
| a Unicode left quote. |
| |
| 'OUTPUT_ENCODING_NAME' |
| Normalized encoding name used for output files. Should be a usable |
| charset name in HTML, typically one of the preferred IANA encoding |
| names. By default, if an input encoding is set (typically through |
| '@documentencoding' or 'INPUT_ENCODING_NAME'), this information is |
| used to set the output encoding name. If no input encoding is |
| specified, the default output encoding name may be set by the |
| output format. In particular, the XML-based formats use 'utf-8' |
| for 'OUTPUT_ENCODING_NAME' if the encoding is not otherwise |
| specified. *Note @documentencoding::. |
| |
| 'OVERVIEW_LINK_TO_TOC' |
| If set, the cross-references in the Overview link to the |
| corresponding Table of Contents entries; default true. |
| |
| 'PACKAGE' |
| 'PACKAGE_VERSION' |
| 'PACKAGE_AND_VERSION' |
| 'PACKAGE_URL' |
| 'PACKAGE_NAME' |
| The implementation's short package name, package version, package |
| name and version concatenated, package url, and full package name, |
| respectively. By default, these variables are all set through |
| Autoconf, Automake, and 'configure'. |
| |
| 'PREFIX' |
| The output file prefix, which is prepended to some output file |
| names. By default it is set by '@setfilename' or from the input |
| file (*note @setfilename::). How this value is used depends on the |
| value of other customization variables or command line options, |
| such as whether the output is split and 'NODE_FILENAMES'. The |
| default is unset. |
| |
| 'PROGRAM' |
| Name of the program used. By default, it is set to the name of the |
| program launched, with a trailing '.pl' removed. |
| |
| 'RENAMED_NODES_FILE' |
| If set, use the value for the renamed nodes description file. If |
| not set, the file is 'DOC_BASENAME-noderename.cnf'. *Note HTML |
| Xref Link Preservation::. |
| |
| 'RENAMED_NODES_REDIRECTIONS' |
| If set, create redirection files for renamed nodes. Set by default |
| when generating HTML. |
| |
| 'SHOW_MENU' |
| If set, Texinfo menus are output. By default, it is set unless |
| generating Docbook or if '--no-headers' is specified. |
| |
| 'SORT_ELEMENT_COUNT' |
| If set, the name of a file to which a list of elements (nodes or |
| sections, depending on the output format) is dumped, sorted by the |
| number of lines they contain after removal of @-commands; default |
| unset. This is used by the program 'texi-elements-by-size' in the |
| 'util/' directory of the Texinfo source distribution (*note |
| texi-elements-by-size::). |
| |
| 'SORT_ELEMENT_COUNT_WORDS' |
| When dumping the elements-by-size file (see preceding item), use |
| word counts instead of line counts; default false. |
| |
| 'TEST' |
| If set to true, some variables which are normally dynamically |
| generated anew for each run (date, program name, version) are set |
| to fixed and given values. This is useful to compare the output to |
| a reference file, as is done for the tests. The default is false. |
| |
| 'TEXI2DVI' |
| Name of the command used to produce PostScript, PDF, and DVI; |
| default 'texi2dvi'. *Note texi2any Printed Output::. |
| |
| 'TEXI2HTML' |
| Generate HTML and try to be as compatible as possible with |
| 'texi2html'; default false. |
| |
| 'TEXINFO_COLUMN_FOR_DESCRIPTION' |
| Used with the 'indent_menu_descriptions' tree transformation, |
| described below; default 32 (matching |
| 'texinfo-column-for-description' in Emacs)). |
| |
| 'TEXINFO_DTD_VERSION' |
| For XML. Version of the DTD used in the XML output preamble. The |
| default is set based on a variable in 'configure.ac'. |
| |
| 'TEXTCONTENT_COMMENT' |
| For stripped text content output (i.e., when |
| 'TEXINFO_OUTPUT_FORMAT' is set to 'textcontent'). If set, also |
| output comments. Default false. |
| |
| 'TOP_NODE_UP' |
| Up node for the Top node; default '(dir)'. For overriding the url |
| in HTML output, see 'TOP_NODE_UP_URL' in *note HTML Customization |
| Variables::. |
| |
| 'TREE_TRANSFORMATIONS' |
| The associated value is a comma separated list of transformations |
| that can be applied to the Texinfo tree prior to outputting the |
| result. If more than one is specified, the ordering is irrelevant; |
| each is always applied at the necessary point during processing. |
| |
| The only one executed by default is |
| 'move_index_entries_after_items' for HTML and Docbook output. |
| Here's an example of updating the master menu in a document: |
| |
| makeinfo \ |
| -c TREE_TRANSFORMATIONS=regenerate_master_menu \ |
| -c PLAINTEXINFO=1 \ |
| mydoc.texi \ |
| -o /tmp/out |
| |
| (Caveat: Since 'PLAINTEXINFO' output does expand Texinfo macros and |
| conditionals, it's necessary to remove any such differences before |
| installing the updates in the original document. This will be |
| remedied in a future release.) |
| |
| The following transformations are currently supported (many are |
| used in the 'pod2texi' utility distributed with Texinfo; *note |
| Invoking pod2texi::): |
| |
| 'complete_tree_nodes_menus' |
| Add menu entries or whole menus for nodes associated with |
| sections of any level, based on the sectioning tree. |
| |
| 'fill_gaps_in_sectioning' |
| Adds empty '@unnumbered...' sections in a tree to fill gaps in |
| sectioning. For example, an '@unnumberedsec' will be inserted |
| if a '@chapter' is followed by a '@subsection'. |
| |
| 'indent_menu_descriptions' |
| Reformat menus so that descriptions start at column |
| 'TEXINFO_COLUMN_DESCRIPTION'. |
| |
| 'insert_nodes_for_sectioning_commands' |
| Insert nodes for sectioning commands lacking a corresponding |
| node. |
| |
| 'move_index_entries_after_items' |
| In '@enumerate' and '@itemize', move index entries appearing |
| just before an '@item' to just after the '@item'. Comment |
| lines between index entries are moved too. As mentioned, this |
| is always done for HTML and Docbook output. |
| |
| 'regenerate_master_menu' |
| Update the Top node master menu, either replacing the (first) |
| '@detailmenu' in the Top node menu, or creating it at the end |
| of the Top node menu. |
| |
| 'simple_menu' |
| Mostly the same as 'SIMPLE_MENU': use a simple preformatted |
| style for the menu. It differs from setting 'SIMPLE_MENU' in |
| that 'SIMPLE_MENU' only has an effect in HTML output. |
| |
| 'USE_NODES' |
| Preferentially use nodes to decide where elements are separated. |
| If set to false, preferentially use sectioning to decide where |
| elements are separated. The default is true. |
| |
| 'USE_NODE_TARGET' |
| If set, use the node associated with a section for the section |
| target in cross-references; default true. |
| |
| 'USE_NUMERIC_ENTITY' |
| For HTML and XML. If set, use numeric entities instead of ASCII |
| characters when there is no named entity. By default, set to true |
| for HTML. |
| |
| 'USE_UP_NODE_FOR_ELEMENT_UP' |
| Fill in up sectioning direction with node direction when there is |
| no sectioning up direction. In practice this can only happen when |
| there is no @top section. Not set by default. |
| |
| 'USE_SETFILENAME_EXTENSION' |
| Default is on for Info, off for other output. If set, use exactly |
| what '@setfilename' gives for the output file name, including the |
| extension. You should not need to explicitly set this variable. |
| |
| 'USE_TITLEPAGE_FOR_TITLE' |
| Use the full '@titlepage' as the title, not a simple title string; |
| default false. |
| |
| 'USE_UNIDECODE' |
| If set to false, do not use the 'Text::Unidecode' Perl module to |
| transliterate more characters; default true. |
| |
| |
| File: texinfo.info, Node: Internationalization of Document Strings, Next: Invoking pod2texi, Prev: Customization Variables, Up: Generic Translator texi2any |
| |
| 20.6 Internationalization of Document Strings |
| ============================================= |
| |
| 'texi2any' writes fixed strings into the output document at various |
| places: cross-references, page footers, the help page, alternate text |
| for images, and so on. The string chosen depends on the value of the |
| 'documentlanguage' at the time of the string being output (*note |
| @documentlanguage::, for the Texinfo command interface). |
| |
| The Gettext framework is used for those strings (*note |
| (gettext)Top::). The 'libintl-perl' package is used as the 'gettext' |
| implementation; more specifically, the pure Perl implementation is used, |
| so Texinfo can support consistent behavior across all platforms and |
| installations, which would not otherwise be possible. 'libintl-perl' is |
| included in the Texinfo distribution and always installed, to ensure |
| that it is available if needed. It is also possible to use the system |
| 'gettext' (the choice can be made at build-time). |
| |
| The Gettext domain 'texinfo_document' is used for the strings. |
| Translated strings are written as Texinfo, and may include @-commands. |
| In translated strings, the varying parts of the string are not usually |
| denoted by '%s' and the like, but by '{arg_name}'. (This convention is |
| common for 'gettext' in Perl and is fully supported in GNU Gettext; |
| *note Perl Format Strings: (gettext)perl-format.) For example, in the |
| following, '{section}' will be replaced by the section name: |
| |
| see {section} |
| |
| These Perl-style brace format strings are used for two reasons: |
| first, changing the order of 'printf' arguments is only available since |
| Perl 5.8.0; second, and more importantly, the order of arguments is |
| unpredictable, since @-command expansion may lead to different orders |
| depending on the output format. |
| |
| The expansion of a translation string is done like this: |
| |
| 1. First, the string is translated. The locale is |
| @DOCUMENTLANGUAGE'.'@DOCUMENTENCODING. |
| |
| If the @DOCUMENTLANGUAGE has the form 'll_CC', that is tried first, |
| and then just 'll'. If that does not exist, and the encoding is |
| not 'us-ascii', then 'us-ascii' is tried. |
| |
| The idea is that if there is a 'us-ascii' encoding, it means that |
| all the characters in the charset may be expressed as @-commands. |
| For example, there is a 'fr.us-ascii' locale that can accommodate |
| any encoding, since all the Latin 1 characters have associated |
| @-commands. On the other hand, Japanese has only a translation |
| 'ja.utf-8', since there are no @-commands for Japanese characters. |
| |
| 2. Next, the string is expanded as Texinfo, and converted. The |
| arguments are substituted; for example, '{arg_name}' is replaced by |
| the corresponding actual argument. |
| |
| In the following example, '{date}', '{program_homepage}' and |
| '{program}' are the arguments of the string. Since they are used in |
| '@uref', their order is not predictable. '{date}', '{program_homepage}' |
| and '{program}' are substituted after the expansion: |
| |
| Generated on @emph{{date}} using |
| @uref{{program_homepage}, @emph{{program}}}. |
| |
| This approach is admittedly a bit complicated. Its usefulness is |
| that it supports having translations available in different encodings |
| for encodings which can be covered by @-commands, and also specifying |
| how the formatting for some commands is done, independently of the |
| output format--yet still be language-dependent. For example, the |
| '@pxref' translation string can be like this: |
| |
| see {node_file_href} section `{section}\' in @cite{{book}} |
| |
| which allows for specifying a string independently of the output format, |
| while nevertheless with rich formatting it may be translated |
| appropriately in many languages. |
| |
| |
| File: texinfo.info, Node: Invoking pod2texi, Next: texi2html, Prev: Internationalization of Document Strings, Up: Generic Translator texi2any |
| |
| 20.7 Invoking 'pod2texi': Convert POD to Texinfo |
| ================================================ |
| |
| The 'pod2texi' program translates Perl pod documentation file(s) to |
| Texinfo. There are two basic modes of operation: generating a |
| standalone manual from each input pod, or (if '--base-level=1' or higher |
| is given) generating Texinfo subfiles suitable for use with '@include'. |
| |
| Although ordinarily this documentation in the Texinfo manual would be |
| the best place to look, in this case we have documented all the options |
| and examples in the 'pod2texi' program itself, since it may be useful |
| outside of the rest of Texinfo. Thus, please see the output of |
| 'pod2texi --help', the version on the web at |
| <http://www.gnu.org/software/texinfo/manual/pod2texi.html>, etc. |
| |
| For an example of using 'pod2texi' to make Texinfo out of the Perl |
| documentation itself, see 'contrib/perldoc-all' |
| (http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo) |
| in the Texinfo source distribution (the output is available at |
| <http://www.gnu.org/software/perl/manual>). |
| |
| |
| File: texinfo.info, Node: texi2html, Prev: Invoking pod2texi, Up: Generic Translator texi2any |
| |
| 20.8 'texi2html': Ancestor of 'texi2any' |
| ======================================== |
| |
| Conceptually, the 'texi2html' program is the parent of today's |
| 'texi2any' program. 'texi2html' was developed independently, originally |
| by Lionel Cons in 1998; at the time, 'makeinfo' could not generate HTML. |
| Many other people contributed to 'texi2html' over the years. |
| |
| The present 'texi2any' uses little of the actual code of 'texi2html', |
| and has quite a different basic approach to the implementation (namely, |
| parsing the Texinfo document into a tree), but still, there is a family |
| resemblance. |
| |
| By design, 'texi2any' supports nearly all the features of 'texi2html' |
| in some way. However, we did not attempt to maintain strict |
| compatibility, so no 'texi2html' executable is installed by the Texinfo |
| package. An approximation can be run with an invocation like this |
| (available as 'util/texi2html' in the Texinfo source): |
| |
| texi2any --set-customization-variable TEXI2HTML=1 ... |
| |
| but, to emphasize, this is _not_ a drop-in replacement for the previous |
| 'texi2html'. Here are the biggest differences: |
| |
| * Most blatantly, the command line options of 'texi2html' are now |
| customization variables, for the most part. A table of approximate |
| equivalents is given below. |
| |
| * The program-level customization API is very different in |
| 'texi2any'. |
| |
| * Indices cannot be split. |
| |
| * Translated strings cannot be customized; we hope to introduce this |
| feature in 'texi2any' in the future. |
| |
| Aside from the last, we do not intend to reimplement these |
| differences. Therefore, the route forward for authors is alter manuals |
| and build processes as necessary to use the new features and methods of |
| 'texi2any'. The 'texi2html' maintainers (one of whom is the principal |
| author of 'texi2any') do not intend to make further releases. |
| |
| Here is the table showing 'texi2html' options and corresponding |
| 'texi2any' customization variables. |
| |
| '--toc-links' 'TOC_LINKS' |
| '--short-ext' 'SHORTEXTN' |
| '--prefix' 'PREFIX' |
| '--short-ref' 'SHORT_REF' |
| '--idx-sum' 'IDX_SUMMARY' |
| '--def-table' 'DEF_TABLE' |
| '--ignore-preamble-text' 'IGNORE_PREAMBLE_TEXT' |
| '--html-xref-prefix' 'EXTERNAL_DIR' |
| '--l2h' 'L2H' |
| '--l2h-l2h' 'L2H_L2H' |
| '--l2h-skip' 'L2H_SKIP' |
| '--l2h-tmp' 'L2H_TMP' |
| '--l2h-file' 'L2H_FILE' |
| '--l2h-clean' 'L2H_CLEAN' |
| '--use-nodes' 'USE_NODES' |
| '--monolithic' 'MONOLITHIC' |
| '--top-file' 'TOP_FILE' |
| '--toc-file' 'TOC_FILE' |
| '--frames' 'FRAMES' |
| '--menu' 'SHOW_MENU' |
| '--debug' 'DEBUG' |
| '--doctype' 'DOCTYPE' |
| '--frameset-doctype' 'FRAMESET_DOCTYPE' |
| '--test' 'TEST' |
| |
| Finally, any 'texi2html' users seeking more detailed information can |
| check the draft file 'doc/texi2oldapi.texi' in the Texinfo source |
| repository. It consists mainly of very rough notes, but may still be |
| useful to some. |
| |
| |
| File: texinfo.info, Node: Creating and Installing Info Files, Next: Generating HTML, Prev: Generic Translator texi2any, Up: Top |
| |
| 21 Creating and Installing Info Files |
| ************************************* |
| |
| This chapter describes how to create and install Info files. *Note Info |
| Files::, for general information about the file format itself. |
| |
| * Menu: |
| |
| * Creating an Info File:: |
| * Installing an Info File:: |
| |
| |
| File: texinfo.info, Node: Creating an Info File, Next: Installing an Info File, Up: Creating and Installing Info Files |
| |
| 21.1 Creating an Info File |
| ========================== |
| |
| 'makeinfo' is a program that converts a Texinfo file into an Info file, |
| HTML file, or plain text. 'texinfo-format-region' and |
| 'texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to |
| Info. |
| |
| For information on installing the Info file in the Info system, *note |
| Installing an Info File::. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: texinfo.info, Node: makeinfo Advantages, Next: makeinfo in Emacs, Up: Creating an Info File |
| |
| 21.1.1 'makeinfo' Advantages |
| ---------------------------- |
| |
| The 'makeinfo' utility creates an Info file from a Texinfo source |
| providing better error messages than either of the Emacs formatting |
| commands. We recommend it. The 'makeinfo' program is independent of |
| Emacs. You can run 'makeinfo' in any of three ways: from an operating |
| system shell, from a shell inside Emacs, or by typing the 'C-c C-m C-r' |
| or the 'C-c C-m C-b' command in Texinfo mode in Emacs. |
| |
| The 'texinfo-format-region' and the 'texinfo-format-buffer' commands |
| may be useful if you cannot run 'makeinfo'. |
| |
| |
| File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: makeinfo Advantages, Up: Creating an Info File |
| |
| 21.1.2 Running 'makeinfo' Within Emacs |
| -------------------------------------- |
| |
| You can run 'makeinfo' in GNU Emacs Texinfo mode by using either the |
| 'makeinfo-region' or the 'makeinfo-buffer' commands. In Texinfo mode, |
| the commands are bound to 'C-c C-m C-r' and 'C-c C-m C-b' by default. |
| |
| 'C-c C-m C-r' |
| 'M-x makeinfo-region' |
| Format the current region for Info. |
| |
| 'C-c C-m C-b' |
| 'M-x makeinfo-buffer' |
| Format the current buffer for Info. |
| |
| When you invoke 'makeinfo-region' the output goes to a temporary |
| buffer. When you invoke 'makeinfo-buffer' output goes to the file set |
| with '@setfilename' (*note @setfilename::). |
| |
| The Emacs 'makeinfo-region' and 'makeinfo-buffer' commands run the |
| 'makeinfo' program in a temporary shell buffer. If 'makeinfo' finds any |
| errors, Emacs displays the error messages in the temporary buffer. |
| |
| You can parse the error messages by typing 'C-x `' ('next-error'). |
| This causes Emacs to go to and position the cursor on the line in the |
| Texinfo source that 'makeinfo' thinks caused the error. *Note Running |
| 'make' or Compilers Generally: (emacs)Compilation, for more information |
| about using the 'next-error' command. |
| |
| In addition, you can kill the shell in which the 'makeinfo' command |
| is running or make the shell buffer display its most recent output. |
| |
| 'C-c C-m C-k' |
| 'M-x makeinfo-kill-job' |
| Kill the current running 'makeinfo' job (from 'makeinfo-region' or |
| 'makeinfo-buffer'). |
| |
| 'C-c C-m C-l' |
| 'M-x makeinfo-recenter-output-buffer' |
| Redisplay the 'makeinfo' shell buffer to display its most recent |
| output. |
| |
| (Note that the parallel commands for killing and recentering a TeX job |
| are 'C-c C-t C-k' and 'C-c C-t C-l'. *Note Texinfo Mode Printing::.) |
| |
| You can specify options for 'makeinfo' by setting the |
| 'makeinfo-options' variable with either the 'M-x customize' or the 'M-x |
| set-variable' command, or by setting the variable in your '.emacs' |
| initialization file. |
| |
| For example, you could write the following in your '.emacs' file: |
| |
| (setq makeinfo-options |
| "--paragraph-indent=0 --no-split |
| --fill-column=70 --verbose") |
| |
| For more information, see |
| *note Easy Customization Interface: (emacs)Easy Customization, |
| *note Examining and Setting Variables: (emacs)Examining, |
| *note (emacs)Init File::, and |
| *note makeinfo Options::. |
| |
| |
| File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Creating an Info File |
| |
| 21.1.3 The 'texinfo-format...' Commands |
| --------------------------------------- |
| |
| In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo |
| file with the 'texinfo-format-region' command. This formats the current |
| region and displays the formatted text in a temporary buffer called |
| '*Info Region*'. |
| |
| Similarly, you can format a buffer with the 'texinfo-format-buffer' |
| command. This command creates a new buffer and generates the Info file |
| in it. Typing 'C-x C-s' will save the Info file under the name |
| specified by the '@setfilename' line which must be near the beginning of |
| the Texinfo file. |
| |
| 'C-c C-e C-r' |
| 'texinfo-format-region' |
| Format the current region for Info. |
| |
| 'C-c C-e C-b' |
| 'texinfo-format-buffer' |
| Format the current buffer for Info. |
| |
| The 'texinfo-format-region' and 'texinfo-format-buffer' commands |
| provide you with some error checking, and other functions can provide |
| you with further help in finding formatting errors. These procedures |
| are described in an appendix; see *note Catching Mistakes::. However, |
| the 'makeinfo' program provides better error checking (*note makeinfo in |
| Emacs::). |
| |
| A peculiarity of the 'texinfo-format-buffer' and |
| 'texinfo-format-region' commands is that they do not indent (nor fill) |
| paragraphs that contain '@w' or '@*' commands. |
| |
| |
| File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Creating an Info File |
| |
| 21.1.4 Batch Formatting |
| ----------------------- |
| |
| You can format Texinfo files for Info using 'batch-texinfo-format' and |
| Emacs batch mode. You can run Emacs in batch mode from any shell, |
| including a shell inside of Emacs. (*Note (emacs)Initial Options::.) |
| |
| Here is a shell command to format all the files that end in |
| '.texinfo' in the current directory: |
| |
| emacs -batch -funcall batch-texinfo-format *.texinfo |
| |
| Emacs processes all the files listed on the command line, even if an |
| error occurs while attempting to format some of them. |
| |
| Run 'batch-texinfo-format' only with Emacs in batch mode as shown; it |
| is not interactive. It kills the batch mode Emacs on completion. |
| |
| 'batch-texinfo-format' is convenient if you lack 'makeinfo' and want |
| to format several Texinfo files at once. When you use Batch mode, you |
| create a new Emacs process. This frees your current Emacs, so you can |
| continue working in it. (When you run 'texinfo-format-region' or |
| 'texinfo-format-buffer', you cannot use that Emacs for anything else |
| until the command finishes.) |
| |
| |
| File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Creating an Info File |
| |
| 21.1.5 Tag Files and Split Files |
| -------------------------------- |
| |
| If a Texinfo file has more than 30,000 bytes, 'texinfo-format-buffer' |
| automatically creates a tag table for its Info file; 'makeinfo' always |
| creates a tag table. With a "tag table", Info can jump to new nodes |
| more quickly than it can otherwise. |
| |
| In addition, if the Texinfo file contains more than about 300,000 |
| bytes, 'texinfo-format-buffer' and 'makeinfo' split the large Info file |
| into shorter "indirect" subfiles of about 300,000 bytes each. Big files |
| are split into smaller files so that Emacs does not need to make a large |
| buffer to hold the whole of a large Info file; instead, Emacs allocates |
| just enough memory for the small, split-off file that is needed at the |
| time. This way, Emacs avoids wasting memory when you run Info. (Before |
| splitting was implemented, Info files were always kept short and |
| "include files" were designed as a way to create a single, large printed |
| manual out of the smaller Info files. *Note Include Files::, for more |
| information. Include files are still used for very large documents, |
| such as 'The Emacs Lisp Reference Manual', in which each chapter is a |
| separate file.) |
| |
| When a file is split, Info itself makes use of a shortened version of |
| the original file that contains just the tag table and references to the |
| files that were split off. The split-off files are called "indirect" |
| files. |
| |
| The split-off files have names that are created by appending '-1', |
| '-2', '-3' and so on to the file name specified by the '@setfilename' |
| command. The shortened version of the original file continues to have |
| the name specified by '@setfilename'. |
| |
| At one stage in writing this document, for example, the Info file was |
| saved as the file 'test-texinfo' and that file looked like this: |
| |
| Info file: test-texinfo, -*-Text-*- |
| produced by texinfo-format-buffer |
| from file: new-texinfo-manual.texinfo |
| |
| ^_ |
| Indirect: |
| test-texinfo-1: 102 |
| test-texinfo-2: 50422 |
| test-texinfo-3: 101300 |
| ^_^L |
| Tag table: |
| (Indirect) |
| Node: overview^?104 |
| Node: info file^?1271 |
| Node: printed manual^?4853 |
| Node: conventions^?6855 |
| ... |
| |
| (But 'test-texinfo' had far more nodes than are shown here.) Each of |
| the split-off, indirect files, 'test-texinfo-1', 'test-texinfo-2', and |
| 'test-texinfo-3', is listed in this file after the line that says |
| 'Indirect:'. The tag table is listed after the line that says 'Tag |
| table:'. |
| |
| In the list of indirect files, the number following the file name |
| records the cumulative number of bytes in the preceding indirect files, |
| not counting the file list itself, the tag table, or any permissions |
| text in the first file. In the tag table, the number following the node |
| name records the location of the beginning of the node, in bytes from |
| the beginning of the (unsplit) output. |
| |
| If you are using 'texinfo-format-buffer' to create Info files, you |
| may want to run the 'Info-validate' command. (The 'makeinfo' command |
| does such a good job on its own, you do not need 'Info-validate'.) |
| However, you cannot run the 'M-x Info-validate' node-checking command on |
| indirect files. For information on how to prevent files from being |
| split and how to validate the structure of the nodes, see *note Using |
| Info-validate::. |
| |
| |
| File: texinfo.info, Node: Installing an Info File, Prev: Creating an Info File, Up: Creating and Installing Info Files |
| |
| 21.2 Installing an Info File |
| ============================ |
| |
| Info files are usually kept in the 'info' directory. You can read Info |
| files using the standalone Info program or the Info reader built into |
| Emacs. (*Note (info)Top::, for an introduction to Info.) |
| |
| * Menu: |
| |
| * Directory File:: The top level menu for all Info files. |
| * New Info File:: Listing a new Info file. |
| * Other Info Directories:: How to specify Info files that are |
| located in other directories. |
| * Installing Dir Entries:: How to specify what menu entry to add |
| to the Info directory. |
| * Invoking install-info:: 'install-info' options. |
| |
| |
| File: texinfo.info, Node: Directory File, Next: New Info File, Up: Installing an Info File |
| |
| 21.2.1 The Directory File 'dir' |
| ------------------------------- |
| |
| For Info to work, the 'info' directory must contain a file that serves |
| as a top level directory for the Info system. By convention, this file |
| is called 'dir'. (You can find the location of this file within Emacs |
| by typing 'C-h i' to enter Info and then typing 'C-x C-f' to see the |
| pathname to the 'info' directory.) |
| |
| The 'dir' file is itself an Info file. It contains the top level |
| menu for all the Info files in the system. The menu looks like this: |
| |
| * Menu: |
| * Info: (info). Documentation browsing system. |
| * Emacs: (emacs). The extensible, self-documenting |
| text editor. |
| * Texinfo: (texinfo). With one source file, make |
| either a printed manual using |
| @TeX{} or an Info file. |
| ... |
| |
| Each of these menu entries points to the 'Top' node of the Info file |
| that is named in parentheses. (The menu entry does not need to specify |
| the 'Top' node, since Info goes to the 'Top' node if no node name is |
| mentioned. *Note Nodes in Other Info Files: Other Info Files.) |
| |
| Thus, the 'Info' entry points to the 'Top' node of the 'info' file |
| and the 'Emacs' entry points to the 'Top' node of the 'emacs' file. |
| |
| In each of the Info files, the 'Up' pointer of the 'Top' node refers |
| back to the 'dir' file. For example, the line for the 'Top' node of the |
| Emacs manual looks like this in Info: |
| |
| File: emacs Node: Top, Up: (DIR), Next: Distrib |
| |
| In this case, the 'dir' file name is written in uppercase letters--it |
| can be written in either upper- or lowercase. This is not true in |
| general, it is a special case for 'dir'. |
| |
| |
| File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory File, Up: Installing an Info File |
| |
| 21.2.2 Listing a New Info File |
| ------------------------------ |
| |
| To add a new Info file to your system, you must write a menu entry to |
| add to the menu in the 'dir' file in the 'info' directory. For example, |
| if you were adding documentation for GDB, you would write the following |
| new entry: |
| |
| * GDB: (gdb). The source-level C debugger. |
| |
| The first part of the menu entry is the menu entry name, followed by a |
| colon. The second part is the name of the Info file, in parentheses, |
| followed by a period. The third part is the description. |
| |
| The name of an Info file often has a '.info' extension. Thus, the |
| Info file for GDB might be called either 'gdb' or 'gdb.info'. The Info |
| reader programs automatically try the file name both with and without |
| '.info'(1); so it is better to avoid clutter and not to write '.info' |
| explicitly in the menu entry. For example, the GDB menu entry should |
| use just 'gdb' for the file name, not 'gdb.info'. |
| |
| ---------- Footnotes ---------- |
| |
| (1) On MS-DOS/MS-Windows systems, Info will try the '.inf' extension |
| as well. |
| |
| |
| File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Installing an Info File |
| |
| 21.2.3 Info Files in Other Directories |
| -------------------------------------- |
| |
| If an Info file is not in the 'info' directory, there are three ways to |
| specify its location: |
| |
| 1. Write the pathname in the 'dir' file as the second part of the |
| menu. |
| |
| 2. Specify the Info directory name in the 'INFOPATH' environment |
| variable in your '.profile' or '.cshrc' initialization file. (Only |
| you and others who set this environment variable will be able to |
| find Info files whose location is specified this way.) |
| |
| 3. If you are using Emacs, list the name of the file in a second 'dir' |
| file, in its directory; and then add the name of that directory to |
| the 'Info-directory-list' variable in your personal or site |
| initialization file. |
| |
| This variable tells Emacs where to look for 'dir' files (the files |
| must be named 'dir'). Emacs merges the files named 'dir' from each |
| of the listed directories. (In Emacs version 18, you can set the |
| 'Info-directory' variable to the name of only one directory.) |
| |
| For example, to reach a test file in the '/home/bob/info' directory, |
| you could add an entry like this to the menu in the standard 'dir' file: |
| |
| * Test: (/home/bob/info/info-test). Bob's own test file. |
| |
| In this case, the absolute file name of the 'info-test' file is written |
| as the second part of the menu entry. |
| |
| If you don't want to edit the system 'dir' file, you can tell Info |
| where to look by setting the 'INFOPATH' environment variable in your |
| shell startup file. This works with both the Emacs and standalone Info |
| readers. |
| |
| Specifically, if you use a Bourne-compatible shell such as 'sh' or |
| 'bash' for your shell command interpreter, you set the 'INFOPATH' |
| environment variable in the '.profile' initialization file; but if you |
| use 'csh' or 'tcsh', you set the variable in the '.cshrc' initialization |
| file. On MS-DOS/MS-Windows systems, you must set 'INFOPATH' in your |
| 'autoexec.bat' file or in the registry. Each type of shell uses a |
| different syntax. |
| |
| * In a '.cshrc' file, you could set the 'INFOPATH' variable as |
| follows: |
| |
| setenv INFOPATH .:~/info:/usr/local/emacs/info |
| |
| * In a '.profile' file, you would achieve the same effect by writing: |
| |
| INFOPATH=.:$HOME/info:/usr/local/emacs/info |
| export INFOPATH |
| |
| * In a 'autoexec.bat' file, you write this command (note the use of |
| ';' as the directory separator, and a different syntax for using |
| values of other environment variables): |
| |
| set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info |
| |
| The '.' indicates the current directory as usual. Emacs uses the |
| 'INFOPATH' environment variable to initialize the value of Emacs's own |
| 'Info-directory-list' variable. The standalone Info reader merges any |
| files named 'dir' in any directory listed in the 'INFOPATH' variable |
| into a single menu presented to you in the node called '(dir)Top'. |
| |
| However you set 'INFOPATH', if its last character is a colon (on |
| MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced by |
| the default (compiled-in) path. This gives you a way to augment the |
| default path with new directories without having to list all the |
| standard places. For example (using 'sh' syntax): |
| |
| INFOPATH=/home/bob/info: |
| export INFOPATH |
| |
| will search '/home/bob/info' first, then the standard directories. |
| Leading or doubled colons are not treated specially. |
| |
| When you create your own 'dir' file for use with |
| 'Info-directory-list' or 'INFOPATH', it's easiest to start by copying an |
| existing 'dir' file and replace all the text after the '* Menu:' with |
| your desired entries. That way, the punctuation and special 'CTRL-_' |
| characters that Info needs will be present. |
| |
| As one final alternative, which works only with Emacs Info, you can |
| change the 'Info-directory-list' variable. For example: |
| |
| (add-hook 'Info-mode-hook '(lambda () |
| (add-to-list 'Info-directory-list |
| (expand-file-name "~/info")))) |
| |
| |
| File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Installing an Info File |
| |
| 21.2.4 Installing Info Directory Files |
| -------------------------------------- |
| |
| When you install an Info file onto your system, you can use the program |
| 'install-info' to update the Info directory file 'dir'. Normally the |
| makefile for the package runs 'install-info', just after copying the |
| Info file into its proper installed location. |
| |
| In order for the Info file to work with 'install-info', you include |
| the commands '@dircategory' and '@direntry'...'@end direntry' in the |
| Texinfo source file. Use '@direntry' to specify the menu entries to add |
| to the Info directory file, and use '@dircategory' to specify which part |
| of the Info directory to put it in. Here is how these commands are used |
| in this manual: |
| |
| @dircategory Texinfo documentation system |
| @direntry |
| * Texinfo: (texinfo). The GNU documentation format. |
| * install-info: (texinfo)Invoking install-info. ... |
| ... |
| @end direntry |
| |
| Here's what this produces in the Info file: |
| |
| INFO-DIR-SECTION Texinfo documentation system |
| START-INFO-DIR-ENTRY |
| * Texinfo: (texinfo). The GNU documentation format. |
| * install-info: (texinfo)Invoking install-info. ... |
| ... |
| END-INFO-DIR-ENTRY |
| |
| The 'install-info' program sees these lines in the Info file, and that |
| is how it knows what to do. |
| |
| Always use the '@direntry' and '@dircategory' commands near the |
| beginning of the Texinfo input, before the first '@node' command. If |
| you use them later on in the input, 'install-info' will not notice them. |
| |
| 'install-info' will automatically reformat the description of the |
| menu entries it is adding. As a matter of convention, the description |
| of the main entry (above, 'The GNU documentation format') should start |
| at column 32, starting at zero (as in 'what-cursor-position' in Emacs). |
| This will make it align with most others. Description for individual |
| utilities best start in column 48, where possible. For more information |
| about formatting see the '--calign', '--align', and '--max-width' |
| options in *note Invoking install-info::. |
| |
| If you use '@dircategory' more than once in the Texinfo source, each |
| usage specifies the 'current' category; any subsequent '@direntry' |
| commands will add to that category. |
| |
| When choosing a category name for the '@dircategory' command, we |
| recommend consulting the Free Software Directory |
| (http://www.gnu.org/directory). If your program is not listed there, or |
| listed incorrectly or incompletely, please report the situation to the |
| directory maintainers (<http://directory.fsf.org>) so that the category |
| names can be kept in sync. |
| |
| Here are a few examples (see the 'util/dir-example' file in the |
| Texinfo distribution for large sample 'dir' file): |
| |
| Emacs |
| Localization |
| Printing |
| Software development |
| Software libraries |
| Text creation and manipulation |
| |
| Each 'Invoking' node for every program installed should have a |
| corresponding '@direntry'. This lets users easily find the |
| documentation for the different programs they can run, as with the |
| traditional 'man' system. |
| |
| |
| File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Installing an Info File |
| |
| 21.2.5 Invoking 'install-info' |
| ------------------------------ |
| |
| 'install-info' inserts menu entries from an Info file into the top-level |
| 'dir' file in the Info system (see the previous sections for an |
| explanation of how the 'dir' file works). 'install-info' also removes |
| menu entries from the 'dir' file. It's most often run as part of |
| software installation, or when constructing a 'dir' file for all manuals |
| on a system. Synopsis: |
| |
| install-info [OPTION...] [INFO-FILE [DIR-FILE]] |
| |
| If INFO-FILE or DIR-FILE are not specified, the options (described |
| below) that define them must be. There are no compile-time defaults, |
| and standard input is never used. 'install-info' can read only one Info |
| file and write only one 'dir' file per invocation. |
| |
| If DIR-FILE (however specified) does not exist, 'install-info' |
| creates it if possible (with no entries). |
| |
| If any input file is compressed with 'gzip' (*note (gzip)Top::), |
| 'install-info' automatically uncompresses it for reading. And if |
| DIR-FILE is compressed, 'install-info' also automatically leaves it |
| compressed after writing any changes. If DIR-FILE itself does not |
| exist, 'install-info' tries to open 'DIR-FILE.gz', 'DIR-FILE.xz', |
| 'DIR-FILE.bz2', 'DIR-FILE.lz', and 'DIR-FILE.lzma', in that order. |
| |
| Options: |
| |
| '--add-once' |
| Specifies that the entry or entries will only be put into a single |
| section. |
| |
| '--align=COLUMN' |
| Specifies the column that the second and subsequent lines of menu |
| entry's description will be formatted to begin at. The default for |
| this option is '35'. It is used in conjunction with the |
| '--max-width' option. COLUMN starts counting at 1. |
| |
| '--append-new-sections' |
| Instead of alphabetizing new sections, place them at the end of the |
| DIR file. |
| |
| '--calign=COLUMN' |
| Specifies the column that the first line of menu entry's |
| description will be formatted to begin at. The default for this |
| option is '33'. It is used in conjunction with the '--max-width' |
| option. When the name of the menu entry exceeds this column, |
| entry's description will start on the following line. COLUMN |
| starts counting at 1. |
| |
| '--debug' |
| Report what is being done. |
| |
| '--delete' |
| Delete the entries in INFO-FILE from DIR-FILE. The file name in |
| the entry in DIR-FILE must be INFO-FILE (except for an optional |
| '.info' in either one). Don't insert any new entries. Any empty |
| sections that result from the removal are also removed. |
| |
| '--description=TEXT' |
| Specify the explanatory portion of the menu entry. If you don't |
| specify a description (either via '--entry', '--item' or this |
| option), the description is taken from the Info file itself. |
| |
| '--dir-file=NAME' |
| Specify file name of the Info directory file. This is equivalent |
| to using the DIR-FILE argument. |
| |
| '--dry-run' |
| Same as '--test'. |
| |
| '--entry=TEXT' |
| Insert TEXT as an Info directory entry; TEXT should have the form |
| of an Info menu item line plus zero or more extra lines starting |
| with whitespace. If you specify more than one entry, they are all |
| added. If you don't specify any entries, they are determined from |
| information in the Info file itself. |
| |
| '--help' |
| Display a usage message with basic usage and all available options, |
| then exit successfully. |
| |
| '--info-file=FILE' |
| Specify Info file to install in the directory. This is equivalent |
| to using the INFO-FILE argument. |
| |
| '--info-dir=DIR' |
| Specify the directory where the directory file 'dir' resides. |
| Equivalent to '--dir-file=DIR/dir'. |
| |
| '--infodir=DIR' |
| Same as '--info-dir'. |
| |
| '--item=TEXT' |
| Same as '--entry=TEXT'. An Info directory entry is actually a menu |
| item. |
| |
| '--keep-old' |
| Do not replace pre-existing menu entries. When '--remove' is |
| specified, this option means that empty sections are not removed. |
| |
| '--max-width=COLUMN' |
| Specifies the column that the menu entry's description will be |
| word-wrapped at. COLUMN starts counting at 1. |
| |
| '--maxwidth=COLUMN' |
| Same as '--max-width'. |
| |
| '--menuentry=TEXT' |
| Same as '--name'. |
| |
| '--name=TEXT' |
| Specify the name portion of the menu entry. If the TEXT does not |
| start with an asterisk '*', it is presumed to be the text after the |
| '*' and before the parentheses that specify the Info file. |
| Otherwise TEXT is taken verbatim, and is taken as defining the text |
| up to and including the first period (a space is appended if |
| necessary). If you don't specify the name (either via '--entry', |
| '--item' or this option), it is taken from the Info file itself. |
| If the Info does not contain the name, the basename of the Info |
| file is used. |
| |
| '--no-indent' |
| Suppress formatting of new entries into the 'dir' file. |
| |
| '--quiet' |
| '--silent' |
| Suppress warnings, etc., for silent operation. |
| |
| '--remove' |
| Same as '--delete'. |
| |
| '--remove-exactly' |
| Also like '--delete', but only entries if the Info file name |
| matches exactly; '.info' and/or '.gz' suffixes are _not_ ignored. |
| |
| '--section=SEC' |
| Put this file's entries in section SEC of the directory. If you |
| specify more than one section, all the entries are added in each of |
| the sections. If you don't specify any sections, they are |
| determined from information in the Info file itself. If the Info |
| file doesn't specify a section, the menu entries are put into the |
| Miscellaneous section. |
| |
| '--section REGEX SEC' |
| Same as '--regex=REGEX --section=SEC --add-once'. |
| |
| 'install-info' tries to detect when this alternate syntax is used, |
| but does not always guess correctly. Here is the heuristic that |
| 'install-info' uses: |
| 1. If the second argument to '--section' starts with a hyphen, |
| the original syntax is presumed. |
| |
| 2. If the second argument to '--section' is a file that can be |
| opened, the original syntax is presumed. |
| |
| 3. Otherwise the alternate syntax is used. |
| |
| When the heuristic fails because your section title starts with a |
| hyphen, or it happens to be a filename that can be opened, the |
| syntax should be changed to '--regex=REGEX --section=SEC |
| --add-once'. |
| |
| '--regex=REGEX' |
| Put this file's entries into any section that matches REGEX. If |
| more than one section matches, all of the entries are added in each |
| of the sections. Specify REGEX using basic regular expression |
| syntax, more or less as used with 'grep', for example. |
| |
| '--test' |
| Suppress updating of the directory file. |
| |
| '--version' |
| Display version information and exit successfully. |
| |
| |
| File: texinfo.info, Node: Generating HTML, Next: @-Command Details, Prev: Creating and Installing Info Files, Up: Top |
| |
| 22 Generating HTML |
| ****************** |
| |
| 'makeinfo' generates Info output by default, but given the '--html' |
| option, it will generate HTML, for web browsers and other programs. |
| This chapter gives some details on such HTML output. |
| |
| 'makeinfo' has many user-definable customization variables with which |
| you can influence the HTML output. *Note Customization Variables::. |
| |
| 'makeinfo' can also produce output in XML and Docbook formats, but we |
| do not as yet describe these in detail. *Note Output Formats::, for a |
| brief overview of all the output formats. |
| |
| * Menu: |
| |
| * HTML Translation:: Details of the HTML output. |
| * HTML Splitting:: How HTML output is split. |
| * HTML CSS:: Influencing HTML output with Cascading Style Sheets. |
| * HTML Xref:: Cross-references in HTML output. |
| |
| |
| File: texinfo.info, Node: HTML Translation, Next: HTML Splitting, Up: Generating HTML |
| |
| 22.1 HTML Translation |
| ===================== |
| |
| First, the HTML generated by 'makeinfo' is standard HTML 4. It also |
| tries to be compatible with earlier standards (e.g., HTML 2.0, |
| RFC-1866). Thus, please report output from an error-free run of |
| 'makeinfo' which has practical browser portability problems as a bug |
| (*note Reporting Bugs::). |
| |
| Some known exceptions to HTML 3.2 (using '--init-file=html32.pm' |
| produces strict HTML 3.2 output; *note Invoking texi2any::): |
| |
| 1. HTML 3.2 tables are generated for the '@multitable' command (*note |
| Multi-column Tables::), but they should degrade reasonably in |
| browsers without table support. |
| |
| 2. The HTML 4 'lang' attribute on the '<html>' attribute is used. |
| |
| 3. Entities that are not in the HTML 3.2 standard are also used. |
| |
| 4. CSS is used (*note HTML CSS::). |
| |
| 5. A few HTML 4 elements are used: 'thead', 'abbr', 'acronym'. |
| |
| To achieve maximum portability and accessibility among browsers (both |
| graphical and text-based), systems, and users, the HTML output is |
| intentionally quite plain and generic. It has always been our goal for |
| users to be able to customize the output to their wishes via CSS (*note |
| HTML CSS::) or other means (*note Customization Variables::. If you |
| cannot accomplish a reasonable customization, feel free to report that. |
| |
| However, we do not wish to depart from our basic goal of widest |
| readability for the core output. For example, using fancy CSS may make |
| it possible for the HTML output to more closely resemble the TeX output |
| in some details, but this result is not even close to being worth the |
| ensuing difficulties. |
| |
| It is also intentionally not our goal, and not even possible, to pass |
| through every conceivable validation test without any diagnostics. |
| Different validation tests have different goals, often about pedantic |
| enforcement of some standard or another. Our overriding goal is to help |
| users, not blindly comply with standards. |
| |
| To repeat what was said at the top: please report output from an |
| error-free run of 'makeinfo' which has _practical_ browser portability |
| problems as a bug (*note Reporting Bugs::). |
| |
| A few other general points about the HTML output follow. |
| |
| *Navigation bar:* By default, a navigation bar is inserted at the |
| start of each node, analogous to Info output. If the '--no-headers' |
| option is used, the navigation bar is only inserted at the beginning of |
| split files. Header '<link>' elements in split output can support |
| Info-like navigation with browsers like Lynx and Emacs W3 which |
| implement this HTML 1.0 feature. |
| |
| *Footnotes:* for HTML, when the footnote style is 'end', or if the |
| output is not split, footnotes are put at the end of the output. If the |
| footnoet style is set to 'separate', and the output is split, they are |
| placed in a separate file. *Note Footnote Styles::. |
| |
| *Raw HTML*: 'makeinfo' will include segments of Texinfo source |
| between '@ifhtml' and '@end ifhtml' in the HTML output (but not any of |
| the other conditionals, by default). Source between '@html' and '@end |
| html' is passed without change to the output (i.e., suppressing the |
| normal escaping of input '<', '>' and '&' characters which have special |
| significance in HTML). *Note Conditional Commands::. |
| |
| |
| File: texinfo.info, Node: HTML Splitting, Next: HTML CSS, Prev: HTML Translation, Up: Generating HTML |
| |
| 22.2 HTML Splitting |
| =================== |
| |
| When splitting output at nodes (which is the default), 'makeinfo' writes |
| HTML output into (basically) one output file per Texinfo source '@node'. |
| |
| Each output file name is the node name with spaces replaced by '-''s |
| and special characters changed to '_' followed by their code point in |
| hex (*note HTML Xref::). This is to make it portable and easy to use as |
| a filename. In the unusual case of two different nodes having the same |
| name after this treatment, they are written consecutively to the same |
| file, with HTML anchors so each can be referred to independently. |
| |
| If 'makeinfo' is run on a system which does not distinguish case in |
| file names, nodes which are the same except for case (e.g., 'index' and |
| 'Index') will also be folded into the same output file with anchors. |
| You can also pretend to be on a case insensitive filesystem by setting |
| the customization variable 'CASE_INSENSITIVE_FILENAMES'. |
| |
| It is also possible to split at chapters or sections with '--split' |
| (*note Invoking texi2any::). In that case, the file names are |
| constructed after the name of the node associated with the relevant |
| sectioning command. Also, unless '--no-node-files' is specified, a |
| redirection file is output for every node in order to more reliably |
| support cross-references to that manual (*note HTML Xref::). |
| |
| When splitting, the HTML output files are written into a |
| subdirectory, with the name chosen as follows: |
| |
| 1. 'makeinfo' first tries the subdirectory with the base name from |
| '@setfilename' (that is, any extension is removed). For example, |
| HTML output for '@setfilename gcc.info' would be written into a |
| subdirectory named 'gcc/'. |
| |
| 2. If that directory cannot be created for any reason, then 'makeinfo' |
| tries appending '.html' to the directory name. For example, output |
| for '@setfilename texinfo' would be written to 'texinfo.html/'. |
| |
| 3. If the 'NAME.html' directory can't be created either, 'makeinfo' |
| gives up. |
| |
| In any case, the top-level output file within the directory is always |
| named 'index.html'. |
| |
| Monolithic output ('--no-split') is named according to '@setfilename' |
| (with any '.info' extension is replaced with '.html'), '--output' (the |
| argument is used literally), or based on the input file name as a last |
| resort (*note @setfilename::). |
| |
| |
| File: texinfo.info, Node: HTML CSS, Next: HTML Xref, Prev: HTML Splitting, Up: Generating HTML |
| |
| 22.3 HTML CSS |
| ============= |
| |
| Cascading Style Sheets (CSS for short) is an Internet standard for |
| influencing the display of HTML documents: see |
| <http://www.w3.org/Style/CSS/>. |
| |
| By default, 'makeinfo' includes a few simple CSS commands to better |
| implement the appearance of some Texinfo environments. Here are two of |
| them, as an example: |
| |
| pre.display { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| |
| A full explanation of CSS is (far) beyond this manual; please see the |
| reference above. In brief, however, the above tells the web browser to |
| use a 'smaller' font size for '@smalldisplay' text, and to use the same |
| font as the main document for both '@smalldisplay' and '@display'. By |
| default, the HTML '<pre>' command uses a monospaced font. |
| |
| You can influence the CSS in the HTML output with two 'makeinfo' |
| options: '--css-include=FILE' and '--css-ref=URL'. |
| |
| The option '--css-ref=URL' adds to each output HTML file a '<link>' |
| tag referencing a CSS at the given URL. This allows using external |
| style sheets. You may find the file |
| 'texi2html/examples/texinfo-bright-colors.css' useful for visualizing |
| the CSS elements in Texinfo output. |
| |
| The option '--css-include=FILE' includes the contents FILE in the |
| HTML output, as you might expect. However, the details are somewhat |
| tricky, as described in the following, to provide maximum flexibility. |
| |
| The CSS file may begin with so-called '@import' directives, which |
| link to external CSS specifications for browsers to use when |
| interpreting the document. Again, a full description is beyond our |
| scope here, but we'll describe how they work syntactically, so we can |
| explain how 'makeinfo' handles them. |
| |
| There can be more than one '@import', but they have to come first in |
| the file, with only whitespace and comments interspersed, no normal |
| definitions. (Technical exception: a '@charset' directive may precede |
| the '@import''s. This does not alter 'makeinfo''s behavior, it just |
| copies the '@charset' if present.) Comments in CSS files are delimited |
| by '/* ... */', as in C. An '@import' directive must be in one of these |
| two forms: |
| |
| @import url(http://example.org/foo.css); |
| @import "http://example.net/bar.css"; |
| |
| As far as 'makeinfo' is concerned, the crucial characters are the '@' |
| at the beginning and the semicolon terminating the directive. When |
| reading the CSS file, it simply copies any such '@'-directive into the |
| output, as follows: |
| |
| * If FILE contains only normal CSS declarations, it is included after |
| 'makeinfo''s default CSS, thus overriding it. |
| |
| * If FILE begins with '@import' specifications (see below), then the |
| 'import''s are included first (they have to come first, according |
| to the standard), and then 'makeinfo''s default CSS is included. |
| If you need to override 'makeinfo''s defaults from an '@import', |
| you can do so with the '! important' CSS construct, as in: |
| pre.smallexample { font-size: inherit ! important } |
| |
| * If FILE contains both '@import' and inline CSS specifications, the |
| '@import''s are included first, then 'makeinfo''s defaults, and |
| lastly the inline CSS from FILE. |
| |
| * Any @-directive other than '@import' and '@charset' is treated as a |
| CSS declaration, meaning 'makeinfo' includes its default CSS and |
| then the rest of the file. |
| |
| If the CSS file is malformed or erroneous, 'makeinfo''s output is |
| unspecified. 'makeinfo' does not try to interpret the meaning of the |
| CSS file in any way; it just looks for the special '@' and ';' |
| characters and blindly copies the text into the output. Comments in the |
| CSS file may or may not be included in the output. |
| |
| In addition to the possibilities offered by CSS, 'makeinfo' has many |
| user-definable customization variables with which you can influence the |
| HTML output. *Note Customization Variables::. |
| |
| |
| File: texinfo.info, Node: HTML Xref, Prev: HTML CSS, Up: Generating HTML |
| |
| 22.4 HTML Cross-references |
| ========================== |
| |
| Cross-references between Texinfo manuals in HTML format become, in the |
| end, a standard HTML '<a>' link, but the details are unfortunately |
| complex. This section describes the algorithm used in detail, so that |
| Texinfo can cooperate with other programs, such as 'texi2html', by |
| writing mutually compatible HTML files. |
| |
| This algorithm may or may not be used for links _within_ HTML output |
| for a Texinfo file. Since no issues of compatibility arise in such |
| cases, we do not need to specify this. |
| |
| We try to support references to such "external" manuals in both |
| monolithic and split forms. A "monolithic" (mono) manual is entirely |
| contained in one file, and a "split" manual has a file for each node. |
| (*Note HTML Splitting::.) |
| |
| The algorithm was primarily devised by Patrice Dumas in 2003-04. |
| |
| * Menu: |
| |
| * Link Basics: HTML Xref Link Basics. |
| * Node Expansion: HTML Xref Node Name Expansion. |
| * Command Expansion: HTML Xref Command Expansion. |
| * 8-bit Expansion: HTML Xref 8-bit Character Expansion. |
| * Mismatch: HTML Xref Mismatch. |
| * Configuration: HTML Xref Configuration. htmlxref.cnf. |
| * Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. |
| |
| |
| File: texinfo.info, Node: HTML Xref Link Basics, Next: HTML Xref Node Name Expansion, Up: HTML Xref |
| |
| 22.4.1 HTML Cross-reference Link Basics |
| --------------------------------------- |
| |
| For our purposes, an HTML link consists of four components: a host name, |
| a directory part, a file part, and a target part. We always assume the |
| 'http' protocol. For example: |
| |
| http://HOST/DIR/FILE.html#TARGET |
| |
| The information to construct a link comes from the node name and |
| manual name in the cross-reference command in the Texinfo source (*note |
| Cross References::), and from "external information" (*note HTML Xref |
| Configuration::). |
| |
| We now consider each part in turn. |
| |
| The HOST is hardwired to be the local host. This could either be the |
| literal string 'localhost', or, according to the rules for HTML links, |
| the 'http://localhost/' could be omitted entirely. |
| |
| The DIR and FILE parts are more complicated, and depend on the |
| relative split/mono nature of both the manual being processed and the |
| manual that the cross-reference refers to. The underlying idea is that |
| there is one directory for Texinfo manuals in HTML, and a given MANUAL |
| is either available as a monolithic file 'MANUAL.html', or a split |
| subdirectory 'MANUAL/*.html'. Here are the cases: |
| |
| * If the present manual is split, and the referent manual is also |
| split, the directory is '../REFERENT/' and the file is the expanded |
| node name (described later). |
| |
| * If the present manual is split, and the referent manual is mono, |
| the directory is '../' and the file is 'REFERENT.html'. |
| |
| * If the present manual is mono, and the referent manual is split, |
| the directory is 'REFERENT/' and the file is the expanded node |
| name. |
| |
| * If the present manual is mono, and the referent manual is also |
| mono, the directory is './' (or just the empty string), and the |
| file is 'REFERENT.html'. |
| |
| Another rule, that only holds for filenames, is that base filenames |
| are truncated to 245 characters, to allow for an extension to be |
| appended and still comply with the 255-character limit which is common |
| to many filesystems. Although technically this can be changed with the |
| 'BASEFILENAME_LENGTH' customization variable (*note Other Customization |
| Variables::), doing so would make cross-manual references to such nodes |
| invalid. |
| |
| Any directory part in the filename argument of the source cross |
| reference command is ignored. Thus, '@xref{,,,../foo}' and |
| '@xref{,,,foo}' both use 'foo' as the manual name. This is because any |
| such attempted hardwiring of the directory is very unlikely to be useful |
| for both Info and HTML output. |
| |
| Finally, the TARGET part is always the expanded node name. |
| |
| Whether the present manual is split or mono is determined by user |
| option; 'makeinfo' defaults to split, with the '--no-split' option |
| overriding this. |
| |
| Whether the referent manual is split or mono, however, is another bit |
| of the external information (*note HTML Xref Configuration::). By |
| default, 'makeinfo' uses the same form of the referent manual as the |
| present manual. |
| |
| Thus, there can be a mismatch between the format of the referent |
| manual that the generating software assumes, and the format it's |
| actually present in. *Note HTML Xref Mismatch::. |
| |
| |
| File: texinfo.info, Node: HTML Xref Node Name Expansion, Next: HTML Xref Command Expansion, Prev: HTML Xref Link Basics, Up: HTML Xref |
| |
| 22.4.2 HTML Cross-reference Node Name Expansion |
| ----------------------------------------------- |
| |
| As mentioned in the previous section, the key part of the HTML cross |
| reference algorithm is the conversion of node names in the Texinfo |
| source into strings suitable for XHTML identifiers and filenames. The |
| restrictions are similar for each: plain ASCII letters, numbers, and the |
| '-' and '_' characters are all that can be used. (Although HTML anchors |
| can contain most characters, XHTML is more restrictive.) |
| |
| Cross-references in Texinfo can refer either to nodes or anchors |
| (*note @anchor::). However, anchors are treated identically to nodes in |
| this context, so we'll continue to say "node" names for simplicity. |
| |
| A special exception: the Top node (*note The Top Node::) is always |
| mapped to the file 'index.html', to match web server software. However, |
| the HTML _target_ is 'Top'. Thus (in the split case): |
| |
| @xref{Top,,, emacs, The GNU Emacs Manual}. |
| => <a href="emacs/index.html#Top"> |
| |
| 1. The standard ASCII letters (a-z and A-Z) are not modified. All |
| other characters may be changed as specified below. |
| |
| 2. The standard ASCII numbers (0-9) are not modified except when a |
| number is the first character of the node name. In that case, see |
| below. |
| |
| 3. Multiple consecutive space, tab and newline characters are |
| transformed into just one space. (It's not possible to have |
| newlines in node names with the current implementation, but we |
| specify it anyway, just in case.) |
| |
| 4. Leading and trailing spaces are removed. |
| |
| 5. After the above has been applied, each remaining space character is |
| converted into a '-' character. |
| |
| 6. Other ASCII 7-bit characters are transformed into '_00XX', where XX |
| is the ASCII character code in (lowercase) hexadecimal. This |
| includes '_', which is mapped to '_005f'. |
| |
| 7. If the node name does not begin with a letter, the literal string |
| 'g_t' is prefixed to the result. (Due to the rules above, that |
| string can never occur otherwise; it is an arbitrary choice, |
| standing for "GNU Texinfo".) This is necessary because XHTML |
| requires that identifiers begin with a letter. |
| |
| For example: |
| |
| @node A node --- with _'% |
| => A-node-_002d_002d_002d-with-_005f_0027_0025 |
| |
| Example translations of common characters: |
| |
| * '_' => '_005f' |
| * '-' => '_002d' |
| * 'A node' => 'A-node' |
| |
| On case-folding computer systems, nodes differing only by case will |
| be mapped to the same file. In particular, as mentioned above, Top |
| always maps to the file 'index.html'. Thus, on a case-folding system, |
| Top and a node named 'Index' will both be written to 'index.html'. |
| Fortunately, the targets serve to distinguish these cases, since HTML |
| target names are always case-sensitive, independent of operating system. |
| |