[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texinfo.txi doc/texi2olda...
|
From: |
Karl Berry |
|
Subject: |
texinfo ChangeLog doc/texinfo.txi doc/texi2olda... |
|
Date: |
Fri, 05 Nov 2010 23:26:22 +0000 |
CVSROOT: /sources/texinfo
Module name: texinfo
Changes by: Karl Berry <karl> 10/11/05 23:26:22
Modified files:
. : ChangeLog
doc : texinfo.txi
Added files:
doc : texi2oldapi.texi
Log message:
move likely-obsoleted sections to texi2oldapi.texi
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1172&r2=1.1173
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.341&r2=1.342
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texi2oldapi.texi?cvsroot=texinfo&rev=1.1
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1172
retrieving revision 1.1173
diff -u -b -r1.1172 -r1.1173
--- ChangeLog 3 Nov 2010 18:04:50 -0000 1.1172
+++ ChangeLog 5 Nov 2010 23:26:20 -0000 1.1173
@@ -1,3 +1,17 @@
+2010-11-05 Karl Berry <address@hidden>
+
+ * doc/texi2oldapi.texi: new file archiving several API sections
+ which will likely become obsolete with the new tree-based translator.
+ * doc/texinfo.txi (Customizing HTML Basic Commands,
+ Customizing HTML References,
+ Customizing HTML Footnotes
+ Customizing HTML Block Commands,
+ Paragraph and preformatted region,
+ Lists tables and definitions formatting,
+ Menus indices and floats formatting,
+ Handling special regions,
+ Other and unknown commands): these sections removed.
+
2010-11-03 Karl Berry <address@hidden>
* doc/texinfo.txi (HTML Customization of Alignment Commands):
Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.341
retrieving revision 1.342
diff -u -b -r1.341 -r1.342
--- doc/texinfo.txi 3 Nov 2010 18:04:49 -0000 1.341
+++ doc/texinfo.txi 5 Nov 2010 23:26:21 -0000 1.342
@@ -1,5 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.341 2010/11/03 18:04:49 karl Exp $
address@hidden $Id: texinfo.txi,v 1.342 2010/11/05 23:26:21 karl Exp $
@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi
@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
@@ -18522,15 +18522,6 @@
* Customizing Special Elements:: The top, toc, about, etc., elements.
* Customizing Output-Related Names:: File names and target names.
* Customizing HTML Headings:: Sectioning commands.
-* Customizing HTML Basic Commands:: Commands with no arguments, images, etc.
-* Customizing HTML References:: @code{@@xref}, external node pointers, etc.
-* Customizing HTML Footnotes:: Footnotes.
-* Customizing HTML Block Commands:: Environments.
-* Paragraph and preformatted region::
-* Lists tables and definitions formatting::
-* Menus indices and floats formatting::
-* Handling special regions::
-* Other and unknown commands::
* External index files::
* Customizing CSS::
@end menu
@@ -19366,8 +19357,9 @@
@end deftypefn
By default, this is used to keep track of multitable nesting, and so
-it is linked with multitable formating (@pxref{Multitable
-Formatting}).
+it is linked with multitable formating.
+
address@hidden oldapi @pxref{Multitable Formatting}
@node Init File Expansion Contexts
@@ -19389,9 +19381,11 @@
When spaces between words are kept. For example, within the
@code{@@display} (@pxref{display,, @code{@@display}}) and
@code{@@example} environments (@pxref{example,, @code{@@example}}), and
-in menu comments (@pxref{Menu formatting}). The preformatted regions
+in menu comments. The preformatted regions
are usually rendered using @code{<pre>} elements in HTML.
address@hidden oldapi (@pxref{Menu formatting})
+
@item string context
@cindex String expansion context
When rendering strings without formatting elements, for example in
@@ -20243,9 +20237,11 @@
element.
@end deftypefn
-The following sections describe the details for each special element
-except footnotes, which are formatted when the @code{@@footnote}
-command is expanded (@pxref{Customizing HTML Footnotes}).
+The following sections describe the details for the special elements
+other than footnotes, which are formatted when the @code{@@footnote}
+command is expanded.
+
address@hidden oldapi (@pxref{Customizing HTML Footnotes}).
@menu
* Top Element Customization::
@@ -20853,2184 +20849,6 @@
@end deftypefn
address@hidden Customizing HTML Basic Commands
address@hidden Customizing HTML Basic Commands
-
-This section describes customizing the HTML output for the basic
-Texinfo commands used within the running text.
-
address@hidden
-* Argless: HTML Customization for Commands Without Arguments.
-* @@-Colon: HTML Customization After @@-Colon.
-* Simple: HTML Customization for Simple Commands. Indicators, accents, etc.
-* Anchors: HTML Customization for Anchors.
-* Images: HTML Customization for Images.
-* sp: HTML Customization for @code{sp}.
-* Abbrs: HTML Customization for Abbreviations. @code{@@acronym}, @code{@@abbr}.
-* Text: HTML Customization for Text Sequences. @code{-- --- `` ''}, etc.
-* Title: HTML Customization for Title Commands. @code{@@title}, etc.
address@hidden menu
-
-
address@hidden HTML Customization for Commands Without Arguments
address@hidden HTML Customization for Commands Without Arguments
-
address@hidden HTML customization for commands without arguments
address@hidden Commands without arguments, customizing HTML for
address@hidden Insertion commands, customizing HTML for
-
-These commands include those whose names are a single nonletter
-character, such as @code{@@@@}, and those with a normal alphabetic
-name but whose braces should be empty, such as @code{@@address@hidden@}} and
address@hidden@@address@hidden@}}.
-
-Each of these categories of commands have associated hashes for each
-expansion context: normal, preformatted, string, and math (@pxref{Init
-File Expansion Contexts}). The keys of each hash are the command
-names, the associated value is the text replacing the command. In
-math context, if a command is not a key of these hashes, the defaults
-for the command are used.
-
address@hidden %simple_map
address@hidden %things_map
address@hidden %simple_map_pre
address@hidden %pre_map
address@hidden %simple_map_texi
address@hidden %texi_map
address@hidden %simple_map_math
address@hidden %math_map
-The hashes are:
-
address@hidden {preformatted} {one nonlettered character} {empty braces}
address@hidden command type @tab one nonlettered character @tab empty braces
address@hidden normal @tab @code{%simple_map} @tab @code{%things_map}
address@hidden preformatted @tab @code{%simple_map_pre} @tab @code{%pre_map}
address@hidden string @tab @code{%simple_map_texi} @tab @code{%texi_map}
address@hidden math @tab @code{%simple_map_math} @tab @code{%math_map}
address@hidden multitable
-
-To change the formatting of a command, change the associated value in
-the desired hash. For example, if you want @code{­} to be output
-for @code{@@-} in normal and preformatted context, write this in your
-init file:
-
address@hidden
address@hidden'-'@} = '­';
address@hidden'-'@} = '­';
address@hidden example
-
address@hidden %sorting_things_map
-An additional hash is used preferentially when sorting indices,
-overriding @code{%texi_map} entries: @code{%sorting_things_map}.
-
-For better control, function references are available, although they
-are not used in string context. @code{simple_command} is for
-formatting of the single-nonletter @@-commands:
-
address@hidden {Function Reference} $formatted_command simple_command
- @ $command $in_preformatted $in_math $line_nr \%state
address@hidden is the @@-command name. @var{$in_preformatted} is true
-if in a preformatted region. @var{$in_math} is true if in math.
address@hidden is an opaque structure containing information about the
-line number of the @@-command. @var{\%state} holds information about
-the current context.
address@hidden deftypefn
-
-For @@-commands with empty brace arguments, @code{thing_command} may
-be redefined:
-
address@hidden {Function Reference} $formatted_command thing_command
- @ $command $text $in_preformatted $in_math $line_nr \%state
address@hidden is the formatted text appearing in the @@-command. It is
-invalid Texinfo to have anything other than the empty string there.
address@hidden, @var{$in_preformatted}, @var{$in_math},
address@hidden, and @var{\%state} are as above.
address@hidden deftypefn
-
-
address@hidden HTML Customization After @@-Colon
address@hidden HTML Customization After @@-Colon
-
address@hidden HTML customization after @code{@@:}
address@hidden Punctuation after @code{@@:}, customizing HTML for
address@hidden Sentence punctuation, customizing HTML for
-
address@hidden %colon_command_punctuation_characters
-The formatting of a punctuation character followed by @code{@@:} is
-determined by the hash @code{%colon_command_punctuation_characters}.
-If a @code{@@:} command is preceded by a character in this hash, it is
-replaced by the associated value. By default, the associated value is
-also the character, so this leaves the punctuation character
-unmodified.
-
-The following function reference may be redefined to handle characters
-that are in @code{%colon_command_punctuation_characters}:
-
address@hidden {Function Reference} $punctuation colon_command $character
address@hidden is a character appearing in
address@hidden and preceding an
address@hidden@@:} command. By default, the associated value in
address@hidden is returned.
address@hidden deftypefn
-
-
address@hidden HTML Customization for Simple Commands
address@hidden HTML Customization for Simple Commands
-
address@hidden HTML customization for simple commands
address@hidden Simple commands, customizing HTML for
address@hidden Style commands, customizing HTML for
address@hidden Accent commands, customizing HTML for
-
address@hidden %style_map
address@hidden %style_map_pre
address@hidden %style_map_texi
address@hidden %style_map_math
-The formatting of the output produced by ``indicator'' and font
-commands (e.g., @code{@@code}, @code{@@t}, @code{@@titlefont}), the
-accent-related commands with arguments (e.g., @code{@@'},
address@hidden@@udotaccent}, @code{@@dotless}) and other simple commands with
-arguments (e.g., @code{@@w}, @code{@@uref}, @code{@@math},
address@hidden@@asis}) is controlled by the following hashes by default
-(@pxref{Init File Expansion Contexts}):
-
address@hidden @code
address@hidden %style_map
-In normal context.
-
address@hidden %style_map_pre
-In preformatted context.
-
address@hidden %style_map_texi
-In string context.
-
address@hidden %style_map_math
-Preferentially in math context, falling back to other hashes if not found.
address@hidden table
-
-If defined, a function reference is called at the @@-command opening:
-
address@hidden {Function Reference} begin_style_texi $command \%state \@@stack @
- $real_style_or_accent $remove_texi
address@hidden @var
address@hidden $command
-The @@-command name.
-
address@hidden \%state
-Information about the current context.
-
address@hidden \@@stack
-An opaque variable.
-
address@hidden $real_style_or_accent
-Set if the command is an accent or a font command.
-
address@hidden $remove_texi
-Set if in a context where output is simple text.
address@hidden table
address@hidden deffn
-
address@hidden %accent_map
-The nonlettered accent commands where the following character is taken
-as the argument (e.g., @code{@@`a}) should be keys of the
address@hidden hash, even if no value is associated.
-
-Command with braces may be handled differently; @pxref{Init File
-Formatting of Commands}. For example, this is used for @code{@@math}
-if @LaTeX{}2HTML is used.
-
-The key of the hashes are the command names. The values may be
-strings or hash references. The hash reference interface is the only
-one described in this manual, the other is retained primarily for
-backward compatibility. You can also define your own interface.
-
address@hidden
-* Hash Interface for Simple HTML Customization::
-* Custom Interface for Simple HTML Customization::
address@hidden menu
-
-
address@hidden Hash Interface for Simple HTML Customization
address@hidden Hash Interface for Simple HTML Customization
-
address@hidden Hash interface for simple HTML customization
address@hidden Interface for simple HTML customization, hash
-
-The keys of the hashes given above are Texinfo command names. The
-values determine how the command argument is formatted. Each value is
-a hash reference. In this value hash, each key corresponds with a
-type of information for formatting, and the value is the corresponding
-data.
-
-Here's an example:
-
address@hidden
address@hidden'command'@} = @{
- 'args' => ['code'],
- 'inline_attribute' => 'code',
address@hidden;
address@hidden example
-
-Here, the arguments for @code{@@command} are interpreted as specified
-by the values associated with the @samp{args} key, namely a code
-argument; and the @code{inline_attribute} associated with that command
-is @samp{<code>}.
-
-Here is a list of the possible keys in the value hashes:
-
address@hidden @samp
address@hidden args
address@hidden Hash Args}
-The value associated is an array reference. Each element of the array
-defines how the corresponding argument (separated by @samp{,} in the
-Texinfo input) for the @@-command should be formatted. The
-possibilities are:
-
address@hidden @code
address@hidden normal
-for normal text,
-
address@hidden code
-for text where @samp{---}, @samp{--}, @samp{''}, and @samp{``} should
-be kept as-is, and
-
address@hidden keep
-if the input should be kept entirely as-is, with no interpretation of
-any @@-commands.
address@hidden table
-
-The default is @samp{['normal']} for one normally-interpreted argument.
-
-For example, we specify
-
address@hidden
address@hidden'email'@}->@{'args'@} = ['code', 'normal'];
address@hidden example
-
-because @samp{---}, @samp{--}, @samp{''} and @samp{``} should be kept
-as-is in the first argument of @code{@@email}
-(@pxref{email,, @code{@@email}}).
-
address@hidden attribute
-If the associated value is a word, it is considered to be an XML
-element name, and the argument is enclosed between the element opening
-and the element closing. For example, if the value is @code{elem}, the
-resulting HTML is @code{<elem>@var{arg}</elem>}.
-
-If the text is a word followed by some text, the word is interpreted
-as above, and the text is considered to be the attributes text of the
-element. Thus @code{elem class="elem"} leads to @code{<elem
-class="elem">@var{arg}</elem>}. This only works if there is only one
-argument.
-
address@hidden inline_attribute
-Like @code{attribute}, except that it is closed at each paragraph end
-and reopened at each beginning of paragraph. This is more often used
-than @samp{attribute} since it allows to have well-formed HTML and
-XML.
-
address@hidden inline_begin
-The associated value is added in front of the text and each time a
-paragraph is restarted while within the command.
-
address@hidden inline_end
-The associated value is added after the text and each time a paragraph
-is ended while within the command.
-
address@hidden begin
-The associated value is added in front of the text.
-
address@hidden end
-The associated value is added after the text.
-
address@hidden quotes
-If the corresponding value is true, the result is enclosed in quotes
-associated with configuration variables @code{OPEN_QUOTE_SYMBOL} and
address@hidden; the defaults depend on the output format
-but fall back to @samp{`} and @samp{'}.
-
address@hidden function
-The corresponding value should be a function reference, which is
-called with the following arguments:
-
address@hidden @code
address@hidden $command
-The @@-command name.
-
address@hidden \@@args
-An array reference containing the arguments of the @@-command.
-
address@hidden \@@command_stack
-An array reference with the names of the @@-commands containing the
-@@-command being formatted, latest on top.
-
address@hidden \%state
-A hash reference containing context information.
-
address@hidden $line_nr
-An opaque structure containing line number information for the
-@@-command. It can be used to call @code{main::line_error} or
address@hidden::line_warn} with the first argument being the message, and
-the second argument @code{$line_nr}.
-
address@hidden \@@line_numbers
-An array reference containing the line numbers (the same opaque
-structure as above) of the lines produced by the @@-command.
address@hidden table
address@hidden table
-
-
address@hidden Custom Interface for Simple HTML Customization
address@hidden Custom Interface for Simple HTML Customization
-
address@hidden Custom interface for simple HTML customization
address@hidden Interface for simple HTML customization, custom
-
-If the hash interface described in the previous section does not
-suffice, it is possible to change how the ``simple'' Texinfo commands
-are processed by redefining the following function reference:
-
address@hidden {Function Reference} $resulting_text style $style $command $text
@
- $args $no_close $no_open $line_nr \%state $command_stack \@@line_numbers
address@hidden @var
address@hidden $command
-The @@-command
-
address@hidden $style
-The value associated with the @var{$command} in the @code{%style_map},
address@hidden or @code{%style_map_texi} hashes.
-
address@hidden $text
-The argument text appearing within the @@-command braces.
-
address@hidden $args
-Array reference containing the command arguments, formatted according
-to the same conventions as the hash reference style (provided that the
-value associated with the @@-command is a hash reference with an
address@hidden key; @pxref{Reference Hash Args}).
-
address@hidden $no_close
address@hidden $no_open
-If @var{$text} is split into paragraphs, each paragraph is passed
-through the function, and @var{$no_close} is true if this is not the
-last paragraph, while @var{$no_open} is true if this is not the first
-paragraph.
-
address@hidden $line_nr
address@hidden \%state
address@hidden $command_stack
address@hidden \@@line_numbers
-See the previous section.
address@hidden table
address@hidden deftypefn
-
-
address@hidden HTML Customization for Anchors
address@hidden HTML Customization for Anchors
-
address@hidden HTML customization for anchors
address@hidden Anchors, customizing HTML for
-
-The HTML formatting of anchors (@pxref{anchor,, @code{@@anchor}}) is
-controlled by functions. To customize the output, the function
-reference @code{$anchor_label} should be redefined. The function
-should return the formatted text.
-
address@hidden {Function Reference} $anchor_label anchor_label $identifier
$anchor
address@hidden is the anchor identifier, and @var{$anchor} is the
address@hidden@@anchor} argument.
address@hidden deftypefn
-
-By default, this uses a function reference, @code{$anchor}, which can
-do a reference target or link. This is especially relevant for HTML
-but can potentially be used in other formats, since it is a rather
-common element among output formats.
-
address@hidden {Function Reference} $anchor anchor @
- $identifier $href $text $attributes
-If @var{$identifier} is not empty, its value should be used to create
-a target for links (typically associated with a name or id attribute
-in HTML). The @var{$href} argument specifies a hypertext reference
-which should be used to link to a target. If both @var{$identifier}
-and @var{$href} are given, the text produced should be both a target
-for @var{$identifier} and a link to @var{$href}. @var{$text} is the
-text to be displayed. @var{$attributes} are additional attributes for
-an @code{<a>} HTML element.
address@hidden deftypefn
-
-
address@hidden HTML Customization for Images
address@hidden HTML Customization for Images
-
address@hidden HTML customization for images
address@hidden Images, customizing HTML for
-
address@hidden @@IMAGE_EXTENSIONS
-To customize the images produced by @code{@@image} (@pxref{Images}),
-the first possibility is to modify the @code{@@IMAGE_EXTENSIONS}
-array, which holds a list of filename extensions for image files.
-
-Second, it is also possible to redefine the function used to determine
-the filename of the image:
-
address@hidden {Function Reference} $filename image_files @
- $basename $extension $texi_base $texi_extension
address@hidden is the first @code{@@image} argument, and
address@hidden is the corresponding @code{@@image} argument; both
-are formatted. @var{$texi_base} is the first @code{@@image} argument
-and @var{$texi_extension} is the extension, unformatted. This
-function reference should return an array of array references, each
-holding both formatted and unformatted image filenames without any path
-for which the main program should look.
address@hidden deftypefn
-
-Third, it is possible to control the formatting of @code{@@image} by
-redefining this:
-
address@hidden {Function Reference} $image image $file_path $basename @
- $preformatted $file_name $alt_text $width $height $raw_alt @
- $extension $working_dir $file_relative_path $in_paragraph @
- \@@file_locations $base_simple_format @
- $extension_simple_format $file_name_simple_format $line_nr
address@hidden @var
address@hidden $file_path
-The image file name with the path from the output directory to the
-source manual directory prepended.
-
address@hidden $basename
-The file name without extension---the first argument to the
address@hidden@@image} command.
-
address@hidden $preformatted
-True if the image appears in preformatted text.
-
address@hidden $file_name
-The file name without path but with extension.
-
address@hidden $alt_text
-The alternate text, possibly undefined.
-
address@hidden $width
address@hidden $height
-The corresponding @code{@@image} arguments.
-
address@hidden $raw_alt
-The unmodified alternate-text @code{@@image} argument.
-
address@hidden $extension
-The corresponding @code{@@image} argument.
-
address@hidden $working_dir
-Path to the working directory relative to the output directory.
-
address@hidden $file_relative_path
-The file name relative to @var{$working_dir}.
-
address@hidden $in_paragraph
-True if within a paragraph.
-
address@hidden \@@file_locations
-Array reference holding another array reference with 3 elements: the
-file name array reference as returned by @code{image_files}; the image
-location if it was found, or undef; and the file name formatted using
-simple formatting in string context.
-
address@hidden $base_simple_format
address@hidden $extension_simple_format
address@hidden $file_name_simple_format
-The corresponding arguments formatted using simple formatting in
-string context.
-
address@hidden $line_nr
-An opaque structure containing the information about the line number
-of the @@-command.
address@hidden table
address@hidden deftypefn
-
-
address@hidden HTML Customization for @code{sp}
address@hidden HTML Customization for @code{sp}
-
address@hidden HTML customization for @code{sp}
address@hidden @code{sp}, customizing HTML for
-
-The formatting of @code{@@sp} (@pxref{sp,,@code{@@sp}}) is controlled by:
-
address@hidden {Function Reference} $sp sp $number $preformatted
address@hidden is the numeric argument of @code{@@sp}.
address@hidden is true if the @code{@@sp} appears in preformatted
-text.
address@hidden deftypefn
-
-
address@hidden HTML Customization for Abbreviations
address@hidden HTML Customization for Abbreviations
-
address@hidden HTML customization for abbreviations
address@hidden @code{abbr}, customizing HTML for
address@hidden @code{acronym}, customizing HTML for
-
-The formatting of @code{@@acronym} and @code{@@abbr} (@pxref{acronym,,
address@hidden@@acronym}} and @ref{abbr,, @code{@@abbr}}) is controlled by:
-
address@hidden {Function Reference} $acronym acronym_like @
- $acronym_texi $acronym_text $with_explanation \@@explanation_lines @
- $explanation_text $explanation_simply_formatted
-
address@hidden is the original acronym argument with @@-commands,
-while @var{$acronym_text} is formatted.
-
-The other arguments are related to the explanation (the second arg of
-the acronym). @var{$with_explanation} is true if the second argument
-of the acronym command is present. If an explanation exists, coming
-from a previous @code{@@acronym} or as an argument to the present
-command, the remaining arguments are defined:
-
address@hidden @var
address@hidden \@@explanation_lines
-Array reference containing simply formatted explanation lines
-(@pxref{Init File Expansion Contexts}).
-
address@hidden $explanation_text
-Formatted explanation text.
-
address@hidden $explanation_simply_formatted
-Explanation simply formatted in a string context.
address@hidden table
address@hidden deftypefn
-
-
address@hidden HTML Customization for Text Sequences
address@hidden HTML Customization for Text Sequences
-
address@hidden HTML customization for text sequences
address@hidden Text sequences, customizing HTML for
address@hidden Ligatures in text, customizing HTML for
-
-Some character sequences are processed especially in text: @samp{---},
address@hidden, @samp{``} and @samp{''}. This should only be done only if
-in normal text and not within commands for preformatted output
-(@code{@@code}, @code{@@address@hidden). A function reference is called
-to process the text and take care of these constructs. It may also be
-used to transform the text, for example, convert to upper case if it
-is in @code{@@sc}. The function should also take care of protecting
-special characters.
-
address@hidden {Function Reference} $processed_text normal_text $text @
- $in_raw_text $in_preformatted $in_code $in_math $in_simple $command_stack
-Process @var{$text} and return @var{$processed_text}. The other
-arguments give some information about the context of the text.
-
address@hidden @var
address@hidden $in_raw_text
-True if the text appears in a place where there is no formatting at
-all; e.g., in comments.
-
address@hidden $in_preformatted
-True if within a preformatted environemnt
-
address@hidden $in_code
-True if within a special command such as @code{@@code} or @code{@@env}
-where the text sequences should be left as is.
-
address@hidden $in_math
-True if within @code{@@math}.
-
address@hidden $in_simple
-True if in a string context with minimal formatting.
-
address@hidden $command_stack
-Array containing the name of the formatting @@-commands that enclose
-the text.
address@hidden table
-
-By default, the @samp{---}, @samp{--}, @samp{``} and @samp{''}
-constructs are expanded if needed and the text is upper-cased if in
address@hidden@@sc}. Special characters (@samp{&}, @samp{"}, @samp{<} and
address@hidden>} in HTML) are protected if needed.
address@hidden deftypefn
-
address@hidden Protecting special output characters
address@hidden Output format characters, protecting
address@hidden HTML characters, protecting
-Some characters are special in a particular output format, such as
address@hidden<} in HTML. Some text is not processed by the above function,
-but still needs protection before output. This is done by the
-following:
-
address@hidden {Function Reference} $protected_text protect_text $text
-Process the general text @var{$text} and return the resulting
-protected text @var{$protected_text}.
address@hidden deftypefn
-
address@hidden Empty lines, removing
-Empty lines are processed by the following function reference, which
-can be useful if empty lines are to be removed.
-
address@hidden Definition commands, empty lines after
address@hidden {Function Reference} $resulting_text empty_line $empty_line
$state
-Process @var{$empty_line} and return @var{$resulting_text}.
address@hidden is a structure holding information about the state of
-parsing. By default, empty lines are left as-is except right after a
-definition @@-command.
address@hidden deftypefn
-
-
address@hidden HTML Customization for Title Commands
address@hidden HTML Customization for Title Commands
-
address@hidden HTML customization for title commands
address@hidden Title commands, customizing HTML for
-
address@hidden %line_command_map
-Some @@-commands related to titles appear on a line by themselves and
-take the rest of the line as their argument: @code{@@titlepage},
address@hidden@@title}, @code{@@subtitle}, and @code{@@author}
-(@pxref{Titlepage & Copyright Page}). These are listed in
address@hidden and the following function reference is used
-to format them:
-
address@hidden {Function Reference} $resulting_text line_command @
- $command $arg_text $arg_texi \%state
-
address@hidden the @@-command, @var{$arg_text} is the
-@@-command's formatted argument, and @var{$arg_texi} is the @@-command
-argument without any formatting. @var{\%state} is a hash reference
-containing context information. The function returns
address@hidden
address@hidden deftypefn
-
-For more customization of title pages, @pxref{HTML Title Page
-Customization}.
-
-
address@hidden Customizing HTML References
address@hidden Customizing HTML References
-
address@hidden References, HTML customization for
address@hidden Cross references, HTML customization for
-
address@hidden
-* Internal: HTML Customization for Internal References.
-* External: HTML Customization for External References.
address@hidden menu
-
-
address@hidden HTML Customization for Internal References
address@hidden HTML Customization for Internal References
-
address@hidden HTML customization for internal references
address@hidden Internal references, HTML customization for
-
-This function reference is used to format a reference to a node in the
-current manual (@pxref{Cross References}).
-
address@hidden {Function Reference} $text internal_ref $command $href
$short_name @
- $name $is_section \@@args_texi \@@formatted_args \%element
-
address@hidden @var
address@hidden $command
-The reference command, namely @code{ref}, @code{xref}, @code{pxref} or
address@hidden).
-
address@hidden $href
-An HTML href to the node.
-
address@hidden $short_name
address@hidden $name
-The text for the reference. @var{$short_name} can be the node name
-which is assumed to be no longer than the section name.
-
address@hidden $is_section
-True if the reference is to a sectioning element.
-
address@hidden \@@args_texi
address@hidden \@@formatted_args
-Array references containing the @@-command arguments, not formatted
-and formatted, respectively.
-
address@hidden \%element
-Hash reference with information about the target element of the
-reference.
address@hidden table
-
-The function should return the full formatted text of the internal
-reference.
address@hidden deftypefn
-
-
address@hidden HTML Customization for External References
address@hidden HTML Customization for External References
-
address@hidden HTML customization for external references
address@hidden External references, HTML customization for
-
-These references are produced by one of two function references:
address@hidden is used for menu items which refer to other
-manuals (@pxref{Other Info Files}), while @code{external_ref} is used
-for full external cross references (@pxref{Four and Five Arguments}).
-
address@hidden {Function Reference} $href external_href $node $node_identifier @
- $xml_node_identifier $file
-This function formats a reference to a node in an external Texinfo manual.
-
address@hidden @var
address@hidden $node
-The node name, with @@-commands.
-
address@hidden $node_identifer
-The node name mapped to an identifier acceptable as a file name.
-
address@hidden $xml_node_identifier
-The node name mapped to an identifier acceptable for XML.
-
address@hidden $file
-The manual file name of the external reference.
address@hidden table
-
-The function should return an HTML href for the external reference.
-
address@hidden Xref}, for how the identifiers are built in order to allow
-for cross references to external manuals to succeed.
address@hidden deftypefn
-
address@hidden {Function Reference} $text external_ref $command $section $book @
- $file $href $cross_ref_name \@@args_texi \@@formatted_args $node
-This function formats a general cross reference to an external Texinfo manual.
-
address@hidden @var
address@hidden $command
-The reference command (@code{ref}, @code{xref}, @code{pxref} or
address@hidden).
-
address@hidden $section
-The section in the external manual; may be empty.
-
address@hidden $book
-The book title; may be empty.
-
address@hidden $file
-The manual file name.
-
address@hidden $href
-An HTML href to the external manual constructed using the above
address@hidden function.
-
address@hidden $cross_ref_name
-Optional cross reference name appearing in the reference command.
-
address@hidden \@@args_texi
address@hidden \@@formatted_args
-Array references containing the @@-command arguments, not formatted
-and formatted, respectively.
-
address@hidden $node
-The node name, formatted.
address@hidden table
-
-The function should return the HTML text for the external manual
-reference.
address@hidden deftypefn
-
-
address@hidden Customizing HTML Footnotes
address@hidden Customizing HTML Footnotes
-
address@hidden Customizing HTML footnotes
address@hidden Footnotes, customizing HTML
-
-Each footnote is associated with a footnote entry. Several footnote
-entries are grouped in a footnote section. When a footnote appears,
-two things must be formatted: the footnote text, and the place in the
-main text where the footnote marker appears.
-
-It is possible to replace the footnote with other text before
-formatting the footnote. The following function reference
-is used for this if it is defined:
-
address@hidden {Function Reference} $added_text footnote_texi $footnote_text @
- \%state \@@command_stack
address@hidden @var
address@hidden $footnote_text
-The footnote text.
-
address@hidden \%state
-Hash referencing with information about the context of the footnote
-location in the main document. Specifically, the entries
address@hidden>@{'outside_document'@}} or
address@hidden>@{'multiple_pass'@}} can be used.
-
address@hidden \@@command_stack
-Array reference containing the commands enclosing the footnote.
address@hidden table
-
-This function should return new formatted text for the footnote.
address@hidden deftypefn
-
-Two functions, with corresponding function references, control the
-formatting of the footnotes:
-
address@hidden {Function Reference} {(\@@lines $doc_text)} foot_line_and_ref @
- $number_in_doc $number_in_page $footnote_id $place_id @
- $document_file $footnote_file \@@lines \%state
address@hidden @var
address@hidden $number_in_doc
-The footnote number counted through the whole document,
-
address@hidden $number_in_page
-The footnote number counted on the current page.
-
address@hidden $footnote_id
-An identifier for the footnote text, which should be used to make the
-target for references to the footnote.
-
address@hidden $place_id
-Identifier for the location of the footnote in the main document.
-
address@hidden $document_file
-Name of the file containing the text where the footnote appears in the
-main document
-
address@hidden $footnote_file
-Name of the file where the footnote text appears.
-
address@hidden \@@lines
-Array reference containing the footnote text lines, formatted.
-
address@hidden \%state
-Information about the context at the footnote location in the main
-document. As usual, the most useful entry is @code{preformatted},
-which is true if the footnote appears in a preformatted context.
address@hidden table
-
-The function should return a list of two elements: an array reference
-(@var{\@@lines}) containing the updated footnote text for the footnote
-entry, and a string (@var{$doc_text}), for the text to appear at the
-location of the footnote in the main document, i.e., linking to the
-footnote entry.
address@hidden deftypefn
-
-The following function is only used when footnotes are at the bottom
-of a page and the document is split. For customization in the case
-when footnotes are on a separate page or section, @pxref{Customizing
-Layout of Special Elements}. The footnote location is determined by
address@hidden (@pxref{Footnote Styles}).
-
address@hidden {Function Reference} foot_section \@@footnotes_lines
-This function formats a group of footnotes. @var{\@@footnotes_lines}
-is an array reference holding the lines of all the footnote entries
-formatted as explained above. The function should modify the
-reference.
address@hidden deffn
-
-
address@hidden Customizing HTML Block Commands
address@hidden Customizing HTML Block Commands
-
address@hidden Customizing HTML block commands
address@hidden Block commands, customizing HTML
address@hidden Environments, customizing HTML
-
address@hidden
-* Align: HTML Customization of Alignment Commands. @code{@@flushleft}, etc.
-* Preformatted block command formatting::
-* Other block commands formatting::
address@hidden menu
-
address@hidden HTML Customization of Alignment Commands
address@hidden HTML Customization of Alignment Commands
-
address@hidden HTML customization of alignment environments
address@hidden Customization of alignment environments
address@hidden Alignment environments, HTML customization of
address@hidden @code{@@center}, HTML customization of
address@hidden @code{@@flushleft}, HTML customization of
address@hidden @code{@@flushright}, HTML customization of
-
address@hidden %paragraph_style
-When a block with special text alignment of text is used, namely
address@hidden@@center} (@pxref{titlefont center sp},,
address@hidden@@address@hidden @code{@@address@hidden and @code{@@sp}),
address@hidden@@flushleft} or @code{@@flushright} (@pxref{flushleft &
-flushright,, @code{@@flushleft} and @code{@@flushright}}, the main
-program takes care of opening and closing paragraphs. The alignment
-commands are the keys in the @code{%paragraph_style} hash. The value
-is used in the function doing the formatting of the paragraphs
-(@pxref{Paragraph and preformatted region}).
-
-This function reference allows for customizing the formatting of the
-command argument.
-
address@hidden {Function Reference} $result paragraph_style_command $command
$text
address@hidden is the command name and @var{$text} is the text
-appearing within the command. This function should return the
-formatted text. The default is to return the text unmodified.
address@hidden deftypefn
-
-
address@hidden Preformatted block command formatting
address@hidden Preformatted block command (@code{@@example},
@code{@@address@hidden) formatting
-
-Here we see how a whole preformatted block command is
-formatted. For the formatting
-of the text, see @ref{Paragraph and preformatted region}.
-
address@hidden %complex_format_map
-The formatting of the block commands is ultimately controlled by a
-function, however the default for this function uses a hash and
-changing the hash values should be enough in most cases. This
-hash is called @code{%complex_format_map}. It has a key for each
-of the preformatted block commands (@code{example}, @code{smallexample},
address@hidden, @code{smalllisp}, @code{display}, @code{smalldisplay},
address@hidden, @code{smallformat}).
-
-The associated value is a reference on a hash. The keys are:
-
address@hidden @code
address@hidden begin
-The @code{begin} should lead to the beginning of the
-formatted output.
address@hidden end
-The @code{end} should lead to the end of the
-formatted output.
address@hidden class
-The HTML class. If not defined, the command name.
address@hidden pre_style
-The preformatted style. If not defined the corresponding @acronym{CSS} style
-is used.
address@hidden style
-If the associated value is @code{code}, the format is assumed to be in
-code style, where
-with @samp{---}, @samp{--}, @samp{''} and @samp{``} kept as is.
-If the key is absent the format inherits the code style
-and the font from the enclosing context.
address@hidden table
-The enclosed text will be formatted as described in
address@hidden and preformatted region}, and the name of the complex
-format will be available to the function formatting the text.
-
-If you aren't satisfied with this scheme, you can redefine the following
-function reference for a better control over the complex format formatting:
-
address@hidden {Function Reference} $complex_format_text complex_format
$format_name $preformatted_text
-
address@hidden is the complex format name, @var{$preformatted_text} is the
-text allready formatted as described in @ref{Paragraph and preformatted
region}.
-This function returns the whole complex format.
address@hidden deftypefn
-
address@hidden Other block commands formatting
address@hidden Formatting of other block commands (@code{@@verbatim},
@code{@@cartouche}, @code{@@quotation}, @code{@@html})
-
address@hidden FIXME verbatiminclude is distinct
-Regions corresponding with raw text, like @code{@@verbatim}, @code{@@html},
address@hidden@@tex} or the content of the file given in
@code{@@verbatiminclude}
-argument are formatted according to the following function reference:
-
address@hidden {Function Reference} $raw_region raw $command $text
address@hidden is the command name, @var{$text} is the raw text.
-In the default case, if @var{$command} is @code{verbatiminclude}
-the text is the content of the @code{@@verbatiminclude} file argument.
address@hidden deftypefn
-
-If address@hidden is used, @code{@@tex} regions are handled differently,
-(@pxref{Init File Formatting of Commands}).
-
-The @code{@@cartouche} command formatting is controlled by the
-function reference:
-
address@hidden {Function Reference} $cartouche cartouche $text
address@hidden is the text appearing within the cartouche.
address@hidden deftypefn
-
-The formatting of @code{@@quotation} and @code{@@smallquotation}
-is controlled by two function references.
-The first one is usefull in case the @code{@@quotation} has an argument, as
-it allows to prepend a string to the quotation text:
-
address@hidden {Function Reference} $prepended_string quotation_prepend_text
$command $text
address@hidden is the @@-command.
address@hidden is the argument of the quotation with @@-commands not
-interpreted. This function
-can return a string which will be prepended to the quotation text.
address@hidden deftypefn
-
-The whole quotation is formatted by:
-
address@hidden {Function Reference} $quotation quotation $command
$quotation_text $argument_text $argument_text_texi \@@quote_authors
address@hidden is the @@-command.
address@hidden is the quotation text, formatted, with the text
-prepended by the function above. @var{$argument_text} is the argument
-of the @code{@@quotation}, formatted. @var{$argument_text_texi} is the
argument
-of the @code{@@quotation}, simply formatted.
address@hidden@@quote_authors} is a reference on an array holding information
-about the @code{@@author} command arguments appearing within the
address@hidden@@quotation}. Each of the array element is a reference on a
-hash with the following keys:
address@hidden @code
address@hidden author_texi
-Texinfo code of this @code{@@author} line.
address@hidden author_text
-Formatted argument of the @code{@@author} line.
address@hidden table
address@hidden deftypefn
-
address@hidden Paragraph and preformatted region
address@hidden Formatting of paragraph and preformatted regions
-
-
address@hidden FIXME not sure that it is stable enough to be documented?
-If defined, the following function reference is called at the paragraph
-opening:
-
address@hidden {Function Reference} begin_paragraph_texi
$paragraph_or_preformatted \@@paragraph_at_commands $context_command \%state
\@@stack
address@hidden is @samp{paragraph} when opening a paragraph,
-or @samp{preformatted} at the beginning of a preformatted region.
address@hidden@@paragraph_at_commands} is a reference on an array containing the
-listof th ecommands with brace opened outside of the paragraph or
-preformatted. @var{$context_command} is a reference on a structure describing
-in what generalized block @@-command we are.
address@hidden holds informations about the current context.
address@hidden@@stack} is an opaque variable.
address@hidden deffn
-
address@hidden
-* Paragraph and preformatted formatting::
-* Avoiding paragraphs::
address@hidden menu
-
address@hidden Paragraph and preformatted formatting
address@hidden Paragraph and preformatted region formatting
-
-The formatting of a paragraph region or a preformatted region, is controlled
-by function references:
-
address@hidden {Function Reference} $paragraph_text paragraph $text $alignement
$index $formatting_command $formatting_command_formatted \$paragraph_number
$format $item_number $enumerate_style $number $command_stack_at_end
$command_stack_at_begin
-This function formats a paragraph. @var{$text} is the text of the paragraph,
address@hidden is the empty string when no alignement command has
-been seen, otherwise it is the current alignement command name (see
-the previous section).
address@hidden holds @samp{noindent} or @samp{indent} if the corresponding
-@@-command appeared in the paragraph.
address@hidden and @var{$command_stack_at_begin} are arrays
-containing the opened @@-commands at end and at beginning of the paragraph,
-latest on top.
-
-The remaining arguments are usefull when the paragraph appears within a
-list or table. It is usefull whenever the paragraph has to be formatted
-differently when appearing in such environments.
-Moreover in that case the format command (@code{@@address@hidden)
-may have an associated formatting command.
address@hidden is this formatting command
-(like @code{@@minus}).
address@hidden is the command formatted in html
-in case the formatting command is a leading command (like @code{@@minus})
-which should be leading the first paragraph.
address@hidden is a reference on the number of
-paragraphs in that format command. The corresponding variable should be
-increased when a paragraph is added. @var{$format} is the format command.
address@hidden and list items formatting}.
-
-If the @var{$format} is an enumerate, @var{$item_number} is the number of
-the item in the list, @var{$enumerate_style} is the argument of the enumerate,
address@hidden is the number or letter corresponding with this item.
address@hidden deftypefn
-
address@hidden {Function Reference} $preformatted_text preformatted $text
$style $region_name $formatting_command $formatting_command_formatted
\$preformatted_number $format $item_number $enumerate_style $number
$command_stack_at_end $command_stack_at_begin
-This function formats a preformatted region. @var{$text} is the text of the
-preformatted region, @var{$style} is the css style associated with that
-preformatted region (@pxref{Customizing CSS}). @var{$region_name} is the
-name of the command opening
-the preformatted region (@address@hidden, see @ref{Preformatted block command
formatting})
-or a identifier for the preformatted context (for example
address@hidden, see @ref{Menu formatting}).
-The alignment commands are not taken into account, as the spaces are
-preserved in preformatted regions, you should flush and center by hand.
address@hidden and @var{$command_stack_at_begin} are arrays
-containing the opened @@-commands at end and at beginning of the preformatted
-region, latest on top.
-
-The remaining arguments are usefull when the preformatted region appears
-within a list or table. It is usefull whenever the preformatted region
-has to be formatted
-differently when appearing in such environments.
-Moreover in that case the format command (@code{@@address@hidden)
-may have
-an associated formatting command.
address@hidden is this formatting command
-(like @code{@@minus}).
address@hidden is the command formatted in html
-in case the formatting command is a leading command (like @code{@@minus})
-which should be leading the first preformatted region.
address@hidden is a reference on the number of
-preformatted regions in that format command. The corresponding variable
-should be increased when a preformatted region is added. @var{$format} is the
-format command.
address@hidden and list items formatting}.
-
-If the @var{$format} is an enumerate, @var{$item_number} is the number of
-the item in the list, @var{$enumerate_style} is the argument of the enumerate,
address@hidden is the number or letter corresponding with this item.
address@hidden deftypefn
-
-A special function reference is called instead if the preformatted
-is empty and the function reference is defined:
-
address@hidden {Function Reference} $preformatted_text empty_preformatted $text
address@hidden is the text of th epreformatted which should contain only
-spaces. The function refernece should return the formatted text for
-this empty preformatted region.
address@hidden deftypefn
-
address@hidden Avoiding paragraphs
address@hidden Avoiding paragraphs in @@-commands
-
address@hidden Avoid paragraph opening
-
address@hidden %format_in_paragraph
-It is possible to avoid that a format closes the previous paragraph or
-preformatted region and reopens one, by putting the format command in a
-hash, @code{%format_in_paragraph} with a true value. This only
-makes sense for few commands since otherwise the nesting of formats and
-paragraphs could become wrong.
-
address@hidden %no_paragraph_commands
-If the value of @code{%no_paragraph_commands} associated with a command is
-true, no paragraph is started by the command if outside of a paragraph
-(after an empty line, for example). If the value is set to 0, it will start
-a paragraph. If the value is not set, reasonable defaults are
-set.
-
address@hidden %stop_paragraph_command
-It is also possible to stop a paragraph when an @@-command happens by
-putting the @@-command in the @code{%stop_paragraph_command} hash
-associated with a true value.
-
address@hidden Lists tables and definitions formatting
address@hidden Lists, tables and definitions formatting
-
address@hidden
-* Lists and tables formatting::
-* Definition formatting::
address@hidden menu
-
address@hidden Lists and tables formatting
address@hidden Customizing the formatting of lists and tables
-
-The formatting of lists and tables is done at two levels:
address@hidden
address@hidden
-At the level of the whole region (table or list),
address@hidden
-At the level of the individual items, rows or cells of the list or table.
address@hidden itemize
-
address@hidden
-* Table and list items formatting::
-* Whole table and list formatting::
address@hidden menu
-
-
address@hidden Table and list items formatting
address@hidden Formatting individual table and list items
-
-In texinfo it is possible to give @code{@@itemize} or table command (hereafter
-called a @dfn{format command}) a @dfn{formatting command}.
-For example @code{@@minus} is the formatting command here:
address@hidden
-@@table @@minus
address@hidden example
-
address@hidden %special_list_commands
-The default is to apply the command to the text item, however it is possible
-to avoid it.
-The hash @code{%special_list_commands} has an entry for each of the
-format command. Each of these entries is a hash reference. If a formatting
-command is a key of the hash reference, then the formatting command is not
-applied to the text item for that format command. For example, if we have:
-
address@hidden
address@hidden'itemize'@} = @{ 'bullet' => '' @};
address@hidden example
-
-and we have the following @code{@@itemize}:
address@hidden
-@@itemize @@bullet
-@@item an item
-@@end itemize
address@hidden example
-
-then @code{@@bullet} will not be applied to @code{an item}.
-
-Every time a @code{@@tab} or an @code{@@item} is encountered, the following
-function reference is called, if defined:
address@hidden {Function Reference} $result_line tab_item_texi $command
\@@command_stack \@@stack \%state $line $line_nr
address@hidden is the command name.
address@hidden@@command_stack} is an array with all the @@-commands opened,
latest
-on top.
address@hidden@@stack} is an opaque variable.
address@hidden holds informations about the current context.
address@hidden is the line appearing after the command.
address@hidden
-is an opaque structure containing the information about the line number of the
-@@-command.
-The function returns the line that may be further processed.
address@hidden deftypefn
-
-
-More control of the text before formatting of the line or the item is
-achieved with the following function reference:
-
address@hidden {Function Reference} ($result_line, $open_command)
format_list_item_texi $format $line $prepended $command $number
-The @var{$format} is the list or table @@-command,
address@hidden is the item line, @var{$command} is the @dfn{format command},
address@hidden is set to the text folllowing the @dfn{format command}
-on the format argument line.
-The @var{$number} is the number of the item, as set in @code{@@enumerate}.
-The @var{$result_line} replaces the item argument.
address@hidden is an obsolete return code that can be set to
-anything.
address@hidden deftypefn
-
-Then the different @@-commands items are formatted thanks to
-function references:
-
address@hidden @strong
address@hidden lists
-The items of lists are formatted using the following function reference:
address@hidden {Function Reference} $list_item list_item $text $format $command
$formatted_command $item_number $enumerate_style $number $prepended_texi
$prepended_formatted $only_inter_item_commands $before_items $item_command
-This function formats the text between @code{@@item} commands. @var{$text}
-is the text corresponding with the item. @var{$format} is the type of format,
address@hidden or @samp{enumerate}. @var{$command} is the formatting command
-given in argument to @code{@@itemize}, @var{$formatted_command} is this command
-formatted if it is a leading command, like @code{@@minus}.
-
-If the @var{$format} is an enumerate, @var{$item_number} is the number of
-the item in the list, @var{$enumerate_style} is the argument of the enumerate,
address@hidden is the number or letter corresponding with this item.
-
-If the @var{$format} is an itemize, @var{$prepended_texi} is the text that
-appeared on the itemize line, maybe after the formatting command
-(if any), and @var{$prepended_formatted} is the corresponding text,
-formatted.
-
address@hidden is true if there are only @@-commands
-that are not considered as the item argument in the item, like
-index entries.
address@hidden is set if there is in fact no leading @code{@@item}
-for the text, as it may happen for some text following the @var{$format}
-@@-command, as in
-
address@hidden
-@@table @@asis
-Tex before items.
-
address@hidden example
address@hidden is the item command name.
-
address@hidden deftypefn
-
address@hidden two column tables
-The two columns tables (@code{@@table}, @code{@@ftable} and @code{@@vtable}),
-items are formatted using two function references,
-one for the first line located on the @code{@@item} line corresponding
-with the first column, the other for the text appearing on the
-following lines, corresponding with the second column text.
-
address@hidden {Function Reference} $table_item table_item $item_text
$index_label_text $format $command \@@command_stack $item_command
$formatted_index_entry
-This function is used to format the text on the @code{@@item} line.
address@hidden is the text line. In case there is an index entry
-associated with the @code{@@item} (as with @code{@@ftable} and
address@hidden@@vtable}), @var{$index_label_text} is the text inserted at
-the place where an index entry appears. @xref{Index entry place formatting}.
address@hidden is the type of format,
address@hidden, @samp{ftable} or @samp{vtable}. @var{$command} is the
formatting command
-given in argument to the table format command.
address@hidden@@command_stack} is an array with all the @@-commands opened,
latest
-on top.
address@hidden is the item command, @samp{@@item} or @samp{@@itemx}.
address@hidden is the index entry formatted.
address@hidden deftypefn
-
address@hidden {Function Reference} $table_line table_line $text
-This function is used to format the text on the lines following
-the @code{@@item} line. @var{$text} is the corresponding text.
address@hidden deftypefn
-
address@hidden multitable
address@hidden Formatting}
-The multitable elements formatting is controlled by the functions associated
-with two function references. One for a cell, and the other for a row.
-
address@hidden {Function Reference} $multitable_cell cell $text $item_command
\@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
-This function is used to format the text of a multitable cell, the text
-following a @code{@@item} or a @code{@@tab}.
address@hidden is the corresponding text. @var{$item_command} is the command
-used to introduce the row, such that it is possible to distinguish
-between @code{@@item} and @code{@@headitem}.
address@hidden@@columnfractions} is a reference on an array
-containing the @code{@@columnfraction} arguments, if any, and
address@hidden@@prototype_row} is a reference on an array containing the row
prototypes
-given on the @code{@@multitable} line, if any.
address@hidden@@prototype_lengths} array contains the lengths of the row
prototypes
-formatted.
address@hidden is the maximal number of columns.
address@hidden deftypefn
-
address@hidden {Function Reference} $multitable_row row $text $item_command
\@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
-This function is used to format a multitable row. @var{$text} is
-the row text, with cells allready formatted with the @code{$cell}
-function reference. @var{$item_command}, @var{\@@columnfractions},
address@hidden@@prototype_row}, @var{\@@prototype_lengths}
-and @var{$column_number} are the same than in the function reference above.
address@hidden deftypefn
-
address@hidden table
-
-By default, this function is interlinked with
address@hidden (@pxref{Init File General Block Commands})
-and @code{@@multitable} formatting since a stack of possibly nested
-multitables is stored in order to know the cell number.
-
-
address@hidden Whole table and list formatting
address@hidden Formatting of a whole table or list
-
address@hidden %format_map
-If the Texinfo command is a key of the @code{%format_map}, the associated
-value is used to specify the formatting of the construct, otherwise a function
-is called.
-The value in @code{%format_map} associated with a command is interpreted
-similarly with values associated with more simpler commands:
-
address@hidden
address@hidden
-If the text is a word, in HTML or XML, it is considered to be an XML
-or HTML element
-name, and the whole table or list is enclosed between the element opening
-and the element closing.
address@hidden
-If the text is a word followed by some text,
-the word and is interpreted as above, and the
-text is considered to be the attributes text of the element.
address@hidden
-If the text is empty nothing is added to the text.
address@hidden itemize
-
-In case the @code{%format_map} isn't used, a function reference called
address@hidden
-should be redefined, the associated function will be called each time
-a command isn't found in @code{%format_map}.
-
address@hidden {Function Reference} $whole_table_list table_list
$format_command $text $command $formatted_command $item_nr $enumerate_style
$prepended_texi $prepended_formatted \@@columnfractions \@@prototype_row
\@@prototype_lengths $column_number
address@hidden is the Texinfo command name, @var{$text} is the
-formatted items. @var{$command} is the @dfn{format command} given in argument
-to the format command, @var{$formatted_command} is the same, but formatted.
address@hidden is the remaining text on the format command line,
address@hidden is the same, but formatted.
-Only relevant in @code{@@enumerate}, @var{$item_nr} is the item number, and
address@hidden is the @code{@@enumerate} style. Only relevant in
address@hidden@@multitable}
address@hidden@@columnfractions} is a reference on an array
-containing the @code{@@columnfraction} arguments, if any,
address@hidden@@prototype_row} is a reference on an array containing the row
prototypes
-given on the @code{@@multitable} line, if any,
address@hidden@@prototype_lengths} array contains the lengths of the row
prototypes
-formatted and
address@hidden is the maximal number of columns.
address@hidden deftypefn
-
-If you still want to use @code{%format_map} but differently from
-the default, it is possible to redefine the following function reference:
-
address@hidden {Function Reference} $whole_table_list format $command $format
$text
address@hidden is the @@-command, @var{$format} is the entry associated with
address@hidden in @code{%format_map}. @var{$text} is the formatted items.
address@hidden deftypefn
-
-
address@hidden Definition formatting
address@hidden Interpretation and formatting of the definition formatting
-
-The formatting of definition commands is controlled by a main hash,
-3 strings and another hash, and and five
-functions. The main hash describes how the text on the definition line is
-interpreted, the functions control the formatting of the definition line
-and the definition function text.
-
address@hidden
-* Definition line interpretation::
-* Definition command formatting::
address@hidden menu
-
-
address@hidden Definition line interpretation
address@hidden Customizing the interpretation of a definition line
-
address@hidden %def_map
-The keys of the hash @code{%def_map} are definition command names.
-There are two types of entries:
-
address@hidden
-
address@hidden If the command is a shortcut for
-another definition command the value is a text and the definition
-command is replaced by the text.
-
-For example if we have:
address@hidden
address@hidden'deftruc'@} = '@@defvr @{A address@hidden';
address@hidden example
-
-and a line like
address@hidden
-@@deftruc var
address@hidden example
-
-the line will be transformed in
address@hidden
-@@defvr @{A address@hidden var
address@hidden example
-
address@hidden
-If the command is not a shortcut, it is associated with an array
-reference. The first element is @samp{f}, @samp{v} or @samp{t} corresponding
-with the index type (@samp{f} for function, @samp{v} for variable,
address@hidden for type).
-
-The remaining of the array describes how to interpret the text following
-the definition command on the definition command line.
-The entry item specify what corresponds
-with the next bracketed item or word. Currently the possibilities are
address@hidden, @samp{name}, @samp{type}, @samp{class}, @samp{arg}
-and @samp{argtype}. @samp{arg} means that the arguments are not mixed
-with type definitions, with @samp{argtype} types are mixed with
-definitions. When there is no @samp{arg} nor @samp{argtype} it is
-the same than @samp{argtype}.
-
-For example if we have
address@hidden
address@hidden'defvr'@} = [ 'v', 'category', 'name' ];
address@hidden example
-
-The first bracketed item following @code{@@defvr} is considered
-to be the category and the next one is the name. The index associated
-with the definition line is the variables index.
address@hidden itemize
-
-Some characters are special with regard with definition parsing, they
-are delimiters, the can have a role in definition argument determination,
-and also hae a special meaning in arguments parsing.
-This is not very well documented in the Texinfo manual,
-so it is subject to change. Strings allow to determine the delimiters:
-
address@hidden @code
address@hidden $def_argument_separator_delimiters
-Characters that separate arguments, currently @code{()[],}.
address@hidden $def_always_delimiters
-Character that are always delimiters, if they appear in a type or a
-parameter,
address@hidden()[]}.
address@hidden $def_in_type_delimiters
-Character that are considered as delimiters only if in a type. In
-a parameter they are part of the parameter.
address@hidden vtable
-
-
address@hidden Definition command formatting
address@hidden Customization of the definition formatting
-
-Five functions are used when formatting a definition command:
-
address@hidden @strong
address@hidden category name
address@hidden {Function Reference} $category definition_category $category
$class $style $command
-This function precise a category name associating a class
address@hidden (if given) with @var{$category}. The @var{$style} of the
-definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t},
-for type. The @var{$command} is the definition @@-command.
address@hidden deftypefn
-
address@hidden {Function Reference} $entry definition_index_entry $name $class
$style $command
-This function precise a name associating a class
address@hidden (if given) with @var{$name}. This is used to do an index
-entry associated with th edefinition command. The @var{$style} of the
-definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t},
-for type. The @var{$command} is the definition @@-command.
address@hidden deftypefn
-
address@hidden formatting of the definition line
address@hidden {Function Reference} $line def_line $class_category_class $name
$type $arguments $index_label \@@arguments_array \@@arguments_type_array
\@@unformatted_arguments_array $command $class_name $category $class $style
$original_command
-This function formats the definition line. @var{$class_category} is the
-category
-formatted with @code{$definition_category}, @var{$name}, @var{$type} and
address@hidden are the element of the definition line. @var{$index_label} is
-the text inserted at the place where an index entry appears.
address@hidden entry place formatting}.
address@hidden@@arguments_array} is an array holding the definition arguments,
-formatted. @var{\@@arguments_type_array} holds the type of the definition
-arguments, like @samp{name}, @samp{type} and similar arguments,
address@hidden
address@hidden and @samp{param}. @var{\@@unformatted_arguments_array}
-holds the arguments without @@-command substitution. @var{$command} is the
-definition command, after substitution.
address@hidden is the class applied on name, formatted
-as specified in @code{definition_index_entry}. @var{$category} and
address@hidden are the corresponding arguments. @var{$style} corresponds
-with the index style, as explained above. @var{$original_command} is the
-unmodified definition @@-command.
address@hidden deftypefn
-
address@hidden definition text
address@hidden {Function Reference} $definition_text def_item $text
$only_inter_item_commands $command
-This function formats the definition text, @var{$text}.
address@hidden is true if there are only @@-commands
-that are not considered as the definition argument in the definition
-text, like index entries.
address@hidden is the definition @@-command.
address@hidden deftypefn
-
address@hidden the whole definition
address@hidden {Function Reference} $definition def $text $command
-This function formats the whole definition. The definition line and text
-formatted by the above functions are in @var{$text}.
address@hidden is the definition @@-command.
address@hidden deftypefn
-
address@hidden table
-
address@hidden Menus indices and floats formatting
address@hidden Menus, indices and floats formatting
-
address@hidden
-* Menu formatting::
-* Indices formatting::
-* Floats and lists of floats formatting::
address@hidden menu
-
address@hidden Menu formatting
address@hidden Menu formatting
-
-There are two possibilities for menu formatting:
-
address@hidden @bullet
address@hidden format the whole menu in a preformatted environment, like
-in @ref{Preformatted block command formatting};
address@hidden format the menu in table with more specialized formatting for
each
-part of the menu;
address@hidden itemize
-
-The simple formatting in a preformatted is used if
-the configuration variable @code{SIMPLE_MENU} is true,
-otherwise the format with tables is used (this is the default).
-
-In HTML, if the configuration variable @code{USE_ACCESSKEY} is set,
-the @code{accesskey} attribute is used in anchors. In that case the
address@hidden hash is used for the access key.
-
-In @command{texi2any}, a menu is considered to be composed of 2 parts, the
address@hidden entries} and the @dfn{menu comments} (@pxref{Writing a Menu}).
-Menu entries are further
-divided in an @dfn{entry link} and optionnaly an @dfn{entry description}.
-The entry link consists in a node name and an optional menu entry
-name (@pxref{Menu Parts}).
-
address@hidden
-* Menu components formatting::
-* Simple menu formatting:: formatting of a whole menu in a simple
- preformatted environement
-* Table menu formatting:: formatting of a whole menu in a
- table environment
address@hidden menu
-
-
address@hidden Menu components formatting
address@hidden The formatting of the different menu components
-
-If in a preformatted context (and @code{SIMPLE_MENU} isn't set), the
-menu link and description are put in the same preformatted environment.
-This can be avoided with the configuration variable
address@hidden
-
-Two function references are associated with the formatting of the
-different parts of a menu:
address@hidden {Function Reference} $link menu_link $section \%state $href
$node $name $ending $has_name \@@command_stack $preformatted
$node_normalized_formatted
address@hidden is the section name corresponding with the link, @var{$href}
-is the link hypertextual reference. @var{$href} may be absent.
address@hidden holds informations about the current context.
address@hidden is the node name, @var{$name} is the
-name of the node. @var{$ending} is the text ending the link entry,
-in general @samp{::} followed by some spaces.
address@hidden is true if the entry has an explicit name, otherwise
address@hidden has been constructed using the formatted node name.
address@hidden@@command_stack} is an array containing the commands enclosing
-the menu link. It is used in the default case to detect if the
-menu link is right in the @command{@@menu} or not, since if it is not
-right below the menu the formatting is simpler.
address@hidden is true if in preformatted context.
address@hidden File Expansion Contexts}.
address@hidden is the node with spaces normalized
-and formatted.
address@hidden deftypefn
-
-This command is not called if @code{SIMPLE_MENU} is set.
-
address@hidden {Function Reference} $description menu_description
$description_text \%state $element_text
address@hidden is the text of the menu description.
-The formatted link is also here if in preformatted context and
address@hidden is not set.
address@hidden
-should be used similarly than for the menu link. @var{$element_text}
-is the heading of the element associated with the node.
address@hidden and @var{$preformatted} are the same than for the
-menu link.
address@hidden deftypefn
-
-The @dfn{menu comment} part is formatted like a normal command,
-called @code{menu_comment}. It is only used if not in preformatted
-environment.
-The default is to have it be formatted
-like a @ref{Preformatted block command formatting}, with
address@hidden
address@hidden'menu_comment'@} =
address@hidden
- 'begin' => "<tr><th colspan=\"3\" align=\"left\" valign=\"top\">",
- 'end' => "</th></tr>", 'class' => 'menu-comment',
address@hidden
address@hidden example
-
-
address@hidden Simple menu formatting
address@hidden Simple menu formatting in a preformatted environment
-
-If the menu is to be formatted in a single preformatted environment,
-an entry for @samp{menu} and @samp{detailmenu}
-should be added to the @code{%complex_format_map}
-hash (@pxref{Preformatted block command formatting}).
-In the default case, if the user didn't add an entry himself, a very simple
-entry is used, with:
-
address@hidden
-$complex_format_map->@{'menu'@} = @{ 'begin' => '' , 'end' => '',
- 'class' => 'menu-preformatted' @};
address@hidden example
-
-
address@hidden Table menu formatting
address@hidden The formatting of the menu in a table
-
-In the default case, the name of the section corresponding with the
-node is used instead of the node name. If the configuration
-variable @code{NODE_NAME_IN_MENU} is
-true, however, node names are used. If the configuration variable
address@hidden
-is true and menu entry equal menu description the description is not printed.
-This is the default. Likewise, if node or section name equal entry name,
-do not print entry name.
-
address@hidden $MENU_SYMBOL
address@hidden $UNNUMBERED_SYMBOL_IN_MENU
-A symbol, @code{$MENU_SYMBOL} is put at the beginning of menu entries
-when the node name is used. The default is @samp{•} for HTML, @samp{*}
-for text formats.
-If @code{$UNNUMBERED_SYMBOL_IN_MENU} is true it is
-also put at the beginning of unnumbered section names (in HTML). This is not
-done by default.
-
address@hidden $MENU_PRE_STYLE
address@hidden $MENU_PRE_COMPLEX_FORMAT
-The menu comments are considered to be preformatted text. The style
-associated with this preformatted text is determined by
address@hidden Default is @samp{font-family: serif}.
-The entry similar with an entry in @code{%complex_format_map}
-(@pxref{Preformatted block command formatting}) used when the menu
-appears in a preformatted
-enviroment is in
address@hidden, and, in the default case is:
address@hidden
-$MENU_PRE_COMPLEX_FORMAT = @{
- 'pre_style' => $MENU_PRE_STYLE,
- 'class' => 'menu-preformatted'
- @};
address@hidden example
-
-The CSS class associated with menu comments is @code{menu-comments}.
-
-The following function reference controls the formatting of a wole menu
-or a detailmenu in that case:
-
address@hidden {Function Reference} $menu menu_command $command
$menu_components_text
address@hidden is the menu command, currently @samp{menu}, @samp{detailmenu}
-or @samp{direntry}.
address@hidden is the formatted menu components text, obtained
-as explained above.
address@hidden deftypefn
-
-
address@hidden Indices formatting
address@hidden Indices formatting
-
-Two different things needs to be handled for indices formatting, the place
-where the index term appears, the index entry, and the index list itself.
-The indexing commands like @code{@@cindex} determines where index entries
-appear, and the index list is printed with a @code{@@printindex} command.
-
address@hidden
-* Index entry place formatting:: Index entries in the main document are
- targets for hypertext references
-* Index list formatting:: Customizing the formatting of the index list
address@hidden menu
-
-
address@hidden Index entry place formatting
address@hidden Formatting of index entries
-
-Index entry places in the main text may be the target for
-references. Their formatting
-is controlled by the function associated with the following function
-reference:
-
address@hidden {Function Reference} $target index_entry_label $identifier
$preformatted $entry $index_name $index_command $texi_entry $formatted_entry
$in_region_not_in_output \%index_entry
address@hidden should be used to create
-a target for links (typically associated with a name or id
-attribute in HTML).
address@hidden is true if the index entry appeared in preformatted text.
address@hidden is the index entry with all the @@-commands removed.
address@hidden is the index name, @var{$command} is the index command which
-may be a index command like @code{@@cindex}, but also a definition or
-a table. @var{$texi_entry} is the index entry with @@-commands, and
address@hidden the entry formatted.
address@hidden is set if the index entry appears in a region
-formatting (for example @code{@@titlepage}) and not in the
-output document.
address@hidden is a reference on a hash holding informations about
-the index entry.
address@hidden deftypefn
-
-Regular index entries are (like @code{@@cindex}) are
-formatted using the following function reference:
address@hidden {Function Reference} $index_entry index_entry_command $command
$index_name $label $entry_texi $entry_formatted
address@hidden, @var{$index_name}, @var{$entry_texi} and @var{$entry_formatted}
-are the same as above, and @var{$label} is what could be used as a label,
-formatted using the function above.
address@hidden deftypefn
-
-
address@hidden Index list formatting
address@hidden Customizing the formatting of index lists
-
-There is an elaborate default index formatting, with
-index summary by letter linking to index entries grouped by letters too,
-with the possibility of index pages split accross files. This system may be
-completly bypassed by redefining the function reference that is called when
address@hidden@@printindex} is encountered:
-
address@hidden {Function Reference} $index_text printindex $index_name
\%printindex
address@hidden is the index name appearing on the
address@hidden@@printindex} line.
address@hidden is a reference on a hash holding informations
-on the index.
-The index formatted should be returned by this function reference.
address@hidden deftypefn
-
-If the default index formatting is used, there are still possibilities
-to customize part of the formatting.
-The index entries are sorted alphabetically. A whole index list is
-considered to be composed of letter entries. A letter entry is composed
-by all the index entries beginning with that letter. A letter may
-be a non alphabetical character, but we call it letter here.
-
-An index summary appears at the beginning and at the end of an index list,
-and should be used to jump directly to a letter entry. Indices lists
-may be split across pages, thus the different letters may appear on different
-files. The number of index entries appearing on each page is determined
-by a configuration variable @code{SPLIT_INDEX}, if set. The default is not
-to split indices.
-
-The formatting of all these elements is controlled by the following
-function references:
-
address@hidden @emph
address@hidden formatting of a letter in a summary
address@hidden {Function Reference} {($result_letter, $identifier, $is_symbol)}
summary_letter $letter $file $identifier $index_element_id $number
$index_element $index_name
-This function is used to format a letter appearing in a summary, refering
-to a letter entry in the index list.
address@hidden is the letter. @var{$file} is the file name where the letter
-entry appears. More precisely, it is empty when the letter entry is on the
-same page than the summary, it contains the file name when the index page
-is split accross page. @var{$identifier} is an identifier for the target
-letter entry. @var{$index_element_id} is the identifier associated with the
-element holding the letter. @var{$number} and @var{$index_element} are
-not specified. @var{$index_name} is the name of the index.
-The function returns the resulting letter @var{$result_letter}, an
-identifier for the letter @var{$identifier}, to be used in anchors, for example
-and @code{$is_symbol} should be true if the letter is not a regular letter
-but a symbol.
address@hidden deftypefn
-
address@hidden formatting of a summary
address@hidden {Function Reference} $summary index_summary
\@@alphabetical_letters \@@nonalphabetical_letters
address@hidden@@alphabetical_letters} and @var{\@@nonalphabetical_letters}
contain the
-formatted summary letters, formatted with the above function.
address@hidden deftypefn
-
address@hidden formatting of an index entry
address@hidden {Function Reference} $entry index_entry $entry_href $entry_text
$element_href $element_heading $entry_file $element_file $entry_target
$entry_element_target $in_region_not_in_output \%index_entry
address@hidden is a reference to the place where the index entry
-appeared, @var{$entry_text} is the corresponding text. @var{$element_href}
-is a reference to the beginning of the element containing
-the index entry, @var{$element_heading} is the heading of the element.
address@hidden is the file where the index entry appear, while
address@hidden is the file of the element. @var{$entry_target} is the
-target of the index entry, @var{$entry_element_target} is the
-element target.
address@hidden is set if the index entry appears in a region
-formatting (for example @code{@@titlepage}) and not in the
-output document.
address@hidden is a reference on a hash holding informations about
-the index entry.
address@hidden deftypefn
-
address@hidden formatting of letter entry
address@hidden {Function Reference} $letter_entry index_letter $letter
$identifier $index_entries_text
-This function formats a letter entry, consisting in all the index entries
-beginning with this letter. @var{$letter} is the letter, @var{$identifier}
-should be used to create a target for links (typically links from summaries),
-and @var{$index_entries_text} is the text of the index entries formatted as
-described above.
address@hidden deftypefn
-
address@hidden formatting of whole index
address@hidden {Function Reference} $index print_index $index_text $index_name
address@hidden is the text of all the index entries grouped by letter
-appearing in that page formatted as above. It is undef if there are
-no entries or theindex name isn't known. @var{index_name} is the name of
-the index, the argument of @code{@@printindex}.
address@hidden deftypefn
address@hidden table
-
-
address@hidden Floats and lists of floats formatting
address@hidden Floats and lists of floats
-
-Floats appear in the @code{@@float} environment, optionaly with a style
-and a label, and with optionnal @code{@@caption} and @code{@@shortcaption}.
-Their list appear after a @code{@@listoffloats}.
-
-A hash reference is associated with each float, it is available in some
-formatting functions. The keys are:
address@hidden @code
address@hidden caption_texi
address@hidden shortcaption_texi
-A reference on an array containing the caption or shortcaption lines,
-with texi @@-commands.
address@hidden style_texi
-The style with texi @@-commands.
address@hidden style_id
-The unique identifier associated with the style.
address@hidden style
-The style formatted.
address@hidden nr
-The number with the same conventions than makeinfo (use the chapter number a
-dot and then the number of the float of that style in the chapter, or an
-absolute number if in unnumbered).
address@hidden chapter_nr
-The number of the chapter containing the float.
address@hidden nr_in_chapter
-The number of the float in the chapter.
address@hidden absolut_nr
-The number of the float in the document.
address@hidden texi
-The label with @@-commands.
address@hidden name
-The label formatted.
address@hidden id
-The unique identifier associated with the label. Usefull to make an anchor
-or a reference.
address@hidden target
-The target that can be used to refer to that float.
address@hidden element
-A reference on a structure representing the element the float appear in.
address@hidden table
-
address@hidden
-* Float formatting:: Formatting of floats
-* List of floats formatting:: Formatting the lists of floats
address@hidden menu
-
address@hidden Float formatting
address@hidden Formatting a float
-
-First there is an occasion to construct a texinfo text for the caption, using
-the caption texinfo lines and the informations in the float structure.
-The returned lines will be formatted in the main program. A function reference
-is used here:
-
address@hidden {Function Reference} {(\@@caption_lines_returned,
\@@shortcaption_lines_returned)} caption_shortcaption \%float \@@caption_lines
\@@shortcaption_lines
address@hidden is the structure defined above. @var{\@@caption_lines} and
address@hidden@@shortcaption_lines} are references on arrays containing the
-texinfo lines for caption and short caption. @var{\@@caption_lines_returned}
-and @var{\@@shortcaption_lines_returned} are references on an array
-containing the texinfo lines for the caption and shortcaption.
address@hidden deftypefn
-
-Then the float is formatted with the following function reference:
-
address@hidden {Function Reference} $text float $float_text \%float
$caption_text $shortcaption_text
address@hidden is the text appearing within the @code{@@float}, formatted.
address@hidden is still the structure defined above. @var{$caption_text} and
address@hidden are the caption and short caption build with the
-above function and formatted.
address@hidden deftypefn
-
-It is also possible to do something when a caption or a shortcaption appear
-with the following function reference:
-
address@hidden {Function Reference} $text caption_shortcaption_command $command
$formatted_caption \@@texi_lines \%float
address@hidden is the @@-command, @samp{caption} or @samp{shortcaption}.
address@hidden is the caption text, formatted, while
address@hidden@@texi_lines} is a reference on an array containing the caption
lines,
-this time without any formatting.
address@hidden is still the structure defined above.
-
-In the default case this function reference returns an empty string.
address@hidden deftypefn
-
-
address@hidden List of floats formatting
address@hidden Formatting lists of floats
-
-A list of floats is introduced by @code{@@listoffloats}. The argument of
address@hidden@@listoffloats} is the @dfn{style}. First the style texinfo can
be
-modified with the following function reference:
-
address@hidden {Function Reference} $style_texi_returned listoffloats_style
$style_texi
address@hidden is the @code{@@listoffloats} argument with texinfo
-@@-commands kept. It is possible to make changes to the @var{$style_texi} and
-return a modified string, still with @@-commands. The modified string
-is formatted in the main program.
address@hidden deftypefn
-
-After that, for each of the floats with that style, first there is a
-possibility to modify the float style and the float caption before they
-are formatted in the main program, with the following function references:
-
address@hidden {Function Reference} $float_style_texi_returned
listoffloats_float_style $style_texi \%float
address@hidden is the style, and @var{\%float} is the structure described
-above. This function reference returns a style to be formatted in the
-main program.
address@hidden deftypefn
-
address@hidden {Function Reference} (\@@caption_texi_returned,
$caption_or_shortcaption) listoffloats_caption \%float
address@hidden is the structure described
-above. This function reference returns a caption to be formatted in the
-main program, @var{\@@caption_texi_returned}, and a string,
address@hidden that is either @samp{caption} or
address@hidden that can be used by the main program if this information
-is needed.
address@hidden deftypefn
-
-Each entry is formatted by:
-
address@hidden {Function Reference} $listoffloats_entry listoffloats_entry
$style_texi \%float $float_style $caption $href
address@hidden is the style with @@-commands, @var{$float_style} is the
-style returned by the above function and formatted. @var{$caption} is the
-caption returned by the above function formatted. @var{\%float} is the
-structure corresponding with the float, and @var{$href} is an href pointing to
-the float location.
address@hidden deftypefn
-
-Lastly, the whole @code{@@listoffloats} is formatted by:
-
address@hidden {Function Reference} $listoffloats listoffloats $style_texi
$style \@@listoffloats_entries
address@hidden is the style with @@-commands, @var{$style} is the
-style returned by the above function and formatted. The array reference
address@hidden@@listoffloats_entries} holds the entries formatted by the above
-function.
address@hidden deftypefn
-
address@hidden Handling special regions
address@hidden Handling special regions
-
address@hidden %region_formats_kept
-Special regions @code{@@titlepage}, @code{@@documentdescription} and
address@hidden@@copying} are removed from the document before the last pass in
the
-default case. They can be kept if the value associated with the @@-command
-in the @code{%region_formats_kept} hash is true.
-
-The following function reference is called when starting the
-formatting of a special region, if defined:
-
address@hidden {Function Reference} begin_special_region $region_name \%state
\@@region_lines
address@hidden is the region name.
address@hidden holds informations about the context of the region formatting.
address@hidden@@region_lines} holds the region lines.
address@hidden deffn
-
-The following function reference is called when ending the formatting
-of the special region, if defined:
-
address@hidden {Function Reference} $formatting_result end_special_region
$region_name \%state $formatted_region
address@hidden is the region name.
address@hidden holds informations about the context of the region formatting.
address@hidden is the result of the region formatting.
-The function reference returns the result of the region formatting, after
-possibly modifying it.
address@hidden deftypefn
-
-The @code{@@insertcopying} @@-command is formatted by
address@hidden {Function Reference} $insertcopying insertcopying $text $comment
$simple_text
address@hidden is the text appearing in @code{@@copying}, formatted.
address@hidden is the text with texi removed, should be very simple
-text.
address@hidden is the text formatted in string context
-with minimal formatting but no elements.
address@hidden deftypefn
-
-The copying commane that is to be used at the beginning of output
-files is formatted by
address@hidden {Function Reference} $copying_comment_formatted copying_coment
\@@copying_lines $text $comment $simple_text
address@hidden@@copying_lines} is an array containing the Texinfo lines in
@code{@@copying}.
address@hidden is the text appearing in @code{@@copying}, formatted.
address@hidden is the text with texi removed, should be very simple
-text.
address@hidden is the text formatted in string context
-with minimal formatting but no elements.
address@hidden deftypefn
-
address@hidden@@documentdescription} is handled by the following function
-reference, that should set the configuration variable
@code{documentdescription}:
-
address@hidden {Function Reference} documentdescription
\@@documentdescription_lines $text $comment $simple_text
address@hidden@@documentdescription_lines} is an array containing the Texinfo
lines in @code{@@documentdescription}.
address@hidden is the text appearing in @code{@@documentdescription}, formatted.
address@hidden is the text with texi removed, should be very simple
-text.
address@hidden is the text formatted in string context
-with minimal formatting but no elements.
address@hidden deffn
-
address@hidden Title Page Customization}, for specifics about the title
-page handling.
-
-
address@hidden Other and unknown commands
address@hidden Customizing other commands, and unknown commands
-
address@hidden skipped command
address@hidden unknown command
-
-Many commands without braces are available in Texinfo, sometimes with
-a specific syntax. For example we have @code{@@sp}, @code{@@noindent},
address@hidden@@documentlanguage}, @code{@@oddheading}, @code{@@headings},
address@hidden@@shortcontents}, @code{@@shorttitlepage} or @code{@@comment}.
address@hidden interprets
-some of these commands and some functions or variables are used for
-their formatting or to access their information.
-In the default case, however, most of these constructs are ignored.
-
-It is possible to change how the things following these commands
-on the line are handled, what is considered to be an arg for those
-commands and it is also possible to keep them instead of discarding
-them such that it is possible to handle them specially, with the
-same function than the one used for unknown commands.
-
address@hidden %misc_command
-Those special commands without braces are the key of a hash:
address@hidden The associated value is a reference on a
-hash enabling to set the properties of these commands. The
-keys of this hash reference is the name of a property, the value
-is the value of the property. For example here we have @code{line}
-for the @code{arg} property for the @code{command} @@-command.
-
address@hidden
address@hidden'command'@} = @{'arg' => 'line', 'skip' => 'space'@};
address@hidden example
-
-The properties and possible values are:
-
address@hidden @code
address@hidden skip
-This property enables to set what is skipped after the command arguments.
-Here are the possible values:
address@hidden @code
address@hidden line
-The remaining of the line is skipped.
address@hidden space
-Spaces are skipped but not newline.
address@hidden whitespace
-Spaces are skipped
address@hidden linewhitespace
-Spaces are skipped if there are only spaces remaining on the line.
address@hidden linespace
-Spaces are skipped, but not newline if
-there are only spaces remaining on the line
address@hidden table
-
address@hidden arg
-If the associated value is @code{line} the line is considered to be the
-argument. If it is a number it is the number of args (separated by spaces).
address@hidden keep
-If true the args and the macro are kept, otherwise they are discarded.
-The defaut is to have @code{keep} undef for all the commands.
-If @code{keep} is true for @code{@@verbatiminclude} the default
-action for this macro is not done.
address@hidden table
-
-These commands are processed by the @code{misc_command_line} function
-reference. This is somehow redundant with @ref{HTML Customization for
-Title Commands} xx.
-
address@hidden {Function Reference} {($command, $line, $result)}
misc_command_line $command $line \@@args \@@stack \%state
address@hidden is the @@-command name. @var{$line} is what the main program
-would leave on the line. @var{\@@args} holds the @@-command arguments.
address@hidden@@stack} is an opaque variable.
address@hidden holds informations about the current context.
-The result is the @@-command that should be considered in the
-main program, the line that should be processed further and
-the result of the command formatting.
address@hidden deftypefn
-
-
-Commands which do not appear in the hashes
address@hidden, @code{%simple_map_pre},
address@hidden, @code{%line_command_map} or @code{%misc_command},
-or that appear in
address@hidden but with @code{keep} true are processed by the
-following function reference:
-
address@hidden {Function Reference} {($result_line, $result, $result_text,
$message)} unknown $command $line $pass
address@hidden is the @@-command, @var{$line} is the line following
-the @var{$command}. @var{$pass} is the pass of texi2html
-(@pxref{texi2any's Three Passes}). @var{$result} is a boolean. If it
-is true then the other return values are taken into account otherwise
-the default actions are used. In case @var{$result} is true,
address@hidden is the new line to be processed further,
address@hidden is the resulting formatted text and @var{$message},
-if defined is a message outputted to the output with line number added
-by @command{texi2any}.
address@hidden deftypefn
-
-Commands with braces not specified above
-nor in @code{%style_map}, @code{%style_map_pre} and
address@hidden are processed
-by the following function reference
-
address@hidden {Function Reference} {($result, $result_text, $message)}
unknown_style $command $text \%state $no_close $no_open
address@hidden is the @@-command, @var{$text} is the text appearing within
-the braces (allready formatted).
address@hidden holds informations about the current context.
-If @var{$text} is split in paragraphs each paragraph is passed through
-the function, and @var{$no_close} is true if it is not the last paragraph,
-while @var{$no_open} is true if it is not the first paragraph.
address@hidden is a boolean. If it is true then the other return
-values are taken into account otherwise the default actions are
-used. In case @var{$result} is true, @var{$result_text} is the resulting
-formatted text
-and @var{$message}, if defined is a message outputted to the output
-with line number added by @command{texi2any}.
address@hidden deftypefn
-
@node External index files
@section Generation of external files for index entries
@@ -24971,7 +22789,7 @@
(@url{http://www.gnu.org/software/rcs}) version control systems, which
expand it into a string such as:
@example
-$Id: texinfo.txi,v 1.341 2010/11/03 18:04:49 karl Exp $
+$Id: texinfo.txi,v 1.342 2010/11/05 23:26:21 karl Exp $
@end example
(This is useful in all sources that use version control, not just manuals.)
You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -25050,7 +22868,7 @@
@verbatim
\input texinfo @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.341 2010/11/03 18:04:49 karl Exp $
address@hidden $Id: texinfo.txi,v 1.342 2010/11/05 23:26:21 karl Exp $
@comment %**start of header
@setfilename sample.info
@include version.texi
Index: doc/texi2oldapi.texi
===================================================================
RCS file: doc/texi2oldapi.texi
diff -N doc/texi2oldapi.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/texi2oldapi.texi 5 Nov 2010 23:26:21 -0000 1.1
@@ -0,0 +1,2197 @@
address@hidden sections from the texi2html manual (only partly edited), removed
address@hidden because the new tree-based translators is likely to obviate them.
address@hidden Doesn't format on its own, is just here (for now) for archival
purposes.
address@hidden
address@hidden Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
address@hidden 2001, 2002, 2003, 2004, 2009, 2010 Free Software Foundation,
Inc.
address@hidden See texinfo.txi for copying conditions.
+
+
+* Customizing HTML Basic Commands:: Commands with no arguments, images, etc.
+* Customizing HTML References:: @code{@@xref}, external node pointers, etc.
+* Customizing HTML Footnotes:: Footnotes.
+* Customizing HTML Block Commands:: Environments.
+* Paragraph and preformatted region::
+* Lists tables and definitions formatting::
+* Menus indices and floats formatting::
+* Handling special regions::
+* Other and unknown commands::
+
address@hidden Customizing HTML Basic Commands
address@hidden Customizing HTML Basic Commands
+
+This section describes customizing the HTML output for the basic
+Texinfo commands used within the running text.
+
address@hidden
+* Argless: HTML Customization for Commands Without Arguments.
+* @@-Colon: HTML Customization After @@-Colon.
+* Simple: HTML Customization for Simple Commands. Indicators, accents, etc.
+* Anchors: HTML Customization for Anchors.
+* Images: HTML Customization for Images.
+* sp: HTML Customization for @code{sp}.
+* Abbrs: HTML Customization for Abbreviations. @code{@@acronym}, @code{@@abbr}.
+* Text: HTML Customization for Text Sequences. @code{-- --- `` ''}, etc.
+* Title: HTML Customization for Title Commands. @code{@@title}, etc.
address@hidden menu
+
+
address@hidden HTML Customization for Commands Without Arguments
address@hidden HTML Customization for Commands Without Arguments
+
address@hidden HTML customization for commands without arguments
address@hidden Commands without arguments, customizing HTML for
address@hidden Insertion commands, customizing HTML for
+
+These commands include those whose names are a single nonletter
+character, such as @code{@@@@}, and those with a normal alphabetic
+name but whose braces should be empty, such as @code{@@address@hidden@}} and
address@hidden@@address@hidden@}}.
+
+Each of these categories of commands have associated hashes for each
+expansion context: normal, preformatted, string, and math (@pxref{Init
+File Expansion Contexts}). The keys of each hash are the command
+names, the associated value is the text replacing the command. In
+math context, if a command is not a key of these hashes, the defaults
+for the command are used.
+
address@hidden %simple_map
address@hidden %things_map
address@hidden %simple_map_pre
address@hidden %pre_map
address@hidden %simple_map_texi
address@hidden %texi_map
address@hidden %simple_map_math
address@hidden %math_map
+The hashes are:
+
address@hidden {preformatted} {one nonlettered character} {empty braces}
address@hidden command type @tab one nonlettered character @tab empty braces
address@hidden normal @tab @code{%simple_map} @tab @code{%things_map}
address@hidden preformatted @tab @code{%simple_map_pre} @tab @code{%pre_map}
address@hidden string @tab @code{%simple_map_texi} @tab @code{%texi_map}
address@hidden math @tab @code{%simple_map_math} @tab @code{%math_map}
address@hidden multitable
+
+To change the formatting of a command, change the associated value in
+the desired hash. For example, if you want @code{­} to be output
+for @code{@@-} in normal and preformatted context, write this in your
+init file:
+
address@hidden
address@hidden'-'@} = '­';
address@hidden'-'@} = '­';
address@hidden example
+
address@hidden %sorting_things_map
+An additional hash is used preferentially when sorting indices,
+overriding @code{%texi_map} entries: @code{%sorting_things_map}.
+
+For better control, function references are available, although they
+are not used in string context. @code{simple_command} is for
+formatting of the single-nonletter @@-commands:
+
address@hidden {Function Reference} $formatted_command simple_command
+ @ $command $in_preformatted $in_math $line_nr \%state
address@hidden is the @@-command name. @var{$in_preformatted} is true
+if in a preformatted region. @var{$in_math} is true if in math.
address@hidden is an opaque structure containing information about the
+line number of the @@-command. @var{\%state} holds information about
+the current context.
address@hidden deftypefn
+
+For @@-commands with empty brace arguments, @code{thing_command} may
+be redefined:
+
address@hidden {Function Reference} $formatted_command thing_command
+ @ $command $text $in_preformatted $in_math $line_nr \%state
address@hidden is the formatted text appearing in the @@-command. It is
+invalid Texinfo to have anything other than the empty string there.
address@hidden, @var{$in_preformatted}, @var{$in_math},
address@hidden, and @var{\%state} are as above.
address@hidden deftypefn
+
+
address@hidden HTML Customization After @@-Colon
address@hidden HTML Customization After @@-Colon
+
address@hidden HTML customization after @code{@@:}
address@hidden Punctuation after @code{@@:}, customizing HTML for
address@hidden Sentence punctuation, customizing HTML for
+
address@hidden %colon_command_punctuation_characters
+The formatting of a punctuation character followed by @code{@@:} is
+determined by the hash @code{%colon_command_punctuation_characters}.
+If a @code{@@:} command is preceded by a character in this hash, it is
+replaced by the associated value. By default, the associated value is
+also the character, so this leaves the punctuation character
+unmodified.
+
+The following function reference may be redefined to handle characters
+that are in @code{%colon_command_punctuation_characters}:
+
address@hidden {Function Reference} $punctuation colon_command $character
address@hidden is a character appearing in
address@hidden and preceding an
address@hidden@@:} command. By default, the associated value in
address@hidden is returned.
address@hidden deftypefn
+
+
address@hidden HTML Customization for Simple Commands
address@hidden HTML Customization for Simple Commands
+
address@hidden HTML customization for simple commands
address@hidden Simple commands, customizing HTML for
address@hidden Style commands, customizing HTML for
address@hidden Accent commands, customizing HTML for
+
address@hidden %style_map
address@hidden %style_map_pre
address@hidden %style_map_texi
address@hidden %style_map_math
+The formatting of the output produced by ``indicator'' and font
+commands (e.g., @code{@@code}, @code{@@t}, @code{@@titlefont}), the
+accent-related commands with arguments (e.g., @code{@@'},
address@hidden@@udotaccent}, @code{@@dotless}) and other simple commands with
+arguments (e.g., @code{@@w}, @code{@@uref}, @code{@@math},
address@hidden@@asis}) is controlled by the following hashes by default
+(@pxref{Init File Expansion Contexts}):
+
address@hidden @code
address@hidden %style_map
+In normal context.
+
address@hidden %style_map_pre
+In preformatted context.
+
address@hidden %style_map_texi
+In string context.
+
address@hidden %style_map_math
+Preferentially in math context, falling back to other hashes if not found.
address@hidden table
+
+If defined, a function reference is called at the @@-command opening:
+
address@hidden {Function Reference} begin_style_texi $command \%state \@@stack @
+ $real_style_or_accent $remove_texi
address@hidden @var
address@hidden $command
+The @@-command name.
+
address@hidden \%state
+Information about the current context.
+
address@hidden \@@stack
+An opaque variable.
+
address@hidden $real_style_or_accent
+Set if the command is an accent or a font command.
+
address@hidden $remove_texi
+Set if in a context where output is simple text.
address@hidden table
address@hidden deffn
+
address@hidden %accent_map
+The nonlettered accent commands where the following character is taken
+as the argument (e.g., @code{@@`a}) should be keys of the
address@hidden hash, even if no value is associated.
+
+Command with braces may be handled differently; @pxref{Init File
+Formatting of Commands}. For example, this is used for @code{@@math}
+if @LaTeX{}2HTML is used.
+
+The key of the hashes are the command names. The values may be
+strings or hash references. The hash reference interface is the only
+one described in this manual, the other is retained primarily for
+backward compatibility. You can also define your own interface.
+
address@hidden
+* Hash Interface for Simple HTML Customization::
+* Custom Interface for Simple HTML Customization::
address@hidden menu
+
+
address@hidden Hash Interface for Simple HTML Customization
address@hidden Hash Interface for Simple HTML Customization
+
address@hidden Hash interface for simple HTML customization
address@hidden Interface for simple HTML customization, hash
+
+The keys of the hashes given above are Texinfo command names. The
+values determine how the command argument is formatted. Each value is
+a hash reference. In this value hash, each key corresponds with a
+type of information for formatting, and the value is the corresponding
+data.
+
+Here's an example:
+
address@hidden
address@hidden'command'@} = @{
+ 'args' => ['code'],
+ 'inline_attribute' => 'code',
address@hidden;
address@hidden example
+
+Here, the arguments for @code{@@command} are interpreted as specified
+by the values associated with the @samp{args} key, namely a code
+argument; and the @code{inline_attribute} associated with that command
+is @samp{<code>}.
+
+Here is a list of the possible keys in the value hashes:
+
address@hidden @samp
address@hidden args
address@hidden Hash Args}
+The value associated is an array reference. Each element of the array
+defines how the corresponding argument (separated by @samp{,} in the
+Texinfo input) for the @@-command should be formatted. The
+possibilities are:
+
address@hidden @code
address@hidden normal
+for normal text,
+
address@hidden code
+for text where @samp{---}, @samp{--}, @samp{''}, and @samp{``} should
+be kept as-is, and
+
address@hidden keep
+if the input should be kept entirely as-is, with no interpretation of
+any @@-commands.
address@hidden table
+
+The default is @samp{['normal']} for one normally-interpreted argument.
+
+For example, we specify
+
address@hidden
address@hidden'email'@}->@{'args'@} = ['code', 'normal'];
address@hidden example
+
+because @samp{---}, @samp{--}, @samp{''} and @samp{``} should be kept
+as-is in the first argument of @code{@@email}
+(@pxref{email,, @code{@@email}}).
+
address@hidden attribute
+If the associated value is a word, it is considered to be an XML
+element name, and the argument is enclosed between the element opening
+and the element closing. For example, if the value is @code{elem}, the
+resulting HTML is @code{<elem>@var{arg}</elem>}.
+
+If the text is a word followed by some text, the word is interpreted
+as above, and the text is considered to be the attributes text of the
+element. Thus @code{elem class="elem"} leads to @code{<elem
+class="elem">@var{arg}</elem>}. This only works if there is only one
+argument.
+
address@hidden inline_attribute
+Like @code{attribute}, except that it is closed at each paragraph end
+and reopened at each beginning of paragraph. This is more often used
+than @samp{attribute} since it allows to have well-formed HTML and
+XML.
+
address@hidden inline_begin
+The associated value is added in front of the text and each time a
+paragraph is restarted while within the command.
+
address@hidden inline_end
+The associated value is added after the text and each time a paragraph
+is ended while within the command.
+
address@hidden begin
+The associated value is added in front of the text.
+
address@hidden end
+The associated value is added after the text.
+
address@hidden quotes
+If the corresponding value is true, the result is enclosed in quotes
+associated with configuration variables @code{OPEN_QUOTE_SYMBOL} and
address@hidden; the defaults depend on the output format
+but fall back to @samp{`} and @samp{'}.
+
address@hidden function
+The corresponding value should be a function reference, which is
+called with the following arguments:
+
address@hidden @code
address@hidden $command
+The @@-command name.
+
address@hidden \@@args
+An array reference containing the arguments of the @@-command.
+
address@hidden \@@command_stack
+An array reference with the names of the @@-commands containing the
+@@-command being formatted, latest on top.
+
address@hidden \%state
+A hash reference containing context information.
+
address@hidden $line_nr
+An opaque structure containing line number information for the
+@@-command. It can be used to call @code{main::line_error} or
address@hidden::line_warn} with the first argument being the message, and
+the second argument @code{$line_nr}.
+
address@hidden \@@line_numbers
+An array reference containing the line numbers (the same opaque
+structure as above) of the lines produced by the @@-command.
address@hidden table
address@hidden table
+
+
address@hidden Custom Interface for Simple HTML Customization
address@hidden Custom Interface for Simple HTML Customization
+
address@hidden Custom interface for simple HTML customization
address@hidden Interface for simple HTML customization, custom
+
+If the hash interface described in the previous section does not
+suffice, it is possible to change how the ``simple'' Texinfo commands
+are processed by redefining the following function reference:
+
address@hidden {Function Reference} $resulting_text style $style $command $text
@
+ $args $no_close $no_open $line_nr \%state $command_stack \@@line_numbers
address@hidden @var
address@hidden $command
+The @@-command
+
address@hidden $style
+The value associated with the @var{$command} in the @code{%style_map},
address@hidden or @code{%style_map_texi} hashes.
+
address@hidden $text
+The argument text appearing within the @@-command braces.
+
address@hidden $args
+Array reference containing the command arguments, formatted according
+to the same conventions as the hash reference style (provided that the
+value associated with the @@-command is a hash reference with an
address@hidden key; @pxref{Reference Hash Args}).
+
address@hidden $no_close
address@hidden $no_open
+If @var{$text} is split into paragraphs, each paragraph is passed
+through the function, and @var{$no_close} is true if this is not the
+last paragraph, while @var{$no_open} is true if this is not the first
+paragraph.
+
address@hidden $line_nr
address@hidden \%state
address@hidden $command_stack
address@hidden \@@line_numbers
+See the previous section.
address@hidden table
address@hidden deftypefn
+
+
address@hidden HTML Customization for Anchors
address@hidden HTML Customization for Anchors
+
address@hidden HTML customization for anchors
address@hidden Anchors, customizing HTML for
+
+The HTML formatting of anchors (@pxref{anchor,, @code{@@anchor}}) is
+controlled by functions. To customize the output, the function
+reference @code{$anchor_label} should be redefined. The function
+should return the formatted text.
+
address@hidden {Function Reference} $anchor_label anchor_label $identifier
$anchor
address@hidden is the anchor identifier, and @var{$anchor} is the
address@hidden@@anchor} argument.
address@hidden deftypefn
+
+By default, this uses a function reference, @code{$anchor}, which can
+do a reference target or link. This is especially relevant for HTML
+but can potentially be used in other formats, since it is a rather
+common element among output formats.
+
address@hidden {Function Reference} $anchor anchor @
+ $identifier $href $text $attributes
+If @var{$identifier} is not empty, its value should be used to create
+a target for links (typically associated with a name or id attribute
+in HTML). The @var{$href} argument specifies a hypertext reference
+which should be used to link to a target. If both @var{$identifier}
+and @var{$href} are given, the text produced should be both a target
+for @var{$identifier} and a link to @var{$href}. @var{$text} is the
+text to be displayed. @var{$attributes} are additional attributes for
+an @code{<a>} HTML element.
address@hidden deftypefn
+
+
address@hidden HTML Customization for Images
address@hidden HTML Customization for Images
+
address@hidden HTML customization for images
address@hidden Images, customizing HTML for
+
address@hidden @@IMAGE_EXTENSIONS
+To customize the images produced by @code{@@image} (@pxref{Images}),
+the first possibility is to modify the @code{@@IMAGE_EXTENSIONS}
+array, which holds a list of filename extensions for image files.
+
+Second, it is also possible to redefine the function used to determine
+the filename of the image:
+
address@hidden {Function Reference} $filename image_files @
+ $basename $extension $texi_base $texi_extension
address@hidden is the first @code{@@image} argument, and
address@hidden is the corresponding @code{@@image} argument; both
+are formatted. @var{$texi_base} is the first @code{@@image} argument
+and @var{$texi_extension} is the extension, unformatted. This
+function reference should return an array of array references, each
+holding both formatted and unformatted image filenames without any path
+for which the main program should look.
address@hidden deftypefn
+
+Third, it is possible to control the formatting of @code{@@image} by
+redefining this:
+
address@hidden {Function Reference} $image image $file_path $basename @
+ $preformatted $file_name $alt_text $width $height $raw_alt @
+ $extension $working_dir $file_relative_path $in_paragraph @
+ \@@file_locations $base_simple_format @
+ $extension_simple_format $file_name_simple_format $line_nr
address@hidden @var
address@hidden $file_path
+The image file name with the path from the output directory to the
+source manual directory prepended.
+
address@hidden $basename
+The file name without extension---the first argument to the
address@hidden@@image} command.
+
address@hidden $preformatted
+True if the image appears in preformatted text.
+
address@hidden $file_name
+The file name without path but with extension.
+
address@hidden $alt_text
+The alternate text, possibly undefined.
+
address@hidden $width
address@hidden $height
+The corresponding @code{@@image} arguments.
+
address@hidden $raw_alt
+The unmodified alternate-text @code{@@image} argument.
+
address@hidden $extension
+The corresponding @code{@@image} argument.
+
address@hidden $working_dir
+Path to the working directory relative to the output directory.
+
address@hidden $file_relative_path
+The file name relative to @var{$working_dir}.
+
address@hidden $in_paragraph
+True if within a paragraph.
+
address@hidden \@@file_locations
+Array reference holding another array reference with 3 elements: the
+file name array reference as returned by @code{image_files}; the image
+location if it was found, or undef; and the file name formatted using
+simple formatting in string context.
+
address@hidden $base_simple_format
address@hidden $extension_simple_format
address@hidden $file_name_simple_format
+The corresponding arguments formatted using simple formatting in
+string context.
+
address@hidden $line_nr
+An opaque structure containing the information about the line number
+of the @@-command.
address@hidden table
address@hidden deftypefn
+
+
address@hidden HTML Customization for @code{sp}
address@hidden HTML Customization for @code{sp}
+
address@hidden HTML customization for @code{sp}
address@hidden @code{sp}, customizing HTML for
+
+The formatting of @code{@@sp} (@pxref{sp,,@code{@@sp}}) is controlled by:
+
address@hidden {Function Reference} $sp sp $number $preformatted
address@hidden is the numeric argument of @code{@@sp}.
address@hidden is true if the @code{@@sp} appears in preformatted
+text.
address@hidden deftypefn
+
+
address@hidden HTML Customization for Abbreviations
address@hidden HTML Customization for Abbreviations
+
address@hidden HTML customization for abbreviations
address@hidden @code{abbr}, customizing HTML for
address@hidden @code{acronym}, customizing HTML for
+
+The formatting of @code{@@acronym} and @code{@@abbr} (@pxref{acronym,,
address@hidden@@acronym}} and @ref{abbr,, @code{@@abbr}}) is controlled by:
+
address@hidden {Function Reference} $acronym acronym_like @
+ $acronym_texi $acronym_text $with_explanation \@@explanation_lines @
+ $explanation_text $explanation_simply_formatted
+
address@hidden is the original acronym argument with @@-commands,
+while @var{$acronym_text} is formatted.
+
+The other arguments are related to the explanation (the second arg of
+the acronym). @var{$with_explanation} is true if the second argument
+of the acronym command is present. If an explanation exists, coming
+from a previous @code{@@acronym} or as an argument to the present
+command, the remaining arguments are defined:
+
address@hidden @var
address@hidden \@@explanation_lines
+Array reference containing simply formatted explanation lines
+(@pxref{Init File Expansion Contexts}).
+
address@hidden $explanation_text
+Formatted explanation text.
+
address@hidden $explanation_simply_formatted
+Explanation simply formatted in a string context.
address@hidden table
address@hidden deftypefn
+
+
address@hidden HTML Customization for Text Sequences
address@hidden HTML Customization for Text Sequences
+
address@hidden HTML customization for text sequences
address@hidden Text sequences, customizing HTML for
address@hidden Ligatures in text, customizing HTML for
+
+Some character sequences are processed especially in text: @samp{---},
address@hidden, @samp{``} and @samp{''}. This should only be done only if
+in normal text and not within commands for preformatted output
+(@code{@@code}, @code{@@address@hidden). A function reference is called
+to process the text and take care of these constructs. It may also be
+used to transform the text, for example, convert to upper case if it
+is in @code{@@sc}. The function should also take care of protecting
+special characters.
+
address@hidden {Function Reference} $processed_text normal_text $text @
+ $in_raw_text $in_preformatted $in_code $in_math $in_simple $command_stack
+Process @var{$text} and return @var{$processed_text}. The other
+arguments give some information about the context of the text.
+
address@hidden @var
address@hidden $in_raw_text
+True if the text appears in a place where there is no formatting at
+all; e.g., in comments.
+
address@hidden $in_preformatted
+True if within a preformatted environemnt
+
address@hidden $in_code
+True if within a special command such as @code{@@code} or @code{@@env}
+where the text sequences should be left as is.
+
address@hidden $in_math
+True if within @code{@@math}.
+
address@hidden $in_simple
+True if in a string context with minimal formatting.
+
address@hidden $command_stack
+Array containing the name of the formatting @@-commands that enclose
+the text.
address@hidden table
+
+By default, the @samp{---}, @samp{--}, @samp{``} and @samp{''}
+constructs are expanded if needed and the text is upper-cased if in
address@hidden@@sc}. Special characters (@samp{&}, @samp{"}, @samp{<} and
address@hidden>} in HTML) are protected if needed.
address@hidden deftypefn
+
address@hidden Protecting special output characters
address@hidden Output format characters, protecting
address@hidden HTML characters, protecting
+Some characters are special in a particular output format, such as
address@hidden<} in HTML. Some text is not processed by the above function,
+but still needs protection before output. This is done by the
+following:
+
address@hidden {Function Reference} $protected_text protect_text $text
+Process the general text @var{$text} and return the resulting
+protected text @var{$protected_text}.
address@hidden deftypefn
+
address@hidden Empty lines, removing
+Empty lines are processed by the following function reference, which
+can be useful if empty lines are to be removed.
+
address@hidden Definition commands, empty lines after
address@hidden {Function Reference} $resulting_text empty_line $empty_line
$state
+Process @var{$empty_line} and return @var{$resulting_text}.
address@hidden is a structure holding information about the state of
+parsing. By default, empty lines are left as-is except right after a
+definition @@-command.
address@hidden deftypefn
+
+
address@hidden HTML Customization for Title Commands
address@hidden HTML Customization for Title Commands
+
address@hidden HTML customization for title commands
address@hidden Title commands, customizing HTML for
+
address@hidden %line_command_map
+Some @@-commands related to titles appear on a line by themselves and
+take the rest of the line as their argument: @code{@@titlepage},
address@hidden@@title}, @code{@@subtitle}, and @code{@@author}
+(@pxref{Titlepage & Copyright Page}). These are listed in
address@hidden and the following function reference is used
+to format them:
+
address@hidden {Function Reference} $resulting_text line_command @
+ $command $arg_text $arg_texi \%state
+
address@hidden the @@-command, @var{$arg_text} is the
+@@-command's formatted argument, and @var{$arg_texi} is the @@-command
+argument without any formatting. @var{\%state} is a hash reference
+containing context information. The function returns
address@hidden
address@hidden deftypefn
+
+For more customization of title pages, @pxref{HTML Title Page
+Customization}.
+
+
address@hidden Customizing HTML References
address@hidden Customizing HTML References
+
address@hidden References, HTML customization for
address@hidden Cross references, HTML customization for
+
address@hidden
+* Internal: HTML Customization for Internal References.
+* External: HTML Customization for External References.
address@hidden menu
+
+
address@hidden HTML Customization for Internal References
address@hidden HTML Customization for Internal References
+
address@hidden HTML customization for internal references
address@hidden Internal references, HTML customization for
+
+This function reference is used to format a reference to a node in the
+current manual (@pxref{Cross References}).
+
address@hidden {Function Reference} $text internal_ref $command $href
$short_name @
+ $name $is_section \@@args_texi \@@formatted_args \%element
+
address@hidden @var
address@hidden $command
+The reference command, namely @code{ref}, @code{xref}, @code{pxref} or
address@hidden).
+
address@hidden $href
+An HTML href to the node.
+
address@hidden $short_name
address@hidden $name
+The text for the reference. @var{$short_name} can be the node name
+which is assumed to be no longer than the section name.
+
address@hidden $is_section
+True if the reference is to a sectioning element.
+
address@hidden \@@args_texi
address@hidden \@@formatted_args
+Array references containing the @@-command arguments, not formatted
+and formatted, respectively.
+
address@hidden \%element
+Hash reference with information about the target element of the
+reference.
address@hidden table
+
+The function should return the full formatted text of the internal
+reference.
address@hidden deftypefn
+
+
address@hidden HTML Customization for External References
address@hidden HTML Customization for External References
+
address@hidden HTML customization for external references
address@hidden External references, HTML customization for
+
+These references are produced by one of two function references:
address@hidden is used for menu items which refer to other
+manuals (@pxref{Other Info Files}), while @code{external_ref} is used
+for full external cross references (@pxref{Four and Five Arguments}).
+
address@hidden {Function Reference} $href external_href $node $node_identifier @
+ $xml_node_identifier $file
+This function formats a reference to a node in an external Texinfo manual.
+
address@hidden @var
address@hidden $node
+The node name, with @@-commands.
+
address@hidden $node_identifer
+The node name mapped to an identifier acceptable as a file name.
+
address@hidden $xml_node_identifier
+The node name mapped to an identifier acceptable for XML.
+
address@hidden $file
+The manual file name of the external reference.
address@hidden table
+
+The function should return an HTML href for the external reference.
+
address@hidden Xref}, for how the identifiers are built in order to allow
+for cross references to external manuals to succeed.
address@hidden deftypefn
+
address@hidden {Function Reference} $text external_ref $command $section $book @
+ $file $href $cross_ref_name \@@args_texi \@@formatted_args $node
+This function formats a general cross reference to an external Texinfo manual.
+
address@hidden @var
address@hidden $command
+The reference command (@code{ref}, @code{xref}, @code{pxref} or
address@hidden).
+
address@hidden $section
+The section in the external manual; may be empty.
+
address@hidden $book
+The book title; may be empty.
+
address@hidden $file
+The manual file name.
+
address@hidden $href
+An HTML href to the external manual constructed using the above
address@hidden function.
+
address@hidden $cross_ref_name
+Optional cross reference name appearing in the reference command.
+
address@hidden \@@args_texi
address@hidden \@@formatted_args
+Array references containing the @@-command arguments, not formatted
+and formatted, respectively.
+
address@hidden $node
+The node name, formatted.
address@hidden table
+
+The function should return the HTML text for the external manual
+reference.
address@hidden deftypefn
+
+
address@hidden Customizing HTML Footnotes
address@hidden Customizing HTML Footnotes
+
address@hidden Customizing HTML footnotes
address@hidden Footnotes, customizing HTML
+
+Each footnote is associated with a footnote entry. Several footnote
+entries are grouped in a footnote section. When a footnote appears,
+two things must be formatted: the footnote text, and the place in the
+main text where the footnote marker appears.
+
+It is possible to replace the footnote with other text before
+formatting the footnote. The following function reference
+is used for this if it is defined:
+
address@hidden {Function Reference} $added_text footnote_texi $footnote_text @
+ \%state \@@command_stack
address@hidden @var
address@hidden $footnote_text
+The footnote text.
+
address@hidden \%state
+Hash referencing with information about the context of the footnote
+location in the main document. Specifically, the entries
address@hidden>@{'outside_document'@}} or
address@hidden>@{'multiple_pass'@}} can be used.
+
address@hidden \@@command_stack
+Array reference containing the commands enclosing the footnote.
address@hidden table
+
+This function should return new formatted text for the footnote.
address@hidden deftypefn
+
+Two functions, with corresponding function references, control the
+formatting of the footnotes:
+
address@hidden {Function Reference} {(\@@lines $doc_text)} foot_line_and_ref @
+ $number_in_doc $number_in_page $footnote_id $place_id @
+ $document_file $footnote_file \@@lines \%state
address@hidden @var
address@hidden $number_in_doc
+The footnote number counted through the whole document,
+
address@hidden $number_in_page
+The footnote number counted on the current page.
+
address@hidden $footnote_id
+An identifier for the footnote text, which should be used to make the
+target for references to the footnote.
+
address@hidden $place_id
+Identifier for the location of the footnote in the main document.
+
address@hidden $document_file
+Name of the file containing the text where the footnote appears in the
+main document
+
address@hidden $footnote_file
+Name of the file where the footnote text appears.
+
address@hidden \@@lines
+Array reference containing the footnote text lines, formatted.
+
address@hidden \%state
+Information about the context at the footnote location in the main
+document. As usual, the most useful entry is @code{preformatted},
+which is true if the footnote appears in a preformatted context.
address@hidden table
+
+The function should return a list of two elements: an array reference
+(@var{\@@lines}) containing the updated footnote text for the footnote
+entry, and a string (@var{$doc_text}), for the text to appear at the
+location of the footnote in the main document, i.e., linking to the
+footnote entry.
address@hidden deftypefn
+
+The following function is only used when footnotes are at the bottom
+of a page and the document is split. For customization in the case
+when footnotes are on a separate page or section, @pxref{Customizing
+Layout of Special Elements}. The footnote location is determined by
address@hidden (@pxref{Footnote Styles}).
+
address@hidden {Function Reference} foot_section \@@footnotes_lines
+This function formats a group of footnotes. @var{\@@footnotes_lines}
+is an array reference holding the lines of all the footnote entries
+formatted as explained above. The function should modify the
+reference.
address@hidden deffn
+
+
address@hidden Customizing HTML Block Commands
address@hidden Customizing HTML Block Commands
+
address@hidden Customizing HTML block commands
address@hidden Block commands, customizing HTML
address@hidden Environments, customizing HTML
+
address@hidden
+* Align: HTML Customization of Alignment Commands. @code{@@flushleft}, etc.
+* Preformatted block command formatting::
+* Other block commands formatting::
address@hidden menu
+
address@hidden HTML Customization of Alignment Commands
address@hidden HTML Customization of Alignment Commands
+
address@hidden HTML customization of alignment environments
address@hidden Customization of alignment environments
address@hidden Alignment environments, HTML customization of
address@hidden @code{@@center}, HTML customization of
address@hidden @code{@@flushleft}, HTML customization of
address@hidden @code{@@flushright}, HTML customization of
+
address@hidden %paragraph_style
+When a block with special text alignment of text is used, namely
address@hidden@@center} (@pxref{titlefont center sp},,
address@hidden@@address@hidden @code{@@address@hidden and @code{@@sp}),
address@hidden@@flushleft} or @code{@@flushright} (@pxref{flushleft &
+flushright,, @code{@@flushleft} and @code{@@flushright}}, the main
+program takes care of opening and closing paragraphs. The alignment
+commands are the keys in the @code{%paragraph_style} hash. The value
+is used in the function doing the formatting of the paragraphs
+(@pxref{Paragraph and preformatted region}).
+
+This function reference allows for customizing the formatting of the
+command argument.
+
address@hidden {Function Reference} $result paragraph_style_command $command
$text
address@hidden is the command name and @var{$text} is the text
+appearing within the command. This function should return the
+formatted text. The default is to return the text unmodified.
address@hidden deftypefn
+
+
address@hidden Preformatted block command formatting
address@hidden Preformatted block command (@code{@@example},
@code{@@address@hidden) formatting
+
+Here we see how a whole preformatted block command is
+formatted. For the formatting
+of the text, see @ref{Paragraph and preformatted region}.
+
address@hidden %complex_format_map
+The formatting of the block commands is ultimately controlled by a
+function, however the default for this function uses a hash and
+changing the hash values should be enough in most cases. This
+hash is called @code{%complex_format_map}. It has a key for each
+of the preformatted block commands (@code{example}, @code{smallexample},
address@hidden, @code{smalllisp}, @code{display}, @code{smalldisplay},
address@hidden, @code{smallformat}).
+
+The associated value is a reference on a hash. The keys are:
+
address@hidden @code
address@hidden begin
+The @code{begin} should lead to the beginning of the
+formatted output.
address@hidden end
+The @code{end} should lead to the end of the
+formatted output.
address@hidden class
+The HTML class. If not defined, the command name.
address@hidden pre_style
+The preformatted style. If not defined the corresponding @acronym{CSS} style
+is used.
address@hidden style
+If the associated value is @code{code}, the format is assumed to be in
+code style, where
+with @samp{---}, @samp{--}, @samp{''} and @samp{``} kept as is.
+If the key is absent the format inherits the code style
+and the font from the enclosing context.
address@hidden table
+The enclosed text will be formatted as described in
address@hidden and preformatted region}, and the name of the complex
+format will be available to the function formatting the text.
+
+If you aren't satisfied with this scheme, you can redefine the following
+function reference for a better control over the complex format formatting:
+
address@hidden {Function Reference} $complex_format_text complex_format
$format_name $preformatted_text
+
address@hidden is the complex format name, @var{$preformatted_text} is the
+text allready formatted as described in @ref{Paragraph and preformatted
region}.
+This function returns the whole complex format.
address@hidden deftypefn
+
address@hidden Other block commands formatting
address@hidden Formatting of other block commands (@code{@@verbatim},
@code{@@cartouche}, @code{@@quotation}, @code{@@html})
+
address@hidden FIXME verbatiminclude is distinct
+Regions corresponding with raw text, like @code{@@verbatim}, @code{@@html},
address@hidden@@tex} or the content of the file given in
@code{@@verbatiminclude}
+argument are formatted according to the following function reference:
+
address@hidden {Function Reference} $raw_region raw $command $text
address@hidden is the command name, @var{$text} is the raw text.
+In the default case, if @var{$command} is @code{verbatiminclude}
+the text is the content of the @code{@@verbatiminclude} file argument.
address@hidden deftypefn
+
+If address@hidden is used, @code{@@tex} regions are handled differently,
+(@pxref{Init File Formatting of Commands}).
+
+The @code{@@cartouche} command formatting is controlled by the
+function reference:
+
address@hidden {Function Reference} $cartouche cartouche $text
address@hidden is the text appearing within the cartouche.
address@hidden deftypefn
+
+The formatting of @code{@@quotation} and @code{@@smallquotation}
+is controlled by two function references.
+The first one is usefull in case the @code{@@quotation} has an argument, as
+it allows to prepend a string to the quotation text:
+
address@hidden {Function Reference} $prepended_string quotation_prepend_text
$command $text
address@hidden is the @@-command.
address@hidden is the argument of the quotation with @@-commands not
+interpreted. This function
+can return a string which will be prepended to the quotation text.
address@hidden deftypefn
+
+The whole quotation is formatted by:
+
address@hidden {Function Reference} $quotation quotation $command
$quotation_text $argument_text $argument_text_texi \@@quote_authors
address@hidden is the @@-command.
address@hidden is the quotation text, formatted, with the text
+prepended by the function above. @var{$argument_text} is the argument
+of the @code{@@quotation}, formatted. @var{$argument_text_texi} is the
argument
+of the @code{@@quotation}, simply formatted.
address@hidden@@quote_authors} is a reference on an array holding information
+about the @code{@@author} command arguments appearing within the
address@hidden@@quotation}. Each of the array element is a reference on a
+hash with the following keys:
address@hidden @code
address@hidden author_texi
+Texinfo code of this @code{@@author} line.
address@hidden author_text
+Formatted argument of the @code{@@author} line.
address@hidden table
address@hidden deftypefn
+
address@hidden Paragraph and preformatted region
address@hidden Formatting of paragraph and preformatted regions
+
+
address@hidden FIXME not sure that it is stable enough to be documented?
+If defined, the following function reference is called at the paragraph
+opening:
+
address@hidden {Function Reference} begin_paragraph_texi
$paragraph_or_preformatted \@@paragraph_at_commands $context_command \%state
\@@stack
address@hidden is @samp{paragraph} when opening a paragraph,
+or @samp{preformatted} at the beginning of a preformatted region.
address@hidden@@paragraph_at_commands} is a reference on an array containing the
+listof th ecommands with brace opened outside of the paragraph or
+preformatted. @var{$context_command} is a reference on a structure describing
+in what generalized block @@-command we are.
address@hidden holds informations about the current context.
address@hidden@@stack} is an opaque variable.
address@hidden deffn
+
address@hidden
+* Paragraph and preformatted formatting::
+* Avoiding paragraphs::
address@hidden menu
+
address@hidden Paragraph and preformatted formatting
address@hidden Paragraph and preformatted region formatting
+
+The formatting of a paragraph region or a preformatted region, is controlled
+by function references:
+
address@hidden {Function Reference} $paragraph_text paragraph $text $alignement
$index $formatting_command $formatting_command_formatted \$paragraph_number
$format $item_number $enumerate_style $number $command_stack_at_end
$command_stack_at_begin
+This function formats a paragraph. @var{$text} is the text of the paragraph,
address@hidden is the empty string when no alignement command has
+been seen, otherwise it is the current alignement command name (see
+the previous section).
address@hidden holds @samp{noindent} or @samp{indent} if the corresponding
+@@-command appeared in the paragraph.
address@hidden and @var{$command_stack_at_begin} are arrays
+containing the opened @@-commands at end and at beginning of the paragraph,
+latest on top.
+
+The remaining arguments are usefull when the paragraph appears within a
+list or table. It is usefull whenever the paragraph has to be formatted
+differently when appearing in such environments.
+Moreover in that case the format command (@code{@@address@hidden)
+may have an associated formatting command.
address@hidden is this formatting command
+(like @code{@@minus}).
address@hidden is the command formatted in html
+in case the formatting command is a leading command (like @code{@@minus})
+which should be leading the first paragraph.
address@hidden is a reference on the number of
+paragraphs in that format command. The corresponding variable should be
+increased when a paragraph is added. @var{$format} is the format command.
address@hidden and list items formatting}.
+
+If the @var{$format} is an enumerate, @var{$item_number} is the number of
+the item in the list, @var{$enumerate_style} is the argument of the enumerate,
address@hidden is the number or letter corresponding with this item.
address@hidden deftypefn
+
address@hidden {Function Reference} $preformatted_text preformatted $text
$style $region_name $formatting_command $formatting_command_formatted
\$preformatted_number $format $item_number $enumerate_style $number
$command_stack_at_end $command_stack_at_begin
+This function formats a preformatted region. @var{$text} is the text of the
+preformatted region, @var{$style} is the css style associated with that
+preformatted region (@pxref{Customizing CSS}). @var{$region_name} is the
+name of the command opening
+the preformatted region (@address@hidden, see @ref{Preformatted block command
formatting})
+or a identifier for the preformatted context (for example
address@hidden, see @ref{Menu formatting}).
+The alignment commands are not taken into account, as the spaces are
+preserved in preformatted regions, you should flush and center by hand.
address@hidden and @var{$command_stack_at_begin} are arrays
+containing the opened @@-commands at end and at beginning of the preformatted
+region, latest on top.
+
+The remaining arguments are usefull when the preformatted region appears
+within a list or table. It is usefull whenever the preformatted region
+has to be formatted
+differently when appearing in such environments.
+Moreover in that case the format command (@code{@@address@hidden)
+may have
+an associated formatting command.
address@hidden is this formatting command
+(like @code{@@minus}).
address@hidden is the command formatted in html
+in case the formatting command is a leading command (like @code{@@minus})
+which should be leading the first preformatted region.
address@hidden is a reference on the number of
+preformatted regions in that format command. The corresponding variable
+should be increased when a preformatted region is added. @var{$format} is the
+format command.
address@hidden and list items formatting}.
+
+If the @var{$format} is an enumerate, @var{$item_number} is the number of
+the item in the list, @var{$enumerate_style} is the argument of the enumerate,
address@hidden is the number or letter corresponding with this item.
address@hidden deftypefn
+
+A special function reference is called instead if the preformatted
+is empty and the function reference is defined:
+
address@hidden {Function Reference} $preformatted_text empty_preformatted $text
address@hidden is the text of th epreformatted which should contain only
+spaces. The function refernece should return the formatted text for
+this empty preformatted region.
address@hidden deftypefn
+
address@hidden Avoiding paragraphs
address@hidden Avoiding paragraphs in @@-commands
+
address@hidden Avoid paragraph opening
+
address@hidden %format_in_paragraph
+It is possible to avoid that a format closes the previous paragraph or
+preformatted region and reopens one, by putting the format command in a
+hash, @code{%format_in_paragraph} with a true value. This only
+makes sense for few commands since otherwise the nesting of formats and
+paragraphs could become wrong.
+
address@hidden %no_paragraph_commands
+If the value of @code{%no_paragraph_commands} associated with a command is
+true, no paragraph is started by the command if outside of a paragraph
+(after an empty line, for example). If the value is set to 0, it will start
+a paragraph. If the value is not set, reasonable defaults are
+set.
+
address@hidden %stop_paragraph_command
+It is also possible to stop a paragraph when an @@-command happens by
+putting the @@-command in the @code{%stop_paragraph_command} hash
+associated with a true value.
+
address@hidden Lists tables and definitions formatting
address@hidden Lists, tables and definitions formatting
+
address@hidden
+* Lists and tables formatting::
+* Definition formatting::
address@hidden menu
+
address@hidden Lists and tables formatting
address@hidden Customizing the formatting of lists and tables
+
+The formatting of lists and tables is done at two levels:
address@hidden
address@hidden
+At the level of the whole region (table or list),
address@hidden
+At the level of the individual items, rows or cells of the list or table.
address@hidden itemize
+
address@hidden
+* Table and list items formatting::
+* Whole table and list formatting::
address@hidden menu
+
+
address@hidden Table and list items formatting
address@hidden Formatting individual table and list items
+
+In texinfo it is possible to give @code{@@itemize} or table command (hereafter
+called a @dfn{format command}) a @dfn{formatting command}.
+For example @code{@@minus} is the formatting command here:
address@hidden
+@@table @@minus
address@hidden example
+
address@hidden %special_list_commands
+The default is to apply the command to the text item, however it is possible
+to avoid it.
+The hash @code{%special_list_commands} has an entry for each of the
+format command. Each of these entries is a hash reference. If a formatting
+command is a key of the hash reference, then the formatting command is not
+applied to the text item for that format command. For example, if we have:
+
address@hidden
address@hidden'itemize'@} = @{ 'bullet' => '' @};
address@hidden example
+
+and we have the following @code{@@itemize}:
address@hidden
+@@itemize @@bullet
+@@item an item
+@@end itemize
address@hidden example
+
+then @code{@@bullet} will not be applied to @code{an item}.
+
+Every time a @code{@@tab} or an @code{@@item} is encountered, the following
+function reference is called, if defined:
address@hidden {Function Reference} $result_line tab_item_texi $command
\@@command_stack \@@stack \%state $line $line_nr
address@hidden is the command name.
address@hidden@@command_stack} is an array with all the @@-commands opened,
latest
+on top.
address@hidden@@stack} is an opaque variable.
address@hidden holds informations about the current context.
address@hidden is the line appearing after the command.
address@hidden
+is an opaque structure containing the information about the line number of the
+@@-command.
+The function returns the line that may be further processed.
address@hidden deftypefn
+
+
+More control of the text before formatting of the line or the item is
+achieved with the following function reference:
+
address@hidden {Function Reference} ($result_line, $open_command)
format_list_item_texi $format $line $prepended $command $number
+The @var{$format} is the list or table @@-command,
address@hidden is the item line, @var{$command} is the @dfn{format command},
address@hidden is set to the text folllowing the @dfn{format command}
+on the format argument line.
+The @var{$number} is the number of the item, as set in @code{@@enumerate}.
+The @var{$result_line} replaces the item argument.
address@hidden is an obsolete return code that can be set to
+anything.
address@hidden deftypefn
+
+Then the different @@-commands items are formatted thanks to
+function references:
+
address@hidden @strong
address@hidden lists
+The items of lists are formatted using the following function reference:
address@hidden {Function Reference} $list_item list_item $text $format $command
$formatted_command $item_number $enumerate_style $number $prepended_texi
$prepended_formatted $only_inter_item_commands $before_items $item_command
+This function formats the text between @code{@@item} commands. @var{$text}
+is the text corresponding with the item. @var{$format} is the type of format,
address@hidden or @samp{enumerate}. @var{$command} is the formatting command
+given in argument to @code{@@itemize}, @var{$formatted_command} is this command
+formatted if it is a leading command, like @code{@@minus}.
+
+If the @var{$format} is an enumerate, @var{$item_number} is the number of
+the item in the list, @var{$enumerate_style} is the argument of the enumerate,
address@hidden is the number or letter corresponding with this item.
+
+If the @var{$format} is an itemize, @var{$prepended_texi} is the text that
+appeared on the itemize line, maybe after the formatting command
+(if any), and @var{$prepended_formatted} is the corresponding text,
+formatted.
+
address@hidden is true if there are only @@-commands
+that are not considered as the item argument in the item, like
+index entries.
address@hidden is set if there is in fact no leading @code{@@item}
+for the text, as it may happen for some text following the @var{$format}
+@@-command, as in
+
address@hidden
+@@table @@asis
+Tex before items.
+
address@hidden example
address@hidden is the item command name.
+
address@hidden deftypefn
+
address@hidden two column tables
+The two columns tables (@code{@@table}, @code{@@ftable} and @code{@@vtable}),
+items are formatted using two function references,
+one for the first line located on the @code{@@item} line corresponding
+with the first column, the other for the text appearing on the
+following lines, corresponding with the second column text.
+
address@hidden {Function Reference} $table_item table_item $item_text
$index_label_text $format $command \@@command_stack $item_command
$formatted_index_entry
+This function is used to format the text on the @code{@@item} line.
address@hidden is the text line. In case there is an index entry
+associated with the @code{@@item} (as with @code{@@ftable} and
address@hidden@@vtable}), @var{$index_label_text} is the text inserted at
+the place where an index entry appears. @xref{Index entry place formatting}.
address@hidden is the type of format,
address@hidden, @samp{ftable} or @samp{vtable}. @var{$command} is the
formatting command
+given in argument to the table format command.
address@hidden@@command_stack} is an array with all the @@-commands opened,
latest
+on top.
address@hidden is the item command, @samp{@@item} or @samp{@@itemx}.
address@hidden is the index entry formatted.
address@hidden deftypefn
+
address@hidden {Function Reference} $table_line table_line $text
+This function is used to format the text on the lines following
+the @code{@@item} line. @var{$text} is the corresponding text.
address@hidden deftypefn
+
address@hidden multitable
address@hidden Formatting}
+The multitable elements formatting is controlled by the functions associated
+with two function references. One for a cell, and the other for a row.
+
address@hidden {Function Reference} $multitable_cell cell $text $item_command
\@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
+This function is used to format the text of a multitable cell, the text
+following a @code{@@item} or a @code{@@tab}.
address@hidden is the corresponding text. @var{$item_command} is the command
+used to introduce the row, such that it is possible to distinguish
+between @code{@@item} and @code{@@headitem}.
address@hidden@@columnfractions} is a reference on an array
+containing the @code{@@columnfraction} arguments, if any, and
address@hidden@@prototype_row} is a reference on an array containing the row
prototypes
+given on the @code{@@multitable} line, if any.
address@hidden@@prototype_lengths} array contains the lengths of the row
prototypes
+formatted.
address@hidden is the maximal number of columns.
address@hidden deftypefn
+
address@hidden {Function Reference} $multitable_row row $text $item_command
\@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
+This function is used to format a multitable row. @var{$text} is
+the row text, with cells allready formatted with the @code{$cell}
+function reference. @var{$item_command}, @var{\@@columnfractions},
address@hidden@@prototype_row}, @var{\@@prototype_lengths}
+and @var{$column_number} are the same than in the function reference above.
address@hidden deftypefn
+
address@hidden table
+
+By default, this function is interlinked with
address@hidden (@pxref{Init File General Block Commands})
+and @code{@@multitable} formatting since a stack of possibly nested
+multitables is stored in order to know the cell number.
+
+
address@hidden Whole table and list formatting
address@hidden Formatting of a whole table or list
+
address@hidden %format_map
+If the Texinfo command is a key of the @code{%format_map}, the associated
+value is used to specify the formatting of the construct, otherwise a function
+is called.
+The value in @code{%format_map} associated with a command is interpreted
+similarly with values associated with more simpler commands:
+
address@hidden
address@hidden
+If the text is a word, in HTML or XML, it is considered to be an XML
+or HTML element
+name, and the whole table or list is enclosed between the element opening
+and the element closing.
address@hidden
+If the text is a word followed by some text,
+the word and is interpreted as above, and the
+text is considered to be the attributes text of the element.
address@hidden
+If the text is empty nothing is added to the text.
address@hidden itemize
+
+In case the @code{%format_map} isn't used, a function reference called
address@hidden
+should be redefined, the associated function will be called each time
+a command isn't found in @code{%format_map}.
+
address@hidden {Function Reference} $whole_table_list table_list
$format_command $text $command $formatted_command $item_nr $enumerate_style
$prepended_texi $prepended_formatted \@@columnfractions \@@prototype_row
\@@prototype_lengths $column_number
address@hidden is the Texinfo command name, @var{$text} is the
+formatted items. @var{$command} is the @dfn{format command} given in argument
+to the format command, @var{$formatted_command} is the same, but formatted.
address@hidden is the remaining text on the format command line,
address@hidden is the same, but formatted.
+Only relevant in @code{@@enumerate}, @var{$item_nr} is the item number, and
address@hidden is the @code{@@enumerate} style. Only relevant in
address@hidden@@multitable}
address@hidden@@columnfractions} is a reference on an array
+containing the @code{@@columnfraction} arguments, if any,
address@hidden@@prototype_row} is a reference on an array containing the row
prototypes
+given on the @code{@@multitable} line, if any,
address@hidden@@prototype_lengths} array contains the lengths of the row
prototypes
+formatted and
address@hidden is the maximal number of columns.
address@hidden deftypefn
+
+If you still want to use @code{%format_map} but differently from
+the default, it is possible to redefine the following function reference:
+
address@hidden {Function Reference} $whole_table_list format $command $format
$text
address@hidden is the @@-command, @var{$format} is the entry associated with
address@hidden in @code{%format_map}. @var{$text} is the formatted items.
address@hidden deftypefn
+
+
address@hidden Definition formatting
address@hidden Interpretation and formatting of the definition formatting
+
+The formatting of definition commands is controlled by a main hash,
+3 strings and another hash, and and five
+functions. The main hash describes how the text on the definition line is
+interpreted, the functions control the formatting of the definition line
+and the definition function text.
+
address@hidden
+* Definition line interpretation::
+* Definition command formatting::
address@hidden menu
+
+
address@hidden Definition line interpretation
address@hidden Customizing the interpretation of a definition line
+
address@hidden %def_map
+The keys of the hash @code{%def_map} are definition command names.
+There are two types of entries:
+
address@hidden
+
address@hidden If the command is a shortcut for
+another definition command the value is a text and the definition
+command is replaced by the text.
+
+For example if we have:
address@hidden
address@hidden'deftruc'@} = '@@defvr @{A address@hidden';
address@hidden example
+
+and a line like
address@hidden
+@@deftruc var
address@hidden example
+
+the line will be transformed in
address@hidden
+@@defvr @{A address@hidden var
address@hidden example
+
address@hidden
+If the command is not a shortcut, it is associated with an array
+reference. The first element is @samp{f}, @samp{v} or @samp{t} corresponding
+with the index type (@samp{f} for function, @samp{v} for variable,
address@hidden for type).
+
+The remaining of the array describes how to interpret the text following
+the definition command on the definition command line.
+The entry item specify what corresponds
+with the next bracketed item or word. Currently the possibilities are
address@hidden, @samp{name}, @samp{type}, @samp{class}, @samp{arg}
+and @samp{argtype}. @samp{arg} means that the arguments are not mixed
+with type definitions, with @samp{argtype} types are mixed with
+definitions. When there is no @samp{arg} nor @samp{argtype} it is
+the same than @samp{argtype}.
+
+For example if we have
address@hidden
address@hidden'defvr'@} = [ 'v', 'category', 'name' ];
address@hidden example
+
+The first bracketed item following @code{@@defvr} is considered
+to be the category and the next one is the name. The index associated
+with the definition line is the variables index.
address@hidden itemize
+
+Some characters are special with regard with definition parsing, they
+are delimiters, the can have a role in definition argument determination,
+and also hae a special meaning in arguments parsing.
+This is not very well documented in the Texinfo manual,
+so it is subject to change. Strings allow to determine the delimiters:
+
address@hidden @code
address@hidden $def_argument_separator_delimiters
+Characters that separate arguments, currently @code{()[],}.
address@hidden $def_always_delimiters
+Character that are always delimiters, if they appear in a type or a
+parameter,
address@hidden()[]}.
address@hidden $def_in_type_delimiters
+Character that are considered as delimiters only if in a type. In
+a parameter they are part of the parameter.
address@hidden vtable
+
+
address@hidden Definition command formatting
address@hidden Customization of the definition formatting
+
+Five functions are used when formatting a definition command:
+
address@hidden @strong
address@hidden category name
address@hidden {Function Reference} $category definition_category $category
$class $style $command
+This function precise a category name associating a class
address@hidden (if given) with @var{$category}. The @var{$style} of the
+definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t},
+for type. The @var{$command} is the definition @@-command.
address@hidden deftypefn
+
address@hidden {Function Reference} $entry definition_index_entry $name $class
$style $command
+This function precise a name associating a class
address@hidden (if given) with @var{$name}. This is used to do an index
+entry associated with th edefinition command. The @var{$style} of the
+definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t},
+for type. The @var{$command} is the definition @@-command.
address@hidden deftypefn
+
address@hidden formatting of the definition line
address@hidden {Function Reference} $line def_line $class_category_class $name
$type $arguments $index_label \@@arguments_array \@@arguments_type_array
\@@unformatted_arguments_array $command $class_name $category $class $style
$original_command
+This function formats the definition line. @var{$class_category} is the
+category
+formatted with @code{$definition_category}, @var{$name}, @var{$type} and
address@hidden are the element of the definition line. @var{$index_label} is
+the text inserted at the place where an index entry appears.
address@hidden entry place formatting}.
address@hidden@@arguments_array} is an array holding the definition arguments,
+formatted. @var{\@@arguments_type_array} holds the type of the definition
+arguments, like @samp{name}, @samp{type} and similar arguments,
address@hidden
address@hidden and @samp{param}. @var{\@@unformatted_arguments_array}
+holds the arguments without @@-command substitution. @var{$command} is the
+definition command, after substitution.
address@hidden is the class applied on name, formatted
+as specified in @code{definition_index_entry}. @var{$category} and
address@hidden are the corresponding arguments. @var{$style} corresponds
+with the index style, as explained above. @var{$original_command} is the
+unmodified definition @@-command.
address@hidden deftypefn
+
address@hidden definition text
address@hidden {Function Reference} $definition_text def_item $text
$only_inter_item_commands $command
+This function formats the definition text, @var{$text}.
address@hidden is true if there are only @@-commands
+that are not considered as the definition argument in the definition
+text, like index entries.
address@hidden is the definition @@-command.
address@hidden deftypefn
+
address@hidden the whole definition
address@hidden {Function Reference} $definition def $text $command
+This function formats the whole definition. The definition line and text
+formatted by the above functions are in @var{$text}.
address@hidden is the definition @@-command.
address@hidden deftypefn
+
address@hidden table
+
address@hidden Menus indices and floats formatting
address@hidden Menus, indices and floats formatting
+
address@hidden
+* Menu formatting::
+* Indices formatting::
+* Floats and lists of floats formatting::
address@hidden menu
+
address@hidden Menu formatting
address@hidden Menu formatting
+
+There are two possibilities for menu formatting:
+
address@hidden @bullet
address@hidden format the whole menu in a preformatted environment, like
+in @ref{Preformatted block command formatting};
address@hidden format the menu in table with more specialized formatting for
each
+part of the menu;
address@hidden itemize
+
+The simple formatting in a preformatted is used if
+the configuration variable @code{SIMPLE_MENU} is true,
+otherwise the format with tables is used (this is the default).
+
+In HTML, if the configuration variable @code{USE_ACCESSKEY} is set,
+the @code{accesskey} attribute is used in anchors. In that case the
address@hidden hash is used for the access key.
+
+In @command{texi2any}, a menu is considered to be composed of 2 parts, the
address@hidden entries} and the @dfn{menu comments} (@pxref{Writing a Menu}).
+Menu entries are further
+divided in an @dfn{entry link} and optionnaly an @dfn{entry description}.
+The entry link consists in a node name and an optional menu entry
+name (@pxref{Menu Parts}).
+
address@hidden
+* Menu components formatting::
+* Simple menu formatting:: formatting of a whole menu in a simple
+ preformatted environement
+* Table menu formatting:: formatting of a whole menu in a
+ table environment
address@hidden menu
+
+
address@hidden Menu components formatting
address@hidden The formatting of the different menu components
+
+If in a preformatted context (and @code{SIMPLE_MENU} isn't set), the
+menu link and description are put in the same preformatted environment.
+This can be avoided with the configuration variable
address@hidden
+
+Two function references are associated with the formatting of the
+different parts of a menu:
address@hidden {Function Reference} $link menu_link $section \%state $href
$node $name $ending $has_name \@@command_stack $preformatted
$node_normalized_formatted
address@hidden is the section name corresponding with the link, @var{$href}
+is the link hypertextual reference. @var{$href} may be absent.
address@hidden holds informations about the current context.
address@hidden is the node name, @var{$name} is the
+name of the node. @var{$ending} is the text ending the link entry,
+in general @samp{::} followed by some spaces.
address@hidden is true if the entry has an explicit name, otherwise
address@hidden has been constructed using the formatted node name.
address@hidden@@command_stack} is an array containing the commands enclosing
+the menu link. It is used in the default case to detect if the
+menu link is right in the @command{@@menu} or not, since if it is not
+right below the menu the formatting is simpler.
address@hidden is true if in preformatted context.
address@hidden File Expansion Contexts}.
address@hidden is the node with spaces normalized
+and formatted.
address@hidden deftypefn
+
+This command is not called if @code{SIMPLE_MENU} is set.
+
address@hidden {Function Reference} $description menu_description
$description_text \%state $element_text
address@hidden is the text of the menu description.
+The formatted link is also here if in preformatted context and
address@hidden is not set.
address@hidden
+should be used similarly than for the menu link. @var{$element_text}
+is the heading of the element associated with the node.
address@hidden and @var{$preformatted} are the same than for the
+menu link.
address@hidden deftypefn
+
+The @dfn{menu comment} part is formatted like a normal command,
+called @code{menu_comment}. It is only used if not in preformatted
+environment.
+The default is to have it be formatted
+like a @ref{Preformatted block command formatting}, with
address@hidden
address@hidden'menu_comment'@} =
address@hidden
+ 'begin' => "<tr><th colspan=\"3\" align=\"left\" valign=\"top\">",
+ 'end' => "</th></tr>", 'class' => 'menu-comment',
address@hidden
address@hidden example
+
+
address@hidden Simple menu formatting
address@hidden Simple menu formatting in a preformatted environment
+
+If the menu is to be formatted in a single preformatted environment,
+an entry for @samp{menu} and @samp{detailmenu}
+should be added to the @code{%complex_format_map}
+hash (@pxref{Preformatted block command formatting}).
+In the default case, if the user didn't add an entry himself, a very simple
+entry is used, with:
+
address@hidden
+$complex_format_map->@{'menu'@} = @{ 'begin' => '' , 'end' => '',
+ 'class' => 'menu-preformatted' @};
address@hidden example
+
+
address@hidden Table menu formatting
address@hidden The formatting of the menu in a table
+
+In the default case, the name of the section corresponding with the
+node is used instead of the node name. If the configuration
+variable @code{NODE_NAME_IN_MENU} is
+true, however, node names are used. If the configuration variable
address@hidden
+is true and menu entry equal menu description the description is not printed.
+This is the default. Likewise, if node or section name equal entry name,
+do not print entry name.
+
address@hidden $MENU_SYMBOL
address@hidden $UNNUMBERED_SYMBOL_IN_MENU
+A symbol, @code{$MENU_SYMBOL} is put at the beginning of menu entries
+when the node name is used. The default is @samp{•} for HTML, @samp{*}
+for text formats.
+If @code{$UNNUMBERED_SYMBOL_IN_MENU} is true it is
+also put at the beginning of unnumbered section names (in HTML). This is not
+done by default.
+
address@hidden $MENU_PRE_STYLE
address@hidden $MENU_PRE_COMPLEX_FORMAT
+The menu comments are considered to be preformatted text. The style
+associated with this preformatted text is determined by
address@hidden Default is @samp{font-family: serif}.
+The entry similar with an entry in @code{%complex_format_map}
+(@pxref{Preformatted block command formatting}) used when the menu
+appears in a preformatted
+enviroment is in
address@hidden, and, in the default case is:
address@hidden
+$MENU_PRE_COMPLEX_FORMAT = @{
+ 'pre_style' => $MENU_PRE_STYLE,
+ 'class' => 'menu-preformatted'
+ @};
address@hidden example
+
+The CSS class associated with menu comments is @code{menu-comments}.
+
+The following function reference controls the formatting of a wole menu
+or a detailmenu in that case:
+
address@hidden {Function Reference} $menu menu_command $command
$menu_components_text
address@hidden is the menu command, currently @samp{menu}, @samp{detailmenu}
+or @samp{direntry}.
address@hidden is the formatted menu components text, obtained
+as explained above.
address@hidden deftypefn
+
+
address@hidden Indices formatting
address@hidden Indices formatting
+
+Two different things needs to be handled for indices formatting, the place
+where the index term appears, the index entry, and the index list itself.
+The indexing commands like @code{@@cindex} determines where index entries
+appear, and the index list is printed with a @code{@@printindex} command.
+
address@hidden
+* Index entry place formatting:: Index entries in the main document are
+ targets for hypertext references
+* Index list formatting:: Customizing the formatting of the index list
address@hidden menu
+
+
address@hidden Index entry place formatting
address@hidden Formatting of index entries
+
+Index entry places in the main text may be the target for
+references. Their formatting
+is controlled by the function associated with the following function
+reference:
+
address@hidden {Function Reference} $target index_entry_label $identifier
$preformatted $entry $index_name $index_command $texi_entry $formatted_entry
$in_region_not_in_output \%index_entry
address@hidden should be used to create
+a target for links (typically associated with a name or id
+attribute in HTML).
address@hidden is true if the index entry appeared in preformatted text.
address@hidden is the index entry with all the @@-commands removed.
address@hidden is the index name, @var{$command} is the index command which
+may be a index command like @code{@@cindex}, but also a definition or
+a table. @var{$texi_entry} is the index entry with @@-commands, and
address@hidden the entry formatted.
address@hidden is set if the index entry appears in a region
+formatting (for example @code{@@titlepage}) and not in the
+output document.
address@hidden is a reference on a hash holding informations about
+the index entry.
address@hidden deftypefn
+
+Regular index entries are (like @code{@@cindex}) are
+formatted using the following function reference:
address@hidden {Function Reference} $index_entry index_entry_command $command
$index_name $label $entry_texi $entry_formatted
address@hidden, @var{$index_name}, @var{$entry_texi} and @var{$entry_formatted}
+are the same as above, and @var{$label} is what could be used as a label,
+formatted using the function above.
address@hidden deftypefn
+
+
address@hidden Index list formatting
address@hidden Customizing the formatting of index lists
+
+There is an elaborate default index formatting, with
+index summary by letter linking to index entries grouped by letters too,
+with the possibility of index pages split accross files. This system may be
+completly bypassed by redefining the function reference that is called when
address@hidden@@printindex} is encountered:
+
address@hidden {Function Reference} $index_text printindex $index_name
\%printindex
address@hidden is the index name appearing on the
address@hidden@@printindex} line.
address@hidden is a reference on a hash holding informations
+on the index.
+The index formatted should be returned by this function reference.
address@hidden deftypefn
+
+If the default index formatting is used, there are still possibilities
+to customize part of the formatting.
+The index entries are sorted alphabetically. A whole index list is
+considered to be composed of letter entries. A letter entry is composed
+by all the index entries beginning with that letter. A letter may
+be a non alphabetical character, but we call it letter here.
+
+An index summary appears at the beginning and at the end of an index list,
+and should be used to jump directly to a letter entry. Indices lists
+may be split across pages, thus the different letters may appear on different
+files. The number of index entries appearing on each page is determined
+by a configuration variable @code{SPLIT_INDEX}, if set. The default is not
+to split indices.
+
+The formatting of all these elements is controlled by the following
+function references:
+
address@hidden @emph
address@hidden formatting of a letter in a summary
address@hidden {Function Reference} {($result_letter, $identifier, $is_symbol)}
summary_letter $letter $file $identifier $index_element_id $number
$index_element $index_name
+This function is used to format a letter appearing in a summary, refering
+to a letter entry in the index list.
address@hidden is the letter. @var{$file} is the file name where the letter
+entry appears. More precisely, it is empty when the letter entry is on the
+same page than the summary, it contains the file name when the index page
+is split accross page. @var{$identifier} is an identifier for the target
+letter entry. @var{$index_element_id} is the identifier associated with the
+element holding the letter. @var{$number} and @var{$index_element} are
+not specified. @var{$index_name} is the name of the index.
+The function returns the resulting letter @var{$result_letter}, an
+identifier for the letter @var{$identifier}, to be used in anchors, for example
+and @code{$is_symbol} should be true if the letter is not a regular letter
+but a symbol.
address@hidden deftypefn
+
address@hidden formatting of a summary
address@hidden {Function Reference} $summary index_summary
\@@alphabetical_letters \@@nonalphabetical_letters
address@hidden@@alphabetical_letters} and @var{\@@nonalphabetical_letters}
contain the
+formatted summary letters, formatted with the above function.
address@hidden deftypefn
+
address@hidden formatting of an index entry
address@hidden {Function Reference} $entry index_entry $entry_href $entry_text
$element_href $element_heading $entry_file $element_file $entry_target
$entry_element_target $in_region_not_in_output \%index_entry
address@hidden is a reference to the place where the index entry
+appeared, @var{$entry_text} is the corresponding text. @var{$element_href}
+is a reference to the beginning of the element containing
+the index entry, @var{$element_heading} is the heading of the element.
address@hidden is the file where the index entry appear, while
address@hidden is the file of the element. @var{$entry_target} is the
+target of the index entry, @var{$entry_element_target} is the
+element target.
address@hidden is set if the index entry appears in a region
+formatting (for example @code{@@titlepage}) and not in the
+output document.
address@hidden is a reference on a hash holding informations about
+the index entry.
address@hidden deftypefn
+
address@hidden formatting of letter entry
address@hidden {Function Reference} $letter_entry index_letter $letter
$identifier $index_entries_text
+This function formats a letter entry, consisting in all the index entries
+beginning with this letter. @var{$letter} is the letter, @var{$identifier}
+should be used to create a target for links (typically links from summaries),
+and @var{$index_entries_text} is the text of the index entries formatted as
+described above.
address@hidden deftypefn
+
address@hidden formatting of whole index
address@hidden {Function Reference} $index print_index $index_text $index_name
address@hidden is the text of all the index entries grouped by letter
+appearing in that page formatted as above. It is undef if there are
+no entries or theindex name isn't known. @var{index_name} is the name of
+the index, the argument of @code{@@printindex}.
address@hidden deftypefn
address@hidden table
+
+
address@hidden Floats and lists of floats formatting
address@hidden Floats and lists of floats
+
+Floats appear in the @code{@@float} environment, optionaly with a style
+and a label, and with optionnal @code{@@caption} and @code{@@shortcaption}.
+Their list appear after a @code{@@listoffloats}.
+
+A hash reference is associated with each float, it is available in some
+formatting functions. The keys are:
address@hidden @code
address@hidden caption_texi
address@hidden shortcaption_texi
+A reference on an array containing the caption or shortcaption lines,
+with texi @@-commands.
address@hidden style_texi
+The style with texi @@-commands.
address@hidden style_id
+The unique identifier associated with the style.
address@hidden style
+The style formatted.
address@hidden nr
+The number with the same conventions than makeinfo (use the chapter number a
+dot and then the number of the float of that style in the chapter, or an
+absolute number if in unnumbered).
address@hidden chapter_nr
+The number of the chapter containing the float.
address@hidden nr_in_chapter
+The number of the float in the chapter.
address@hidden absolut_nr
+The number of the float in the document.
address@hidden texi
+The label with @@-commands.
address@hidden name
+The label formatted.
address@hidden id
+The unique identifier associated with the label. Usefull to make an anchor
+or a reference.
address@hidden target
+The target that can be used to refer to that float.
address@hidden element
+A reference on a structure representing the element the float appear in.
address@hidden table
+
address@hidden
+* Float formatting:: Formatting of floats
+* List of floats formatting:: Formatting the lists of floats
address@hidden menu
+
address@hidden Float formatting
address@hidden Formatting a float
+
+First there is an occasion to construct a texinfo text for the caption, using
+the caption texinfo lines and the informations in the float structure.
+The returned lines will be formatted in the main program. A function reference
+is used here:
+
address@hidden {Function Reference} {(\@@caption_lines_returned,
\@@shortcaption_lines_returned)} caption_shortcaption \%float \@@caption_lines
\@@shortcaption_lines
address@hidden is the structure defined above. @var{\@@caption_lines} and
address@hidden@@shortcaption_lines} are references on arrays containing the
+texinfo lines for caption and short caption. @var{\@@caption_lines_returned}
+and @var{\@@shortcaption_lines_returned} are references on an array
+containing the texinfo lines for the caption and shortcaption.
address@hidden deftypefn
+
+Then the float is formatted with the following function reference:
+
address@hidden {Function Reference} $text float $float_text \%float
$caption_text $shortcaption_text
address@hidden is the text appearing within the @code{@@float}, formatted.
address@hidden is still the structure defined above. @var{$caption_text} and
address@hidden are the caption and short caption build with the
+above function and formatted.
address@hidden deftypefn
+
+It is also possible to do something when a caption or a shortcaption appear
+with the following function reference:
+
address@hidden {Function Reference} $text caption_shortcaption_command $command
$formatted_caption \@@texi_lines \%float
address@hidden is the @@-command, @samp{caption} or @samp{shortcaption}.
address@hidden is the caption text, formatted, while
address@hidden@@texi_lines} is a reference on an array containing the caption
lines,
+this time without any formatting.
address@hidden is still the structure defined above.
+
+In the default case this function reference returns an empty string.
address@hidden deftypefn
+
+
address@hidden List of floats formatting
address@hidden Formatting lists of floats
+
+A list of floats is introduced by @code{@@listoffloats}. The argument of
address@hidden@@listoffloats} is the @dfn{style}. First the style texinfo can
be
+modified with the following function reference:
+
address@hidden {Function Reference} $style_texi_returned listoffloats_style
$style_texi
address@hidden is the @code{@@listoffloats} argument with texinfo
+@@-commands kept. It is possible to make changes to the @var{$style_texi} and
+return a modified string, still with @@-commands. The modified string
+is formatted in the main program.
address@hidden deftypefn
+
+After that, for each of the floats with that style, first there is a
+possibility to modify the float style and the float caption before they
+are formatted in the main program, with the following function references:
+
address@hidden {Function Reference} $float_style_texi_returned
listoffloats_float_style $style_texi \%float
address@hidden is the style, and @var{\%float} is the structure described
+above. This function reference returns a style to be formatted in the
+main program.
address@hidden deftypefn
+
address@hidden {Function Reference} (\@@caption_texi_returned,
$caption_or_shortcaption) listoffloats_caption \%float
address@hidden is the structure described
+above. This function reference returns a caption to be formatted in the
+main program, @var{\@@caption_texi_returned}, and a string,
address@hidden that is either @samp{caption} or
address@hidden that can be used by the main program if this information
+is needed.
address@hidden deftypefn
+
+Each entry is formatted by:
+
address@hidden {Function Reference} $listoffloats_entry listoffloats_entry
$style_texi \%float $float_style $caption $href
address@hidden is the style with @@-commands, @var{$float_style} is the
+style returned by the above function and formatted. @var{$caption} is the
+caption returned by the above function formatted. @var{\%float} is the
+structure corresponding with the float, and @var{$href} is an href pointing to
+the float location.
address@hidden deftypefn
+
+Lastly, the whole @code{@@listoffloats} is formatted by:
+
address@hidden {Function Reference} $listoffloats listoffloats $style_texi
$style \@@listoffloats_entries
address@hidden is the style with @@-commands, @var{$style} is the
+style returned by the above function and formatted. The array reference
address@hidden@@listoffloats_entries} holds the entries formatted by the above
+function.
address@hidden deftypefn
+
address@hidden Handling special regions
address@hidden Handling special regions
+
address@hidden %region_formats_kept
+Special regions @code{@@titlepage}, @code{@@documentdescription} and
address@hidden@@copying} are removed from the document before the last pass in
the
+default case. They can be kept if the value associated with the @@-command
+in the @code{%region_formats_kept} hash is true.
+
+The following function reference is called when starting the
+formatting of a special region, if defined:
+
address@hidden {Function Reference} begin_special_region $region_name \%state
\@@region_lines
address@hidden is the region name.
address@hidden holds informations about the context of the region formatting.
address@hidden@@region_lines} holds the region lines.
address@hidden deffn
+
+The following function reference is called when ending the formatting
+of the special region, if defined:
+
address@hidden {Function Reference} $formatting_result end_special_region
$region_name \%state $formatted_region
address@hidden is the region name.
address@hidden holds informations about the context of the region formatting.
address@hidden is the result of the region formatting.
+The function reference returns the result of the region formatting, after
+possibly modifying it.
address@hidden deftypefn
+
+The @code{@@insertcopying} @@-command is formatted by
address@hidden {Function Reference} $insertcopying insertcopying $text $comment
$simple_text
address@hidden is the text appearing in @code{@@copying}, formatted.
address@hidden is the text with texi removed, should be very simple
+text.
address@hidden is the text formatted in string context
+with minimal formatting but no elements.
address@hidden deftypefn
+
+The copying commane that is to be used at the beginning of output
+files is formatted by
address@hidden {Function Reference} $copying_comment_formatted copying_coment
\@@copying_lines $text $comment $simple_text
address@hidden@@copying_lines} is an array containing the Texinfo lines in
@code{@@copying}.
address@hidden is the text appearing in @code{@@copying}, formatted.
address@hidden is the text with texi removed, should be very simple
+text.
address@hidden is the text formatted in string context
+with minimal formatting but no elements.
address@hidden deftypefn
+
address@hidden@@documentdescription} is handled by the following function
+reference, that should set the configuration variable
@code{documentdescription}:
+
address@hidden {Function Reference} documentdescription
\@@documentdescription_lines $text $comment $simple_text
address@hidden@@documentdescription_lines} is an array containing the Texinfo
lines in @code{@@documentdescription}.
address@hidden is the text appearing in @code{@@documentdescription}, formatted.
address@hidden is the text with texi removed, should be very simple
+text.
address@hidden is the text formatted in string context
+with minimal formatting but no elements.
address@hidden deffn
+
address@hidden Title Page Customization}, for specifics about the title
+page handling.
+
+
address@hidden Other and unknown commands
address@hidden Customizing other commands, and unknown commands
+
address@hidden skipped command
address@hidden unknown command
+
+Many commands without braces are available in Texinfo, sometimes with
+a specific syntax. For example we have @code{@@sp}, @code{@@noindent},
address@hidden@@documentlanguage}, @code{@@oddheading}, @code{@@headings},
address@hidden@@shortcontents}, @code{@@shorttitlepage} or @code{@@comment}.
address@hidden interprets
+some of these commands and some functions or variables are used for
+their formatting or to access their information.
+In the default case, however, most of these constructs are ignored.
+
+It is possible to change how the things following these commands
+on the line are handled, what is considered to be an arg for those
+commands and it is also possible to keep them instead of discarding
+them such that it is possible to handle them specially, with the
+same function than the one used for unknown commands.
+
address@hidden %misc_command
+Those special commands without braces are the key of a hash:
address@hidden The associated value is a reference on a
+hash enabling to set the properties of these commands. The
+keys of this hash reference is the name of a property, the value
+is the value of the property. For example here we have @code{line}
+for the @code{arg} property for the @code{command} @@-command.
+
address@hidden
address@hidden'command'@} = @{'arg' => 'line', 'skip' => 'space'@};
address@hidden example
+
+The properties and possible values are:
+
address@hidden @code
address@hidden skip
+This property enables to set what is skipped after the command arguments.
+Here are the possible values:
address@hidden @code
address@hidden line
+The remaining of the line is skipped.
address@hidden space
+Spaces are skipped but not newline.
address@hidden whitespace
+Spaces are skipped
address@hidden linewhitespace
+Spaces are skipped if there are only spaces remaining on the line.
address@hidden linespace
+Spaces are skipped, but not newline if
+there are only spaces remaining on the line
address@hidden table
+
address@hidden arg
+If the associated value is @code{line} the line is considered to be the
+argument. If it is a number it is the number of args (separated by spaces).
address@hidden keep
+If true the args and the macro are kept, otherwise they are discarded.
+The defaut is to have @code{keep} undef for all the commands.
+If @code{keep} is true for @code{@@verbatiminclude} the default
+action for this macro is not done.
address@hidden table
+
+These commands are processed by the @code{misc_command_line} function
+reference. This is somehow redundant with @ref{HTML Customization for
+Title Commands} xx.
+
address@hidden {Function Reference} {($command, $line, $result)}
misc_command_line $command $line \@@args \@@stack \%state
address@hidden is the @@-command name. @var{$line} is what the main program
+would leave on the line. @var{\@@args} holds the @@-command arguments.
address@hidden@@stack} is an opaque variable.
address@hidden holds informations about the current context.
+The result is the @@-command that should be considered in the
+main program, the line that should be processed further and
+the result of the command formatting.
address@hidden deftypefn
+
+
+Commands which do not appear in the hashes
address@hidden, @code{%simple_map_pre},
address@hidden, @code{%line_command_map} or @code{%misc_command},
+or that appear in
address@hidden but with @code{keep} true are processed by the
+following function reference:
+
address@hidden {Function Reference} {($result_line, $result, $result_text,
$message)} unknown $command $line $pass
address@hidden is the @@-command, @var{$line} is the line following
+the @var{$command}. @var{$pass} is the pass of texi2html
+(@pxref{texi2any's Three Passes}). @var{$result} is a boolean. If it
+is true then the other return values are taken into account otherwise
+the default actions are used. In case @var{$result} is true,
address@hidden is the new line to be processed further,
address@hidden is the resulting formatted text and @var{$message},
+if defined is a message outputted to the output with line number added
+by @command{texi2any}.
address@hidden deftypefn
+
+Commands with braces not specified above
+nor in @code{%style_map}, @code{%style_map_pre} and
address@hidden are processed
+by the following function reference
+
address@hidden {Function Reference} {($result, $result_text, $message)}
unknown_style $command $text \%state $no_close $no_open
address@hidden is the @@-command, @var{$text} is the text appearing within
+the braces (allready formatted).
address@hidden holds informations about the current context.
+If @var{$text} is split in paragraphs each paragraph is passed through
+the function, and @var{$no_close} is true if it is not the last paragraph,
+while @var{$no_open} is true if it is not the first paragraph.
address@hidden is a boolean. If it is true then the other return
+values are taken into account otherwise the default actions are
+used. In case @var{$result} is true, @var{$result_text} is the resulting
+formatted text
+and @var{$message}, if defined is a message outputted to the output
+with line number added by @command{texi2any}.
address@hidden deftypefn
+
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- texinfo ChangeLog doc/texinfo.txi doc/texi2olda...,
Karl Berry <=