[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo/tp/Texinfo Structuring.pm Convert/HTML.pm
From: |
Patrice Dumas |
Subject: |
texinfo/tp/Texinfo Structuring.pm Convert/HTML.pm |
Date: |
Mon, 26 Sep 2011 22:44:37 +0000 |
CVSROOT: /sources/texinfo
Module name: texinfo
Changes by: Patrice Dumas <pertusus> 11/09/26 22:44:37
Modified files:
tp/Texinfo : Structuring.pm
tp/Texinfo/Convert: HTML.pm
Log message:
Document some Texinfo::Structuring methods.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/tp/Texinfo/Structuring.pm?cvsroot=texinfo&r1=1.84&r2=1.85
http://cvs.savannah.gnu.org/viewcvs/texinfo/tp/Texinfo/Convert/HTML.pm?cvsroot=texinfo&r1=1.152&r2=1.153
Patches:
Index: Structuring.pm
===================================================================
RCS file: /sources/texinfo/texinfo/tp/Texinfo/Structuring.pm,v
retrieving revision 1.84
retrieving revision 1.85
diff -u -b -r1.84 -r1.85
--- Structuring.pm 17 Sep 2011 20:28:18 -0000 1.84
+++ Structuring.pm 26 Sep 2011 22:44:36 -0000 1.85
@@ -41,15 +41,21 @@
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
%EXPORT_TAGS = ( 'all' => [ qw(
- sectioning_structure
- nodes_tree
associate_internal_references
- number_floats
elements_directions
elements_file_directions
merge_indices
+ nodes_tree
+ number_floats
+ menu_to_simple_menu
+ output_internal_links
+ sectioning_structure
+ set_menus_to_simple_menu
sort_indices
sort_indices_by_letter
+ split_by_node
+ split_by_section
+ split_pages
) ] );
@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
@@ -59,11 +65,6 @@
$VERSION = '0.01';
-=head1 NAME
-
-Texinfo::Structuring - Set informations in Texinfo::Parser tree and rearrange
-
-=cut
my %types_to_enter;
foreach my $type_to_enter ('brace_command_arg', 'misc_line_arg',
@@ -1322,3 +1323,243 @@
}
1;
+
+__END__
+=head1 NAME
+
+Texinfo::Structuring - informations and transformations in Texinfo::Parser tree
+
+=head1 SYNOPSIS
+
+ use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats
+ associate_internal_references split_by_node split_by_section split_pages
+ merge_indices sort_indices_by_letter sort_indices elements_directions
+ elements_file_directions);
+ # $tree is a Texinfo document tree. $parser is a Texinfo::Parser object.
+ my $sections_root = sectioning_structure ($parser, $tree);
+ my $top_node = nodes_tree($parser);
+ number_floats($parser->floats_information());
+ associate_internal_references($parser);
+ my $elements;
+ if ($split_at_nodes) {
+ $elements = split_by_node($tree);
+ } else {
+ $elements = split_by_section($tree);
+ }
+ # $split may be 'section', 'chapter', a false value. Else means 'node'.
+ my $pages = split_pages($elements, $split);
+ elements_directions($parser, $elements);
+ elements_file_directions($parser, $elements);
+
+ my ($index_names, $merged_indices, $index_entries)
+ = $parser->indices_information();
+ my $merged_index_entries
+ = merge_indices($index_names, $merged_indices, $index_entries);
+ my $index_entries_sorted;
+ if ($sort_by_letter) {
+ $index_entries_sorted = sort_indices_by_letter($parser,
+ $merged_index_entries, $index_names);
+ } else {
+ $index_entries_sorted = sort_indices($parser, $merged_index_entries,
+ $index_names);
+ }
+
+
+=head1 DESCRIPTION
+
+Texinfo::Structuring first allows to collect informations on a Texinfo tree.
+In most case, it also requires a parser object to do that job. Thanks to
+C<sectioning_structure> the hierarchy of sectioning commands is determined.
+The node and menus tree is analysed with C<nodes_tree>. Floats get their
+standard numbering with C<number_floats> and internal references are matched
+up with nodes, floats or anchors with C<associate_internal_references>.
+
+It is also possible to group the top-level contents of the tree, which consist
+in nodes and sectioning commands into elements that group together a node and
+the next sectioning element. With C<split_by_node> nodes are considered
+to be the main sectionning elements, while with C<split_by_section> the
+sectioning command elements are the main elements. The first mode is typical
+of Info format, while the second correspond to a traditional book.
+The elements may be further split in I<pages>, which are not pages as
+in book pages, but more like web pages, and hold series of elements.
+
+The elements may have directions to other elements prepared
+by C<elements_directions>. C<elements_file_directions> should also
+set direction related to files, provided files are associated with
+elements by the user.
+
+C<merge_indices> may be used to merge indices, which may be sorted
+with C<sort_indices> or C<sort_indices_by_letter> to sort by letters.
+
+Other miscellaneous methods include C<set_menus_to_simple_menu> and
+C<menu_to_simple_menu> to change the menu texinfo tree. Last,
+C<output_internal_links> may be used to output element and
+index entries references, mostly for HTML output.
+
+
+=head1 METHODS
+
+No method is exported in the default case.
+
+=over
+
+=item $sections_root = sectioning_structure ($parser, $tree)
+
+This function goes through the tree and gather information on
+the document structure for sectioning commands. It returns the
+root of the sectioning commands tree.
+
+For section elements, it sets:
+
+=over
+
+=item level
+
+The level in the sectioning tree hierarchy. 0 is for C<@top> or
+C<@part>, 1 for C<@chapter>, C<@appendix>... This level is corrected
+by C<@raisesections> and C<@lowersections>.
+
+=item number
+
+The sectioning element number.
+
+=item section_childs
+
+An array holding sectioning elements children of the element.
+
+=item section_up
+
+=item section_prev
+
+=item section_next
+
+The up, previous and next sectioning elements.
+
+=item toplevel_next
+
+=item toplevel_prev
+
+The next and previous sectioning elements of toplevel sectioning
+elements (like C<@top>, C<@chapter>, C<@appendix>) , not taking into
+account C<@part> elements.
+
+=back
+
+=item my $top_node = nodes_tree($parser)
+
+Goes through menu and nodes and set directions. Returns the top
+node.
+
+This functions sets:
+
+=over
+
+=item menu_child
+
+The first child in the menu of the node.
+
+=item menu_up
+
+=item menu_next
+
+=item menu_prev
+
+Up, next and previous directions as set in menus.
+
+=item node_up
+
+=item node_prev
+
+=item node_next
+
+Up, next and previous directions for the node.
+
+=back
+
+=item number_floats($float_information)
+
+Number the floats as described in the Texinfo manual. Sets
+the I<number> key of the float tree elements.
+
+=item associate_internal_references($parser)
+
+Verify that internal references (C<@ref> and similar without
+fourth of fifth argument) have an associated node, anchor or float.
+Set the I<label> key in the I<extra> hash of the reference tree
+element to the associated labeled tree element.
+
+=item $elements = split_by_node($tree)
+
+Returns a reference array of elements where a node is associated to
+the following sectioning commands. Sectioning commands without nodes
+are also with the previous node, while nodes without sectioning commands
+are alone in their elements.
+
+Elements are regular tree items with type I<element>, the
+associated nodes and sectioning tree items are in the array associated
+with the I<contents> key. They have directions, namely I<element_next>
+and I<element_prev> pointing to the previous and the next element.
+
+In the I<extra> hash they have
+
+=over
+
+=item no_node
+
+A special case, if there are no nodes in the document, the value is set.
+
+=item node
+
+=item element_command
+
+The node command associated with the element.
+
+=item section
+
+The sectioning command associated with the element node.
+
+=back
+
+=item $elements = split_by_section($tree)
+
+Similarly with C<split_by_node>, returns an array of elements. This time,
+lone nodes are associtated with the previous sections and lone sections
+makes up an element.
+
+The extra hash keys set are the same, except that I<element_command> is
+the sectioning command associated with the element, and I<no_node> is
+replaced by I<no_section>.
+
+=item $pages = split_pages($elements, $split)
+
+The elements from the array reference argument are grouped based on the
+value of I<$split>. The I<$pages> array with all those groupings
+is returned by the function. The possible values for I<$split> are
+
+=over
+
+=item chapter
+
+The elements are split at chapter or other toplevel sectioning elements.
+
+=item section
+
+The elements are split at sectioning commands below chapter.
+
+=item value evaluating to false
+
+No splitting, only one page is returned, holding all the elements.
+
+=item anything else
+
+Each element has its own page.
+
+=back
+
+Pages are regular tree items with type I<page>, holding thier elements
+in the I<contents> array. They also have directions, namely I<page_next>
+and I<page_prev> pointing to the previous and the next page.
+
+=back
+
+=cut
Index: Convert/HTML.pm
===================================================================
RCS file: /sources/texinfo/texinfo/tp/Texinfo/Convert/HTML.pm,v
retrieving revision 1.152
retrieving revision 1.153
diff -u -b -r1.152 -r1.153
--- Convert/HTML.pm 19 Sep 2011 17:53:45 -0000 1.152
+++ Convert/HTML.pm 26 Sep 2011 22:44:37 -0000 1.153
@@ -1267,7 +1267,7 @@
if (!defined($text)) {
# happens with bogus @-commands without argument, like @strong something
#cluck "text not defined in _convert_style_command";
- #print STDERR Texinfo::Structuring::_print_current($command);
+ #print STDERR Texinfo::Parser::_print_current($command);
return '';
}
# handle the effect of kbdinputstyle
@@ -1616,7 +1616,7 @@
my $text = $args->[0]->{'normal'};
if (!defined($text)) {
# happens with bogus @-commands without argument, like @strong something
- #print STDERR Texinfo::Structuring::_print_current($command);
+ #print STDERR Texinfo::Parser::_print_current($command);
return '';
}
return $self->xml_protect_text('<') .$text .$self->xml_protect_text('>');
@@ -1635,7 +1635,7 @@
my $text = $args->[0]->{'normal'};
if (!defined($text)) {
# happens with bogus @-commands without argument, like @strong something
- #print STDERR Texinfo::Structuring::_print_current($command);
+ #print STDERR Texinfo::Parser::_print_current($command);
return '';
}
return $self->xml_protect_text('<').'<code>' .$text
@@ -1656,7 +1656,7 @@
my $text = $args->[0]->{'normal'};
if (!defined($text)) {
# happens with bogus @-commands without argument, like @strong something
- #print STDERR Texinfo::Structuring::_print_current($command);
+ #print STDERR Texinfo::Parser::_print_current($command);
return '';
}
return $self->xml_protect_text('^') .$text;
@@ -1674,7 +1674,7 @@
my $text = $args->[0]->{'normal'};
if (!defined($text)) {
# happens with bogus @-commands without argument, like @strong something
- #print STDERR Texinfo::Structuring::_print_current($command);
+ #print STDERR Texinfo::Parser::_print_current($command);
return '';
}
# FIXME is it the right way to do? Or should it be handled in heading_text?
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- texinfo/tp/Texinfo Structuring.pm Convert/HTML.pm,
Patrice Dumas <=