From a86d14742b305868a1c2b1f33f1263a6b7d0e03d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 2 May 2012 21:48:32 +0000 Subject: texdef 1.6 (2may12) git-svn-id: svn://tug.org/texlive/trunk@26176 c570f23f-e606-0410-a88d-b1316a301751 --- .../texk/texlive/linked_scripts/texdef/texdef.pl | 96 ++++++++-- Master/texmf-dist/doc/support/texdef/README | 9 +- Master/texmf-dist/doc/support/texdef/texdef.pdf | Bin 142486 -> 143473 bytes Master/texmf-dist/doc/support/texdef/texdef.tex | 193 -------------------- Master/texmf-dist/scripts/texdef/texdef.pl | 96 ++++++++-- Master/texmf-dist/source/support/texdef/texdef.tex | 195 +++++++++++++++++++++ 6 files changed, 373 insertions(+), 216 deletions(-) delete mode 100644 Master/texmf-dist/doc/support/texdef/texdef.tex create mode 100644 Master/texmf-dist/source/support/texdef/texdef.tex diff --git a/Build/source/texk/texlive/linked_scripts/texdef/texdef.pl b/Build/source/texk/texlive/linked_scripts/texdef/texdef.pl index 826ad869704..43edbabcd44 100755 --- a/Build/source/texk/texlive/linked_scripts/texdef/texdef.pl +++ b/Build/source/texk/texlive/linked_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 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 , -t : Use given flavour of TeX: 'tex', 'latex', 'context'. + --tex , -t : 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 , -p : (M) Load given tex-file, package or module depending on whether '*tex', '*latex' @@ -136,7 +140,7 @@ Options: --class , -c : (LaTeX only) Load given class instead of default ('article'). The can start with `[]` and end with `` or `{}`. - --environment , -p : (M) Show definition inside the given environment . + --environment , -e : (M) Show definition inside the given environment . --othercode , -o : (M) Add other code into the preamble before the definition is shown. This can be used to e.g. load PGF/TikZ libraries. --before , -b : (M) Place before definition is shown. @@ -145,7 +149,6 @@ Options: The 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/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 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 , -t : Use given flavour of TeX: 'tex', 'latex', 'context'. + --tex , -t : 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 , -p : (M) Load given tex-file, package or module depending on whether '*tex', '*latex' @@ -26,7 +28,7 @@ Options: --class , -c : (LaTeX only) Load given class instead of default ('article'). The can start with `[]` and end with `` or `{}`. - --environment , -p : (M) Show definition inside the given environment . + --environment , -e : (M) Show definition inside the given environment . --othercode , -o : (M) Add other code into the preamble before the definition is shown. This can be used to e.g. load PGF/TikZ libraries. --before , -b : (M) Place before definition is shown. @@ -35,6 +37,7 @@ Options: The 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 Binary files a/Master/texmf-dist/doc/support/texdef/texdef.pdf and b/Master/texmf-dist/doc/support/texdef/texdef.pdf differ diff --git a/Master/texmf-dist/doc/support/texdef/texdef.tex b/Master/texmf-dist/doc/support/texdef/texdef.tex deleted file mode 100644 index eefa7e730f2..00000000000 --- a/Master/texmf-dist/doc/support/texdef/texdef.tex +++ /dev/null @@ -1,193 +0,0 @@ -\documentclass{ydoc} -\usepackage{tabularx} - -\title{The \textsf{texdef} script} -\author{Martin Scharrer} -\email{martin@scharrer.me} -\date{Version 1.5 -- 2011/04/29} - -\makeatletter -\DeclareRobustCommand{\LATeX}{% - (L\kern -.36em{\sbox \z@ T\vbox to\ht \z@ {\hbox {\check@mathfonts \fontsize \sf@size \z@ \math@fontsfalse \selectfont A}\vss }}\kern -.075em)\kern -.15em\TeX -} -\makeatother - -\newenvironment{options}{% - \def\cstart{\begingroup\ttfamily\par\noindent\ignorespaces}% - \def\csep{\endgroup\begingroup\list {}{}\item \relax}% - \def\cend{\endlist\par\medskip\endgroup\cstart}% - \cstart -}{% - \endgroup -} - -\begin{document} -\maketitle - -\begin{abstract} -This Perl script shows the definition of \LATeX\ commands in a similar way as the \TeX\ primitive \Macro\show. -It is intended to allow users to quickly see the definitions of user level or internal package macros as well as the -values of registers. The given commands are compiled internally with \LATeX\ and the output of \Macro\show is formatted -and shown to the user. -\end{abstract} - -\tableofcontents - - -\section{Usage} -The script executable is called \texttt{texdef} (or maybe \texttt{texdef.pl}). -A normal installation is supposed to also install it as \texttt{latexdef} (e.g.\ using a symlink to \texttt{texdef}) in order to -allow for quick access to the \LaTeX\ format. Further format shortcuts are possible as explained in the installation section. - -\parindent=0pt -\DescribeScript{texdef}[]~~[~!\ldots!] -\DescribeScript{latexdef}[]~~[~!\ldots!] - -Other program names are possible. See the \texttt{tex} option. Command names do not need to start with `|\|'. - -\subsection*{Options} -The following options can be used: -\par\medskip - -\begin{options} - --tex \MacroArgs, -t \MacroArgs \csep Use given flavour 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 - --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 - --beforeclass, -B \csep Show definition of the command before \Macro\documentclass.\cend - --package \MacroArgs, -p \MacroArgs \csep (M) Load given tex-file, package or module depending on whether '*tex', '*latex' - or 'context' is used. For LaTeX the \MacroArgs can start with `[]` and end - with \MacroArgs or \MacroArgs{}.\cend - --class \MacroArgs, -c \MacroArgs \csep (LaTeX only) Load given class instead of default ('article'). - The \MacroArgs can start with \MacroArgs[] and end - with \MacroArgs or \MacroArgs{}.\cend - --environment \MacroArgs, -p \MacroArgs \csep (M) Show definition inside the given environment \MacroArgs.\cend - --othercode \MacroArgs, -o \MacroArgs \csep (M) Add other code into the preamble before the definition is shown. - This can be used to e.g. load PGF/TikZ libraries.\cend - --before \MacroArgs, -b \MacroArgs \csep (M) Place \MacroArgs before definition is shown. - The \MacroArgs can be arbitray TeX code and doesn't need be be balanced.\cend - --after \MacroArgs, -a \MacroArgs \csep (M) Place \MacroArgs after definition is shown. - The \MacroArgs 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 - --list-defs-all, -LL \csep List all command sequences and their shorten definitions of the given packages (L).\cend - --ignore-cmds \MacroArgs, -i \csep Ignore the following command sequence(s) in the above lists. (M)\cend - --ignore-regex \MacroArgs, -I \csep Ignore all command sequences in the above lists which match the given Perl regular expression(s). (M)\cend - --pgf-keys, -k \csep Takes commands as \pkg{pgfkeys} and displays their definitions. Keys must use the full path but the common '.\@cmd' prefix is applied.\cend - --pgf-Keys, -K \csep Takes commands as \pkg{pgfkeys} and displays their definitions. Keys must use the full path.\cend - --version, -V \csep If used alone prints version of this script. - (L) Together with -p or -c prints version of LaTeX package(s) or class, respectively.\cend - --tempdir \csep Use given existing directory for temporary files.\cend - --help, -h \csep Print this help and quit.\cend -\end{options} - -\noindent \textbf{Notes:}\\ - Long option can be shorten as long the are still unique. Short options can be combined. - If the option 'environment', 'before' and 'after' are used toegether the - produced code will be inserted in the given order (reversed order for 'after').\\ - (M) = This option can be given multiple times.\\ - (L) = LaTeX only. Requires the packages 'filehook' and 'currfile'. - - -\section{Installation}\label{sec:install} - -The latest official release of the script can be obtained from CTAN under \url{http://mirrors.ctan.org/support/texdef/texdef.pl}. -The latest develop version (which can be unstable!) can be obtained from the source code repository under -\url{https://bitbucket.org/martin_scharrer/texdef/src/tip/texdef.pl}. - -For installation the script file |texdef.pl| must simply renamed to |texdef| and be copied to a location suitable for executables, -i.e. a directory in the |PATH|, e.g.\ |/usr/bin| or |/usr/local/bin| for Linux/Unix. -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 -(|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}, -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} -to the real script is enough on operation systems/file systems which support -this. -At least the two variations |texdef| and |latexdef| should be installed. - - -\subsection*{Requirements} - -The |texdef| program is a Perl script which needs a Perl interpreter to work. -Informations about installing Perl can be found at \url{http://www.perl.org/get.html}. - -The script calls a TeX compiler (|tex|, |latex|, \ldots) to display the definition of commands/macros. -Therefore \LATeX\ must also be installed. -Informations about installing \LATeX\ can be found at \url{http://www.latex-project.org/ftp.html}. - - - - -\subsection*{Quick Install Nodes for Linux/Unix} - -\begin{verbatim} - cp texdef.pl /usr/local/bin/ - cd /usr/local/bin - ln -s texdef.pl texdef - ln -s texdef.pl latexdef - ln -s texdef.pl etexdef - ln -s texdef.pl luatexdef - ln -s texdef.pl lualatexdef - ln -s texdef.pl pdftexdef - 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' -\end{verbatim} - -\noindent or use the Makefile (defaults to |/usr/local/bin|) - -\begin{verbatim} - 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}): - -\begin{verbatim} -latexdef chapter -latexdef -c book chapter -latexdef -c scrbook chapter -\end{verbatim} - -Show value of \Macro\textwidth with different class options: - -\begin{verbatim} -latexdef -c [a4paper]{book} -v paperwidth -latexdef -c [letter]{book} -v paperwidth -\end{verbatim} - -Show definition of TikZ's \Macro\draw outside and inside a \env{tikzpicture} environment: - -\begin{verbatim} -latexdef -p tikz draw -latexdef -p tikz --env tikzpicture draw -\end{verbatim} - -Show definition of TikZ's \Macro\draw inside a node, inside a \cls{beamer} frame in \opt{handout} mode: - -\begin{verbatim} -latexdef -c [handout]beamer -p tikz --env frame \ - --env tikzpicture -b '\node {' -a '};' draw -\end{verbatim} - -List all user level command sequences (macros) defined by the \pkg{xspace} LaTeX package: - -\begin{verbatim} -latexdef -l -p xspace -\end{verbatim} - - -\end{document} - 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 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 , -t : Use given flavour of TeX: 'tex', 'latex', 'context'. + --tex , -t : 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 , -p : (M) Load given tex-file, package or module depending on whether '*tex', '*latex' @@ -136,7 +140,7 @@ Options: --class , -c : (LaTeX only) Load given class instead of default ('article'). The can start with `[]` and end with `` or `{}`. - --environment , -p : (M) Show definition inside the given environment . + --environment , -e : (M) Show definition inside the given environment . --othercode , -o : (M) Add other code into the preamble before the definition is shown. This can be used to e.g. load PGF/TikZ libraries. --before , -b : (M) Place before definition is shown. @@ -145,7 +149,6 @@ Options: The 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/source/support/texdef/texdef.tex b/Master/texmf-dist/source/support/texdef/texdef.tex new file mode 100644 index 00000000000..d0501025237 --- /dev/null +++ b/Master/texmf-dist/source/support/texdef/texdef.tex @@ -0,0 +1,195 @@ +\documentclass{ydoc} +\usepackage{tabularx} + +\title{The \textsf{texdef} script} +\author{Martin Scharrer} +\email{martin@scharrer-online.de} +\repository{https://bitbucket.org/martin_scharrer/texdef} +\date{Version 1.6 -- 2011/05/02} + +\makeatletter +\DeclareRobustCommand{\LATeX}{% + (L\kern -.36em{\sbox \z@ T\vbox to\ht \z@ {\hbox {\check@mathfonts \fontsize \sf@size \z@ \math@fontsfalse \selectfont A}\vss }}\kern -.075em)\kern -.15em\TeX +} +\makeatother + +\newenvironment{options}{% + \def\cstart{\begingroup\ttfamily\par\noindent\ignorespaces}% + \def\csep{\endgroup\begingroup\list {}{}\item \relax}% + \def\cend{\endlist\par\medskip\endgroup\cstart}% + \cstart +}{% + \endgroup +} + +\begin{document} +\maketitle + +\begin{abstract} +This Perl script shows the definition of \LATeX\ commands in a similar way as the \TeX\ primitive \Macro\show. +It is intended to allow users to quickly see the definitions of user level or internal package macros as well as the +values of registers. The given commands are compiled internally with \LATeX\ and the output of \Macro\show is formatted +and shown to the user. +\end{abstract} + +\tableofcontents + + +\section{Usage} +The script executable is called \texttt{texdef} (or maybe \texttt{texdef.pl}). +A normal installation is supposed to also install it as \texttt{latexdef} (e.g.\ using a symlink to \texttt{texdef}) in order to +allow for quick access to the \LaTeX\ format. Further format shortcuts are possible as explained in the installation section. + +\parindent=0pt +\DescribeScript{texdef}[]~~[~!\ldots!] +\DescribeScript{latexdef}[]~~[~!\ldots!] + +Other program names are possible. See the \texttt{tex} option. Command names do not need to start with `|\|'. + +\subsection*{Options} +The following options can be used: +\par\medskip + +\begin{options} + --tex \MacroArgs, -t \MacroArgs \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, -p \MacroArgs \csep (M) Load given tex-file, package or module depending on whether '*tex', '*latex' + or 'context' is used. For LaTeX the \MacroArgs can start with `[]` and end + with \MacroArgs or \MacroArgs{}.\cend + --class \MacroArgs, -c \MacroArgs \csep (LaTeX only) Load given class instead of default ('article'). + The \MacroArgs can start with \MacroArgs[] and end + with \MacroArgs or \MacroArgs{}.\cend + --environment \MacroArgs, -p \MacroArgs \csep (M) Show definition inside the given environment \MacroArgs.\cend + --othercode \MacroArgs, -o \MacroArgs \csep (M) Add other code into the preamble before the definition is shown. + This can be used to e.g. load PGF/TikZ libraries.\cend + --before \MacroArgs, -b \MacroArgs \csep (M) Place \MacroArgs before definition is shown. + The \MacroArgs can be arbitray TeX code and doesn't need be be balanced.\cend + --after \MacroArgs, -a \MacroArgs \csep (M) Place \MacroArgs after definition is shown. + The \MacroArgs 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 + --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 + --list-defs-all, -LL \csep List all command sequences and their shorten definitions of the given packages (L).\cend + --ignore-cmds \MacroArgs, -i \csep Ignore the following command sequence(s) in the above lists. (M)\cend + --ignore-regex \MacroArgs, -I \csep Ignore all command sequences in the above lists which match the given Perl regular expression(s). (M)\cend + --pgf-keys, -k \csep Takes commands as \pkg{pgfkeys} and displays their definitions. Keys must use the full path but the common '.\@cmd' prefix is applied.\cend + --pgf-Keys, -K \csep Takes commands as \pkg{pgfkeys} and displays their definitions. Keys must use the full path.\cend + --version, -V \csep If used alone prints version of this script. + (L) Together with -p or -c prints version of LaTeX package(s) or class, respectively.\cend + --tempdir \csep Use given existing directory for temporary files.\cend + --help, -h \csep Print this help and quit.\cend +\end{options} + +\noindent \textbf{Notes:}\\ + Long option can be shorten as long the are still unique. Short options can be combined. + If the option 'environment', 'before' and 'after' are used toegether the + produced code will be inserted in the given order (reversed order for 'after').\\ + (M) = This option can be given multiple times.\\ + (L) = LaTeX only. Requires the packages 'filehook' and 'currfile'. + + +\section{Installation}\label{sec:install} + +The latest official release of the script can be obtained from CTAN under \url{http://mirrors.ctan.org/support/texdef/texdef.pl}. +The latest develop version (which can be unstable!) can be obtained from the source code repository under +\url{https://bitbucket.org/martin_scharrer/texdef/src/tip/texdef.pl}. + +For installation the script file |texdef.pl| must simply renamed to |texdef| and be copied to a location suitable for executables, +i.e. a directory in the |PATH|, e.g.\ |/usr/bin| or |/usr/local/bin| for Linux/Unix. +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 formats of TeX +(|tex|, |etex|, |latex|, |pdftex|, |pdfetex|, |pdflatex|, |xetex|, |xelatex|, |context|, \ldots). +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} +to the real script is enough on operation systems/file systems which support +this. +At least the two variations |texdef| and |latexdef| should be installed. + + +\subsection*{Requirements} + +The |texdef| program is a Perl script which needs a Perl interpreter to work. +Informations about installing Perl can be found at \url{http://www.perl.org/get.html}. + +The script calls a TeX compiler (|tex|, |latex|, \ldots) to display the definition of commands/macros. +Therefore \LATeX\ must also be installed. +Informations about installing \LATeX\ can be found at \url{http://www.latex-project.org/ftp.html}. + + + + +\subsection*{Quick Install Nodes for Linux/Unix} + +\begin{verbatim} + cp texdef.pl /usr/local/bin/ + cd /usr/local/bin + ln -s texdef.pl texdef + ln -s texdef.pl latexdef + ln -s texdef.pl etexdef + ln -s texdef.pl luatexdef + ln -s texdef.pl lualatexdef + ln -s texdef.pl pdftexdef + ln -s texdef.pl pdflatexdef + ln -s texdef.pl xetexdef + ln -s texdef.pl xelatexdef + ln -s texdef.pl 'some other TeX format of your choice' +\end{verbatim} + +\noindent or use the Makefile (defaults to |/usr/local/bin|) + +\begin{verbatim} + make install INSTALLDIR=/your/path +\end{verbatim} + +\section{Examples} +Show the definition of \Macro\chapter with different classes (\cls{article} (default), \cls{book} and \cls{scrbook}): + +\begin{verbatim} +latexdef chapter +latexdef -c book chapter +latexdef -c scrbook chapter +\end{verbatim} + +Show value of \Macro\textwidth with different class options: + +\begin{verbatim} +latexdef -c [a4paper]{book} -v paperwidth +latexdef -c [letter]{book} -v paperwidth +\end{verbatim} + +Show definition of TikZ's \Macro\draw outside and inside a \env{tikzpicture} environment: + +\begin{verbatim} +latexdef -p tikz draw +latexdef -p tikz --env tikzpicture draw +\end{verbatim} + +Show definition of TikZ's \Macro\draw inside a node, inside a \cls{beamer} frame in \opt{handout} mode: + +\begin{verbatim} +latexdef -c [handout]beamer -p tikz --env frame \ + --env tikzpicture -b '\node {' -a '};' draw +\end{verbatim} + +List all user level command sequences (macros) defined by the \pkg{xspace} LaTeX package: + +\begin{verbatim} +latexdef -l -p xspace +\end{verbatim} + + +\end{document} + -- cgit v1.2.3