[Po4a-commits] po4a/lib/Locale/Po4a TeX.pm,1.26,1.27

Nicolas FRAN??OIS po4a-devel@lists.alioth.debian.org
Sat, 19 Feb 2005 21:47:40 +0000


Update of /cvsroot/po4a/po4a/lib/Locale/Po4a
In directory haydn:/tmp/cvs-serv21276/lib/Locale/Po4a

Modified Files:
	TeX.pm 
Log Message:
Some cleanups and more documentation.


Index: TeX.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/TeX.pm,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- TeX.pm	19 Feb 2005 21:43:08 -0000	1.26
+++ TeX.pm	19 Feb 2005 21:47:37 -0000	1.27
@@ -52,7 +52,7 @@
 
 This module can also be customized by lines starting with "% po4a:" in the
 TeX file.
-These customization are described
+These customization are described in the B<INLINE CUSTOMIZATION> section.
 
 =head1 OPTIONS ACCEPTED BY THIS MODULE
 
@@ -144,11 +144,58 @@
 in the default lists.
 
 Note: currently, the behaviour of commands specified in the TeX files (see the
-B<INLINE CUSTIOMIZATION> section) cannot be overriden with these options.
+B<INLINE CUSTOMIZATION> section) cannot be overriden with these options.
 
 If you don't want to translate the chapters and sections, then you can specify:
  -o untranslated=chapter,section
 
+=head1 INLINE CUSTOMIZATION
+
+The TeX module can be customized with lines starting by "% po4a:".
+These lines are interpreted as commands to the parser.
+The following commands are recognized:
+
+=over 4
+
+=item % po4a: command I<command1> alias I<command2>
+
+Indicates that the arguments of the I<command1> command should be
+treated as the arguments of the I<command2> command.
+
+=item % po4a: command I<command1> I<function1>
+
+Indicates that the I<command1> command should be handled by I<function1>.
+
+=item % po4a: command <command1> x,y,z,t
+
+This permits a better control of the translated arguments and some
+verifications of the number of arguments.
+
+The meaning of the x, y, z and t is the following:
+  * x is the number of optional arguments (between [])
+      0 - no optional argument
+     -1 - variable
+      n - maximum number of optional arguments
+  * y is the number of arguments
+    maybe x and y are not needed
+  * z indexes of the optional arguments that have to be translated
+     -1 - all optional argument should be translated
+      0 - none
+  1 3 7 - the 1st, 3rd and 7th arguments should be translated
+  * t indexes of the arguments that have to be translated
+
+It could be useful to define commands without argument as "0,0,,"
+instead of either translated or untranslated.
+
+=item % po4a: environment <env1> <function1>
+
+Indicates that the I<env1> environment should be handled by I<function1>.
+
+=back
+
+See the B<INTERNAL FUNCTIONS> section for the list of function which could be
+used for commands or environments.
+
 =cut
 
 # Directory name of the main file.
@@ -176,40 +223,9 @@
 
 =head1 WRITING DERIVATE MODULES
 
-=head1 INTERNAL FUNCTIONS used to write derivated parsers
-
-=head2 Command functions
-
 =over 4
 
-=item translate_joined
-
-Every argument of the command is translated separately, and the command is
-reassembled with its arguments in the output document.
-
-=item untranslated
-
-No argument of the command is proposed for translation. The command is
-reassembled with its arguments in the output document.
-
-=back
-
-=head2 Environment functions
-
-These functions are called when a \begin command is found.
-
-=over 4
-
-=item push_environment
-
-This function push the environment name in a stack, and push the \begin command
-untranslated in the output document.
-This stack of environments is then used to change the behaviour of the parser
-(e.g. blocks are not re-wrapped in the verbatim environment).
-The type of PO strings is either set to the last environment of this stack or
-to the name of the command (if the string is part of a command argument).
-
-=back
+=item pre_trans
 
 =cut
 
@@ -237,6 +253,10 @@
     return $str;
 }
 
