doc/tta_api/api_includes/Texinfo-Transformations.texi

@node Texinfo@asis{::}Transformations
@chapter Texinfo::Transformations

@node Texinfo@asis{::}Transformations NAME
@section Texinfo::Transformations NAME

Texinfo::Transformations - transformations of Texinfo tree

@node Texinfo@asis{::}Transformations NOTES
@section Texinfo::Transformations NOTES

The Texinfo Perl module main purpose is to be used in @code{texi2any} to convert
Texinfo to other formats.  There is no promise of API stability.

@node Texinfo@asis{::}Transformations DESCRIPTION
@section Texinfo::Transformations DESCRIPTION

Includes miscellaneous methods such as as
@code{insert_nodes_for_sectioning_commands} that adds nodes for sectioning commands
without nodes and @code{complete_tree_nodes_menus_in_document} and
@code{complete_tree_nodes_missing_menu} that completes the node menus based on the
sectioning tree.

Methods for copying and modifying the Texinfo tree used for default
conversion to output formats are in @ref{Texinfo@asis{::}ManipulateTree NAME,, Texinfo::ManipulateTree}.

@node Texinfo@asis{::}Transformations METHODS
@section Texinfo::Transformations METHODS

No method is exported in the default case.

@table @asis
@item complete_tree_nodes_menus_in_document($document, $add_section_names_in_entries)
@anchor{Texinfo@asis{::}Transformations complete_tree_nodes_menus_in_document($document@comma{} $add_section_names_in_entries)}
@cindex @code{complete_tree_nodes_menus_in_document}

Add menu entries or whole menus for nodes associated with sections,
based on the sectioning tree.  If the optional
@code{$add_section_names_in_entries} argument is set, a menu entry
name is added using the section name.  This function should be
called after @ref{Texinfo@asis{::}Structuring sectioning_structure($document),, sectioning_structure}.

@item complete_tree_nodes_missing_menu($document, $use_section_names_in_entries)
@anchor{Texinfo@asis{::}Transformations complete_tree_nodes_missing_menu($document@comma{} $use_section_names_in_entries)}
@cindex @code{complete_tree_nodes_missing_menu}

Add whole menus for nodes associated with sections and without menu,
based on the @emph{$document} sectioning tree.
If the optional @emph{$add_section_names_in_entries} argument is set, a menu entry
name is added using the section name.  This function should be
called after @ref{Texinfo@asis{::}Structuring sectioning_structure($document),, sectioning_structure}.

@item fill_gaps_in_sectioning_in_document($document, $commands_heading_tree)
@anchor{Texinfo@asis{::}Transformations fill_gaps_in_sectioning_in_document($document@comma{} $commands_heading_tree)}
@cindex @code{fill_gaps_in_sectioning_in_document}

This function adds empty @code{@@unnumbered} and similar commands in a
@emph{$document} tree to fill gaps in sectioning.  This may be used, for example,
when converting from a format that can handle gaps in sectioning.

In the default case, the added sectioning commands headings are empty.  It is
possible to use instead the @emph{$commands_heading_tree} Texinfo tree element.

If the sectioning commands are lowered or raised (with @code{@@raisesections},
@code{@@lowersection}) the tree may be modified with @code{@@raisesections} or
@code{@@lowersection} added to some tree elements.

@item insert_nodes_for_sectioning_commands($document)
@anchor{Texinfo@asis{::}Transformations insert_nodes_for_sectioning_commands($document)}
@cindex @code{insert_nodes_for_sectioning_commands}

Insert nodes for sectioning commands without node in @code{$document}
tree.

@item menu_to_simple_menu($menu)
@anchor{Texinfo@asis{::}Transformations menu_to_simple_menu($menu)}
@cindex @code{menu_to_simple_menu}

@code{menu_to_simple_menu} transforms the tree of a menu tree element.

A simple menu has no @emph{menu_comment}, @emph{menu_entry} or @emph{menu_entry_description}
container anymore, their content are merged directly in the menu in
@emph{preformatted} container.

Note that this kind of tree is not supported by other codes, so this
transformation should be avoided unless one knows exactly what to expect.

@item protect_hashchar_at_line_beginning($tree, $document)
@anchor{Texinfo@asis{::}Transformations protect_hashchar_at_line_beginning($tree@comma{} $document)}
@cindex @code{protect_hashchar_at_line_beginning}

Protect hash (#) character at the beginning of line such that they would not be
considered as lines to be processed by the CPP processor.  The @emph{$document}
argument is optional.  If defined, the @emph{$document} is used for error reporting
in case an hash character could not be protected because it appeared in a raw
formatted environment (@code{@@tex}, @code{@@html}...).

@item $modified_tree = reference_to_arg_in_tree($tree, $document)
@anchor{Texinfo@asis{::}Transformations $modified_tree = reference_to_arg_in_tree($tree@comma{} $document)}
@cindex @code{reference_to_arg_in_tree}

Modify @emph{$tree} by converting reference @@-commands to simple text using one of
the arguments.  This transformation can be used, for example, to remove
reference @@-command from constructed node names trees, as node names cannot
contain reference @@-command while there could be some in the tree used in input
for the node name tree.  The @emph{$document} argument is optional.  If given,
the converted reference @@-command is removed from the @emph{$document} internal
references list.

A @emph{$modified_tree} is not systematically returned, if the @emph{$tree} in argument
is not replaced, undef may also be returned.

@item regenerate_master_menu($document, $use_sections)
@anchor{Texinfo@asis{::}Transformations regenerate_master_menu($document@comma{} $use_sections)}
@cindex @code{regenerate_master_menu}

Regenerate the @emph{$document} Top node master menu, replacing the first
detailmenu in Top node menus or appending at the end of the Top node menu.

@emph{$use_sections} is an optional argument.  If set, sections associated with
nodes are used as labels in the generated master menu.

@end table

@node Texinfo@asis{::}Transformations SEE ALSO
@section Texinfo::Transformations SEE ALSO

@url{http://www.gnu.org/s/texinfo/manual/texinfo/, Texinfo manual},
@ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}, @ref{Texinfo@asis{::}ManipulateTree NAME,, Texinfo::ManipulateTree}.

@node Texinfo@asis{::}Transformations AUTHOR
@section Texinfo::Transformations AUTHOR

Patrice Dumas, <bug-texinfo@@gnu.org>

@node Texinfo@asis{::}Transformations COPYRIGHT AND LICENSE
@section Texinfo::Transformations COPYRIGHT AND LICENSE

Copyright 2010- Free Software Foundation, Inc.  See the source file for
all copyright years.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.