Texinfo::Common
***************

NAME
====

Texinfo::Common - Classification of commands and miscellaneous methods

SYNOPSIS
========

  use Texinfo::Common qw(expand_today expand_verbatiminclude);
  if ($Texinfo::Common::accent_commands{$a_command}) {
    print STDERR "$a_command is an accent command\n";
  }

  my $today_tree = expand_today($converter);
  my $verbatiminclude_tree
     = expand_verbatiminclude(undef, $verbatiminclude);

DESCRIPTION
===========

Texinfo::Common holds interesting hashes classifying Texinfo @-commands, as well as miscellaneous methods that may be useful for any backend converting texinfo trees.

It also defines, as our variable a hash for default indices, named %index_names.  The format of this hash is described in Texinfo::Parser indices_information.

COMMAND CLASSES
===============

Hashes are defined as our variables, and are therefore available outside of the module.

The key of the hashes are @-command names without the @.  The following hashes are available:

%all_commands

     All the @-commands.

%no_brace_commands

     Commands without brace with a single character as name, like * or :.  The value is an ascii representation of the command.  It may be an empty string.

%misc_commands

     Command that do not take braces and are not block commands either, like @node, @chapter, @cindex, @deffnx, @end, @footnotestyle, @set, @settitle, @indent, @definfoenclose, @comment and many others.

%default_index_commands

     Index entry commands corresponding to default indices. For example @cindex.

%root_commands

     Commands that are at the root of a Texinfo document, namely @node and sectioning commands, except heading commands.

%sectioning_commands

     All the sectioning and heading commands.

%brace_commands

     The commands that take braces.  The associated value is the maximum number of arguments.

%letter_no_arg_commands

     @-commands with braces but no argument corresponding to letters, like @AA{} or @ss{} or @o{}.

%accent_commands

     Accent @-commands taking an argument, like @' or @ringaccent including @dotless and @tieaccent.

%style_commands

     Commands that mark a fragment of texinfo, like @strong, @cite, @code or @asis.

%code_style_commands

     style_commands that have their argument in code style, like @code.

%regular_font_style_commands

     style_commands that have their argument in regular font, like @r or @slanted.

%context_brace_commands

     @-commands with brace like @footnote, @caption and @math whose argument is outside of the main text flow in one way or another.

%ref_commands

     Cross reference @-command referencing nodes, like @xref.

%explained_commands

     @-commands whose second argument explain first argument and further @-command call without first argument, as @abbr and @acronym.

%block commands

     Commands delimiting a block with a closing @end.  The value is conditional for @if commands, def for definition commands like @deffn, raw for @-commands that have no expansion of @-commands in their bodies and multitable for @multitable. Otherwise it is set to the number of arguments separated by commas that may appear on the @-command line. That means 0 in most cases, 1 for @quotation and 2 for @float.

%raw_commands

     @-commands that have no expansion of @-commands in their bodies, as @macro, @verbatim or @ignore.

%format_raw_commands

     @-commands associated with raw output format, like @html, or @docbook.

%texinfo_output_formats

     Cannonical output formats that have associated conditionals.  In practice %format_raw_commands plus info and plaintext.

%def_commands

%def_aliases

     Definition commands.  %def_aliases associates an aliased command to the original command, for example defun is associated to deffn.

%menu_commands

     @-commands with menu entries.

%align_commands

     @-commands related with alignement of text.

%region_commands

     Block @-commands that enclose full text regions, like @titlepage.

%preformatted_commands

%preformatted_code_commands

     %preformatted_commands is for commands whose content should not be filled, like @example or @display.  If the command is meant for code, it is also in %preformatted_code_commands, like @example.

%item_container_commands

     Commands holding @item with @item that contains blocks of text, like @itemize.

%item_line_commands

     Commands with @item that have their arguments on their lines, like @ftable.

METHODS
=======

No method is exported in the default case.

Most methods takes a $converter as argument, sometime optionally, to get some information and use methods for error reporting, see Texinfo::Convert::Converter NAME and Texinfo::Report NAME.

$tree = expand_today($converter)

     Expand today's date, as a texinfo tree with translations.

$tree = expand_verbatiminclude($converter, $verbatiminclude)

     The $converter argument may be undef.  $verbatiminclude is a @verbatiminclude tree element.  This function returns a @verbatim tree elements after finding the included file and reading it.

$tree = definition_category($converter, $def_line)

     The $converter argument may be undef.  $def_line is a def_line texinfo tree container.  This function returns a texinfo tree corresponding to the category of the $def_line taking the class into account, if there is one.

$result = numbered_heading ($converter, $heading_element, $heading_text, $do_number)

     The $converter argument may be undef.  $heading_element is a heading command tree element.  $heading_text is the already formatted heading text.  if the $do_number optional argument is defined and false, no number is used and the text is returned as is. This function returns the heading with a number and the appendix part if needed.

($caption, $prepended) = float_name_caption ($converter, $float)

     $float is a texinfo tree @float element.  This function returns the caption that should be used for the float formatting and the $prepended texinfo tree combining the type and label of the float.

$text = enumerate_item_representation($specification, $number)

     This function returns the number or letter correponding to item number $number for an @enumerate specification $specification, appearing on an @enumerate line.  For example

       enumerate_item_representation('c', 3)

     is e.

trim_spaces_comment_from_content($contents)

     Remove empty spaces after commands or braces at begin and spaces and comments at end from a content array, modifying it.

$normalized_name = normalize_top_node_name ($node_string)

     Normalize the node name string given in argument, by normalizing Top node case.

protect_comma_in_tree($tree)

     Protect comma characters, replacing , with @comma{} in tree.

protect_colon_in_tree($tree)

protect_node_after_label_in_tree($tree)

     Protect colon with protect_colon_in_tree and characters that are special in node names after a label in menu entries (tab dot and comma) with protect_node_after_label_in_tree. The protection is achieved by putting protected characters in @asis{}.

$contents_result = protect_first_parenthesis ($contents)

     Return a contents array reference with first parenthesis in the contents array reference protected.

protect_hashchar_at_line_beginning($parser, $tree)

     Protect hash character at beginning of line if the line is a cpp line directive.  The $parser argument maybe undef, if it is defined it is used for error reporting in case an hash character could not be protected because it appeared in a raw environment.

move_index_entries_after_items_in_tree($tree)

     In @enumerate and @itemize from the tree, move index entries appearing just before @item after the @item.  Comment lines between index entries are moved too.

$command = find_parent_root_command($parser, $tree_element)

     Find the parent root command of a tree element (sectioning command or node). The $parser argument is optional, it is used to continue through @insertcopying if in a @copying.

valid_tree_transformation($name)

     Return true if the $name is a known tree transformation name that may be passed with TREE_TRANSFORMATIONS to modify a texinfo tree.

SEE ALSO
========

Texinfo::Parser NAME, Texinfo::Convert::Converter NAME and Texinfo::Report NAME.

AUTHOR
======

Patrice Dumas, <pertusus@free.fr>

COPYRIGHT AND LICENSE
=====================

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.