+=item post_trans
+
+=cut
+
 sub post_trans {
     my ($self,$str,$ref,$type)=@_;
     my $transstr=$str;
@@ -264,10 +284,15 @@
 # comment with the first translated string of the paragraph.
 my @comments = ();
 
-# Wrapper arround Transtractor's translate, with pre- and post-processing
-# filters.
-# Comments of a paragraph are inserted as a PO comment for the first
-# translated string of this paragraph.
+=item translate
+Wrapper arround Transtractor's translate, with pre- and post-processing
+filters.
+
+Comments of a paragraph are inserted as a PO comment for the first
+translated string of this paragraph.
+
+=cut
+
 sub translate {
     my ($self,$str,$ref,$type) = @_;
     my (%options)=@_;
@@ -315,37 +340,40 @@
 ### COMMANDS SEPARATION ###
 ###########################
 
-# =item get_leading_command($buffer)
-#
-# This function returns:
-#
-# =over 4
-#
-# =item The command name
-#
-# If no command is found at the beginning of the given buffer, this
-# string will be empty.
-#
-# =item A variant
-#
-# This indicate if a variant is used. For example, an asterisk (*) can
-# be added at the end of sections command to specify that they should
-# not be numbered. In this case, this field will contain "*". If there
-# is not variant, the field is an empty string.
-#
-# =item An array of optional arguments
-#
-# =item An array of mandatory arguments
-#
-# =item The remaining buffer
-#
-# The rest of the buffer after the removal of this leading command and
-# its arguments. If no command is found, the original buffer is not
-# touched and returned in this field.
-#
-# =back
-#
-# =cut
+=item get_leading_command($buffer)
+
+This function returns:
+
+=over 4
+
+=item A command name
+
+If no command is found at the beginning of the given buffer, this string
+will be empty.  Only commands that can be separated are considered.
+The $separated_commands variable contains the space separated list of
+these commands.
+
+=item A variant
+
+This indicate if a variant is used.  For example, an asterisk (*) can
+be added at the end of sections command to specify that they should
+not be numbered.  In this case, this field will contain "*".  If there
+is not variant, the field is an empty string.
+
+=item An array of optional arguments
+
+=item An array of mandatory arguments
+
+=item The remaining buffer
+
+The rest of the buffer after the removal of this leading command and
+its arguments.  If no command is found, the original buffer is not
+touched and returned in this field.
+
+=back
+
+=cut
+
 sub get_leading_command {
     my ($self, $buffer) = (shift,shift);
     my $command = ""; # the command name
@@ -382,9 +410,6 @@
                         $opt .= $2
                     }
                 } else {
-                    # FIXME: an argument can contain an empty line.
-                    # We should change the parse subroutine (so that it doesn't
-                    # break entity).
                     die sprintf "un-balanced [";
                 }
             }
@@ -411,9 +436,6 @@
                         $arg .= $2;
                     }
                 } else {
-                    # FIXME: an argument can contain an empty line.
-                    # We should change the parse subroutine (so that it doesn't
-                    # break entity).
                     die sprintf "un-balanced {";
                 }
             }
@@ -426,7 +448,12 @@
     return ($command,$variant,\@opts,\@args,$buffer);
 }
 
-# Same as get_leading_command, but for commands at the end of a buffer.
+=item get_trailing_command($buffer)
+
+The same as get_leading_command, but for commands at the end of a buffer.
+
+=cut
+
 sub get_trailing_command {
     my ($self, $buffer) = (shift,shift);
     my $orig_buffer = $buffer;
@@ -459,9 +486,6 @@
                      $arg = $2.$arg;
                  }
             } else {
-                # FIXME: an argument can contain an empty line.
-                # We should change the parse subroutine (so that it doesn't
-                # break entity).
                 die sprintf "un-balanced }";
             }
         }
@@ -489,10 +513,6 @@
                      $opt = $2.$opt;
                  }
             } else {
-                # FIXME: an argument can contain an empty line.
-                # We should change the parse subroutine (so that it doesn't
-                # break entity).
-                # FIXME: see ch06:267
                 die sprintf "un-balanced ]";
             }
         }
@@ -521,9 +541,14 @@
     return ($command,$variant,\@opts,\@args,$buffer);
 }
 
