doc/tta_api/api_includes/Texinfo-Document.texi

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

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

Texinfo::Document - Texinfo document tree and information

@node Texinfo@asis{::}Document SYNOPSIS
@section Texinfo::Document SYNOPSIS

@verbatim
  use Texinfo::Parser;

  my $parser = Texinfo::Parser::parser();
  my $document = $parser->parse_texi_file("somefile.texi");

  my $indices_information = $document->indices_information();
  my $float_types_arrays = $document->floats_information();
  my $internal_references_array
    = $document->internal_references_information();

  # $identifier_target is an hash reference on normalized
  # node/float/anchor/namedanchor names.
  my $identifier_target = $document->labels_information();

  # A hash reference, keys are @-command names, value is the
  # corresponding @-commands tree element or an
  # array reference holding all the corresponding @-commands.
  # Also contains dircategory and direntry list.
  my $global_commands_information
                 = $document->global_commands_information();

  # a hash reference on document information (encodings,
  # input file name, for example).
  my $global_information = $document->global_information();
@end verbatim

@node Texinfo@asis{::}Document NOTES
@section Texinfo::Document 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{::}Document DESCRIPTION
@section Texinfo::Document DESCRIPTION

This module is used to represent parsed Texinfo documents, with the Texinfo
tree and associated information.  A document is always obtained from
a Texinfo parser method call as the result of parsing a Texinfo text or file.

For example, the @emph{$document} obtained in the following example is a
@code{Texinfo::Document} object:

@verbatim
  my $parser = Texinfo::Parser::parser();
  my $document = $parser->parse_texi_file("somefile.texi");
@end verbatim

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

@node Texinfo@asis{::}Document Getting document information
@subsection Getting document information

The main purpose of Texinfo::Document methods is to retrieve information
on a Texinfo document.

The Texinfo tree obtained by parsing a Texinfo document is available through
@code{tree}:

@table @asis
@item $tree = tree($document, $handler_only)
@anchor{Texinfo@asis{::}Document $tree = tree($document@comma{} $handler_only)}
@cindex @code{tree}

The @emph{$tree} is a hash reference.  It is described in
@ref{Texinfo@asis{::}Parser TEXINFO TREE}.

If @emph{$handler_only} is set and XS extensions are used, the returned
tree holds a reference to the C Texinfo tree data only, but no actual
Perl Texinfo tree elements.  This avoids building the Perl tree if all the
functions called with the tree as argument have XS interfaces, directly
use the C data and do not need the Perl tree.

@end table

Some global information is available through @code{global_information}:

@table @asis
@item $info = global_information($document)
@anchor{Texinfo@asis{::}Document $info = global_information($document)}
@cindex @code{global_information}

The @emph{$info} returned is a hash reference.  The possible keys are

@table @asis
@item included_files
@anchor{Texinfo@asis{::}Document included_files}

An array of included file paths as they appear in the document.  Binary
strings.  From both @code{@@include} and @code{@@verbatiminclude}.

@item input_encoding_name
@anchor{Texinfo@asis{::}Document input_encoding_name}

@code{input_encoding_name} string is the encoding name used for the
Texinfo code.

@item input_file_name
@anchor{Texinfo@asis{::}Document input_file_name}

@item input_directory
@anchor{Texinfo@asis{::}Document input_directory}

The name of the main Texinfo input file and the associated directory.
Binary strings.  In @code{texi2any}, they should come from the command line
(and can be decoded with the encoding in the customization variable
@code{COMMAND_LINE_ENCODING}).

@end table

If the global information changed, @code{global_information} should be called
to update the hash returned by previous calls before accessing the hash again.

@end table

Some command lists are available, such that it is possible to go through
the corresponding tree elements without walking the tree.  They are
available through @code{global_commands_information}:

@table @asis
@item $commands = global_commands_information($document)
@anchor{Texinfo@asis{::}Document $commands = global_commands_information($document)}
@cindex @code{global_commands_information}

@emph{$commands} is an hash reference.  The keys are @@-command names.  For
@@-commands that may appear multiple time in the Texinfo document, the
associated values are array references containing all the corresponding
tree elements.  For @@-commands that should appear only once, the associated
value is the tree element.

The following list of commands is also available as a key:

@table @asis
@item dircategory_direntry
@anchor{Texinfo@asis{::}Document dircategory_direntry}

An array of successive @code{@@dircategory} and @code{@@direntry} as they appear
in the document.

@item language_commands
@anchor{Texinfo@asis{::}Document language_commands}

An array of successive @code{@@documentlanguage}, @code{@@documentscript}
and @code{@@documentlanguagevariant} as they appear in the document.
@code{@@documentlanguage} and @code{@@documentscript} elements are not registered
if already set from command-line or from initialization files.

