diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texdef/texdef.tex |
Initial commit
Diffstat (limited to 'support/texdef/texdef.tex')
-rw-r--r-- | support/texdef/texdef.tex | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/support/texdef/texdef.tex b/support/texdef/texdef.tex new file mode 100644 index 0000000000..744814822b --- /dev/null +++ b/support/texdef/texdef.tex @@ -0,0 +1,274 @@ +\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.8a -- 2018/03/28} + +\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 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.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} + |