-# Recursively translate a buffer by separating leading and trailing
-# commands (those which should be translatted separately) from the
-# buffer.
+=item translate_buffer
+
+Recursively translate a buffer by separating leading and trailing
+commands (those which should be translatted separately) from the
+buffer.
+
+=cut
+
 sub translate_buffer {
     my ($self,$buffer,@env) = (shift,shift,@_);
     print STDERR "translate_buffer($buffer,@env)="
@@ -636,7 +661,12 @@
 #### EXTERNAL CUSTOMIZATION ####
 ################################
 
-# Overload Transtractor's read
+=item read
+
+Overload Transtractor's read
+
+=cut
+
 sub read {
     my $self=shift;
     my $filename=shift;
@@ -647,9 +677,15 @@
     push @{$self->{TT}{doc_in}}, read_file($self, $filename);
 }
 
-# Recursively read a file, appending included files.
-# Except from the file inclusion part, it is a cut and paste from
-# Transtractor's read.
+=item read_file
+
+Recursively read a file, appending included files.
+
+Except from the file inclusion part, it is a cut and paste from
+Transtractor's read.
+
+=cut
+
 sub read_file {
     my $self=shift;
     my $filename=shift
@@ -664,7 +700,7 @@
     while (defined (my $textline = <$in>)) {
         $linenum++;
         my $ref="$filename:$linenum";
-        # FIXME: includeonly is not supported
+        # TODO: add support for includeonly
         while ($textline =~ /^(.*)\\(include|input)\{([^\{]*)\}(.*)$/) {
             my ($begin,$newfilename,$end) = ($1,$3,$4);
             my $tag = $2;
@@ -716,57 +752,18 @@
     return @entries;
 }
 
-=head1 INLINE CUSTIOMIZATION
+=back
 
-The TeX module can be customized with lines starting by "% po4a:".
-These lines are interpreted as commands to the parser.
-The following commands are recognized:
 
 =over 4
 
-=item % po4a: command I<command1> alias I<command2>
-
-Indicates that the arguments of the I<command1> command should be
-treated as the arguments of the I<command2> command.
-
-=item % po4a: command I<command1> I<function1>
-
-Indicates that the I<command1> command should be handled by I<function1>.
-
-=item % po4a: command <command1> x,y,z,t
-
-This permits a better control of the translated arguments and some
-verifications of the number of arguments.
-
-The meaning of the x, y, z and t is the following:
-  * x is the number of optional arguments (between [])
-      0 - no optional argument
-     -1 - variable
-      n - maximum number of optional arguments
-  * y is the number of arguments
-    maybe x and y are not needed
-  * z indexes of the optional arguments that have to be translated
-     -1 - all optional argument should be translated
-      0 - none
-  1 3 7 - the 1st, 3rd and 7th arguments should be translated
-  * t indexes of the arguments that have to be translated
-
-It could be useful to define commands without argument as "0,0,,"
-instead of either translated or untranslated.
-
-=item % po4a: environment <env1> <function1>
-
-Indicates that the I<env1> environment should be handled by I<function1>.
-
-=back
+=item parse_definition_file
 
-See the B<INTERNAL FUNCTIONS> section for the list of function which could be
-used for commands or environments.
+Subroutine for parsing a file with po4a directive (definitions for
+newcommands).
 
 =cut
 
-# Subroutine for parsing a file with po4a directive (definitions for
-# newcommands).
 sub parse_definition_file {
     my ($self,$filename)=@_;
 
@@ -779,7 +776,15 @@
         }
     }
 }
-# Parse a definition line ("% po4a: ")
+
+=item parse_definition_line
+
+Parse a definition line of the form "% po4a: ".
+
+See the INLINE CUSTOMIZATION section for more details.
+
+=cut
+
 sub parse_definition_line {
     my ($self,$line)=@_;
     $line =~ s/^%\s+po4a:\s*//;
@@ -821,6 +826,10 @@
     }
 }
 
+=item is_closed
+
+=cut
+
 sub is_closed {
     my $paragraph = shift;
 # FIXME: [ and ] are more difficult to handle, because it is not easy to detect if it introduce an optional argument
@@ -838,10 +847,15 @@
     }
     return $opening eq $closing;
 }
+
 #############################
 #### MAIN PARSE FUNCTION ####
 #############################