@end table

@end table

All the @@-commands that have an associated label (so can be the
target of cross references) @asis{}-@asis{}-@asis{} @code{@@node}, @code{@@anchor}, @code{@@namedanchor}
and @code{@@float} with label @asis{}-@asis{}-@asis{} have a normalized name associated, constructed as
described in the @emph{HTML Xref} node in the Texinfo documentation.  Those
normalized labels and the association with @@-commands is available through
@code{labels_information}:

@table @asis
@item $identifier_target = labels_information($document)
@anchor{Texinfo@asis{::}Document $identifier_target = labels_information($document)}
@cindex @code{labels_information}

@emph{$identifier_target} is a hash reference whose keys are normalized
labels, and the associated value is the corresponding @@-command.

@item $labels_list = labels_list ($document)
@anchor{Texinfo@asis{::}Document $labels_list = labels_list ($document)}
@cindex @code{labels_list}

@emph{$labels_list} is a list of Texinfo tree command elements that
could be the target of cross references.

@end table

Information on @code{@@float} grouped by type of floats, each type corresponding
to potential @code{@@listoffloats} is available through @code{floats_information}.

@table @asis
@item $float_types = floats_information($document)
@anchor{Texinfo@asis{::}Document $float_types = floats_information($document)}
@cindex @code{floats_information}

@emph{$float_types} is a hash reference whose keys are normalized float
types (the first float argument, or the @code{@@listoffloats} argument).
The normalization is the same as for the first step of node names
normalization. The value is a list of array references, one per float
of that type.  The first item of the float array reference is the
float tree element.  The second item of the float array reference
is the section relations information of the section containing the float.

@end table

Internal references, nodes and section information may also be available.

@table @asis
@item $internal_references_array = internal_references_information($document)
@anchor{Texinfo@asis{::}Document $internal_references_array = internal_references_information($document)}
@cindex @code{internal_references_information}

The function returns an array reference of cross-reference commands referring
to the same document with @@-commands that refer to node, anchors or floats.

@item $nodes_relations_list = nodes_list($document)
@anchor{Texinfo@asis{::}Document $nodes_relations_list = nodes_list($document)}

Returns an array reference containing each node relations information.

@item $sections_relations_list = sections_list($document)
@anchor{Texinfo@asis{::}Document $sections_relations_list = sections_list($document)}

Returns an array reference containing each section relations information.

@item $sectioning_root = sectioning_root($document)
@anchor{Texinfo@asis{::}Document $sectioning_root = sectioning_root($document)}

Return the sectioning root information.  It is an hash reference with the
@emph{section_children} key, an array reference of the top level sectioning
commands relations.

@end table

Information about defined indexes, indexes merging and index entries is
available through @code{indices_information}.

@table @asis
@item $indices_information = $document->indices_information()
@anchor{Texinfo@asis{::}Document $indices_information = $document->indices_information()}
@cindex @code{indices_information}

@emph{$indices_information} is a hash reference.  The keys are index names.
The associated value is an hash reference with keys:

@table @asis
@item in_code
@anchor{Texinfo@asis{::}Document in_code}

1 if the index entries should be formatted as code, 0 in the opposite case.

@item name
@anchor{Texinfo@asis{::}Document name}

The index name.

@item merged_in
@anchor{Texinfo@asis{::}Document merged_in}

In case the index is merged to another index, this key holds the name of
the index the index is merged into.  It takes into account indirectly
merged indexes.

@item index_entries
@anchor{Texinfo@asis{::}Document index_entries}

An array reference containing index entry structures for index entries
associated with the index.  The index entry could be associated to
@@-commands like @code{@@cindex}, or @code{@@item} in @code{@@vtable}, or definition
commands entries like @code{@@deffn}.

The keys of the index entry structures are

@table @asis
@item index_name
@anchor{Texinfo@asis{::}Document index_name}

The index name associated to the command.  Not modified if the corresponding
index is merged in another index (with @code{@@synindex}, for example).

@item entry_element
@anchor{Texinfo@asis{::}Document entry_element}

The element in the parsed tree associated with the @@-command holding the
index entry.

@item entry_number
@anchor{Texinfo@asis{::}Document entry_number}

The number of the index entry in the index.

@end table

@end table

The following shows a partial view of @emph{$indices_information} corresponding
to the default indexes
@emph{cp} and @emph{fn}, the @emph{fn} index having its entries formatted as code and
the indexes corresponding to the following texinfo

@verbatim
  @defindex some
  @defcodeindex code

  $index_names = {'cp' => {'name' => 'cp', 'in_code' => 0, },
                  'fn' => {'name' => 'fn', 'in_code' => 1, },
                  'some' => {'name' => 'some', 'in_code' => 0},
                  'code' => {'name' => 'code', 'in_code' => 1}};
