path: root/support/texdef/texdef.tex

\documentclass{ydoc}
\usepackage{tabularx}

\title{The \textsf{texdef} script}
\author{Martin Scharrer}
\email{martin@scharrer-online.de}
\repository{https://sourceforge.net/projects/texdef/}
\date{Version 1.9 -- 2020/09/27}

\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}[<options>]~<commandname>~[<commandname>~!\ldots!]
\DescribeScript{latexdef}[<options>]~<commandname>~[<commandname>~!\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<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 postfix '-dev' for develop versions of the format is also supported (e.g. 'latex-dev').
                                                       The default is given by the used program name: 'texdef' -> 'tex', 'latexdef' -> 'latex', etc.\cend
  --texoptions \MacroArgs<options>                   \csep Call \LaTeX/\TeX{} with the given options.\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
                                                       with \MacroArgs<pkgname> or \MacroArgs{<pkgname>}.\cend
  --class \MacroArgs<class>, -c \MacroArgs<class>    \csep (LaTeX only) Load given class instead of default ('article').
                                                       The \MacroArgs<class> can start with \MacroArgs[<class options>] and end
                                                       with \MacroArgs<classname> or \MacroArgs{<classname>}.\cend
  --environment \MacroArgs<env>, -p \MacroArgs<env>  \csep (M) Show definition inside the given environment \MacroArgs<env>.\cend
  --othercode \MacroArgs<code>, -o \MacroArgs<code>  \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<code>, -b \MacroArgs<code>     \csep (M) Place \MacroArgs<code> before definition is shown.
                                                       The \MacroArgs<code> can be arbitray TeX code and doesn't need be be balanced.\cend
  --after  \MacroArgs<code>, -a \MacroArgs<code>     \csep (M) Place \MacroArgs<code> after definition is shown.
                                                       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
  --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<cs,cs,..>,  -i            \csep Ignore the following command sequence(s) in the above lists. (M)\cend
  --ignore-regex \MacroArgs<regex,..>, -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
  --edit                                             \csep Opens the file holding the macro definition. Uses |--Find| and |--source|.
                                                           If the source definition can not be found the definition is printed as normal instead. (L)\cend
  --editor <editor>                                  \csep Can be used to set the used editor. If not used the environment variables |TEXDEF_EDITOR|, |EDITOR| and
                                                       |SELECTED_EDITOR| are read in this order. If none of these are set a list of default
                                                       editors are tried.  The |<editor>| string can include `|%f|' for the filename, `|%n|' for
                                                       the line number and `|%%|' for a literal `|%|'.  If no `|%|' is used `|+%n %f|' is added to
                                                       the given command.\cend
  --tempdir <directory>                              \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}


\section{Changelog}

\subsection*{v1.9 from 2020/09/27}
\begin{itemize}
 \item Added support for develop versions of the formats, e.g.\ "latex-dev".
\end{itemize}

\subsection*{v1.8c from 2010/01/15}
\begin{itemize}
 \item Changed path printing format to native format of the used OS 
      (e.g. under Windows file paths now habe `\textbackslash' instead of `/')
\end{itemize}

\subsection*{v1.8a from 2018/03/28}
\begin{itemize}
 \item Further fixes of braces in regexs to avoid ``Unescaped left brace in regex is deprecated'' warnings or errors.
\end{itemize}

\subsection*{v1.8 from 2018/03/25}
\begin{itemize}
 \item Added "dvitex" and "dvilatex" as formats. These will set DVI mode on "tex" or "latex".
 \item Escaped further braces in regexs to avoid warnings or errors.
 \item Added option "--texoptions" to allow the passing of compiler options for special cases.
\end{itemize}

\subsection*{v1.7c from 2017/12/09}
\begin{itemize}
 \item Fixed 'Unescaped left brace in regex is deprecated' warning.
   Thanks goes to Paulo Cereda <cereda.paulo@gmail.com> for providing the patch.
\end{itemize}

\subsection*{v1.7b from 2012/05/15}
\begin{itemize}
 \item Added support for \Macro\chardef, \Macro\countdef, \Macro\dimendef, \Macro\mathchardef, \Macro\myskip, \Macro\skipdef and \Macro\toksdef.
 \item Added support for \Macro\newbox, \Macro\newcount, \Macro\newdimen, \Macro\newif, \Macro\newinsert, \Macro\newread, \Macro\newskip, \Macro\newtoks, \Macro\newwrite.
 \item Added support for \Macro\newif and \Macro\newcount.
 \item Changed internal processing order to put more frequently used elements first.
\end{itemize}

\subsection*{v1.7a from 2012/05/08}
\begin{itemize}
 \item Fix for currfile v0.6.
\end{itemize}

\subsection*{v1.7 from 2012/05/07}
\begin{itemize}
 \item Changed "--help" to return status code 0.
 \item Changed Windows default editor to texworks. Fixed If-statement.
 \item Fixed bug which reported name of included subpackages.
 \item Added option "--edit".
 \item Added "--editor" option and better editor handling.
 \item Added variable substitution for editor.
 \item Added support for "TEXDEF_EDITOR" variable. Added Mac "open" command.
 \item Fixed for behaviour when -s is used (correct name in message; do not follow protected macros etc.)
\end{itemize}

\subsection*{v1.6 from 2012/05/02}
\begin{itemize}
 \item Changed implementation of -E option to work better with new environment source code.
 \item Added code to detect environment source definitions.
 \item Added -E option.
 \item Changed "flavour" to "format".
 \item Added support for \Macro\let.
 \item Added fallback for when the source code can not be found. Added support for -F with "latex.ltx".
\end{itemize}

\subsection*{v1.5 from 2012/04/29}
\begin{itemize}
 \item Added experimental --source option to show source code of the definitions.
 \item Script now works correctly under MS Windows.
\end{itemize}

\subsection*{v1.4 from 2011/07/28}
\begin{itemize}
 \item Added -F option to display file path.
 \item Added basic support for pdfkeys using -k and -K options.
 \item Added -V option to print version numbers of LaTeX packages or classes.
 \item Added '--tempdir' option to specify the location of the temporary files. Useful for debugging.
\end{itemize}



\end{document}