-sub parse{
+=item parse
+
+=cut
+
+sub parse {
     my $self = shift;
     my ($line,$ref);
     my $paragraph = ""; # Buffer where we put the paragraph while building
@@ -861,7 +875,7 @@
         # FIXME: not always, use return of parse_definition_line?
             $line = "%";
         } elsif ($line =~ /^([^%]*)(?<!\\)%(.*)$/) { # FIXME: even number of \ ...
-        #FIXME: in Python-Doc, there is a % in a verbatim environment,which is not a comment.
+        # FIXME: in Python-Doc, there is a % in a verbatim environment,which is not a comment.
             # remove comments, and store them in @comments
             push @comments, $2
                 if length($2);
@@ -871,7 +885,7 @@
 
         my $closed = is_closed($paragraph);
 
-        if ($closed and $line =~ /^ *$/) {#FIXME: \s*?
+        if ($closed and $line =~ /^ *$/) {#FIXME: should it be \s*?
             # An empty line. This indicates the end of the current
             # paragraph.
             $paragraph =~ s/(?<!\\)%$//; # FIXME: even number of \ ...
@@ -915,6 +929,12 @@
 } # end of parse
 
 
+=item docheader
+
+=back
+
+=cut
+
 sub docheader {
     return "% This file was generated with po4a. Translate the source file.\n".
            "%\n";
@@ -925,6 +945,67 @@
 #### DEFINITION OF THE COMMANDS ####
 ####################################
 
+=head1 INTERNAL FUNCTIONS used to write derivated parsers
+
+Command and environment functions take the following arguments (in
+addition to the $self object):
+
+=over 4
+
+=item a command
+
+=item a variant
+
+=item an array of optional arguments
+
+=item an array of mandatory arguments
+
+=item the current environment
+
+=back
+
+The first 4 arguments are extracted from get_leading_command or
+get_trailing_command.
+
+Command and environment functions return the translation of the command
+with its arguments and a new environment.
+
+Environment functions are called when a \begin command is found. They are
+called with the \begin command and its arguments.
+
+=head2 Command functions
+
+=over 4
+
+=item translate_joined
+
+Every argument of the command is translated separately, and the command is
+reassembled with its arguments in the output document.
+
+=item untranslated
+
+No argument of the command is proposed for translation. The command is
+reassembled with its arguments in the output document.
+
+=back
+
+=head2 Environment functions
+
+=over 4
+
+=item push_environment
+
+This function push the environment name in a stack, and push the \begin command
+untranslated in the output document.
+This stack of environments is then used to change the behaviour of the parser
+(e.g. blocks are not re-wrapped in the verbatim environment).
+The type of PO strings is either set to the last environment of this stack or
+to the name of the command (if the string is part of a command argument).
+
+=back
+
+=cut
+
 # Rebuild the command with the original arguments.
 sub untranslated {
     my $self = shift;
@@ -973,6 +1054,9 @@
 }
 
 # definition of environment related commands
+
+# FIXME: a \begin{env} can be followed by an argument. For example:
+# \begin{important}[the law of conservation of energy]
 $commands{'begin'}= sub {
     my $self = shift;
     my ($command,$variant,$opts,$args,$env) = (shift,shift,shift,shift,shift);
@@ -1107,9 +1191,6 @@
 ########################################
 # push the environment in the environment stack, and do not translate
 # the command
-# FIXME: a \begin{env} can be followed by an argument. For example:
-# \begin{important}[the law of conservation of energy]
-# FIXME: The environment name can be followed by a '*'
 sub push_environment {
     my $self = shift;
     my ($command,$variant,$opts,$args,$env) = (shift,shift,shift,shift,shift);
@@ -1204,6 +1285,12 @@
 
 =item tabular environment
 
+A tabular environment would have to translate every cell separately.
+
+=item Others
+
+Various other points are tagged TODO in the source.
+
 =back
 
 =head1 KNOWN BUGS
@@ -1216,7 +1303,7 @@
 
 =item commands
 
-The parser assumes all commands is followed by optional arguments (enclosed in
+The parser assumes every command is followed by optional arguments (enclosed in
 []) and then by mandatory arguments (enclosed in {}).
 
 =item verbatim environments
@@ -1225,7 +1312,7 @@
 
 =item Others
 
-Various others points are tagged FIXME in the source.
+Various other points are tagged FIXME in the source.
 
 =back
 
@@ -1243,7 +1330,7 @@
 Copyright 2004 by Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
 
 This program is free software; you may redistribute it and/or modify it
-under the terms of GPL (see COPYING file).
+under the terms of GPL (see the COPYING file).
 
 =cut