@end verbatim

@end table

@node Texinfo@asis{::}Document Merging and sorting indexes
@subsection Merging and sorting indexes

Merged and sorted document indexes are also available.  Parsed indexes
are not merged nor sorted, @ref{Texinfo@asis{::}Indices NAME,, Texinfo::Indices} functions are
called to merge or sort the indexes the first time the following
methods are called.  The results are afterwards associated to the
document and simply returned.

@table @asis
@item $merged_indices = $document->merged_indices()
@anchor{Texinfo@asis{::}Document $merged_indices = $document->merged_indices()}
@cindex @code{merged_indices}

Merge indexes if needed and return merged indexes.  The @emph{$merged_indices}
returned is a hash reference whose keys are the index names and values arrays
of index entry structures described in @ref{Texinfo@asis{::}Document index_entries,, index_entries}.

@ref{Texinfo@asis{::}Indices $merged_indices = merge_indices($indices_information),, @code{Texinfo::Indices::merge_indices}}
is used to merge the indexes.

It is not useful to call this function directly if indexes are sorted, as
it is already called by index sorting functions.

@end table

In general, the sorting methods should not be called directly, instead
@ref{Texinfo@asis{::}Convert@asis{::}Converter Index sorting} Converter methods should be
used, which already call the following functions.

@table @asis
@item $sorted_indices = sorted_indices_by_index($document, $converter, $use_unicode_collation, $lang_sorting_locale)
@anchor{Texinfo@asis{::}Document $sorted_indices = sorted_indices_by_index($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale)}

@item $sorted_indices = sorted_indices_by_letter($document, $converter, $use_unicode_collation, $lang_sorting_locale)
@anchor{Texinfo@asis{::}Document $sorted_indices = sorted_indices_by_letter($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale)}
@cindex @code{sorted_indices_by_index}
@cindex @code{sorted_indices_by_letter}

@code{sorted_indices_by_letter} returns the indices sorted by index and letter,
while @code{sorted_indices_by_index} returns the indexes with all entries
of an index together.

