texdef 1.6 (2may12)

git-svn-id: svn://tug.org/texlive/trunk@26176 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 102 insertions, 21 deletions

diff --git a/Master/texmf-dist/doc/support/texdef/README b/Master/texmf-dist/doc/support/texdef/README
index 61e032093ef..a79a310db20 100644
--- a/Master/texmf-dist/doc/support/texdef/README
+++ b/Master/texmf-dist/doc/support/texdef/README
@@ -2,7 +2,7 @@ texdef -- Show definitions of TeX commands
 
 This perl script shows the definition of (La)TeX commands in a similar way as `\show`.
 
-Version 1.5 -- 2012/04/29
+Version 1.6 -- 2012/05/02
 Copyright (C) 2011-2012  Martin Scharrer <martin@scharrer-online.de>
 This program comes with ABSOLUTELY NO WARRANTY;
 This is free software, and you are welcome to redistribute it under certain conditions;
@@ -14,10 +14,12 @@ Usage:
 Other program names are possible. See the 'tex' option.  Command names do not need to start with `\`.
 
 Options:
-  --tex <flv>, -t <flv>         : Use given flavour of TeX: 'tex', 'latex', 'context'.
+  --tex <format>, -t <format>   : Use given format of TeX: 'tex', 'latex', 'context'.
                                   Variations of 'tex' and 'latex', like 'luatex', 'lualatex', 'xetex', 'xelatex' are supported.
                                   The default is given by the used program name: 'texdef' -> 'tex', 'latexdef' -> 'latex', etc.
   --value, -v                   : Show value of command instead (i.e. \the\command).
+  --Environment, -E             : Every command name is taken as an environment name. This will show the definition of
+                                  both \Macro\foo and \Macro\endfoo if \texttt{foo} is used as command name (L).
   --preamble, -P                : Show definition of the command inside the preamble.
   --beforeclass, -B             : Show definition of the command before \documentclass.
   --package <pkg>, -p <pkg>     : (M) Load given tex-file, package or module depending on whether '*tex', '*latex'
@@ -26,7 +28,7 @@ Options:
   --class <class>, -c <class>   : (LaTeX only) Load given class instead of default ('article').
                                   The <class> can start with `[<classs options>]` and end 
                                   with `<classname>` or `{<classname>}`.
-  --environment <env>, -p <env> : (M) Show definition inside the given environment <env>.
+  --environment <env>, -e <env> : (M) Show definition inside the given environment <env>.
   --othercode <code>, -o <code> : (M) Add other code into the preamble before the definition is shown.
                                   This can be used to e.g. load PGF/TikZ libraries.
   --before <code>, -b <code>    : (M) Place <code> before definition is shown.
@@ -35,6 +37,7 @@ Options:
                                   The <code> can be arbitray TeX code and doesn't need be be balanced.
   --find, -f                    : Find file where the command sequence was defined (L).
   --Find, -F                    : Show full filepath of the file where the command sequence was defined (L).
+  --source, -s                  : Try to show the original source code of the command definition (L).
   --list, -l                    : List user level command sequences of the given packages (L).
   --list-defs, -L               : List user level command sequences and their shorten definitions of the given packages (L).
   --list-all, -ll               : List all command sequences of the given packages (L).
diff --git a/Master/texmf-dist/doc/support/texdef/texdef.pdf b/Master/texmf-dist/doc/support/texdef/texdef.pdf
index 3e5dfd7f982..c5a2d9d1b4f 100644
--- a/Master/texmf-dist/doc/support/texdef/texdef.pdf
+++ b/Master/texmf-dist/doc/support/texdef/texdef.pdf
diff --git a/Master/texmf-dist/scripts/texdef/texdef.pl b/Master/texmf-dist/scripts/texdef/texdef.pl
index 826ad869704..43edbabcd44 100755
--- a/Master/texmf-dist/scripts/texdef/texdef.pl
+++ b/Master/texmf-dist/scripts/texdef/texdef.pl
@@ -40,6 +40,7 @@ my $INPREAMBLE = 0;
 my $PRINTVERSION = 0;
 my $TMPDIR     = '';
 my $SHOWVALUE  = 0;
+my $ISENVIRONMENT = 0;
 my $PRINTORIGDEF  = 0;
 my $FINDDEF    = 0;
 my $LISTCMD    = 0;
@@ -108,11 +109,11 @@ my $ISCONTEXT = 0;
 my $BEGINENVSTR = '%s';
 my $ENDENVSTR   = '%s';
 
-my $VERSION = 'Version 1.5 -- 2012/04/29';
+my $VERSION = 'Version 1.6 -- 2012/05/02';
 sub usage {
 print << 'EOT';
 texdef -- Show definitions of TeX commands
-Version 1.5 -- 2012/04/29
+Version 1.6 -- 2012/05/02
 Copyright (C) 2011-2012  Martin Scharrer <martin@scharrer-online.de>
 This program comes with ABSOLUTELY NO WARRANTY;
 This is free software, and you are welcome to redistribute it under certain conditions;
@@ -124,10 +125,13 @@ Usage:
 Other program names are possible. See the 'tex' option.  Command names do not need to start with `\`.
 
 Options:
-  --tex <flv>, -t <flv>         : Use given flavour of TeX: 'tex', 'latex', 'context'.
+  --tex <format>, -t <format>   : Use given format of TeX: 'tex', 'latex', 'context'.
                                   Variations of 'tex' and 'latex', like 'luatex', 'lualatex', 'xetex', 'xelatex' are supported.
                                   The default is given by the used program name: 'texdef' -> 'tex', 'latexdef' -> 'latex', etc.
+  --source, -s                  : Try to show the original source code of the command definition (L).
   --value, -v                   : Show value of command instead (i.e. \the\command).
+  --Environment, -E             : Every command name is taken as an environment name. This will show the definition of
+                                  both \Macro\foo and \Macro\endfoo if \texttt{foo} is used as command name (L).
   --preamble, -P                : Show definition of the command inside the preamble.
   --beforeclass, -B             : Show definition of the command before \documentclass.
   --package <pkg>, -p <pkg>     : (M) Load given tex-file, package or module depending on whether '*tex', '*latex'
@@ -136,7 +140,7 @@ Options:
   --class <class>, -c <class>   : (LaTeX only) Load given class instead of default ('article').
                                   The <class> can start with `[<classs options>]` and end 
                                   with `<classname>` or `{<classname>}`.
-  --environment <env>, -p <env> : (M) Show definition inside the given environment <env>.
+  --environment <env>, -e <env> : (M) Show definition inside the given environment <env>.
   --othercode <code>, -o <code> : (M) Add other code into the preamble before the definition is shown.
                                   This can be used to e.g. load PGF/TikZ libraries.
   --before <code>, -b <code>    : (M) Place <code> before definition is shown.
@@ -145,7 +149,6 @@ Options:
                                   The <code> can be arbitray TeX code and doesn't need be be balanced.
   --find, -f                    : Find file where the command sequence was defined (L).
   --Find, -F                    : Show full filepath of the file where the command sequence was defined (L).
-  --source, -s                  : Try to show the original source code of the command definition (L).
   --list, -l                    : List user level command sequences of the given packages (L).
   --list-defs, -L               : List user level command sequences and their shorten definitions of the given packages (L).
   --list-all, -ll               : List all command sequences of the given packages (L).
@@ -204,6 +207,7 @@ sub envcode {
 Getopt::Long::Configure ("bundling");
 GetOptions (
    'value|v!' => \$SHOWVALUE,
+   'Environment|E!' => \$ISENVIRONMENT,
    'version|V!' => \$PRINTVERSION,
    'tempdir=s' => \$TMPDIR,
    'find|f!' => sub { $FINDDEF = 1 },
@@ -289,6 +293,7 @@ sub print_versions {
 }
 
 usage() if not @cmds;
+
 my $cwd = getcwd();
 my $OS = $^O;
 my $DIRSEP;
@@ -544,8 +549,28 @@ select STDOUT;
 
 # Removes all '{' and '}' characters which no real braces.
 sub remove_invalid_braces {
-    $_[0] =~ s/%.*$//; # remove line comments
-    $_[0] =~ s/\\[{}]//; # remove \{ and \}
+    $_[0] =~ s/\\[\\%]//g; # remove \\ and \%
+    $_[0] =~ s/%.*$//;     # remove line comments
+    $_[0] =~ s/\\[{}]//g;  # remove \{ and \}
+}
+
+sub env_braces {
+    my $line = shift;
+    remove_invalid_braces $line;
+    my $level = shift || 0;
+    my $count = shift || 0;
+    for my $char (split //, $line) {
+        if ($char eq '{') {
+            $level++;
+        }
+        elsif ($char eq '}') {
+            $level--;
+            if ($level == 0) {
+                $count++;
+            }
+        }
+    }
+    return ($level, $count);
 }
 
 sub print_orig_def {
@@ -570,6 +595,26 @@ sub print_orig_def {
         $rmacroname                                              # Macro name without backslash
         [^a-zA-Z@]
         /xms;
+    my $rmacrolet  = qr/
+        ^                                                        # Begin of line (no whitespaces!)
+        \s*
+        (?:
+        (?:(?:\\global)\s*)*       # Prefixes (maybe with whitespace between them)
+        )
+        \\let \s* \\                                             # let
+        $rmacroname                                              # Macro name without backslash
+        \s* =?                                                   # Optional '='
+        \s* \\ ([a-zA-Z@]+)                                      # Second macro
+        /xms;
+    my $renvdef = qr/
+        ^\s*                                                     # Begin of line (no whitespaces!)
+        \\(
+            (?:new|renew|provide)environment\s* { \s*            # LaTeX definitions
+        )
+        ($rmacroname)                                            # Environment names follow same rules as macro names
+        \s* }                                                    # closing brace
+        (.*)                                                     # Rest of line
+        /xms;
     while (my $line = <$fh>) {
         if ($line =~ $rmacrodef) {
             $found = 1;
@@ -588,6 +633,28 @@ sub print_orig_def {
             print "\n";
             last;
         }
+        elsif ($line =~ $rmacrolet) {
+            my $letcmd = $1;
+            $found = 1;
+            print "% $file, line $.:\n";
+            print $line;
+            print "\n";
+            unshift @cmds, $letcmd;
+            last;
+        }
+        elsif ($line =~ $renvdef) {
+            $found = 2;
+            print "% $file, line $.:\n";
+            print $line;
+            my ($level, $count) = env_braces $line;
+            while ($count < 3) {
+                my $line = <$fh>;
+                print $line;
+                ($level, $count) = env_braces $line, $level, $count;
+            }
+            print "\n";
+            last;
+        }
     }
     close($fh);
     return $found;
@@ -598,6 +665,7 @@ open (my $texpipe, '-|', "$TEX $TEXOPTIONS \"$TMPFILE\" ");
 my $name = '';
 my $definition = '';
 my $errormsg = '';
+my $origdeffound = 0;
 
 while (<$texpipe>) {
   if (/^::\s*(.*)/) {
@@ -614,13 +682,18 @@ while (<$texpipe>) {
             my $file = $1;
             my $path = `kpsewhich "$file"`;
             chomp $path;
-            print_orig_def($cmd, $file, $path);
+            $origdeffound = print_orig_def($cmd, $file, $path);
         }
         elsif ($line =~ /is defined by \(La\)TeX./) {
             my $file = 'latex.ltx';
             my $path = `kpsewhich "$file"`;
             chomp $path;
-            print_orig_def($cmd, $file, $path);
+            $file = $path if $FINDDEF > 1;
+            $origdeffound = print_orig_def($cmd, $file, $path);
+        }
+        if (!$origdeffound) {
+            print "Source code definition of '$cmd' could not be found.\n";
+            print "$line\n";
         }
     }
     else {
@@ -733,12 +806,15 @@ if ($cmd eq $LISTSTR) {
             print "\n";
         }
     }
-} elsif (!$PRINTORIGDEF) {
+} elsif (!$PRINTORIGDEF || !$origdeffound) {
     print "\n(in preamble)" if $inpreamble;
     print "\n$name:\n$definition\n\n";
 }
 
 testdef($origcmd,$definition);
+if ($ISENVIRONMENT && $origdeffound < 2 && $cmd !~ /^end/) {
+    unshift @cmds, 'end' . $cmd;
+}
 
 }
 
diff --git a/Master/texmf-dist/doc/support/texdef/texdef.tex b/Master/texmf-dist/source/support/texdef/texdef.tex
index eefa7e730f2..d0501025237 100644
--- a/Master/texmf-dist/doc/support/texdef/texdef.tex
+++ b/Master/texmf-dist/source/support/texdef/texdef.tex
@@ -3,8 +3,9 @@
 
 \title{The \textsf{texdef} script}
 \author{Martin Scharrer}
-\email{martin@scharrer.me}
-\date{Version 1.5 -- 2011/04/29}
+\email{martin@scharrer-online.de}
+\repository{https://bitbucket.org/martin_scharrer/texdef}
+\date{Version 1.6 -- 2011/05/02}
 
 \makeatletter
 \DeclareRobustCommand{\LATeX}{%
@@ -50,11 +51,14 @@ The following options can be used:
 \par\medskip
 
 \begin{options}
-  --tex \MacroArgs<flv>, -t \MacroArgs<flv>          \csep Use given flavour of TeX: 'tex', 'latex', 'context'.
+  --tex \MacroArgs<format>, -t \MacroArgs<format>    \csep Use given format of TeX: 'tex', 'latex', 'context'.
                                                        Variations of 'tex' and 'latex', like 'luatex', 'lualatex', 'xetex', 'xelatex' are supported.
                                                        The default is given by the used program name: 'texdef' -> 'tex', 'latexdef' -> 'latex', etc.\cend
+  --source, -s                                       \csep Try to show the original source code of the command definition (L).\cend
   --value, -v                                        \csep Show value of command instead (i.e. \Macro\the\AlsoMacro\command).\cend
   --preamble, -P                                     \csep Show definition of the command inside the preamble.\cend
+  --Environment, -E                                  \csep Every command name is taken as an environment name. This will show the definition of
+                                                             both \Macro\foo and \Macro\endfoo if \texttt{foo} is used as command name (L).\cend
   --beforeclass, -B                                  \csep Show definition of the command before \Macro\documentclass.\cend
   --package \MacroArgs<pkg>, -p \MacroArgs<pkg>      \csep (M) Load given tex-file, package or module depending on whether '*tex', '*latex'
                                                        or 'context' is used. For LaTeX the \MacroArgs<pkg> can start with `[<options>]` and end
@@ -71,7 +75,6 @@ The following options can be used:
                                                        The \MacroArgs<code> can be arbitray TeX code and doesn't need be be balanced.\cend
   --find, -f                                         \csep Find file where the command sequence was defined (L).\cend
   --Find, -F                                         \csep Show full filepath of the file where the command sequence was defined (L).\cend
-  --source, -s                                       \csep Try to show the original source code of the command definition (L).\cend
   --list, -l                                         \csep List user level command sequences of the given packages (L).\cend
   --list-defs, -L                                    \csep List user level command sequences and their shorten definitions of the given packages (L).\cend
   --list-all, -ll                                    \csep List all command sequences of the given packages (L).\cend
@@ -105,9 +108,9 @@ i.e. a directory in the |PATH|, e.g.\ |/usr/bin| or |/usr/local/bin| for Linux/U
 The script should be set as \emph{executable}, i.e. |chmod +x texdef.pl| for Linux/Unix.
 This is not required for MS Windows.
 
-This script can show the definitions of commands with different flavours of TeX
+This script can show the definitions of commands with different formats of TeX
 (|tex|, |etex|, |latex|, |pdftex|, |pdfetex|, |pdflatex|, |xetex|, |xelatex|, |context|, \ldots).
-The flavour can be given using an command line option or over the \emph{script name},
+The format can be given using an command line option or over the \emph{script name},
 i.e.\ if the script is called |texdef| it will use |tex|, but called |latexdef|
 it will use |latex| and so on.
 The script can be simply copied several times, but creating \emph{symbolic links}
@@ -142,7 +145,7 @@ Informations about installing \LATeX\ can be found at \url{http://www.latex-proj
     ln -s texdef.pl pdflatexdef
     ln -s texdef.pl xetexdef
     ln -s texdef.pl xelatexdef
-    ln -s texdef.pl 'some other TeX flavour of your choice'
+    ln -s texdef.pl 'some other TeX format of your choice'
 \end{verbatim}
 
 \noindent or use the Makefile (defaults to |/usr/local/bin|)
@@ -151,7 +154,6 @@ Informations about installing \LATeX\ can be found at \url{http://www.latex-proj
     make install INSTALLDIR=/your/path
 \end{verbatim}
 
-\clearpage
 \section{Examples}
 Show the definition of \Macro\chapter with different classes (\cls{article} (default), \cls{book} and \cls{scrbook}):