diff options
Diffstat (limited to 'macros/latex/contrib/jobname-suffix/jobname-suffix.tex')
-rw-r--r-- | macros/latex/contrib/jobname-suffix/jobname-suffix.tex | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/macros/latex/contrib/jobname-suffix/jobname-suffix.tex b/macros/latex/contrib/jobname-suffix/jobname-suffix.tex new file mode 100644 index 0000000000..0ae054b602 --- /dev/null +++ b/macros/latex/contrib/jobname-suffix/jobname-suffix.tex @@ -0,0 +1,229 @@ +%% pig.dtx +%% Copyright 2022 Jason Siefken +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Jason Siefken +% +% This work consists of the files jobname-suffix.sty and docs/jobname-suffix.tex +\documentclass{l3doc} +\usepackage{listings,xcolor} + +\lstdefinestyle{mystyle}{ + language=[LaTeX]{TeX}, + texcsstyle=*\color{blue}, + commentstyle={\color{green!50!black}\itshape}, + basicstyle=\ttfamily, + moretexcs={IfSuffixT,IfSuffixF,IfSuffixTF,OverrideSuffix,JobnameSuffix,solution}, % user command highlight + frame=single, +} +\lstset{style=mystyle} + +\title{% + \pkg{jobname-suffix}\\ + Compile different content based on the file name% +} + +\author{% + Jason Siefken% + \thanks{% + Please file an issues/comments to \url{https://github.com/siefkenj/jobname-suffix/issues} + } +} + +\date{Released \today} + +\NewDocumentCommand{\fileshow}{m}{% +\par +\noindent\begin{minipage}{\linewidth} + \noindent\texttt{\itshape #1:} + \vspace{-1cm} +\end{minipage} +} + +\begin{document} + \maketitle + + \tableofcontents + + \begin{abstract} + \pkg{jobname-suffix} allows one to compile a document differently depending + on the document's file name (internally called the \texttt{jobname} in \TeX). + This allows one to have one source file and multiple links to this source file (either + as symbolic links, or as different files referencing the original via an \cs{input} + command) that are each compile differently. For example, an exam might have an + \file{exam-student.tex} and an \file{exam-instructor.tex} which both reference the + same source code but where the instructor version includes solutions and the student + version does not. + \end{abstract} + + \begin{documentation} + + \section{Introduction} + \pkg{jobname-suffix} by default allows you to reference the part of a file name (technically the \cs{jobname}) + that comes after the first ``\texttt{-}'' character and use that information to control what \LaTeX{} produces. + + Consider the following example: you have three files \file{exam.tex}, \file{exam-student.tex}, and \file{exam-instructor.tex}. + The files \file{exam-student.tex} and \file{exam-instructor.tex} are either symbolic links to \file{exam.tex} (if your operating + system supports symbolic links) or use \cs{input}\Arg{exam.tex file path} to include the contents of \file{exam.tex}. + + \fileshow{exam-student.tex \textnormal{and} exam-instructor.tex} + \begin{lstlisting} +\input{exam.tex} + \end{lstlisting} + + \fileshow{exam.tex} + \begin{lstlisting} +\documentclass{article} +\usepackage{jobname-suffix} + +\newcommand{\solution}[1]{#1} +\IfSuffixT[instructor]{ + % Instructors get solutions emboldened + \renewcommand{\solution}[1]{\textbf{#1}} +} +\IfSuffixT[student]{ + % Students don't see solutions at all + \renewcommand{\solution}[1]{} +} + +\begin{document} + \begin{enumerate} + \item First question + \solution{First answer} + + \item Second question + \solution{Second answer} + \end{enumerate} +\end{document} + \end{lstlisting} + + \noindent Then, compiling via + + \noindent\texttt{> lualatex exam-instructor.tex} + + \noindent\texttt{> lualatex exam-student.tex} + + \noindent will produce two pdfs: one with solutions and one without. + + \section{Usage} + \subsection{Variables} + + \begin{variable}{\JobnameSuffix} + The computed suffix of the filename (\cs{jobname}). This is normally the part of the file name after the first ``\texttt{-}'' + character and before the file extension. For example, + \file{file-a.tex} has a \cs{JobnameSuffix} of ``\texttt{a}'', + \file{file-a-b.tex} has a \cs{JobnameSuffix} of ``\texttt{a-b}'', + and \file{file.tex} has a \cs{JobnameSuffix} of consisting of the empty string. + \end{variable} + + \subsection{Commands} + \begin{function}{\IfSuffixTF, \IfSuffixT, \IfSuffixF} + \begin{syntax} + \cs{IfSuffixTF}\oarg{suffixes}\marg{true condition}\marg{false condition} + \cs{IfSuffixT}\oarg{suffixes}\marg{true condition} + \cs{IfSuffixF}\oarg{suffixes}\marg{false condition} + \end{syntax} + The argument \meta{suffixes} is a comma-separated list of all suffixes you wish to test against. + \end{function} + + \begin{function}{\OverrideSuffix} + \begin{syntax} + \cs{OverrideSuffix}\marg{suffix} + \end{syntax} + Override \cs{JobnameSuffix} to be the suffix specified by \meta{suffix} instead. + \end{function} + + \subsection{Environments} + + \DescribeEnv{IfSuffix} + The \env{IfSuffix} environment accepts an optional argument \oarg{suffixes} and will display its contents (unmodified) + if \cs{JobnameSuffix} is among the comma-separated list \meta{suffixes}. Unfortunately this environment cannot contain + \env{verbatim} contents. + + \section{Compiling} + + \pkg{jobname-suffix} works by reading the \cs{jobname} macro that is part of standard \TeX. By default, this is + set to the file name without the file extension. You can affect the jobname in one of two ways: + \begin{enumerate} + \item The name of your file. + \item By supplying the \texttt{-jobname} option during compilation. For example, the following two + commands would both result in compiling with a \cs{jobname} of \texttt{exam-student}. + + \noindent\texttt{> lualatex -jobname exam-instructor exam.tex} + + \noindent\texttt{> lualatex exam-instructor.tex} + \end{enumerate} + + \section{Tips} + + \begin{itemize} + \item + For performance reasons, it is best to \cs{IfSuffixTF} to define/redefine commands in your document preamble + rather than to use them in your document body/macro bodies. For example, do + +\begin{lstlisting} +\documentclass{article} +\usepackage{jobname-suffix} + +\newcommand{\solution}[1]{#1} +\IfSuffixT[instructor]{ + % Instructors get solutions emboldened + \renewcommand{\solution}[1]{\textbf{#1}} +} + +\begin{document} + \solution{Some Text} +\end{document} +\end{lstlisting} + +instead of + +\begin{lstlisting} +\documentclass{article} +\usepackage{jobname-suffix} + +\newcommand{\solution}[1]{% + \IfSuffixTF[instructor]{% + % Instructors get solutions emboldened + \textbf{#1}% + }{% + #1% + } +} + +\begin{document} + \solution{Some Text} +\end{document} +\end{lstlisting} + + \item + To match the case when you have ``no suffix'' (i.e., when the suffix is the empty string because ``\texttt{-}'' did not appear in + the filename), use \cs{IfSuffix[]} with an empty argument list\footnote{ + If you omit the optional argument, \cs{IfSuffixT} will never be true (not even if \cs{JobnameSuffix} is the empty string). + }. + \end{itemize} + + + \section{Installation} + + For manual installation, the package is available from + \href{http://ctan.org/pkg/jobname-suffix}{{CTAN}}. + + The package requires \LaTeX3 support as provided in the \pkg{l3kernel} and + \pkg{l3packages} bundles. Both of these are included in \TeX{} Live and + MiK\TeX{}, or are again available in ready-to-install form from {CTAN}. + + \end{documentation} + + + \PrintIndex +\end{document} |