By default, indexes are sorted according to the @emph{Unicode Collation Algorithm}
defined in the @url{http://www.unicode.org/reports/tr10/, Unicode Technical Standard
#10}, without language-specific collation
tailoring.  If @emph{$use_unicode_collation} is set to 0, the sorting will not use
the @emph{Unicode Collation Algorithm} and simply sort according to the codepoints.
The optional @emph{$lang_sorting_locale} language is used for linguistic
tailoring of the sorting, if possible.

When sorting by letter, an array reference of letter hash references is
associated with each index name.  Each letter hash reference has two
keys, a @emph{letter} key with the letter, and an @emph{entries} key with an array
reference of sorted index entries beginning with the letter.  The letter
is a character string suitable for sorting letters, but is not necessarily
the best to use for output.

When simply sorting, the array of the sorted index entries is associated
with the index name.

The optional @emph{$converter} argument is used for error reporting, if not
defined, the @emph{$document} is used.

@ref{Texinfo@asis{::}Indices $index_entries_sorted = sort_indices_by_index($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale),, @code{Texinfo::Indices::sort_indices_by_index}}
and @ref{Texinfo@asis{::}Indices $index_entries_sorted = sort_indices_by_letter($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale),, @code{Texinfo::Indices::sort_indices_by_letter}}
are used to sort the indexes, if needed.

In general, those methods should not be called directly, instead
@ref{Texinfo@asis{::}Convert@asis{::}Converter $sorted_indices = $converter->get_converter_indices_sorted_by_index(),, @code{Texinfo::Convert::Converter::get_converter_indices_sorted_by_index}}
and @ref{Texinfo@asis{::}Convert@asis{::}Converter $sorted_indices = $converter->get_converter_indices_sorted_by_letter(),, @code{Texinfo::Convert::Converter::get_converter_indices_sorted_by_letter}}
should be used.  The @code{Texinfo::Convert::Converter} methods call
@code{sorted_indices_by_index} and @code{sorted_indices_by_letter}.

@end table

@node Texinfo@asis{::}Document Getting errors and warnings
@subsection Getting errors and warnings

A document has a list of error and warning messages associated, that is used to
register errors and warning messages in.  To get the errors registered in the
document, the @code{errors} method should be called.

@table @asis
@item $error_warnings_list = errors($document)
@anchor{Texinfo@asis{::}Document $error_warnings_list = errors($document)}

This function returns as the errors since setting
up the @emph{$document} (or calling the function). The returned
@emph{$error_warnings_list} is an array of hash references
one for each error, warning or error line continuation.  The format of
these hash references is described
@ref{Texinfo@asis{::}Report $error_count  = count_errors ($error_messages),, Texinfo::Report::count_errors}.

@end table

@node Texinfo@asis{::}Document Getting customization options values registered in document
@subsection Getting customization options values registered in document

By default, customization information is registered in a document object
just after parsing the Texinfo code. Structuring and tree transformation
methods then get customization variables values from the document object
they have in argument. The customization variables set by default may be a
subset selected to be useful for structuring and tree transformation codes.

To retrieve Texinfo customization variables you can call @code{get_conf}:

@table @asis
@item $value = $document->get_conf($variable_name)
@anchor{Texinfo@asis{::}Document $value = $document->get_conf($variable_name)}

Returns the value of the Texinfo customization variable @emph{$variable_name}
(possibly @code{undef}), if the variable value was registered in the document,
or @code{undef}.

@end table

@node Texinfo@asis{::}Document Registering information in document
@subsection Registering information in document

Some information can be registered in the document.

@table @asis
@item register_document_options ($document, $options)
@anchor{Texinfo@asis{::}Document register_document_options ($document@comma{} $options)}
@cindex @code{register_document_options}

The @emph{$options} hash reference holds options for the document. These options
should be Texinfo customization options.  Usually, the options registered in
the document contain those useful for structuring and tree transformation
getting place between Texinfo code parsing and conversion to output formats.
Indeed, document customization options are mainly accessed by structuring and
tree transformation methods (by calling @ref{Texinfo@asis{::}Document $value = $document->get_conf($variable_name),, @code{get_conf}}). The options should in general be registered before
the calls to @code{get_conf}.

@item set_document_global_info($document, $key, $value)
@anchor{Texinfo@asis{::}Document set_document_global_info($document@comma{} $key@comma{} $value)}
@cindex @code{set_document_global_info}

Add @emph{$value} @emph{$key} global information to @emph{$document}.  This method
should not be generally useful, as document global information is already
set by the Texinfo parser.  The information set should be available through
the next calls to @ref{Texinfo@asis{::}Document $info = global_information($document),, global_information}.
The method should in general be called before the calls to
@code{global_information}.

@end table

@node Texinfo@asis{::}Document Methods for Perl and C code interactions
@subsection Methods for Perl and C code interactions

The parsing of Texinfo code, structuring and transformations of the document
and tree called through Texinfo Perl modules may be done by pure Perl modules
or by Perl XS extensions in native code (written in C).
In general, it makes no difference whether pure Perl or C code is used.  When
the document and tree are modified through native code based on C code, the
Perl data are automatically rebuilt when calling the accessors described
previously.  In some cases, however, specific functions need to be called to
pass information from C data to Perl or perform actions related to C data.

When the tree is directly accessed in Perl (not through a document)
but is modified by C code, when the Perl tree holds only a reference to
C data, but no Perl data, or when you want to update all the Perl data
before doing changes in Perl only, you can build the Perl data from the C data
with @code{build_tree}:

@table @asis
@item $perl_tree = build_tree($tree, $no_store)
@anchor{Texinfo@asis{::}Document $perl_tree = build_tree($tree@comma{} $no_store)}
@cindex @code{build_tree}

Return a @emph{$perl_tree}, built from C data.  If there is no Perl extensions in
C, the tree is returned as is.  The tree built is based on the Texinfo parsed
document data associated to the Texinfo tree @emph{$tree}.

If the optional @emph{$no_store} argument is set, remove the C data.  It may be
useful if you call functions that modify the Perl tree only, and not the C
data, followed by functions call that output the result and uses the C data if
present.  Removing the C data makes sure that the output is not based on
unmodified C data, but on the modified Perl data.

@end table

Note that the Perl tree associated to a document is rebuilt from C data
when calling @code{$document->tree()}.  Similarly, the tree is rebuilt when
calling other accessors that depend on the document tree.  Therefore
@code{build_tree} should mainly be called when there is no document associated to a
tree and @code{$document->tree()} cannot be called to rebuild the tree,
or with the @emph{$no_store} argument, if you want to remove the link with C data.

Some methods allow to release the memory held by C data associated
to a Texinfo parsed document:

@table @asis
@item destroy_document($document)
@anchor{Texinfo@asis{::}Document destroy_document($document)}
@cindex @code{destroy_document}

Release the C data corresponding to @emph{$document}.

@end table

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

@ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}. @ref{Texinfo@asis{::}Structuring NAME,, Texinfo::Structuring}.

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

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

@node Texinfo@asis{::}Document COPYRIGHT AND LICENSE
@section Texinfo::Document 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.