From d92cee8eff42fa304294a3e5f674062c8c745632 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 4 Dec 2018 23:09:17 +0000 Subject: diffcoeff (4dec18) git-svn-id: svn://tug.org/texlive/trunk@49317 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/diffcoeff/README.txt | 41 +- .../texmf-dist/doc/latex/diffcoeff/diffcoeff.pdf | Bin 505283 -> 621459 bytes .../texmf-dist/doc/latex/diffcoeff/diffcoeff.tex | 2215 +++++++++++--------- 3 files changed, 1258 insertions(+), 998 deletions(-) (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/diffcoeff/README.txt b/Master/texmf-dist/doc/latex/diffcoeff/README.txt index 74f14fed4ce..bef6346a728 100644 --- a/Master/texmf-dist/doc/latex/diffcoeff/README.txt +++ b/Master/texmf-dist/doc/latex/diffcoeff/README.txt @@ -1,22 +1,29 @@ -README file for LaTeX package: diffcoeff version 1.1 +diffcoeff: a package to ease the writing of a variety +of differential coefficients (derivatives) -Author: Andrew Parsloe (ajparsloe@gmail.com) 2018-10-25 +Andrew Parsloe (ajparsloe@gmail.com) 3 December 2018 -diffcoeff.sty allows the easy writing of ordinary and partial differential -coefficients of arbitrary order. For mixed partial derivatives, the overall -order (algebraic or numeric) is calculated by the package. Optional arguments -allow the easy specification of a point of evaluation for ordinary -derivatives, or variables held constant for partial derivatives, and the -placement of the differentiand (in the numerator or appended). Some tweaking -of the display is possible through key = value settings. Secondary commands -provide analogous coefficients constructed from D, \Delta and \delta and a -command for writing Jacobians. +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 -The packages require the LaTeX3 bundles, l3kernel and l3packages. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -There are three files plus this README: diffcoeff.tex, diffcoeff.pdf, and diffcoeff.sty. +This is version 2 of diffcoeff.sty, and associated files, +and requires the LaTeX3 bundles l3kernel and l3packages. -(Version 1.0 of diffcoeff.sty was accompanied by diffcoeffx.sty. However -that package contained a bug which meant it did not do all the things -claimed for it. Fixing the bug did not seem feasible without a complete -rewrite. diffcoeffx is now withdrawn.) \ No newline at end of file +Version 2 is built on xtemplate (in l3packages). As a result, +the \diffset command of version 1 is now functionless and has +been superseded by the more versatile \diffdef command. + +Manifest +%%%%%%%% +README.txt this document +diffcoeff.sty LaTeX .sty file +diffcoeff.pdf documentation +diffcoeff.tex LaTeX source of documentation +diffcoeff-doc.def definition file to be placed + in same directory as the .pdf + and .tex files diff --git a/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.pdf b/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.pdf index 5753b9ff419..f7f63e84712 100644 Binary files a/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.pdf and b/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.pdf differ diff --git a/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.tex b/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.tex index c8df6968c63..8f1d147fe0e 100644 --- a/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.tex +++ b/Master/texmf-dist/doc/latex/diffcoeff/diffcoeff.tex @@ -6,10 +6,21 @@ \renewcommand{\ttdefault}{lmtt} \usepackage[T1]{fontenc} \usepackage[latin9]{inputenc} -\setcounter{secnumdepth}{2} -\setcounter{tocdepth}{2} +\setcounter{secnumdepth}{4} +\setcounter{tocdepth}{4} +\usepackage{color} +\definecolor{shadecolor}{rgb}{1, 0.667969, 0.5} +\usepackage{babel} +\usepackage{wrapfig} \usepackage{booktabs} -\usepackage{amstext} +\usepackage{calc} +\usepackage{framed} +\usepackage{amsmath} +\usepackage{amssymb} +\usepackage[unicode=true,pdfusetitle, + bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,bookmarksopenlevel=2, + breaklinks=true,pdfborder={0 0 0},pdfborderstyle={},backref=section,colorlinks=true,pdfpagemode=FullScreen] + {hyperref} \makeatletter @@ -30,1243 +41,1485 @@ \normalfont\ttfamily}% \item[]} {\end{list}} -\providecommand*{\strong}[1]{\textbf{#1}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands. -\usepackage{diffcoeff} +\usepackage[def-file=diffcoeff-doc]{diffcoeff} -\@ifundefined{showcaptionsetup}{}{% - \PassOptionsToPackage{caption=false}{subfig}} -\usepackage{subfig} \makeatother -\usepackage{babel} \begin{document} \title{\texttt{diffcoeff}~\\ -a \LaTeX{} package for writing\texttt{}~\\ -differential coefficients easily} +a \LaTeX{} package to ease\texttt{ }the\texttt{}~\\ + writing of differential coefficients \\ +in all their variety\\ +Version 2} \author{Andrew Parsloe\\ {\small{}(ajparsloe@gmail.com)}} \maketitle \begin{abstract} -\noindent \texttt{diffcoeff.sty} allows the easy writing of ordinary and -partial differential coefficients of arbitrary (algebraic or numeric) order. -For mixed partial derivatives, the overall order (the superscript on $\partial$ -in the numerator) is calculated by the package. Optional arguments allow -the easy specification of a point of evaluation for ordinary derivatives, -or variables held constant for partial derivatives, and the placement of -the differentiand (in the numerator or appended). Some tweaking of the -display is possible through key = value settings. Secondary commands provide -analogous coefficients constructed from $D,\thinspace\Delta,$ and $\delta$, -and a command for writing Jacobians. The package uses \texttt{expl3} and -\texttt{xparse} from the \LaTeX 3 bundles, \texttt{l3kernel} and \texttt{l3packages}. +\noindent \texttt{diffcoeff.sty} allows the easy and consistent writing +of ordinary, partial and other derivatives of arbitrary (algebraic or numeric) +order. For mixed partial derivatives, the total order of differentiation +is calculated by the package. Optional arguments allow specification of +points of evaluation (ordinary derivatives), or variables held constant +(partial derivatives), and the placement of the differentiand (numerator +or appended). Version 2 is built on \texttt{xtemplate,} allowing the systematic +fine-tuning of the display and generation and use of variant forms (like +derivatives built from $D$, $\Delta$ or $\delta$). The package requires +the \LaTeX 3 bundles \texttt{l3kernel} and \texttt{l3packages}. \end{abstract} +\tableofcontents{} -\section{Version} - -Version 1.1 of the \texttt{diffcoeff} package changes the handling of error -messages which was just plain wrong in version 1 and caused a conflict -with the \texttt{mhchem} package. - -\texttt{diffcoeff.sty} had a `big brother' \texttt{diffcoeffx.sty} that -was `\texttt{diffcoeff} on steroids'. However a bug in \texttt{diffcoeffx} -means it didn't do all it claimed and it will be withdrawn. - -\section{Requirements} +\section{Introduction} The \LaTeX{} package \texttt{diffcoeff.sty} is written in the expl3 language of \LaTeX 3\texttt{ }and requires the bundles \texttt{l3kernel} and \texttt{l3packages} -(the latter for the \texttt{xparse} module). However, granted the presence -of these bundles in your \TeX{} distribution, the \LaTeX 3 element should -be invisible to the user. - -The package is invoked in the usual way by entering +(the latter for the \texttt{xparse}, \texttt{l3keys2e} and \texttt{xtemplate} +packages\texttt{)}. The package is invoked in the usual way by entering \begin{lyxcode} \textbackslash usepackage\{diffcoeff\} \end{lyxcode} -in the preamble of your document. - -\paragraph{Note on terminology} +in the preamble of your document. There are two package options. The first +is a switch, \texttt{ISO}, which turns on formatting conforming to ISO +recommendations: +\begin{lyxcode} +\textbackslash usepackage{[}ISO{]}\{diffcoeff\} +\end{lyxcode} +The effect of this is discussed in Section~\ref{sec:Changing-defaults}. +The second is a filename for a file containing definitions of variant forms +of derivative: +\begin{lyxcode} +\textbackslash usepackage{[}def-file={]}\{diffcoeff\} +\end{lyxcode} +This is discussed in Subsection~\ref{subsec:The-.def-file}. Of course +both options can be used in the same call if desired: +\begin{lyxcode} +\textbackslash usepackage{[}ISO,def-file={]}\{diffcoeff\} +\end{lyxcode} +For the present document, the call was +\begin{lyxcode} +\textbackslash usepackage{[}def-file=diffcoeff-doc{]}\{diffcoeff\} +\end{lyxcode} +with the file \texttt{diffcoeff-doc.def} in the same directory as \texttt{diffcoeff.tex}. + +\subsection{Version comparison} + +The present document discusses \emph{version 2} of the \texttt{diffcoeff} +package. Unlike version 1, version 2 is built on the the \texttt{xtemplate} +package (included in the \texttt{l3packages} bundle) which makes certain +facilities available which it would be silly not to exploit. Hence the +coding between the versions is completely different and there are consequences. + +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{shaded}% +\begin{enumerate} +\item The \texttt{\textbackslash diffset} command, formerly used to tweak the +display of derivatives, has been superseded by the \texttt{\textbackslash diffdef} +command. \texttt{\textbackslash diffset} now sends a message warning of +its obsolescence to the terminal and \LaTeX{} log but is otherwise functionless. +It should not interfere with the compilation of a document but any intended +fine-tuning of the display by means of the \texttt{\textbackslash diffset} +command\texttt{ }will not eventuate. The warning message is: \texttt{Obsolete +command: \textbackslash diffset has been superseded by the \textbackslash diffdef +command. See the diffcoeff documentation for further information.} The +\texttt{\textbackslash diffdef} command is discussed in Subsection~\ref{subsec:diffdef}. +\item The optional trailing argument used to indicate a point of evaluation or +variables held constant is now delimited by square brackets, \texttt{{[}} +and \texttt{{]}}, as other optional arguments are. For compatibility with +version 1, braces can still be used but their use to delimit an \emph{optional} +argument is now deprecated in \texttt{xparse} on which \texttt{diffcoeff} +depends. Presumably at some stage this provision will be removed from \texttt{xparse}. +For future-proofing documents use square brackets. +\item The commands \texttt{\textbackslash Diff}, \texttt{\textbackslash diffd} +and \texttt{\textbackslash Diffd} used to construct derivatives from $D$, +$\delta$ and $\Delta$ in version 1, are still available in version 2, +but deprecated. A new optional argument in the \texttt{\textbackslash diff} +command offers these and a host of other possibilities and is now the preferred +method of forming such variants; see Subsection~\ref{subsec:D-delta-Delta}. +\end{enumerate} +\end{shaded}% +\end{minipage} + +\subsubsection*{Note on terminology} I refer throughout to the quantity or function being differentiated as the \emph{differentiand} (in line with \emph{integrand}, \emph{operand}, etc.). -\section{Ordinary differential coefficients \label{sec:Ordinary-differential-coefficien}} +\section{A Rogues' Gallery of derivatives} + +\label{sec:Rogues'-gallery}Browsing through texts on statistical mechanics, +relativity and classical mechanics I find the following choice examples +of derivatives `disporting every which way'. + +Multi-character variables of differentiation un-parenthesized: + +\begin{equation} +\diffp{\frac{\psi}{\Theta}}{\frac{1}{\Theta}},\quad\diffp{E/T}{1/T},\quad\diffp{\ln f}{\ln x_{0}},\quad\diffp\psi{a_{i},\frac{1}{\Theta}},\quad\diffp{\mathcal{L}}{\eta_{,i}^{(r)}}\label{eq:eg1} +\end{equation} +Multi-character variables of differentiation parenthesized: +\begin{equation} +\diffp H{\displaystyle \diffp S{q_{k}}[]},\quad\diffp\varepsilon{(1/\Theta)},\label{eq:eg2} +\end{equation} +Higher-order derivatives where the parentheses do not or do include the +operator: +\begin{equation} +\diffp[2]q{\frac{1}{\Theta}},\quad\diffp[2]q{1/\Theta},\quad\diffp[2]\varepsilon{a_{i}},\quad\diff.wrapall.[2]{\phi^{i}(x^{i})}{x^{i}}.\label{eq:eg3} +\end{equation} +Should the $d$ or $\partial$ be included within the parentheses, as in +the last of (\ref{eq:eg3}), or not, as in the others? Logic says `yes'; +practice suggests (generally) `no'. + +Indicating a point of evaluation is similarly varied: +\begin{equation} +\diff.pvrule.\phi\varepsilon[\varepsilon=\varepsilon_{0}],\quad\diff.pvrule.[2]\phi\varepsilon[\varepsilon=\varepsilon_{0}],\quad\diff.psqbra.{b^{\beta}}{a^{\alpha}}[b=0],\quad\diff.paren.uv[v=0].\label{eq:eg4} +\end{equation} + ISO 80000-2 (item 2.11.13) favours the last of these \textendash{} parentheses +\textendash{} for ordinary derivatives. Presumably, partial derivatives +should follow suit, although parentheses are also used to indicate variables +held constant: +\begin{equation} +\diffp*{\frac{P}{T}}U[V],\quad\diffp S{N_{2}}[U,V,N_{1}],\quad\diffp S/T[V].\label{eq:eg5} +\end{equation} + +Other symbols besides $d$ and $\partial$ are used to denote derivative-like +quantities. From introductory calculus, classical mechanics and thermodynamics +come $\delta$ and $\Delta$, from fluid mechanics comes $D$: +\begin{equation} +\diff.delta.yx,\quad\diff.D.\rho t,\quad\diff.pDelta.UT[V],\quad\diff.Delta.U/T,\quad\diff.delta.{\mathcal{L}}{\eta^{(r)}}.\label{eq:eg6} +\end{equation} + +There are those, like the International Organization for Standardization +(ISO), who stipulate (or prefer) an upright `d' for their derivatives: +\begin{equation} +\diff.up.yx.\label{eq:eg11} +\end{equation} +When the differentiand is too big or awkward to sit in the numerator and +is appended to the operator, the $d$ or $\partial$ in the numerator is +generally centred \textendash{} but not always. In texts prior to the age +of computerised typesetting one will sometimes find the symbol pushed to +the \emph{left}: +\begin{equation} +\diff.pleft.*{\diffp{x^{i^{*}}}{x^{k^{*}}}{}}{x^{l^{*}}},\quad\diff.left.*{\left(\frac{m\mathbf{q}_{x}}{\sqrt{1-q^{2}}}\right)}{t}.\label{eq:eg12} +\end{equation} +The observant will note an italic adjustment with the first expression, +so that the $\partial$ in the numerator and the $\partial$ in the denominator +line up in a slanting column, but no such adjustment for the $d$-s in +the second derivative. + +And finally, the operator in the numerator may differ from that in the +denominator. For instance, in tensor calculus acceleration is sometimes +written as +\[ +\diff.nabla.{v^{i}}t=\diff{v^{i}}t+\Gamma_{k\hphantom{i}h}^{\hphantom{k}i}v^{h}\diff{y^{k}}t +\] +where $\nabla v^{i}$ is the `absolute differential' of the velocity +$v^{i}$. + +Version 2 of the \texttt{diffcoeff} package has the generative power to +cope with all these variations \textendash{} see Section~\ref{sec:Changing-defaults} +\textendash{} although it is unlikely an author should need to call on +this capacity to anything like the extent required for this Rogues' Gallery. + +\section{Ordinary derivatives \label{sec:Ordinary-derivatives}} Writing\textbf{ }\texttt{\textbackslash diff\{y\}\{x\}} will produce $\diff{y}{x}$ -in text style (i.e. placed between \texttt{\$ \$}) or +in text style (i.e., placed between \texttt{\$ \$}) or \[ \diff{y}{x} \] -in display style (i.e. placed between \texttt{\textbackslash{[} \textbackslash{]}} +in display style (i.e., placed between \texttt{\textbackslash{[} \textbackslash{]}} ). In fact \texttt{\textbackslash diff yx} (omitting the braces) will produce these results, with a saving on keystrokes. The braces are needed -only when differentiand or variable of differentiation is more than a single -token. +only when an argument \textendash{} differentiand, variable of differentiation +\textendash{} is more than a single token. +\begin{itemize} +\item If you want upright `$\mathrm{d}$'s as default, as ISO 80000-2 recommends, +rather than the math-italic `$d$'s I am using, this can easily be done; +see Section~\ref{sec:Changing-defaults} on changing default settings. +\end{itemize} +For inclusion in a line of text you might prefer to use a slash-fraction +form of derivative. That is achieved by inserting a slash, `/', between +numerator and denominator arguments: \texttt{\textbackslash diff \{\textbackslash ln +x\}/x} produces $\diff{\ln x}/x$. (Braces are required for the numerator +in this case since it contains more than one token.) -There is one other form: we can insert a slash, `/', between numerator -and denominator: \texttt{\textbackslash diff f/x} produces $\diff f/x$ -which may be preferred for textstyle differential coefficients on occasion. -Nothing is gained in this particular instance. It is quicker to type the -five keystrokes d, f, /, d, x than it is to type the nine of \textbackslash , -d, i, f, f, , f, /, x but there are occasions when this is not always the -case. +\subsection{Order of differentiation} An optional first argument allows the order of differentiation to be specified. The order need not be a number; an algebraic order of differentiation is -perfectly acceptable or, indeed, a mix: -\begin{example} -\textbackslash diff{[}2{]}\{y\}\{x\} $\Longrightarrow\quad{\displaystyle \diff[2]{y}{x},}$\medskip{} - -\textbackslash diff{[}n+1{]}\{y\}\{x\} $\Longrightarrow\quad{\displaystyle \diff[n+1]{y}{x}}.$ -\end{example} - -(And again the braces can be omitted for single letters like \textbf{x} -and \textbf{y}.) - -In slash style, \texttt{\textbackslash diff{[}2{]}f/x} (11 keystrokes) -produces $\diff[2]f/x$, not significantly more typing than \texttt{d\textasciicircum 2f/dx\textasciicircum 2} -(9 keystrokes). - -If you want to specify a point at which the derivative is evaluated, append -a final optional argument, but note that it is given in \emph{braces} rather -than square brackets: +perfectly acceptable as is a mix of the two: \begin{example} -\textbackslash diff{[}2{]}\{y\}\{x\}\{0\} $\Longrightarrow\quad{\displaystyle \diff[2]{y}{x}{0}}$ -\end{example} +\textbackslash diff{[}2{]}yx $\Longrightarrow\quad{\displaystyle \diff[2]yx,}$\medskip{} -\noindent (In this example it seems neater \emph{not} to finish with a -full stop or other punctuation.) The use of braces means that the differential -coefficient can be followed immediately by a mathematical expression wrapped -in \texttt{\textbackslash\{ \textbackslash\}}, or \texttt{{[} {]}}, -without the expression being confused with the (final) optional argument. -Note also that there must be \emph{no space} before the argument: it follows -\emph{immediately} on the second mandatory argument (if it follows at all). - -We could save a few keystrokes by writing this last example as \texttt{\textbackslash diff{[}2{]}yx\{0\}}. -The braces around the final optional argument can \emph{not} be omitted -\textendash{} otherwise there is no way of knowing that it \emph{is }the -final optional argument and not part of a following expression. - -In slash style, the trailing optional argument can be used, but perhaps -should not be. It looks ugly: -\begin{example} -\textbackslash diff{[}2{]}y/x\{0\} $\Longrightarrow\quad{\displaystyle \diff[2]{y}/{x}{0}}$ +\textbackslash diff{[}n+1{]}yx $\Longrightarrow\quad{\displaystyle \diff[n+1]yx}.$ \end{example} -Slash style is a more casual rendering of the derivative, intended for -inline use within text and it would be better to use a phrase like `evaluated -at zero'. - -\subsection{\textbackslash diffset: formatting tweaks} - -There are a number of tweaks one can make to the display of a derivative. -Many people now use upright (roman) forms for the `d's of a differential -coefficient, rather than math italic. To do this, put the command +As mentioned, the braces can be and have been omitted around the $x$ and +$y$; the square brackets around the optional argument, the order of differentiation, +are essential. For a first-order derivative, no optional argument is needed +and entering \texttt{1} as the optional argument has no effect: \begin{example} -{\footnotesize{}\textbackslash}diffset{[}roman = true{]} +\textbackslash diff{[}1{]}yx $\Longrightarrow\quad{\displaystyle \diff[1]yx.}$ \end{example} -\noindent in the preamble of your document (following the \texttt{\textbackslash usepackage\{diffcoeff\}} -of course). The default is math italic. +\noindent In slash style, \texttt{\textbackslash diff{[}2{]}y/x} produces +$\diff[2]y/x$, and \texttt{\textbackslash diff{[}n+1{]}y/x} produces +$\diff[n+1]y/x$. -It is possible that you may want more space between the `d' in the numerator -of a differential coefficient and the superscripted order of the derivative. -Using an upright `d' alleviates this problem, but if using the default -math italic for the `d's, the separation can be altered by using the -\begin{example} -\textbackslash diffset{[}d-sep = $n${]} -\end{example} - -\noindent command which adds an extra $n$~mu to \TeX 's spacing. The -default value for $n$ is 1 (i.e. 1~mu). The new separation will affect -all derivatives following the new setting. Put in the preamble, the new -separation will be document-wide. +\subsection{Multi-character variables of differentiation} -A third tweak changes the delimiters used to indicate the point of evaluation. -By default there is nothing on the left side and a vertical rule with the -point of evaluation subscripted to it on the right. You may prefer subscripted -parentheses. In that case write -\begin{example} -\textbackslash diffset{[}d-delims~=~(){]}\textmd{.} -\end{example} - -Whatever delimiters you choose need to work with \LaTeX 's \texttt{\textbackslash left} -and \texttt{\textbackslash right} commands and consist of exactly two -tokens. \texttt{{[}} and \texttt{{]}}\textbf{ }are acceptable as also are -pairs like \texttt{\textbackslash lceil \textbackslash rceil}, \texttt{\textbackslash lfloor -\textbackslash rfloor} but if you want to use \texttt{\textbackslash\{}\textbf{ -}and\textbf{ }\texttt{\textbackslash\}} you need to place the \texttt{\textbackslash diffset} -command between maths delimiters. The default pair, as indicated, is \texttt{. |}, -t or full stop being \LaTeX 's way of suppressing (in this case) the left -delimiter. - -If you change the delimiters, say to \textbf{( )}, then the position of -the subscript may need adjusting. To do this, use the command -\begin{example} -\textbackslash diffset{[}d-nudge = $n${]} -\end{example} - -A suggested setting for parentheses \textbf{( )} is $-6$ (in fact $-6$~mu -but the `mu' is supplied by \texttt{diffcoeff}). Thus the total change -would be -\begin{example} -\textbackslash diffset{[}d-delims = ( ), d-nudge = -6{]} -\end{example} - -producing, for example, -\begin{example} -\textbackslash diff{[}n{]}\{y\}\{x\}\{0\} $\diffset[d-delims=(),d-nudge=-6]\Longrightarrow\quad{\displaystyle \diff[n]{y}{x}{0}}.$ -\end{example} - -The default setting for \textbf{. |} is 0. Simply writing -\begin{example} -\textbackslash diffset $\diffset$ -\end{example} - -will return all settings to their defaults. - -\subsection{Variations} - -\subsubsection{Appending the differentiand: \textbackslash diff{*}} - -If you want the differentiand to follow the differential coefficient rather -than sit in the numerator, perhaps because it is a fraction itself or because -it is long, like a polynomial ($ax^{2}+bx+c$), then one way to achieve -that is to leave the first mandatory argument in the \texttt{\textbackslash diff} -command empty and immediately follow the differential operator with the -differentiand: -\begin{example} -\textbackslash diff\{\}\{x\}(ax\textasciicircum 2+bx+c) $\Longrightarrow\quad{\displaystyle \diff{}{x}(ax^{2}+bx+c)}.$ -\end{example} - -Another is to use the star form of the \texttt{\textbackslash diff }command, -\begin{example} -\textbackslash diff{*}{[}2{]}\{\textbackslash frac\{F(x)\}\{G(x)\}\}\{x\} -$\Longrightarrow\quad{\displaystyle \diff*[2]{\frac{F(x)}{G(x)}}{x}.}$ -\end{example} - -\noindent The LaTeX expression can be harder to read if, as here, one is -using a command like \texttt{\textbackslash frac} with its own pairs of -braces, but it is much easier, if one isn't sure whether the differentiand -should be appended or in the numerator, simply to insert or delete an asterisk -than move the differentiand from one place to the other. The star form -becomes especially useful if you want to both append the differentiand -\emph{and }indicate the point of evaluation, since it saves having to set -up the \texttt{\textbackslash left.} and \texttt{\textbackslash right|}\textbf{ -}delimiters and the subscript: -\begin{example} -\textbackslash diff{*}\{\textbackslash frac\{F(x)\}\{G(x)\}\}\{x\}\{0\} -$\Longrightarrow\quad{\displaystyle \diffset[d-delims=.|,d-nudge=0]\diff*{\frac{F(x)}{G(x)}}{x}{0}}$ -\end{example} - -In slash style with the star option, an example above becomes -\begin{example} -\textbackslash diff{*}\{(ax\textasciicircum 2+bx+c)\}/\{x\} $\Longrightarrow\quad\text{\ensuremath{{\displaystyle \diff*{(ax^{2}+bx+c)}/{x}}}}$, -\end{example} - -where the derivative is automatically enclosed in parentheses by \texttt{diffcoeff}. - -\subsubsection{Multi-character variables of differentiation} - -Derivatives of a function-of-a-function may require forming a differential -coefficient in which the variable of differentiation is more complicated -than a single symbol like \texttt{x} or \texttt{\textbackslash alpha}. -For instance, to differentiate $\ln x^{2}$ (the logarithm of $x^{2}$) -one first differentiates in $x^{2}$ then in $x$. The initial differentiation -can be rendered -\begin{example} -\textbackslash diff\{\textbackslash ln x\textasciicircum 2\}\{x\textasciicircum 2\} -$\Longrightarrow\quad{\displaystyle \diff{\ln x^{2}}{x^{2}}}$; \medskip{} - -diff\{\textbackslash ln x\textasciicircum 2\}/\{x\textasciicircum 2\} -$\Longrightarrow\quad{\displaystyle \diff{\ln x^{2}}/{x^{2}}}.$ -\end{example} - -\noindent Because of the superscript in the variable of differentiation -$x^{2}$, parentheses have been automatically inserted in the denominator. -This does not happen in a first-order derivative unless there is a superscript -present. For instance, +Differentiating a function of a function may involve a multi-character +differentiation variable. For instance, to differentiate $\ln\sin x$ in +$x$ means forming the product \begin{example} \textbackslash diff\{\textbackslash ln\textbackslash sin x\}\{\textbackslash sin -x\} $\Longrightarrow\quad{\displaystyle \diff{\ln\sin x}{\sin x}.}$ +x\}\textbackslash diff\{\textbackslash sin x\}x $\Longrightarrow\quad{\displaystyle \diff{\ln\sin x}{\sin x}\diff{\sin x}x.}$ \end{example} -\noindent displays without parentheses. However, for higher order derivatives -parentheses are \emph{always} inserted to avoid confusion: +\noindent Forming the \emph{second} derivative of $\ln\sin x$ will now +involve forming (among other quantities) \begin{example} \textbackslash diff{[}2{]}\{\textbackslash ln\textbackslash sin x\}\{\textbackslash sin x\} $\Longrightarrow\quad{\displaystyle \diff[2]{\ln\sin x}{\sin x}.}$ \end{example} +\noindent Parentheses have been inserted automatically by \texttt{diffcoeff} +around $\sin x$ in the denominator to avoid any visual hint that we are +differentiating in the sine of the square of $x$. -\paragraph{Positioning the d in the numerator} +The question is: are the parentheses in the right place? Logically, no. +They should include the $d$: $(d\sin x)^{2}$ \textendash{} it is the +differential $d\sin x$ that is of the second order. But as the examples +in the Rogues' Gallery show \textendash{} see particularly (\ref{eq:eg3}) +\textendash{} the inclination seems to be to do otherwise. This may be +because one wants, in any case, to parenthesise the variable. A second, +outer pair of parentheses then seems fussy and distracting: +\[ +\diff.wrapall.[2]{f(x)}{(1/x)}. +\] -When appending a differentiand, you may want to change the position of -the `d' in the numerator, particularly if the variable of differentiation -is a multi-character symbol or the order of differentiation is a multi-character -value like $n+1$. +Customary but illogical notations are familiar in mathematics \textendash{} +think of the position of the superscripts in an identity like $\sin^{2}\theta+\cos^{2}\theta=1$. +But, like other features of the derivative, the manner of this wrapping +in parentheses of long variables for \emph{higher order} derivatives is +customisable; see Section~\ref{sec:Changing-defaults}. -If you `manually' append the differentiand, then there are various ways -of altering the placement of the `d' from the default midpoint: use \texttt{\textbackslash hfill} -to push it hard to the left; use \texttt{\textbackslash hfil} to\textbf{ -}push it to the left an intermediate amount; use \texttt{\textbackslash hphantom} -or \texttt{\textbackslash hspace}, both with a braced argument, to push -it to the left some custom amount; use \texttt{\textbackslash hspace}\textbf{ -}with a \emph{negative} braced argument to push it to the right.\emph{ -}These same means can be used to shift the `d' when using the starred -form of \texttt{\textbackslash diff}.\textbf{ }The effect is exactly the -same, too: +For first order derivatives, parenthesising does not occur. If you want +the variable of differentiation to be parenthesised, you need to insert +them yourself: \begin{example} -\textbackslash diff{[}n+1{]}\{\textbackslash hphantom\{\textbackslash sin -x\}\}\{\textbackslash sin x\}\textbackslash ln\textbackslash sin x $\Longrightarrow\quad{\displaystyle \diff[n+1]{\hphantom{\sin x}}{\sin x}\ln\sin x},$\medskip{} - -\textbackslash diff{*}{[}n+1{]}\{\textbackslash hphantom\{\textbackslash sin -x\}\textbackslash ln\textbackslash sin x\}\{\textbackslash sin x\} $\Longrightarrow\quad{\displaystyle \diff*[n+1]{\hphantom{\sin x}\ln\sin x}{\sin x}}.$ +\textbackslash diff \{f(x)\}\{1/x\}, \textbackslash quad\textbackslash diff +\{f(x)\}\{(1/x)\} $\Longrightarrow\quad{\displaystyle \diff{f(x)}{1/x},\quad\diff{f(x)}{(1/x)}.}$ \end{example} -\noindent In the starred form \texttt{diffcoeff} understands that the formatting -is not appended with the differentiand but stays in the numerator. (But -a \emph{second} \texttt{\textbackslash hphantom} or \texttt{\textbackslash hfil} -etc. would be appended.) These are to be compared with -\begin{example} -\textbackslash diff{*}{[}n+1{]}\{\textbackslash ln\textbackslash sin -x\}\{\textbackslash sin x\} $\Longrightarrow\quad{\displaystyle \diff*[n+1]{\ln\sin x}{\sin x},}$ -\end{example} -where no phantom has been used. Which is better? Deleting the asterisk -gives -\begin{example} -\textbackslash diff{[}n+1{]}\{\textbackslash ln\textbackslash sin x\}\{\textbackslash sin -x\} $\Longrightarrow\quad{\displaystyle \diff[n+1]{\ln\sin x}{\sin x},}$ -\end{example} +\subsection{Appending the differentiand: \texttt{\textbackslash diff{*}}} -In slash style, the phantom (or \texttt{\textbackslash hfil} etc.) is -ignored: +Some differentiands are too big or awkward to be placed neatly in the numerator +of a derivative and it is natural to append them to a preceding differential +operator. One way to do this is to leave the numerator argument empty in +the \texttt{\textbackslash diff} command and follow the command with the +differentiand. A better way is to star the \texttt{\textbackslash diff} +command. This tells \texttt{diffcoeff} to append the differentiand. Thus +suppose the differentiand is a polynomial, say $ax^{2}+bx+c$. Add a star +(an asterisk) to the \texttt{\textbackslash diff} command: \begin{example} -\textbackslash diff{*}{[}n+1{]}\{\textbackslash hphantom\{\textbackslash sin -x\textbackslash sin x\textbackslash sin x\}\textbackslash ln\textbackslash sin -x\}/\{\textbackslash sin x\} $\Longrightarrow\quad{\displaystyle \diff*[n+1]{\hphantom{\sin x\sin x\sin x}\ln\sin x}/{\sin x}}.$ +\textbackslash diff{*}\{(ax\textasciicircum 2+bx+c)\}x $\Longrightarrow\quad{\displaystyle \diff*{(ax^{2}+bx+c)}x.}$ \end{example} - -\subsubsection{Iterated derivatives} - -A second derivative is an iterated derivative, i.e., one in which a differential -coefficient forms the differentiand of another differential coefficient: +A virtue of using an asterisk is that if one isn't sure whether a differentiand +should be appended or not, it is an easy matter to simply insert or delete +the asterisk to compare the results. For example, a second derivative is +an iterated derivative \textendash{} one in which a derivative forms the +differentiand of another derivative: \begin{example} \textbackslash diff{[}2{]}yx = \textbackslash diff{*}\{\textbackslash diff -yx\}x $\Longrightarrow{\displaystyle \diff[2]yx=\diff*{\diff yx}x},$ +yx\}x $\Longrightarrow\quad{\displaystyle \diff[2]yx=\diff*{\diff yx}x},$ \end{example} -or even +\noindent which is more elegant to my eye than \begin{example} \textbackslash diff{[}2{]}yx = \textbackslash diff\{\textbackslash diff -yx\}x $\Longrightarrow{\displaystyle \diff[2]yx=\diff{\diff yx}x},$ +yx\}x $\Longrightarrow\quad{\displaystyle \diff[2]yx=\diff{\diff yx}x},$ \end{example} -where omission of unnecessary braces has aided readability. Note how easy -it is to switch between the different forms on the right, simply by inserting -or removing an asterisk. - -\subsection{Forming `derivatives' with D, \textbackslash Delta, \textbackslash delta} +\noindent although whether the \emph{meaning} is clearer is moot.\emph{ +}It is easy to switch between the two forms on the right, simply by inserting +or removing the asterisk. -Often one wants to construct analogues of a differential coefficient but -with symbols other than $d$ or $\partial$. The \texttt{diffcoeff} package -offers three alternatives, all with the same pattern of optional and mandatory -arguments as for \texttt{\textbackslash diff}, except for the slash form. -There is \emph{no} slash option. - -An uppercase $D$ is used in place of $d$ for the \emph{material} or \emph{substantive} -derivative of a quantity in (for example) fluid dynamics. Write \texttt{\textbackslash Diff} -to invoke this command:\footnote{The \texttt{\textbackslash diffp} command, the partial derivative, in -the example is discussed in the next section.} +In slash style with the star option, the polynomial example becomes \begin{example} -\textbackslash Diff\{\textbackslash rho\}\{t\}=\textbackslash diffp\textbackslash rho -t + \textbackslash mathbf\{u\textbackslash cdot\}\textbackslash nabla\textbackslash rho -$\Longrightarrow{\displaystyle \Diff{\rho}{t}=\diffp\rho t+\mathbf{u\cdot}\nabla\rho.}$ +\textbackslash diff{*}\{(ax\textasciicircum 2+bx+c)\}/x $\Longrightarrow\quad\text{\ensuremath{{\displaystyle (\diff{}/{x})(ax^{2}+bx+c)}}, }$ \end{example} -(The braces could also be removed from the arguments of \texttt{\textbackslash Diff} -as they have been from the arguments of \texttt{\textbackslash diffp}.)\texttt{ } +\noindent where the parentheses around the differential operator are automatically +inserted by \texttt{diffcoeff}. Like other elements of automatic formatting, +this is user-adjustable; see Section~\ref{sec:Changing-defaults}. -The `D's are romanised (along with the `d's of ordinary derivatives) -with the -\begin{example} -\textbackslash diffset{[}roman = true{]} -\end{example} - -command. The default is math italic. +\subsection{Point of evaluation\label{subsec:Point-of-evaluation}} -The command \texttt{\textbackslash diffd} will form a fraction often used -in introductory calculus texts (and other places):\footnote{I considered using \texttt{\textbackslash diffg} for this command as in -`diff greek' but decided that the more likely mind-phrase is `diff delta', -leading to the use of `d' rather than `g'.} +If you want to specify a point at which the derivative is evaluated, append +a final optional argument. Note that there \emph{must be no space} before +the left square bracket of the argument: \begin{example} -\textbackslash diffd\{y\}\{x\} $\Longrightarrow{\displaystyle \diffd yx.}$ +\textbackslash diff{[}2{]}yx{[}0{]} $\Longrightarrow\quad{\displaystyle \diff[2]yx[0]}$ \end{example} -Similarly, \texttt{\textbackslash Diffd} forms a fraction with $\Delta$: +\noindent If a space does slip in before the final optional argument, it +will not cause a \LaTeX{} error. Instead, the argument will be treated as +a square-bracketed mathematical expression following the derivative, and +typeset as such. +\begin{itemize} +\item If you prefer to use subscripted \emph{parentheses} around the derivative +to indicate a point of evaluation \textendash{} as ISO 80000-2 recommends +\textendash{} then this can easily be done; see Section~\ref{sec:Changing-defaults} +on changing default settings. Or use the \texttt{ISO} package option; see +the introduction. +\end{itemize} +Because the slash form spreads the derivative out horizontally, parentheses +are preferred here to indicate a point of evaluation: \begin{example} -\textbackslash Diffd\{y\}\{x\} $\Longrightarrow{\displaystyle \Diffd{y}{x}.}$ +\textbackslash diff\{\textbackslash ln sin x\}/\{sin x\}{[}x=\textbackslash pi/6{]} +$\Longrightarrow\quad{\displaystyle \diff{\ln\sin x}/{\sin x}[x=\pi/6]}$ \end{example} -Higher order forms of these derivatives are produced in the same way as -with \texttt{\textbackslash diff}, using an optional argument to specify -the order: +\noindent A vertical rule (or `pipe') can become too remote from the +opening $d$ of the differential coefficient: $\diff.svrule.{\ln\sin x}/{\sin x}[x=\pi/6]$; +parentheses tie the whole cluster of symbols together. + +\subsubsection{Superscripts} + +It is easy to add a superscript to a derivative to indicate evaluation +at two points and the difference between the values: \begin{example} -\textbackslash diffd{[}2{]}\{y\}\{x\} $\Longrightarrow{\displaystyle \diffd[2]yx.}$ +\textbackslash diff \{\textbackslash sin x\}x{[}0{]}\textasciicircum\{\textbackslash pi/2\} +${\displaystyle \Longrightarrow\quad\diff{\sin x}x[0]^{\pi/2}}$ \end{example} -A final optional argument, enclosed in braces, specifies a point of evaluation, -care being taken, as ever, to ensure that there is no space between it -and the second mandatory argument: +\noindent If you want only the superscript, no subscript, include the final +optional argument but leave it empty. Thus, for a particle of mass $m$ +moving along a line, distance $x$ at time $t$, the kinetic energy is: \begin{example} -\textbackslash Diffd\{y\}\{x\}\{x=0\} $\Longrightarrow{\displaystyle \Diffd yx{x=0}.}$ +\textbackslash tfrac 12 m \textbackslash diff x/t{[}{]}\textasciicircum 2 +$\Longrightarrow\quad{\displaystyle \tfrac{1}{2}m\diff x/t[]^{2}}.$ \end{example} -\section{Partial differential coefficients\label{sec:Partial-differential-coefficient}} +\section{Partial derivatives\label{sec:Partial-derivatives}} \noindent \begin{flushleft} -Partial differential coefficients follow the same pattern as for ordinary -derivatives, with some generalisations arising from the greater possibilities. -The command this time is \texttt{\textbackslash diffp}. Thus \textbf{\textbackslash diffp\{F\}\{x\}} -produces $\diffp{F}{x}$ in text style and +Partial derivatives follow the same pattern as for ordinary derivatives, +with some extensions. The command this time is \texttt{\textbackslash diffp}. +Thus \texttt{\textbackslash diffp\{F\}\{x\}}, or, with a saving on keystrokes,\texttt{ +\textbackslash diffp Fx}, produces $\diffp Fx$ in text style and \[ \diffp{F}{x} \] - in display style. Braces can be omitted for single token differentiands -and variables: \texttt{\textbackslash diffp Fx} does the job.\textbf{ -}As for \texttt{\textbackslash diff}, there is a slash form for more casual -use: \texttt{\textbackslash diffp F/x} displaying as $\diffp F/x$. Given -that \texttt{\textbackslash partial} takes 8 keystrokes to type, the slash -form \emph{does }economise on keystrokes for a partial derivative. +in display style. (As for \texttt{\textbackslash diff}, the omission of +braces is possible when the differentiand or the differentiation variable +are single tokens.) As for \texttt{\textbackslash diff}, there is a slash +form, generally preferred for inline use, \texttt{\textbackslash diffp +F/x}, displaying as $\diffp F/x$. Given that \texttt{\textbackslash partial} +takes 8 keystrokes to type, the slash form \emph{does }economise on keystrokes +for a partial derivative. \par\end{flushleft} \begin{flushleft} Again an optional argument allows the specification of the order of differentiation -and it may be numeric or algebraic or a mix of the two. For a second or, -indeed, an $n+4$th-order partial derivative, +and it may be numeric or algebraic or a mix of the two: \par\end{flushleft} \begin{example} -\textbackslash diffp{[}n+4{]}\{F\}\{x\} $\Longrightarrow\quad{\displaystyle {\displaystyle \diffp[n+4]{F}{x},}}$\medskip{} - -\textbackslash diffp{[}n+4{]}\{F\}/\{x\} $\Longrightarrow\quad{\displaystyle {\displaystyle \diffp[n+4]{F}/{x},}}$ +\textbackslash diffp{[}3{]}F/x , \textbackslash quad \textbackslash diffp{[}n{]}F/x +$\Longrightarrow\quad{\displaystyle {\displaystyle {\displaystyle \diffp[3]F/x}},\quad{\displaystyle \diffp[n]F/x.}}$\medskip{} +\textbackslash diffp{[}n+1{]}Fx $\Longrightarrow\quad{\displaystyle {\displaystyle \diffp[n+1]Fx,}}$ \end{example} + +\subsection{Variables held constant} + In a subject like thermodynamics, there is a need to indicate which variable or variables are held constant when the differentiation occurs. To show -this, append a final optional argument. Thus to differentiate the entropy -$S$ in the temperature $T$ while holding the volume $V$ constant, write +this, append a final square-bracketed optional argument and ensure that +it follows \emph{immediately} on the preceding mandatory argument. A space +here will detach the argument from the derivative and result in it being +treated as a mathematical expression following the derivative. Thus to +differentiate the entropy $S$ in temperature $T$ while holding the volume +$V$ constant, write \begin{example} -\textbackslash diffp\{S\}\{T\}\{V\} $\Longrightarrow\quad{\displaystyle \diffp{S}{T}{V}}$ +\textbackslash diffp ST{[}V{]} $\Longrightarrow\quad{\displaystyle \diffp ST[V]}$ \end{example} -As with \texttt{\textbackslash diff}\textbf{ }note how the final optional -argument is given in braces rather than square brackets, and that there -must be \emph{no space} before the argument: if used, it follows \emph{immediately} -on the second mandatory argument. This means that the differential coefficient -can be followed immediately by a mathematical expression wrapped in \textbackslash\{ -\textbackslash\}, or {[} {]}, without the expression being confused with -the (final) optional argument. - -We could save a few keystrokes by writing this last example as \texttt{\textbackslash diffp -ST\{V\}}. The braces around the optional argument can \emph{not} be dispensed -with (otherwise there is no way of knowing that it \emph{is} the final -optional argument and not part of a following expression). - -Note that for the slash form of the derivative it is anticipated that there -will be no trailing optional argument. If you \emph{do} use one, you will -need to change the nudge value either with the \texttt{\textbackslash diffset} -command or, better, by including a spacing command in the third argument: +\noindent In slash form the same expression looks like \begin{example} -\textbackslash diffp\{S\}/\{T\}\{\textbackslash ;V\} $\Longrightarrow\quad{\displaystyle \diffp{S}/{T}{\;V}}$ +\textbackslash diffp S/T{[}V{]} $\Longrightarrow\quad{\displaystyle \diffp{S}/{T}[V]}.$ \end{example} -Without the spacing command, the subscript encroaches on the right parenthesis. +This use of a parenthesised, subscripted form to indicate a variable or +variables held constant, leaves open the question: how do we represent +a point of evaluation? ISO 80000-2 makes no recommendation for \emph{partial} +derivatives; presumably we follow the same practice as their recommendation +for ordinary derivatives: +\begin{example} +\textbackslash diffp \{F(x,y)\}x{[}(0,0){]} $\Longrightarrow\quad{\displaystyle \diffp{F(x,y)}x[(0,0)]}$ +\end{example} -\subsubsection{Appending the differentiand} +However, you may prefer (as I do) to use a vertical rule for this purpose: +\[ +\diff.pvrule.{F(x,y)}x[(0,0)] +\] +Making this possibility available is discussed in Section~\ref{sec:Changing-defaults}. -If you want to remove the differentiand from the numerator to instead follow -the derivative, one way, as for ordinary derivatives, is to leave the first -mandatory argument empty and manually append the differentiand: +An empty final argument produces a parenthesised derivative with no subscript: \begin{example} -\textbackslash diffp{[}n{]}\{\}xf(x) $\Longrightarrow\quad{\displaystyle \diffp[n]{}xf(x).}$ +\textbackslash diffp yx{[}{]}${\displaystyle \Longrightarrow\quad\diffp yx[]}.$ \end{example} -However, you may wonder how that would look with the differentiand in the -numerator, which is a good reason for preferring the starred form of the -\texttt{\textbackslash diffp} command to achieve an appended derivative: +\noindent This can be useful sometimes, e.g. for writing Lagrange's equations +of motion in analytic mechanics: \begin{example} -\textbackslash diffp{*}{[}n{]}\{f(x)\}x $\Longrightarrow\quad{\displaystyle \diffp*[n]{f(x)}x.}$ +\textbackslash diffp L\{q\_k\}-\textbackslash diff{*}\{\textbackslash diffp +L\{\textbackslash dot\{q\}\_k\}{[}{]}\}t = 0 $\Longrightarrow\quad{\displaystyle \diffp L{q_{k}}-\diff*{\diffp L{\dot{q}_{k}}[]}t}=0.$ \end{example} -Now it is easy to switch between an appended differentiand and one in the -numerator simply by inserting or deleting the asterisk. In the slash form, -parentheses are automatically inserted around the differential operator: + +\subsubsection{Text-style derivatives} + +The \texttt{diffcoeff} package assumes that derivatives formed as `numerator +over denominator' will be used in display-style expressions, and that +the slash form will be used for inline use (text style). This is the familiar +practice in the literature. If one \emph{does} use the first form in an +inline expression where a variable is held constant, say \texttt{\textbackslash diffp +ST{[}V{]}} as here $\diffp ST[V]$, the result is unsatisfactory, the subscript +too tight on the closing parenthesis and too much space between parentheses +and derivative. The matter is easily resolved using `variant forms' \textendash{} +see Subsection~\ref{subsec:Text-and-script-style} below \textendash{} +giving, for our example, $\diff.ptxt.ST[V]$. + +\subsection{Appending the differentiand\label{subsec:Partial-appending}} + +For a long or awkward differentiand, it is generally better to \emph{append} +it to a preceding differential operator, rather than create a fractional +form with the long expression in the numerator. As with ordinary derivatives, +this is achieved by adding an asterisk to (i.e. by starring) the \texttt{\textbackslash diffp} +command. \begin{example} -\textbackslash diffp{*}{[}n{]}\{f(x)\}/x $\Longrightarrow\quad{\displaystyle \diffp*[n]{f(x)}/x.}$ +\textbackslash diffp{*}{[}2{]}\{\textbackslash phi(x,y,z)\}x $\Longrightarrow\quad{\displaystyle \diffp*[2]{\phi(x,y,z)}x.}$ \end{example} -It also happens, for example in thermodynamics, that you may wish to both -append the differentiand \emph{and} indicate variables held constant. In -that case, the starred \texttt{\textbackslash diffp} command is much easier -to use. Thus, to express a relation in thermodynamics, +\noindent Alternatively you could leave the first mandatory argument empty +and manually append the differentiand, but by deleting or inserting an +asterisk, it is easy to compare the two forms, differentiand-in-the-numerator, +differentiand-appended, and see which is preferable. + +In slash form, parentheses are automatically inserted around the differential +operator when the differentiand is appended, \begin{example} -\textbackslash diffp{*}\{\textbackslash frac \{P\}\{T\}\}\{U\}\{V\} = -\textbackslash diffp{*}\{\textbackslash frac\{1\}\{T\}\}\{V\}\{U\} $\Longrightarrow\quad{\displaystyle \diffp*{\frac{P}{T}}{U}{V}=\diffp*{\frac{1}{T}}{V}{U}}$ +\textbackslash diffp{*}{[}n{]}\{f(x)\}/x $\Longrightarrow\quad{\displaystyle \diffp*[n]{f(x)}/x,}$ \end{example} -\noindent where the starred form automatically takes care of the parentheses -and subscripts. Again, not all the braces are necessary, with some help -to readability: +\noindent although this behaviour can be changed (Section~\ref{sec:Changing-defaults} +again). + +If you wish to both append the differentiand \emph{and} indicate variables +held constant, then the starred form is much the easier way to achieve +this. Thus, to express a relation in thermodynamics, \begin{example} -\textbackslash diffp{*}\{\textbackslash frac PT\}U\{V\} = \textbackslash diffp{*}\{\textbackslash frac -1T\}V\{U\} $\Longrightarrow\quad{\displaystyle \diffp*{\frac{P}{T}}U{V}=\diffp*{\frac{1}{T}}V{U}}$ +\textbackslash diffp{*}\{\textbackslash frac PT\}U{[}V{]} = \textbackslash diffp{*}\{\textbackslash frac +1T\}V{[}U{]} $\Longrightarrow\quad{\displaystyle \diffp*{\frac{P}{T}}U[V]=\diffp*{\frac{1}{T}}V[U]}$ \end{example} +\noindent where the starring automatically takes care of the parentheses +and subscripts. \subsection{Mixed partial derivatives} The new thing with partial derivatives, not present with ordinary derivatives, is \emph{mixed} partial derivatives, where there is more than one variable of differentiation. If each variable is differentiated only to the first -order, then it is easy to specify the derivative. Say $f(x,y,z)$ is a -function of three variables, as indicated. Then +order, then it is easy to specify the derivative. Suppose $F$ is a function +of three variables, $x$, $y$ and $z$. Then \begin{example} -\textbackslash diffp\{f\}\{x\c{,}y,z\} $\Longrightarrow\quad{\displaystyle \diffp{f}{x,y,z}}.$ +\textbackslash diffp F\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp F{x,y,z}}.$ \end{example} The variables of differentiation are listed in order in a comma list forming the second mandatory argument. The total order of differentiation (3 in this example) is inserted automatically \textendash{} \texttt{diffcoeff} -does the calculation itself. There is also a slash form: +does the calculation. There is also a slash form: \begin{example} -\textbackslash diffp\{f\}/\{x\c{,}y,z\} $\Longrightarrow\quad{\displaystyle \diffp{f}/{x,y,z}}.$ +\textbackslash diffp F/\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp F/{x,y,z}}.$ \end{example} If we want to differentiate variables to higher order, then their orders -need to be specified explicitly. To do so use a comma list also in the -\emph{optional} argument: +need to be specified explicitly. To do so use a comma list for the optional +argument: \begin{example} -\textbackslash diffp{[}2,3{]}\{f\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[2,3]{f}{x,y,z}.}$ +\textbackslash diffp{[}2,3{]}F\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[2,3]F{x,y,z}.}$ \end{example} \noindent Notice that the overall order of the derivative \textendash{} 6 \textendash{} is again automatically calculated and inserted as a superscript on the $\partial$ symbol in the numerator. In this example, the comma list of orders has only two members, even though there are three variables. -It is assumed that the orders given in the comma list of orders apply in -sequence to the variables, the first order to the first variable, the second -to the second variable, and so on, and that any subsequent orders not listed +It is assumed that the orders given in the comma list apply in sequence +to the variables, the first order to the first variable, the second to +the second variable, and so on, and that any subsequent orders not listed in the optional argument are, by default, 1. Thus we need to specify only -2 and 3 in the example; the order of $z$ is 1 by default. - +2 and 3 in the example; the order of differentiation of $z$ is 1 by default. But you \emph{cannot} use an order specification like \texttt{{[},,2{]}}. -This will be treated as if it were \texttt{{[}2{]}}. (This is a feature -of comma lists in the expl3 language used by \texttt{diffcoeff.sty}.) Instead -write \texttt{{[}1,1,2{]}}.\textbf{ }It is only the \emph{tail} of an order -specification which can be omitted. +Instead write \texttt{{[}1,1,2{]}}.\textbf{ }It is only the \emph{tail} +of an order specification which can be omitted. The automatic calculation of the overall order of differentiation remains -true even when some or all of the orders for the individual variables are -algebraic. For example, differentiating in three variables with orders -\texttt{2k}, \texttt{m-k-2}, \texttt{m+k+3}, we have +true even when some or all of the individual orders are variables rather +than numbers. For example, differentiating in three variables to orders +\texttt{1, m+1, m-1}, \begin{example} -\textbackslash diffp{[}2k-1,m-k-2,m+k+3{]}\{F(x,y,z)\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[2k-1,m-k-2,m+k+3]{F(x,y,z)}{x,y,z}}$, +\textbackslash diffp{[}1,m+1,m-1{]}\{F(x,y,z)\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[1,m+1,m-1]{F(x,y,z)}{x,y,z}.}$ \end{example} +Should you specify \emph{more} orders in the comma list than there are +variables, compilation will fail and an error message will be sent to the +terminal and \LaTeX{} log . For example, if on line 53 (say) of my document +I specify \texttt{{[}1,m-1,m+1,2{]}} for the orders of differentiation +but list only \texttt{\{x,y,z\}} for the variables, the message will be +\begin{lyxcode} +!~Package~diffcoeff~Error:~4~orders~specified~for~3 -\subsection{The order-override option} - -In this example the overall order is presented as \texttt{2k+2m}. You might -prefer this to be presented as \texttt{2(k+m)} instead. Although \texttt{diffcoeff} -takes some steps to present the overall order appropriately, it does not -factorise expressions. If you want to present the order in a manner distinct -from that of \texttt{diffcoeff}, use the\emph{ order-override option}, -which is a second optional argument immediately following the first: +variables;~{[}1,m+1,m-1,2{]}~(on~line~53)~for~variables~x,y,z. +\end{lyxcode} +\noindent Perhaps the differentiations are to orders \texttt{{[}2km,m-1,m+1{]}}: \begin{example} -\textbackslash diffp{[}2k-1,m-k-2,m+k+3{]}{[}2(k+m){]}\{F(x,y,z)\}\{x,y,z\} -$\Longrightarrow\quad{\displaystyle \diffp[2k-1,m-k-2,m+k+3][2(m+k)]{F(x,y,z)}{x,y,z}}$. +\textbackslash diffp{[}2km,m-1,m+1{]}\{F(x,y,z)\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[2km,m-1,m+1]{F(x,y,z)}{x,y,z}.}$ \end{example} -The order-override option does exactly that: overrides the presentation -of the calculated order with the manually given one. (In fact the algorithm -does not get called at all.) - -\subsubsection{Order specifications beyond the scope of \texttt{diffcoeff.sty}} - -The order specification can include signed integers, variables like $k$ -and $\alpha$ with signed integer coeffients, and products of any number -of variables like $mn$ or $kmn$ with signed integer coefficients. The -algorithm that calculates the overall order in \texttt{diffcoeff.sty} \emph{cannot} -handle\texttt{ }exponents, subscripts or parentheses. For such constructs, -or more exotic ones, the order-override option is always available. If -it is present (even if empty), the algorithm is bypassed completely and -one can include `anything' there without causing error. - -I doubt that these limitations matter in any practical sense. We are in -`overkill' territory here. Mixed partial derivatives are used far more -rarely than the `pure' ones, and mixed partial derivatives to `exotic' -orders of differentiation are used \emph{vanishingly} rarely, and in any -case the order-override option is always available. But should you, in -some freak circumstance, find yourself needing to write such things, then -I suggest you use \texttt{diffcoeffx.sty}, which is \texttt{diffcoeff.sty} -`on steroids'. It can handle the situations described above that are -beyond the scope of \texttt{diffcoeff.sty}, and it uses exactly the same -commands so there is nothing new to remember. It also provides additonal -functionality for the trailing optional argument. - -\subsubsection{Presentation of the overall order} - -To take a grotesque example, that will never arise in practice, consider -the following: +\noindent Here the overall order is presented as \texttt{2km+2m}. You might +prefer this to be presented as \texttt{2m(k+1)}. Although \texttt{diffcoeff} +takes some steps to present the overall order appropriately, it is not +a computer algebra system and does not factorise expressions. If you want +to present the order in a manner distinct from that presented by \texttt{diffcoeff}, +use the \emph{order-override option}. + +\subsubsection{The order-override option} + +\noindent This is a second optional argument immediately following the +order specification. For our last example, filling the override option +with \texttt{2m(k+1)} gives the desired result: \begin{example} -\textbackslash diffp{[}kmn-mn+n-1,2kmn-mn+2n-1,n+1{]}\{f\}\{x,y,z,w\} -$\Longrightarrow{\displaystyle \diffp[kmn-mn+n-1,2kmn-mn+2n-1,n+1]{f}{x,y,z,w}}.$ +\textbackslash diffp{[}2km,m-1,m+1{]}{[}2m(k+1){]}\{F(x,y,z)\}\{x,y,z\} +$\Longrightarrow\quad{\displaystyle \diffp[2km,m-1,m+1][2m(k+1)]{F(x,y,z)}{x,y,z}}.$ \end{example} -As noted earlier, since the final variable $w$ is differentiated only -to order 1, there is no need to specify it in the comma list of orders. -The implicit 1 contributes to the vanishing of the numerical part in the -overall order of differentiation. In this example, the overall order contains -multivariable terms, $kmn$ and $mn$. \texttt{diffcoeff} initially organises -these in the sequence: \ldots{} 3-variable terms before 2-variable terms -before single-variable terms, generally before the numerical term. However -if a minus sign precedes the first many-variable term, and the numerical -term is positive, it will be presented first: +\noindent As another example, left to its own devices, \texttt{diffcoeff} +produces \begin{example} -\textbackslash diffp{[}12-2km,k-1,km+1{]}\{f\}\{x,y,z,w\} $\Longrightarrow{\displaystyle \diffp[12-2km,km-1,k+1]{f}{x,y,z,w}}.$ +\textbackslash diffp{[}m/2+n/2,m/2,n/2{]}F\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[m/2+n/2,m/2,n/2]F{x,y,z},}$ \end{example} -Should the numerical term either vanish or be negative and the leading -algebraic term is preceded by a minus sign, \texttt{diffcoeff} will look -for an algebraic term with a preceding $+$ sign and put that first: +\noindent whereas we would like the total order to be presented as $m+n$. +Using the override option, \begin{example} -\textbackslash diffp{[}2km-3k-1,2k-1,-3km+4k+1{]}\{f\}\{x,y,z,w\} $\Longrightarrow{\displaystyle \diffp[2km-3k-1,2k-1,-3km+4k+1]{f}{x,y,z,w}}.$ +\textbackslash diffp{[}m/2+n/2,m/2,n/2{]}{[}m+n{]}F\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[m/2+n/2,m/2,n/2][m+n]F{x,y,z}}.$ \end{example} +The order-override option does exactly that: overrides the presentation +of the calculated order with the manually given one. In fact the calculation +algorithm does not get called at all when the override option is used so +that one can in this way present the total order in whatever manner one +wishes or, indeed, add essentially arbitrary material as a superscript +to the $\partial$ symbol in the numerator. + +\subsubsection{Comma list of variables of differentiation} + +In tensor calculus the differentiations are almost always in terms of super- +or subscripted coordinates. In many other contexts this is the case too +\textendash{} the reciprocal of the temperature in thermodynamics or generalized +cooredinates in analytical mechanics. This is why a comma list is used +in \texttt{diffcoeff} for specifying variables of differentiation for mixed +partial derivatives. Although it would be nice to write the minimal \texttt{\{xy\}} +rather than \texttt{\{x,y}\} when two variables $x$ and $y$ are involved, +the extra writing is trivial and the comma list allows a simpler handling +of multi-character variables. For instance in tensor calculus we get expressions +like +\begin{example} +\textbackslash diffp\{A\_i\}\{ x\textasciicircum j,x\textasciicircum k +\} $\Longrightarrow\quad{\displaystyle \diffp{A_{i}}{x^{j},x^{k}}.}$ +\end{example} -\subsection{\textbackslash diffset: formatting tweaks} +\noindent It is easier to write \texttt{\{x\textasciicircum j,x\textasciicircum k\}} +here than, say, \texttt{\{\{x\textasciicircum j\}\{x\textasciicircum k\}\}} +to distinguish the variables. It does mean that should the variable of +differentiation include a comma then that comma needs to be enclosed in +braces. There are plenty of instances of this out in the world (see, e.g., +the last equation of (\ref{eq:eg1})) but it is overall a rare occurrence. -As with ordinary derivatives, there are a number of tweaks one can make -to the display of a partial derivative. +\subsubsection{Overkill territory} -You may want more space between the $\partial$ symbol in the numerator -of a partial derivative and the superscripted order of the derivative. -The separation can be altered by using the +Two previous examples illustrate limitations of the algorithm that calculates +the overall order of differentiation: \texttt{2m/2+2n/2} is not simplified +to \texttt{m+n} and \texttt{2km+2m} is not factorised to \texttt{2m(k+1)}. +But there is much that the algorithm \emph{can} handle \textendash{} for +instance, the simple use of parentheses: \begin{example} -\textbackslash diffset{[}p-sep = $n${]} +\textbackslash diffp{[}2m-(k+1),2(k+1)-m{]}\{F(x,y,z)\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp[2m-(k+1),2(k+1)-m]{F(x,y,z)}{x,y,z}}.$ \end{example} -\noindent command which adds an extra $n$~mu to \TeX 's spacing. The -default value is 1 (i.e. 1~mu). The new separation will affect all derivatives -following the new setting. Put in the preamble, the new separation will -be document-wide. -You may also want to adjust the spacing between the terms in the denominator. -This can be done with the command -\begin{example} -\textbackslash diffset{[}sep=$n${]} -\end{example} +\paragraph*{Dynamic use of parentheses} -which adds an extra $n$~mu to \TeX 's spacing. The default value is 2~mu. +\noindent For parenthetic expressions to be evaluated as in this example +\textendash{} the \emph{dynamic} use of parentheses \textendash{} the left +parenthesis must be preceded at most by a sign or a number; the right parenthesis +must be followed at most by a sign. -If you wish to indicate the point at which a partial derivative is evaluated, -you may not want to use parentheses, since these when subscripted are widely -held to indicate variables held constant. To change the delimiter on the -right to a vertical line, use -\begin{example} -\textbackslash diffset{[}p-delims = . | {]}\textmd{,} -\end{example} +If a right parenthesis is followed by a \emph{variable}, say by \texttt{m} +as in the order spec. \texttt{{[}(2n+1)m,(2n-1)m{]}}, it will throw an +error and halt compilation. A message will be sent to the terminal and +the \LaTeX{} log like the following (which assumes the order spec. was on +line 53 of the document): +\begin{lyxcode} +!~Package~diffcoeff~Error:~Is~this~intended:~)~followed~ -the dot suppressing the delimiter on the left. (Note that to use \texttt{\textbackslash\{} -and \texttt{\textbackslash\}} as delimiters, \texttt{\textbackslash diffset -}must be placed between maths delimiters.) +by~m~in~the~order~specification~{[}(2n+1)m,(2n-1)m{]}~on~ -Changing the delimiters will usually require a repositioning of the subscript. -The command is -\begin{example} -\textbackslash diffset{[}p-nudge = $n${]}\textmd{.} -\end{example} +line~53?~Diffcoeff~cannot~calculate~the~overall~order~of~ -For parentheses the default value of $n$ is $-6$, but for the vertical -rule a zero value is appropriate. Thus the overall command for . | would -be +differentiation~from~the~specification~in~this~case.~Use~ + +the~order-override~option~to~enter~the~overall~order. +\end{lyxcode} +This is a limitation on the dynamic use of parentheses \textendash{} but +they \emph{can} be nested. + +\paragraph*{Static use of parentheses} + +If a left parenthesis is preceded by a \emph{variable} (i.e., not a sign +or a number) this signals to \texttt{diffcoeff} the \emph{static} use of +parentheses. No attempt is made to evaluate what is between them and they +are treated simply as an extension of the variable. For example, \begin{example} -\textbackslash diffset{[}p-delims = . |, p-nudge = 0{]} \textmd{.} +\textbackslash diffp{[}f(k+1)+1,f(k-1)-1{]}\{F(x,y)\}\{x,y\} $\Longrightarrow\quad{\displaystyle \diffp[f(k+1)+1,f(k-1)-1]{F(x,y)}{x,y}}.$ \end{example} -Writing +\noindent In the static case you \emph{can} follow the right parenthesis +by a variable without generating an error.\emph{ }You can nest them, and +you can include static parentheses within a dynamic pair; for example, \begin{example} -\textbackslash diffset +\textbackslash diffp{[}2(3+f(k))+1,1-3(f(k)-2){]}\{F(x,y)\}\{x,y\} $\Longrightarrow\quad{\displaystyle \diffp[2(3+f(k))+1,1-3(f(k)-2)]{F(x,y)}{x,y}}.$ \end{example} -will return all settings to their default values. - -\subsection{Variations} - -\subsubsection{Multi-character variables of differentiation} +\noindent However, the reverse is not possible: you can't have dynamic +parentheses within a static pair. -In thermodynamics one may want to differentiate in the reciprocal of the -temperature, $1/T$. In tensor calculus the differentiations are almost -always in terms of super- or subscripted coordinates, and in many other -contexts this is the case too. This is why a comma list is used in \texttt{diffcoeff} -for specifying the variables of differentiation for partial derivatives. -Although it would be nice to write the minimal \texttt{\{xy\}} for this -rather than \texttt{\{x,y}\}, the extra writing is trivial and the comma -list allows the simplest handling of multi-character variables: -\begin{example} -\textbackslash diffp\{A\_i\}\{ x\textasciicircum j,x\textasciicircum k -\} $\Longrightarrow{\displaystyle \diffp{A_{i}}{x^{j},x^{k}},}$ -\end{example} +\paragraph*{Other refinements} -taken from tensor calculus, or this strange object taken from statistical -mechanics: +Exponents and subscripts on a \emph{variable} are fine in an order specification, +so long as the exponent or subscript consists of a \emph{single} token: \begin{example} -\textbackslash diffp{[}2{]}q\{\textbackslash frac 1\textbackslash Theta\} -$\Longrightarrow{\displaystyle \diffp[2]q{\frac{1}{\Theta}}}$. +\textbackslash diffp{[}m\textasciicircum 2+2(k-1),m\textasciicircum 2-(k+1){]}F\{x,y,z,w\} +$\Longrightarrow\quad{\displaystyle \diffp[m^{2}+2(k-1),m^{2}-(k+1)]F{x,y,z,w}}.$ \end{example} -The parentheses have been inserted automatically by \texttt{diffcoeff} -to clarify exactly what the variable of differentiation is. +\noindent Braced arguments containing \emph{multiple} tokens as exponents +or subscripts to variables will generally not halt compilation but will +usually give nonsensical results, as will \emph{signs} treated as superscripts +or subscripts. Neither circumstance is checked for by \texttt{diffcoeff}. -\subsubsection{Use of phantoms when appending differentiands} +\emph{Numbers} raised to a power will cause a \LaTeX{} error. (The \texttt{l3int} +module of the expl3 language is used to evaluate expressions, and this +does not cater for raising to a power.) -As for ordinary derivatives, when appending a differentiand you may want -to include a phantom (\texttt{\textbackslash hphantom} etc.) in the numerator -of the differential coefficient to alter the placement of the $\partial$ -symbol. This may be particularly relevant if the order of differentiation -is a multi-character symbol or if there are a number of variables of differentiation. +\paragraph*{Override} -Either means of achieving the appended differentiand achieve the same result: -\begin{example} -\textbackslash diffp{[}m,2{]}\{\textbackslash hphantom\{\textbackslash partial -y \textbackslash partial \}\}\{x,y,z\} (\textbackslash ln \textbackslash cos -x + \textbackslash ln \textbackslash sin y)z $\Longrightarrow\quad{\displaystyle \diffp[m,2]{\hphantom{\partial y\partial}}{x,y,z}}(\ln\cos x+\ln\sin y)z,$\medskip{} +There are limitations on what order specifications the \texttt{diffcoeff} +package can `digest'; equally, it can digest a wide variety of such constructs, +but it is \emph{not} a computer algebra system. In all those cases where +it fails to calculate or present a correct total order, the order-override +option is available. Yes, this is not as convenient as having the overall +order calculated automatically but, let's remind ourselves, we are deep +in overkill territory. Mixed partial derivatives are used far less often +than the pure derivatives, and when they \emph{are} used it is nearly always +to orders 1 or 2 in the variables. Mixed partial derivatives to exotic +orders of differentiation are rarely used, so that the limitations of the +calculational algorithm are of little real moment \textendash{} and the +override option is always available for such cases. -\textbackslash diffp{*}{[}m,2{]}\{\textbackslash hphantom\{\textbackslash partial -y \textbackslash partial \}(\textbackslash ln \textbackslash cos x + -\textbackslash ln \textbackslash sin y)z\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp*[m,2]{\hphantom{\partial y\partial}(\ln\cos x+\ln\sin y)z}{x,y,z}},$ -\end{example} +\subsection{Parentheses around multi-character variables} -which is to be compared with the derivative without the phantom, +In thermodynamics and statistical mechanics one may want to differentiate +in the reciprocal of the temperature, $1/T$ (or $1/\Theta$): \begin{example} -\textbackslash diffp{*}{[}m,2{]}\{(\textbackslash ln \textbackslash cos -x + \textbackslash ln \textbackslash sin y)z\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \diffp*[m,2]{(\ln\cos x+\ln\sin y)z}{x,y,z}}.$ +\textbackslash diffp{[}2{]}q\{\textbackslash frac 1\textbackslash Theta\} +$\Longrightarrow\quad{\displaystyle \diffp[2]q{\frac{1}{\Theta}}.}$ \end{example} -\noindent In the starred form, \texttt{diffcoeff} understands that the -phantom is not appended with the differentiand but stays in the numerator. -(But a \emph{second} phantom would be appended.) +\noindent In this case and for other \emph{higher order} derivatives of +multi-character variables of differentiation, the parentheses are inserted +automatically by \texttt{diffcoeff}. Precisely where parentheses should +be placed is moot. The placement in this example is not strictly logical, +although it feels intuitive, but the placement can be customised (Section~\ref{sec:Changing-defaults}). -\subsubsection{Iterated derivatives} - -Partial derivatives can be iterated. For example, +Parentheses are automatically inserted like this only for higher order +derivatives. When the differentiation is to first order, parenthesising +is up to the user: \begin{example} -\textbackslash diffp f\{x,y\} = \textbackslash diffp{*}\{\textbackslash diffp -fy\}x $\Longrightarrow{\displaystyle \diffp f{x,y}=\diffp*{\diffp fy}x,}$\medskip{} - -\textbackslash diffp f\{x,y\} = \textbackslash diffp\{\textbackslash diffp -fy\}x $\Longrightarrow{\displaystyle \diffp f{x,y}=\diffp{\diffp fy}x.}$ +\textbackslash diffp q\{(\textbackslash frac 1\textbackslash Theta),V\} +$\Longrightarrow{\displaystyle \quad\diffp q{(\frac{1}{\Theta}),V}.}$ \end{example} -It is easy to switch between these forms by inserting or deleting the asterisk. \subsection{Jacobians} \texttt{diffcoeff} provides a command \texttt{\textbackslash jacob} for constructing Jacobians. For example \begin{example} -\textbackslash jacob\{u,v,w\}\{x,y,z\} $\Longrightarrow{\displaystyle \jacob{u,v,w}{x,y,z}.}$ +\textbackslash jacob\{u,v,w\}\{x,y,z\} $\Longrightarrow\quad{\displaystyle \jacob{u,v,w}{x,y,z}.}$ \end{example} The comma lists can contain any number of variables. \texttt{\textbackslash jacob} does \emph{not} check that the two arguments contain the same number of -variables, so it is perfectly possible to form an object like +variables, so it is perfectly possible to form an object like \texttt{\textbackslash jacob\{u,v,w\}\{x,y\}} +which as far as I know has no meaning. + +\section{Changing defaults; variant forms\label{sec:Changing-defaults}} + +\begin{wraptable}[22]{o}{0.5\columnwidth}% +\vspace{-2.5ex} +\caption{{\small{}Defaults (ordinary derivatives})\label{tab:Ordinary-derivatives}} + +\centering{}\abovetopsep=.5ex{\small{}}% +\begin{tabular}{lr} +\toprule +{\small{}key} & {\small{}default}\tabularnewline +\midrule +{\small{}op-symbol } & \texttt{\small{}d}\tabularnewline +{\small{}op-symbol-alt} & \texttt{\small{}= op-symbol}\tabularnewline +{\small{}op-order-sep } & \texttt{\small{}1 mu}\tabularnewline +{\small{}{*}-op-left } & \texttt{\small{}false}\tabularnewline +{\small{}{*}-italic-nudge} & \texttt{\small{}3 mu}\tabularnewline +{\small{}{*}/-op-wrap} & \texttt{\small{}true}\tabularnewline +{\small{}long-var-wrap } & \texttt{\small{}d(v)}\tabularnewline +{\small{}denom-term-sep} & \texttt{\small{}2 mu}\tabularnewline +{\small{}/-denom-term-sep } & \texttt{\small{}1 mu}\tabularnewline +{\small{}left-delim} & \texttt{\small{}\textbackslash left .}\tabularnewline +{\small{}right-delim} & \texttt{\small{}\textbackslash right |}\tabularnewline +{\small{}elbowroom} & \texttt{\small{}0 mu}\tabularnewline +{\small{}subscr-nudge } & \texttt{\small{}0 mu}\tabularnewline +{\small{}/-left-delim} & \texttt{\small{}(}\tabularnewline +{\small{}/-right-delim } & \texttt{\small{})}\tabularnewline +{\small{}/-elbowroom} & \texttt{\small{}0 mu}\tabularnewline +{\small{}/-subscr-nudge } & \texttt{\small{}0 mu}\tabularnewline +\bottomrule +\end{tabular}{\small\par}\end{wraptable}% +To write the range of different examples displayed in the Rogues' Gallery +(Section~\ref{sec:Rogues'-gallery}) I have had to make extensive use +of forms of derivative other than the default. Version 2 of \texttt{diffcoeff} +(as distinct from version 1) is built around the facilities offered by +the \texttt{xtemplate} package (included in the \LaTeX 3 bundle \texttt{l3packages)}. +These facilities are harnessed by means of a command, \texttt{\textbackslash diffdef}, +and a further optional argument of the \texttt{\textbackslash diff} command.\texttt{ } + +How a derivative is displayed in a document is determined by specifying +values in a `key = value' list. This is done with the \texttt{\textbackslash diffdef} +command, which also allows a name to be associated with the list. By using +that name as an argument in the \texttt{\textbackslash diff} command, +a derivative is formed shaped by those values. Examples will make the process +clear. + +\subsection{Default values: ordinary derivatives} + +Table~\ref{tab:Ordinary-derivatives} lists the keys available for forming +derivatives and the default values\footnote{Note that a mu is a `math unit', 1/18 of an em in the math font used.} +they have been assigned. These default values have been chosen to coincide +with those relevant for \emph{ordinary} derivatives (apart from the keys +\texttt{denom-term-sep} and \texttt{/-denom-term-sep} which are ignored +for ordinary derivatives but apply to the case of mixed partial derivatives +when there is more than one variable of differentiation.) Keys with an +opening slash, /, apply only to the slash form of the derivative; keys +with an opening asterisk, {*}, apply only when the differentiand is appended. + +Note that these settings are, in general, font dependent. The values given +are (in the author's opinion) appropriate for the default \LaTeX{} math +fonts, or latin modern fonts. There are also likely to be variations required +for whether a derivative is used in a display-style or text-style or script-style +expression. That matter is discussed below in Subsection~\ref{subsec:Text-and-script-style}. +\begin{description} +\item [{op-symbol}] the operator symbol; for ordinary derivatives, generally +one of \texttt{d} or \texttt{\textbackslash mathrm\{d\}}, \texttt{D} or +\texttt{\textbackslash mathrm\{D\}}, \texttt{\textbackslash delta} or +\texttt{\textbackslash Delta}; for partial derivatives \texttt{\textbackslash partial} +\item [{op-symbol-alt}] if different from \textbf{op-symbol} then used in the +denominator while \textbf{op-symbol} is used in the numerator; otherwise +(and usually) defaults to \textbf{op-symbol}; e.g. for $\diff.nabla.{v^{i}}t$, +\texttt{op-symbol = \textbackslash nabla} and \texttt{op-symbol-alt = +d} +\item [{op-order-sep}] extra horizontal space added between the op-symbol and +the superscripted order of differentiation in higher order derivatives; +compare $d^{2}$ with $d^{\mkern1mu 2}$, $\partial^{2}$ with $\partial^{\mkern1mu 2}$ +where the first symbol in each case has no extra space and the second has +an extra 1 mu +\item [{{*}-op-left}] a choice of \texttt{true} or \texttt{false} indicating +whether the op-symbol is left-aligned or not when the differentiand is +appended; generally it is centred; does not apply to slash forms of the +derivative +\item [{{*}-italic-nudge}] if \textbf{{*}-op-left} is \texttt{true}, makes an +italic adjustment in the numerator, so that the op-symbols in numerator +and denominator align in the same slanting column; for an upright \texttt{d} +this would be set to \texttt{0 mu} +\item [{{*}/-op-wrap}] a choice of \texttt{true} or \texttt{false} for slash +forms of the derivative when the differentiand is appended, dictating whether +the differential coefficient is wrapped in parentheses or not; the default +is \texttt{true}, as here: $\diffp*{F(x,y)}/x$ +\item [{long-var-wrap}] to avoid ambiguity in higher order derivatives it may +be advisable to wrap multi-token variables of differentiation in parentheses; +the choices are +\begin{description} +\item [{\texttt{dv}}] no wrapping, e.g. $dx_{i}^{2}$ or $d\frac{1}{\Theta}^{2}$, +$\partial x_{i}^{2}$ or $\partial\frac{1}{\Theta}^{2}$, +\item [{\texttt{d(v)}}] wrap the variable only, e.g. $d(x_{i})^{2}$ or $d(\frac{1}{\Theta})^{2}$, +$\partial(x_{i})^{2}$ or $\partial(\frac{1}{\Theta})^{2}$, +\item [{\texttt{(dv)}}] wrap the op-symbol and variable, e.g. $(dx_{i})^{2}$ +or $(d\frac{1}{\Theta})^{2}$, $(\partial x_{i})^{2}$ or $(\partial\frac{1}{\Theta})^{2}$ +\end{description} +\item [{denom-term-sep}] (mixed partial derivatives only) extra horizontal spacing +inserted between the differentials in the denominator of a mixed partial +derivative +\item [{/-denom-term-sep}] (mixed partial derivatives only) extra horizontal +spacing inserted between the differentials in the denominator of a slash-form +mixed partial derivative +\item [{left-delim}] the left member of a delimiter pair wrapping the derivative, +the right member of which is subscripted to indicate a point of evaluation +or variables held constant +\item [{right-delim}] the right member of a delimiter pair wrapping the derivative +and subscripted to indicate a point of evaluation or variables held constant +\item [{elbowroom}] adjustment to the whitespace between the left and right +delimiters and the enclosed derivative; negative values reduce the space +\item [{subscr-nudge}] horizontal adjustment of the subscript's placing relative +to the \textbf{right-delim}iter, e.g., a negative value compensates for +the curving inwards of a large right parenthesis; may be font dependent +\item [{/-left-delim}] for the slash form of derivative, the left member of +a delimiter pair wrapping the derivative and subscripted to indicate a +point of evaluation or variables held constant +\item [{/-right-delim}] for the slash form of derivative, the right member of +a delimiter pair wrapping the derivative, the right member of which is +subscripted to indicate a point of evaluation or variables held constant +\item [{/-elbowroom}] adjustment to the whitespace between the left and right +delimiters and the enclosed slash-form derivative +\item [{/-subscr-nudge}] for the slash form of derivative, horizontal adjustment +of the subscript's placing relative to the /-\textbf{right-delim}iter; +may be font dependent +\end{description} + +\subsection{ISO defaults} + +\begin{wraptable}[9]{o}{0.4\columnwidth}% +\centering{}\vspace{-5ex} +\caption{{\small{}ISO default changes}\label{tab:ISO-setting-changes}} +\abovetopsep=.5ex% +\begin{tabular}{lr} +\toprule +{\small{}key} & {\small{}default}\tabularnewline +\midrule +{\small{}op-symbol } & \texttt{\small{}\textbackslash mathrm\{d\}}\tabularnewline +{\small{}op-order-sep } & \texttt{\small{}0 mu}\tabularnewline +{\small{}left-delim} & \texttt{\small{}\textbackslash left (}\tabularnewline +{\small{}right-delim} & \texttt{\small{}\textbackslash right )}\tabularnewline +{\small{}subscr-nudge } & \texttt{\small{}-6 mu}\tabularnewline +\bottomrule +\end{tabular}\end{wraptable}% +\emph{ }You may not like the default settings that come with \texttt{diffcoeff}. +The package does not follow ISO 80000-2 \textendash{} it does not use upright +`d's nor does it wrap an ordinary differential coefficient in subscripted +parentheses to indicate a point of evaluation. Both `defects' can be +remedied by calling the package with the option \texttt{ISO}:\footnote{One can also use \texttt{ISO=true} to turn the option on and \texttt{ISO=false +}to turn the option off. } +\begin{lyxcode} +\textbackslash usepackage{[}ISO{]}\{diffcoeff\} +\end{lyxcode} +The uppercase is essential \textendash{} an option \texttt{iso} is not +recognised. The \texttt{ISO} option results in changes to the default settings +of Table~\ref{tab:Ordinary-derivatives} as listed in Table~\ref{tab:ISO-setting-changes}. +Any settings not mentioned in Table~\ref{tab:ISO-setting-changes} retain +the values presented in Table~\ref{tab:Ordinary-derivatives}. Note that +the subscript nudge figure specified here is \emph{not} part of the standard, +which makes no recommendation about the subscript's positioning. But: the +\texttt{-6 mu} figure with a default or latin modern font gives a better +representation of what is displayed in the standard than a zero figure. + +Because the `d' is upright with the \texttt{ISO} option, no extra space +is required between the symbol and the superscript in a higher order derivative. +Hence the zero value for the \texttt{op-order-sep}. ISO recommends subscripted +parentheses to indicate a point of evaluation. Hence the other entries +in the table. Because a large right parenthesis (penultimate setting) bends +inwards, to the left, a negative value for the last entry ensures the subscript +does not become detached from the derivative, looking lost in a sea of +whitespace. + +Note that the \texttt{ISO} option will also produce upright `D's in derivatives +formed from `D'; see Subsection~\ref{subsec:D-delta-Delta} below. + +\subsection{Partial derivatives} + +\begin{wraptable}{o}{0.4\columnwidth}% +\begin{centering} +\vspace{-5ex} +\caption{{\small{}Default changes: partial derivatives}\label{tab:Partial-deriv-defaults}} +\abovetopsep=.5ex% +\begin{tabular}{lr} +\toprule +{\small{}key} & {\small{}default}\tabularnewline +\midrule +{\small{}op-symbol } & \texttt{\small{}\textbackslash partial}\tabularnewline +{\small{}left-delim} & \texttt{\small{}\textbackslash left (}\tabularnewline +{\small{}right-delim} & \texttt{\small{}\textbackslash right )}\tabularnewline +{\small{}subscr-nudge } & \texttt{\small{}-6 mu}\tabularnewline +\bottomrule +\end{tabular} +\par\end{centering} +\end{wraptable}% +The default values given in Table~\ref{tab:Ordinary-derivatives}, when +they are relevant, apply to \emph{ordinary} derivatives. For partial derivatives, +the defaults are those of Table~\ref{tab:Partial-deriv-defaults}. All +other keys take ther default values listed in Table~\ref{tab:Ordinary-derivatives}. +The last three entries here are not an attempt at ISO compatibility but +reflect the use of subscripted parentheses with partial derivatives to +indicate variables held constant, for instance in the Maxwell relations +of thermodynamics, one of which is +\[ +\diffp SV[T]=\diffp PT[V]. +\] + + +\subsection{Setting your own defaults: \texttt{\textbackslash diffdef\label{subsec:diffdef}}} + +Version 2 of the \texttt{diffcoeff} package provides a command, \texttt{\textbackslash diffdef}, +that enables users to set their own defaults.\texttt{ }For example, if +you wish to use upright `d's but not follow the ISO's use of subscripted +parentheses to indicate a point of evaluation, enter in the preamble of +your document the command\vspace{-2ex} + +\begin{lyxcode} +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{\}~~~ +\begin{lyxcode} +\{~~~~~ +\begin{lyxcode} +op-symbol~~~~=~\textbackslash mathrm\{d\},~~~~ + +op-order-sep~=~0~mu +\end{lyxcode} +\} +\end{lyxcode} +\end{lyxcode} +% +\end{minipage} +\end{lyxcode} +\noindent Since a list of settings, like this one, is a comma-\emph{separated} +list, no comma is required for the last entry. That entry is a consequence +of the first: upright symbols do not require any extra separation between +the `d' and the superscript in a higher order derivative. + +The other point to note is the empty pair of braces after the \texttt{\textbackslash diffdef} +command. \emph{They matter}. Their emptiness is what determines that it +is the \emph{default} values that are changed. If they contain some content, +then that content provides a \emph{name} for the particular set of values +in the following list. The \texttt{diffcoeff} package exploits this facility +to cope with the wide variety of forms displayed in the Rogues' Gallery +of Section~\ref{sec:Rogues'-gallery}. + +\subsection{Variant forms} + +For this package I needed to have a number of variant forms available to +illustrate the wide variety of ways in which derivatives are displayed. +The \texttt{\textbackslash diffdef} command in which the first argument +is \emph{filled} provides one half of the means of doing this. I've given +the single-letter name \texttt{p} to the following settings: + +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{~p~\} + +~~\{ + +~~~~op-symbol~~~~=~\textbackslash partial~, + +~~~~left-delim~~~=~\textbackslash left~(~~, + +~~~~right-delim~~=~\textbackslash right~)~, + +~~~~subscr-nudge~=~-6~mu + +~~\} +\end{lyxcode} +% +\end{minipage} + +The second half of providing variant forms is to insert this name, \texttt{p}, +between dots (periods, full stops) as the \emph{first} argument of the +\texttt{\textbackslash diff} command. Thus, repeating an example at the +end of Subsection~\ref{subsec:Partial-appending}, \begin{example} -\textbackslash jacob\{u,v,w\}\{x,y\} , +\textbackslash diff.p.{*}\{\textbackslash frac PT\}U{[}V{]} = \textbackslash diff.p.{*}\{\textbackslash frac +1T\}V{[}U{]} $\Longrightarrow\quad{\displaystyle \diff.p.*{\frac{P}{T}}U[V]=\diff.p.*{\frac{1}{T}}V[U]}$ \end{example} -which as far as I know has no meaning. +\noindent The effect is exactly the same as previously, when the \texttt{\textbackslash diffp} +command was used. Indeed, \texttt{diffcoeff} identifies \texttt{\textbackslash diffp} +with \texttt{\textbackslash diff.p.}, saving a few keystrokes and maintaining +compatibility with version 1 of the package. In \LaTeXe{} synatx, +\begin{lyxcode} +\textbackslash newcommand~\{~\textbackslash diffp~\}~\{~\textbackslash diff.p.~\} +\end{lyxcode} +Note that this identification of \texttt{\textbackslash diffp} with \texttt{\textbackslash diff.p. }means +there is no equivalent dot-delimited argument available for \texttt{\textbackslash diffp}. +The dot-delimited argument applies only to \texttt{\textbackslash diff}. -\section{Discussion of the code} +For example, to illustrate the upright-d form of derivative, without changing +the default math-italic form (which I prefer), one might enter in the preamble +\begin{lyxcode} +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{~up~\}~ -I set about creating this package when faced with trying to parse \LaTeX{} -expressions involving derivatives for another program I was working on. -Trying to parse \texttt{\textbackslash frac\{d\}\{d\}}, perhaps with \texttt{\textbackslash mathrm\{d\}}'s, and a superscript -on the first \texttt{d}, perhaps with a \texttt{\textbackslash tfrac} -or \texttt{\textbackslash dfrac} for the \texttt{\textbackslash frac},\textbf{ -}wasn't quite hopeless, but it was certainly \emph{messy}. (I used regular -expressions to transform the fraction into something more systematic.) +~~\{ -\subsection{Other packages} +~~~~op-symbol~~~~=~\textbackslash mathrm\{d\}, -Looking through the MiK\TeX{} distribution and, less assiduously, through -CTAN, produced the following packages which provide macros for derivatives. -(Strangely, AMS packages do not touch this subject, as far as I can see.) -\begin{itemize} -\item \texttt{bropd} -\begin{itemize} -\item \texttt{\textbackslash od{[}n{]}\{y\}\{x\}} and \texttt{\textbackslash pd{[}n{]}\{y\}\{x\}} -for ordinary and partial derivatives of order \texttt{n} in one variable -\item \texttt{\textbackslash pd\{u\}\{x,x,t\}} for a mixed partial derivative, -order 2 in \texttt{x}, 1 in \texttt{t} -\item \texttt{\textbackslash pd\{\}\{z\}\{x+y\}} for appending \texttt{(x+y)} -\item \texttt{\textbackslash pd\{!\}\{z\}\{x+y\}} for appending \texttt{x+y} -\end{itemize} -\item \texttt{commath} -\begin{itemize} -\item \texttt{\textbackslash od{[}n{]}\{y\}\{x\}} and \texttt{\textbackslash pd{[}n{]}\{y\}\{x\}} -for ordinary and partial derivatives of order \texttt{n} in one variable -\item \texttt{\textbackslash md\{f\}\{5\}\{x\}\{2\}\{y\}\{3\}} for a 5th order -mixed partial derivative -\item \texttt{\textbackslash tmd}, \texttt{\textbackslash dmd} and similar -commands for forcing text and display styles -\end{itemize} -\item \texttt{esdiff} -\begin{itemize} -\item \texttt{\textbackslash diff{[}n{]}\{y\}\{x\}}\textbf{ }and \texttt{\textbackslash diffp{[}n{]}\{y\}\{x\}}\textbf{ -}for ordinary and partial derivatives of order \texttt{n} in one variable -\item \texttt{\textbackslash diffp\{f\}\{\{x\textasciicircum 2\}\{y\}\{z\textasciicircum 3\}\}} -for a mixed partial derivative of order 6 in three variables -\item \texttt{\textbackslash diff{*}{[}n{]}\{y\}\{x\}\{0\}} for indicating the -point of evaluation of the derivative (using a subscript on parentheses) -\item \texttt{\textbackslash diffp{*}\{P\}\{T\}\{V\}} to indicate a variable -held constant -\end{itemize} -\item \texttt{physymb} -\begin{itemize} -\item \texttt{\textbackslash ud\{y\}\{x\}} and \texttt{\textbackslash pd\{y\}\{x\}} -for ordinary and partial derivatives of first order -\item \texttt{\textbackslash udd\{y\}\{x\}}, \texttt{\textbackslash uddd\{y\}\{x\}} -and \texttt{\textbackslash pdd\{y\}\{x\}}, \texttt{\textbackslash pddd\{y\}\{x\}} -for second and third order ordinary and partial derivatives -\item higher order derivatives not catered for -\end{itemize} -\end{itemize} -None of the packages quite gave what I wanted (but for all that, I suspect -cope with well over 90\% of use cases). \texttt{esdiff} comes closest but -failed when it came to combining algebraic and numeric orders of differentation -in a mixed partial derivative. Also the need to em-brace variables in a -mixed partial derivative in \texttt{esdiff}\textbf{ }was another (small) -count against it. - -\subsection{diffcoeff.sty} -\begin{itemize} -\item The distinctive feature of \texttt{diffcoeff.sty} is that it will automatically -form the overall order of a mixed partial derivative, including those containing -both algebraic and numeric contributions to the order: -\end{itemize} +~~~~op-order-sep~=~0~mu + +~~\} +\end{lyxcode} +% +\end{minipage} +\end{lyxcode} +Apart from the key = value settings, the critical feature here is the name, +\texttt{up} (which is at your discretion and could equally be \texttt{upright} +or \texttt{roman} or even \texttt{Fred} if you so fancied). This ensures +that the changed settings apply only to this particular variant and do +not `infect' the overall defaults. To use this variant, all that is needed +is to add the name, between dots, to the \texttt{\textbackslash diff} +command: \begin{example} -\textbackslash diffp{[}m-k-1,m+k{]}\{F(x,y,z)\}\{x,y,z\} $\Longrightarrow{\displaystyle \diffp[m-k-1,m+k]{F(x,y,z)}{x,y,z}}.$ +\textbackslash diff.up.yx $\Longrightarrow\quad{\displaystyle \diff.up.yx}.$ \end{example} -\begin{itemize} -\item Ease of use was another major consideration, trying to avoid the unnecessary -writing of superscripts and subscripts and brace pairs. In this example, -no superscripts are written and only the two inescapable brace pairs are -required. -\begin{itemize} -\item The use of a comma list for the second mandatory argument in a partial -derivative is another example. That makes differentiations in super- or -subscripted symbols easier to both write and read by avoiding `entanglements' -of braces. -\end{itemize} -\item I've also tried to make the options `natural' and consistent across both -ordinary and partial derivatives. Looking at the other packages listed -above, writing something like \texttt{\textbackslash diff{[}n{]}\{f\}\{x\}} -(which can be trimmed to \texttt{\textbackslash diff{[}n{]}fx} in this -instance) seems `natural' \textendash{} only \texttt{physymb} deviates -from the pattern. It seems consistent with this pattern to use a comma -list as an optional argument for mixed partial derivatives. -\item I debated whether to include provision for points of evaluation and variables -held constant into the \texttt{\textbackslash diff} and \texttt{\textbackslash diffp} -commands. \texttt{esdiff} certainly allows this. I think a case can be -made, in subjects like thermodynamics, to consider the parentheses and -subscript as part of the overall symbol. The partial derivative itself -doesn't give the full story; it is ambiguous. Hence provision for these -extra elements was included in \texttt{\textbackslash diff} and \texttt{\textbackslash diffp}. -It's positioning as a final optional argument also felt natural given the -position of the resulting symbol in the displayed derivative: -\end{itemize} +\noindent Each variant derivative inherits all the default values that +it does not explicitly countermand. Thus a point of evaluation is indicated +by a vertical rule which is the \texttt{diffcoeff} default\footnote{\noindent But not the ISO recommendation.}: \begin{example} -\textbackslash diffp ST\{V\} $\Longrightarrow\quad{\displaystyle \diffp ST{V}}$ +\textbackslash diff.up.{*}\{\textbackslash frac\{F(x)\}\{G(x)\}\}x{[}x=1{]} +$\Longrightarrow\quad{\displaystyle \diff.up.*{\frac{F(x)}{G(x)}}x[x=1]}$ \end{example} -\begin{itemize} -\item Although initially I used standard square brackets for this trailing optional -argument, the possibility of an immediately following mathematical expression -being enclosed in square brackets convinced me to use braces for the argument. -An immediately following expression can now be enclosed in \texttt{{[} -{]}}, or \texttt{\textbackslash\{ \textbackslash\}}, without ambiguity. -\item The star option also prompted the reflection: is it needed? One can always -leave the first mandatory argument empty and append the differentiand `by -hand'. But once the provision for points of evaluation or variables held -constant was incorporated into the \texttt{\textbackslash diff} and \texttt{\textbackslash diffp} -commands, the star option became the simplest way of handling appended -differentiands using the extra provision. (Note that it conflicts with -the star option in \texttt{esdiff}, but I can't see the packages ever being -used together.) And once the option is available, it provides a simple -way to switch between differentiand in the numerator/differentiand appended. -\item The final option added to the package was the slash option. This was prompted -after seeing the expression $\diff*{[\log f(z)]}/z$ in a text on statistical -mechanics. Alerted to the form, I then skimmed through various texts and -found this form of the derivative was used sufficiently often to justify -inclusion. The placement of the slash, between the two mandatory arguments, -seemed more-or-less self-evident. -\end{itemize} +\noindent Dot-delimited arguments must always be the \emph{first} argument +of the \texttt{\textbackslash diff} command, even preceding an asterisk +(star) as in this example. -\subsection{The mixed partial derivatives algorithm} - -It occurred to me, after I had created an algorithm for splitting a linear -expression composed of signs, integers and variables into its numerical -and algebraic parts, that the same algorithm could be used in a recursive -way to simplify the algebraic part of the expression. - -Given an order specification like, say, \textbf{\strong{\textbf{{[}2m+k\textendash 1,2m\textendash k+1,2k,1{]}}}}, -the idea is to concatenate the terms with intervening \textbf{+} signs, -thus \textbf{\strong{\textbf{2m+k\textendash 1+2m\textendash k+1+ 2k+1}}}, -then split this expression into numeric and algebraic parts, giving \textbf{\strong{\textbf{\textendash 1+ 1+1}}} -for the numeric part and \textbf{\strong{\textbf{2m+k+2m\textendash k+2k}}} -for the algebraic part. The numeric part, assumed to be a combination of -integers, is evaluated and the result stored. For the algebraic part, remove -throughout all instances of one of the variables, say \textbf{\strong{\textbf{m}}}. -The result is \textbf{\strong{\textbf{2+k+2\textendash k+2k}}}. Split -this into numeric and algebraic parts: \textbf{\strong{\textbf{2+2}}} -for the numeric part and \textbf{\strong{\textbf{k\textendash k+2k}}} -for the algebraic part. Evaluate the numeric part, \textbf{\strong{\textbf{+4}}}, -and you have the overall coefficient of the variable \textbf{\strong{\textbf{m}}}. -Repeat the process for the next variable, and so on until all variables -have been accounted for. - -In fact repeating the process for the next variable, \strong{k} in this -example, immediately reveals a problem. Removing \strong{k} from \textbf{\strong{\textbf{k\textendash k+2k}}} -leaves \strong{\textendash +2} which evaluates to \strong{\textendash 2} -whereas the correct coefficient for \strong{k} should be \strong{+2}. -The solution is to insert \strong{1} before any `bare' variable \textendash{} -a variable preceded only by a sign rather than a number. In that case the -expression we remove \strong{k} from is \strong{1k\textendash 1k+2k} -giving the correct overall coefficient \strong{+2}. - -A second problem may arise if there are terms involving products of variables -as in the order specification \strong{{[}mk\textendash 2,2m+1,2k+1{]}}. -This splits into a numeric part \strong{\textendash 2+1+1} evaluating -to \strong{0}, and an algebraic part \strong{mk+2m+2k}. If we choose -\strong{m} as the first variable to remove from this expression, we get -\strong{+2} for the numeric part (and hence the overall coefficient of -\strong{m}) and \strong{k+2k} for the algebraic part, which is wrong, -since that will lead to the wrong overall coefficient \strong{+3} for -\strong{k}, and the 2-variable term \strong{mk} will not get treated -at all. The cure is to treat \strong{mk} as a variable itself, count the -number of tokens in each such product and start the removal process with -the largest. - -\subsubsection{The splitting algorithm} - -Write $s$ for a sign, one of \strong{+}, \strong{\textendash{}}, and -\strong{s} for the state of assembling a signed term; a signed term is -a string of one or more signs. Write $d$ for a digit, one of 0123456789, -and \strong{n} for the state of assembling a numeric term; a numeric term -is a signed term followed by a string of one or more digits. Write $v$ -for a variable, usually a letter from the roman alphabet but in principle -any single token that is not a sign or a digit, and \strong{a} for the -state of assembling an algebraic term; an algebraic term is a numeric term -followed by a string of one or more variables. Rather than referring to -a signed-term-assembling state, we shall (obviously) simply refer to a -\emph{signed state}, and similarly to a \emph{numeric state} and an \emph{algebraic -state}. - -\begin{table} -\noindent \centering{}\caption{\label{tab:Input-output-states}State transitions} -\medskip{} -\begin{tabular}{ccccc} -\cmidrule{2-5} - & Curr. state & Curr. token & Action & Next state\tabularnewline -\cmidrule{2-5} -1 & \strong{s} & $s$ & $Ts\to s'$; $T=s'$ & \strong{s}\tabularnewline -\cmidrule{2-5} -2 & \strong{s} & $d$ & $Td$ & \strong{n}\tabularnewline -\cmidrule{2-5} -3 & \strong{s} & $v$ & $Vv$; $T1v$ & \strong{a}\tabularnewline -\cmidrule{2-5} -4 & \strong{n} & $s$ & $\mathbf{N}T$; $T=s$ & \strong{s}\tabularnewline -\cmidrule{2-5} -5 & \strong{n} & $d$ & $Td$ & \strong{n}\tabularnewline -\cmidrule{2-5} -6 & \strong{n} & $v$ & $Vv$; $Tv$ & \strong{a}\tabularnewline -\cmidrule{2-5} -7 & \strong{a} & $s$ & $\mathbf{V}V,$; $V=\textrm{Ø}$; $\mathbf{A}T$; $T=s$ & \strong{s}\tabularnewline -\cmidrule{2-5} -8 & \strong{a} & $d$ & error & \strong{!!}\tabularnewline -\cmidrule{2-5} -9 & \strong{a} & $v$ & $Vv$; $Tv$ & \strong{a}\tabularnewline -\cmidrule{2-5} -\end{tabular} -\end{table} -We also want to record the variables in the extended sense of products -of same. Call a one-token variable a prime variable. Then in this desired -sense, a variable is a string of one or more prime variables. - -Let $\mathbf{E}$ be the initial expression. Let $\mathbf{A}$ be a container -for the algebraic part of $\mathbf{E}$; let $\mathbf{N}$ be a container -for the numeric part of $\mathbf{E}$; and let $\mathbf{V}$ be a container -for the extended variables in $\mathbf{E}$. Let $T$ be a container in -which to accumulate the current term, and $V$ a container in which to -accumulate the current extended variable (if any). Initially all these -containers are empty ($\textrm{Ø}$). - -We work through $\mathbf{E}$ token by token from the left. The table shows -the alternatives. -\begin{itemize} -\item Row 1. The current token is a sign $s$ and the system is in a signed state -\strong{s}. We append $s$ to the current term, $Ts$, then resolve the -juxtaposition of signs according to the familiar rules: $++\to+$, $--\to+$, -$+-\to-$, $-+\to-$, so that $T$ contains only the resolved sign $s'$. -The system remains in a signed state. -\item Row 2. The current token is a digit $d$ and the system is in a signed- -state \strong{s}. We append $d$ to the current term, $Td$ (which will -now consist of a sign and a digit), and the system shifts to a numeric -state \strong{n}. -\item Row 3. The current token is a prime variable $v$ and the system is in -a signed state \strong{s}. We start assembling an extended variable, -$Vv$, and append $1v$ to the current term, $T1v$, where the $1$ is -necessary as discussed earlier (and in any case `sign variable' is not -a recognised \emph{term} \textendash{} neither signed, numeric or algebraic). -The system shifts to an algebraic state \strong{a}. -\item Row 4. The current token is a sign $s$ and the system is in a numeric -state \strong{n}. The current term is a numeric term, a sign followed -by at least one digit, and is complete. We append it to the numeric part -$\mathbf{N}$ of $\mathbf{E}$, $\mathbf{N}T$, then initialise $T$ to -$s$. The system shifts to a signed state. -\item Row 5. The current token is a digit $d$ and the system is in a numeric -state \strong{n}. We append $d$ to the current term, $Td$, and remain -in a numeric state. -\item Row 6. The current token is a prime variable $v$ and the system is in -a numeric state \strong{n}. We start assembling a variable, $Vv$, and -also append $v$ to the current term, $Tv$. The system shifts to an algebraic -state \strong{a}. -\item Row 7. The current token is a sign $s$ and the system is in an algebraic -state \strong{a}. The current term is an algebraic term, a sign followed -by at least one digit followed by at least one prime variable, and is complete. -We append it to the algebraic part $\mathbf{A}$ of $\mathbf{E}$, $\mathbf{A}T$, -then initialise $T$ to $s$. We also append $V$, in which we have been -accumulating the (extended) variable, to $\mathbf{V}$, $\mathbf{V}V,$, -then empty $V$ in preparation for the next (extended) variable. Attention -is drawn to the comma following $V$ also appended to $\mathbf{V}$, so -that we can distinguish where one variable ends and the next begins. The -system shifts to a signed state. -\item Row 8. The current token is a digit $d$ and the system is in an algebraic -state \strong{a}. This situation should not arise.\emph{ }We don't write -$k2$; we write $2k$ \textendash{} number precedes variable. An error -is generated. -\item Row 9. The current token is a variable $v$ and the system is in an algebraic -state \strong{a}. We append $v$ to the current extended variable, $Vv$, -and also append $v$ to the current term, $Tv$. The system remains in -an algebraic state \strong{a}. -\end{itemize} -To get things under way, an initial plus sign is put in $T$, $T=+$, and -the system is set to the signed state \strong{s}. In order that \emph{all} -terms of $\mathbf{E}$ are recorded in either $\mathbf{N}$ or $\mathbf{A}$, -and all extended variables in $\mathbf{V}$, we append a plus sign to $\mathbf{E}$: -$\mathbf{E}+$. Since an expression doesn't end with a trailing sign (we -don't write, e.g., \textbf{\strong{\textbf{2m+k\textendash{}}}}), the -process necessarily terminates either in row 4 or row 7 with the final -term appended either to $\mathbf{N}$ or $\mathbf{A}$ and with $T=+$; -if it terminates in row 7, the final extended variable is appended to $\mathbf{V}$, -$\mathbf{V}V$ (and $V$ is emptied, although that hardly matters at this -point). - -\subsubsection{An enlarged scheme?} - -Row 8 of our table generates an error: a digit following a variable. But -having allowed products of variables like \texttt{mn} ($mn$), it is very -tempting to allow \texttt{mm}, i.e. \texttt{m\textasciicircum 2} ($m^{2}$) -and, indeed, \texttt{m\textasciicircum n} ($m^{n}$). And if we allow -\texttt{m\textasciicircum 2} and \texttt{m\textasciicircum n}, how can -we say no to subscripted forms like \texttt{k\_2} ($k_{2}$) and \texttt{k\_n} -($k_{n}$)? Or, for that matter, \texttt{k\_+} ($k_{+}$) and \texttt{k\_-} -($k_{-}$), and therefore \texttt{m\textasciicircum +} ($m^{+}$) and -\texttt{m\textasciicircum -} ($m^{-}$)? And having extended the scheme -in this way to exponents of \emph{variables}, surely it should also encompass -exponents of \emph{numbers}, not only an obvious case like \texttt{2\textasciicircum 2} -($2^{2}$) but less obviously, yet still compellingly, \texttt{2\textasciicircum n} -($2^{n}$)? - -Each of these extensions produces its own problems, but they can all be -accommodated within an enlarged scheme, as can the use of parentheses (with -numerical coefficients). Table~\ref{tab:Input-output-states} translates -neatly into code. Rather than add these complications to \texttt{diffcoeff.sty}, -I have transferred the enlarged scheme to \texttt{diffcoeff.sty}'s `big -brother', \texttt{diffcoeffx.sty}. The comparable table and routine resulting -from it in \texttt{diffcoeffx.sty} is much bigger and less obvious than -in \texttt{diffcoeff.sty}. - -\subsubsection{Some code details} - -In the code, the states are distinguished by integers as indicated in Table~\ref{tab:State-integers}. -Tokens are assigned similar integer indexes, as indicated in the table. -The relevant routine is \texttt{\textbackslash\_\_diffco\_get\_curr\_index:NN}. -The actions embodied in Table~\ref{tab:Input-output-states} are encoded -in \texttt{\textbackslash\_\_diffco\_compare\_states:NNNNN} which is -a direct translation of the table into expl3 code. - -\begin{table}[h] -\caption{Some code details} - -\noindent \centering{}\subfloat[\label{tab:State-integers}State integers]{\centering{}% -\begin{tabular}{|c|c|c|} -\hline -State & Index & Tokens\tabularnewline -\hline -\hline -signed & 0 & $+$ $-$\tabularnewline -\hline -numeric & 1 & 0123456789\tabularnewline -\hline -algebraic & 2 & variables\tabularnewline -\hline -\end{tabular}}~~~\subfloat[Translations]{ -\centering{}% -\begin{tabular}{|c|c|} -\hline -Symbol & Code variable\tabularnewline -\hline -\hline -$s$,$d$,$v$ & \texttt{\textbackslash l\_\_diffco\_curr\_tok\_tl}\tabularnewline -\hline -$T$ & \texttt{\textbackslash l\_\_diffco\_curr\_term\_tl}\tabularnewline -\hline -$V$ & \texttt{\textbackslash l\_\_diffco\_curr\_var\_tl}\tabularnewline -\hline -$\mathbf{N}$ & \texttt{\textbackslash l\_\_diffco\_nos\_tl}\tabularnewline -\hline -$\mathbf{A}$ & \texttt{\textbackslash l\_\_diffco\_alg\_tl}\tabularnewline -\hline -$\mathbf{V}$ & \texttt{\textbackslash l\_\_diffco\_vars\_prop}\tabularnewline -\hline -\end{tabular}} -\end{table} -A property list is used to store the variables, organised by size \textendash{} -the number of tokens composing an extended variable. This enables the sorting -by size needed for the determination of the overall coefficients of variables -by removing them in turn from the algebraic part of the expression. That -process is conducted in the routine \texttt{\textbackslash\_\_diffco\_eval\_vars:NN}. -The variables are recorded only on the first scan through the order specification -expression. This is the function of the boolean \texttt{\textbackslash l\_\_diffco\_vars\_noted\_bool} -which is set in \texttt{\textbackslash\_\_diffco\_eval\_vars:NN}. Evaluation -of the numeric parts of expressions is provided by \texttt{\textbackslash\_\_diffco\_eval\_nos:N}. - -\section{Summary of main commands} - -\subsubsection{Ordinary derivatives} - -The syntax is +As another example, suppose for the subscripted indication of variables +held constant in a partial derivative that you want to see what things +look like if the subscript is \emph{not }nudged in towards the right parenthesis. +In that case define a variant form +\begin{lyxcode} +\textbackslash diffdef~\{~padrift~\}~\{~subscr-nudge~=~0~mu~\} +\end{lyxcode} +I have attached a name, \texttt{padrift},\texttt{ }to this setting, \begin{example} -{\small{}\textbackslash diff{[}order{]}\{differentiand\}\{variable\}\{point -of evaluation\}}{\small\par} +\textbackslash diff.padrift.Fx{[}y{]} $\Longrightarrow{\displaystyle \diff.padrift.Fx[y]}$ \end{example} -for the differentiand in the numerator, and where the final argument, although -using braces, is an \emph{optional} argument. A starred form appends the -differentiand: +\noindent since, to my eye, the subscript seems detached from the expression +it qualifies and `adrift in a sea of whitespace'. Is it perhaps a typo? +This is to be compared with the default \begin{example} -{\small{}\textbackslash diff{*}{[}order{]}\{differentiand\}\{variable\}\{point -of evaluation\}}{\small\par} +\textbackslash diffpFx{[}y{]} $\Longrightarrow{\displaystyle \diffp Fx[y]}$ \end{example} -No space must occur between the final optional argument, if it is used, -and the second mandatory argument. +\noindent where the subscript is tucked in close to the right parenthesis +and is clearly connected to it and the expression it delimits. -There are also slash forms of both these commands: +Some might want to distinguish notationally a point of evaluation for a +partial derivative from variables held constant, perhaps using a vertical +rule for the former and (the default) parentheses for the latter. It would +suffice then to add to the preamble +\begin{lyxcode} +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{~pvrule~\}~\{~op-symbol~=~\textbackslash partial~\}~ +\end{lyxcode} +% +\end{minipage} +\end{lyxcode} +(or some other name of your choosing). This gives \begin{example} -{\small{}\textbackslash diff{[}order{]}\{differentiand\}/\{variable\}\{point -of evaluation\}}{\small\par} - -{\small{}\textbackslash diff{*}{[}order{]}\{differentiand\}/\{variable\}\{point -of evaluation\}}{\small\par} +\textbackslash diff.pvrule.\{F(x,y)\}x{[}x=1{]}$\Longrightarrow{\displaystyle \diff.pvrule.{F(x,y)}x[x=1]}$ \end{example} -For the starred form, the differential coefficient is enclosed in parentheses. -Precisely similar definitions, but without the slash forms, apply to \texttt{\textbackslash Diff}, -forming a differential coefficient with $D$, \texttt{\textbackslash diffd}, -forming a differential coefficient with $\delta$, and \texttt{\textbackslash Diffd}, -forming a differential coefficient with $\Delta$. +\subsubsection{Text-style and script-style derivatives\label{subsec:Text-and-script-style}} -\subsubsection{Partial derivatives} +As noted earlier, the \texttt{diffcoeff} package assumes that derivatives +of fraction-like form will be used in display-style expressions and that +the slash form will be used for inline use (text style). This is the usual +practice. But if one does want to use the fraction form in an inline expression, +say \texttt{\textbackslash diffp ST{[}V{]}} displaying as $\diffp ST[V]$, +then some tweaking of settings is necessary: the subscript is obviously +too close to the right parenthesis and, to my eye, there is too much `elbowroom' +between the derivative and the enclosing parentheses: -The syntax is -\begin{example} -{\small{}\textbackslash diffp{[}order spec.{]}{[}order override{]}\{differentiand\}\{variables\}\{constant -variables\}}{\small\par} -\end{example} +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{~ptxt~\}~ + +~~\{ + +~~~~op-symbol~~~~~~=~\textbackslash partial, + +~~~~denom-term-sep~=~1~mu~~~~, -for the differentiand in the numerator and where the final argument, although -in braces, is an \emph{optional} argument. No space must occur between -the final optional argument, if it is used, and the second mandatory argument. -The \textbf{\strong{\textbf{order spec.}}} is a comma-separated list; -the \strong{variables} is also a comma-separated list. A starred form -appends the differentiand: +~~~~left-delim~~~~~=~\textbackslash left~(~, + +~~~~right-delim~~~~=~\textbackslash right~), + +~~~~elbowroom~~~~~~=~-2~mu~~~, + +~~~~subscr-nudge~~~=~-3~mu~~~ + +~~\} +\end{lyxcode} +% +\end{minipage} + +This gives, for the same example, \texttt{\textbackslash diff.ptxt.ST{[}V{]}} +displaying as $\diff.ptxt.ST[V]$, where the subscript is better positioned +and there is a better fit between parentheses and derivative. For a mixed +partial derivative, \texttt{\textbackslash diff.ptxt.\{F(x,y,z)\}\{x,y\}{[}z{]}} +displays now as $\diff.ptxt.{F(x,y,z)}{x,y}[z]$. + +\subsubsection{Derivatives from D, \textbackslash delta, \textbackslash Delta\label{subsec:D-delta-Delta}} + +In addition to \texttt{\textbackslash diff.p.},\texttt{ diffcoeff} has +three further \emph{built-in} variant forms that are commonly used: \texttt{\textbackslash diff.D.}, +\texttt{\textbackslash diff.delta.}, and \texttt{\textbackslash diff.Delta.}, +corresponding to derivatives formed from $D$, $\delta$ and $\Delta$ +respectively. + +In fluid dynamics the \emph{material }or \emph{substantive} derivative +uses an uppercase $D$ in place of $d$. For example, the continuity equation +is, \begin{example} -{\small{}\textbackslash diffp{*}{[}order{]}{[}order~override{]}\{differentiand\}\{variables\}\{constant -variables\}}{\small\par} +\textbackslash diff.D.\{\textbackslash rho\}t=\textbackslash diffp\textbackslash rho +t + \textbackslash mathbf\{u\textbackslash cdot\}\textbackslash nabla\textbackslash rho +$\Longrightarrow{\displaystyle \diff.D.\rho t=\diffp\rho t+\mathbf{u\cdot}\nabla\rho}$ \end{example} -Slash forms exist also for these commands: -\begin{example} -{\small{}\textbackslash diffp{[}order spec.{]}{[}order override{]}\{differentiand\}/\{variables\}\{constant -variables\}}{\small\par} +\noindent where \texttt{\textbackslash diff.D.} produces the D-derivative. +If you want upright `D's, then the \texttt{ISO} package option will produce +that effect. Alternatively, \vspace{-2ex} + +\begin{lyxcode} +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{~Up~\}~ + +~~\{ -{\small{}\textbackslash diffp{*}{[}order{]}{[}order~override{]}\{differentiand\}/\{variables\}\{constant -variables\}}{\small\par} +~~~~op-symbol~~~~=~\textbackslash mathrm\{D\}, + +~~~~op-order-sep~=~0~mu + +~~\} +\end{lyxcode} +% +\end{minipage} +\end{lyxcode} +\noindent provides a variant with upright `D's. + +In introductory calculus texts the simple $\delta$-derivative is used. +This is achieved with the \texttt{\textbackslash diff.delta.} command +\begin{example} +\textbackslash diff.delta.yx $\Longrightarrow{\displaystyle \diff.delta.yx}.$ \end{example} -For the starred version of the slash form, the differential coefficient -is enclosed in parentheses. +\noindent This form also features in analytical mechanics (in the Rogues' +Gallery, the final example at (\ref{eq:eg6})). -\subsubsection{Settings} +Similarly, \texttt{\textbackslash diff.Delta.} forms a derivative from +$\Delta$: \begin{example} -\textbackslash diffset{[}option1=,option2=,...{]} +\textbackslash diff.Delta.y/x $\Longrightarrow{\displaystyle \diff.Delta.y/x,}$ \end{example} -All numerical values should be integers (\texttt{diffcoeff} interprets -this in units of mu, 1/18 of an em). To return all options to default values, -write +\noindent where the slash form of the derivative is shown in this instance. + +Higher order forms of these derivatives, points of evaluation, appending +the differentiand with a star argument, all follow exactly as for the `pure' +\texttt{\textbackslash diff} command. + +\paragraph{The commands \textbackslash Diff, \textbackslash diffd, \textbackslash Diffd} + +For compatibility with version 1 of \texttt{diffcoeff}, the commands \texttt{\textbackslash Diff}, +\texttt{\textbackslash diffd} and \texttt{\textbackslash Diffd} are available +and also produce the $D$, $\delta$ and $\Delta$ derivatives. Just as +\texttt{\textbackslash diffp} is identified with \texttt{\textbackslash diff.p.} +for partial derivatives, these commands are identified with \texttt{\textbackslash diff.D.}, +\texttt{\textbackslash diff.delta.}, and \texttt{\textbackslash diff.Delta} +through commands equivalent to\footnote{In fact the actual commands in \texttt{diffcoeff.sty} use the syntax of +the \texttt{xparse} package, e.g. \texttt{\textbackslash NewDocumentCommand +\{ \textbackslash Diff \} \{ \} \{ }\textbackslash diff.D. \}, and similarly +for the others.} +\begin{lyxcode} +\textbackslash newcommand\{\textbackslash Diff\}\{\textbackslash diff.D.\} + +\textbackslash newcommand\{\textbackslash diffd\}\{\textbackslash diff.delta.\} + +\textbackslash newcommand\{\textbackslash Diffd\}\{\textbackslash diff.Delta.\} +\end{lyxcode} +Unless one is using such variant forms frequently, it seems simpler to +remember that they are available as dot-delimited arguments to the \texttt{\textbackslash diff} +command, using the obvious name in each case, rather than having to remember +the precise camel-case form of name of the \texttt{\textbackslash Diff}, +\texttt{\textbackslash diffd} and \texttt{\textbackslash Diffd} commands. + +\subsection{The \texttt{.def} file\label{subsec:The-.def-file}} + +This mechanism of variant formation is how I have been able to illustrate +in the Rogues' Gallery, Section~\ref{sec:Rogues'-gallery}, the wide variety +of different usages culled from the literature. But the thought arises: +if a variant is to be used only once or twice, isn't this a lot of bother? +Why not just construct the variant derivative `by hand' out of \texttt{\textbackslash frac} +and \texttt{\textbackslash mkern} for example? The reason for making such +definitions is that they can be transferred from document to document. +For instance, definitions placed in the preamble can be copied to the preamble +of another document. + +But that is hardly optimal. Instead, \texttt{diffcoeff} allows such definitions +to be placed in a text file with the the extension \texttt{.def} and a +name of your choosing. For the present document the file is called \texttt{diffcoeff-doc.def} +and has been placed in the same directory as \texttt{diffcoeff.tex}. To +use these definitions, the \texttt{diffcoeff} package is called with the +command +\begin{lyxcode} +\textbackslash usepackage{[}def-file=diffcoeff-doc{]}\{diffcoeff\} +\end{lyxcode} +But even this process still means copying a definition file from directory +to directory as one works on different documents. The solution is to make +a definition file available for \emph{all} documents and the way to do +that is by placing it in the texmf tree, preferably not the one created +by your \TeX{} distribution (perhaps MiKTeX or TexLive), but your own \emph{personal} +texmf tree. + +\texttt{\vspace{2ex} +} + +\noindent % +\noindent\fbox{\begin{minipage}[t]{1\columnwidth - 2\fboxsep - 2\fboxrule}% +\textbf{Personal texmf tree? } + +This is a directory for `waifs and strays' of the \TeX{} system that are +not included in standard distributions like MiK\TeX{} or \TeX Live. For +instance, it is the place for personal packages designed for your own particular +circumstances or preferences, and is structured like the standard MiK\TeX{} +or \TeX Live hierarchy but placed in another location so that there is +no chance of its being overwritten when MiK\TeX{} or \TeX Live are updated. +However, those distributions need to be alerted to its existence. For MiK\TeX , +open the MiK\TeX{} console, click on \textsf{Settings} and then the \textsf{Directories} +tab. Click the \textsf{+} button and navigate to your personal texmf tree +to add it to the MiK\TeX{} search path. Having added it, you will then need +to refresh the filename database by clicking on the \textsf{Tasks} menu +and selecting the obvious entry. I am not familiar with \TeX Live but presume +a similar process will apply there.% +\end{minipage}} + +\medskip{} + +\noindent Provided your \LaTeX{} distribution knows about your personal +texmf tree, then a \texttt{.def} file placed within it, will be accessible +to all documents. + +\subsubsection{Structure of the \texttt{.def} file} + +The best way to see what a \texttt{.def} file looks like is to view \texttt{diffcoeff-doc.def +}in a text editor.\footnote{This file should be in the same directory as \texttt{diffcoeff.pdf} and +\texttt{diffcoeff.tex} in your \LaTeX{} distribution.} + +If you want your variant definitions to use defaults different from those +supplied with the \texttt{diffcoeff} package, then the first definition +in the \texttt{.def} file should be the one setting the new defaults, with +an \emph{empty} first argument to the \texttt{\textbackslash diffdef} +command: +\begin{lyxcode} +\noindent\begin{minipage}[t]{1\columnwidth}% +\begin{lyxcode} +\textbackslash diffdef~\{\}~~~ +\begin{lyxcode} +\{~~~~~ +\begin{lyxcode} +key-1~=~value-1,~~~~ + +key-2~=~value-2, + +... + +key-n~=~value-n +\end{lyxcode} +\} +\end{lyxcode} +\end{lyxcode} +% +\end{minipage} +\end{lyxcode} +The key-value list is a comma-separated list; hence the last entry doesn't +need to end with a comma. Nudge and separation values need to include the +unit, \texttt{mu}; a numerical value alone will result in error.\texttt{ }Because +a \texttt{.def} file\texttt{ }is a \LaTeX{} file, comments need to start +with a \texttt{\%} character. + +\subsubsection{\texttt{diffcoeff.def}} + +Note that if the \texttt{diffcoeff} package is invoked without an explicit +\texttt{def-file= } option statement, as here, +\begin{lyxcode} +\textbackslash usepackage\{diffcoeff\} +\end{lyxcode} +then it will search in the texmf tree (the \LaTeX{} distribution's and your +personal one) and the document directory for a file \texttt{diffcoeff.def} +and if found will load that. This file should contain definitions of those +variants you are likely to use in multiple documents. In my personal texmf +tree (which I've put at \texttt{D:\textbackslash texmf\textbackslash} +on a Windows machine) the file \texttt{diffcoeff.def} is located in the +directory \texttt{D:\textbackslash texmf\textbackslash tex\textbackslash latex\textbackslash diffcoeff\textbackslash}. +(The backslashes are replaced by forward slashes on linux machines.) Variants +likely to be of value only to a specific document should be added to the +preamble of that document, or they can be added to \texttt{diffcoeff.def} +and that file saved to the document directory under a \emph{different} +name \textendash{} e.g. I've saved the variants required for the present +document under the name \texttt{diffcoeff-doc.def}. Many of these variants +were created solely to illustrate points in the present document and I +have no intention of using them in my own work. Consequently my \texttt{diffcoeff.def} +file is smaller, containing only a selection from \texttt{diffcoeff-doc.def}. + +\section{Rationale} + +Version 1 of the \texttt{diffcoeff} package arose from a need to simplify +the parsing of differential coefficients for another program I was working +on which was struggling to `read' all the possible permutations of \texttt{\textbackslash frac} +or \texttt{\textbackslash tfrac} or \texttt{\textbackslash dfrac} or +slash forms of the derivative, of \texttt{d} or \texttt{\textbackslash mathrm\{d\}} +or \texttt{\textbackslash partial} or \texttt{D} or \texttt{\textbackslash mathrm\{D\}} +or \texttt{\textbackslash nabla},\texttt{ }and of points of evaluation +delimited by vertical rules or parentheses.\texttt{ }Although regular expressions +coped with most of these cases, it was \emph{messy}. + +There are other packages which have commands for the derivative (e.g., +\texttt{bropd}, \texttt{commath},\texttt{ esdiff}, \texttt{physymb}) but +none quite gave what I wanted \textendash{} although they probably cope +with most users' needs. \texttt{esdiff} came closest to what I was seeking +but failed when it came to combining algebraic and numeric orders of differentation +in a mixed partial derivative (and made heavier use of braces than I would +like in that case too). + +\subsection{\texttt{diffcoeff.sty}} + +I have tried to make using \texttt{diffcoeff} intuitive. Looking at the +other packages mentioned, writing something like \texttt{\textbackslash diff{[}n{]}\{f\}\{x\}} +(which can be trimmed to \texttt{\textbackslash diff{[}n{]}fx} for single-token +arguments) seems `natural' \textendash{} only \texttt{physymb} deviates +from the pattern. +\begin{itemize} +\item It seems consistent with this pattern to use a comma list for specifying +the orders of differentiation of the variables in a higher order mixed +partial derivative (and its suppression when all are of order 1) +\item Having specified the orders, surely the program itself should calculate +the overall order? \texttt{esdiff} does this for numerical orders; \texttt{diffcoeff} +does this for both numeric and algebraic orders, +\end{itemize} \begin{example} -\textbackslash diffset +\textbackslash diffp{[}m-(k+1),m+(k-1){]}\{F(x,y,z)\}\{x,y,z\} + +$\Longrightarrow{\displaystyle \diffp[m-(k+1),m+(k-1)]{F(x,y,z)}{x,y,z}},$ \end{example} -The options and defaults are -\begin{description} -\item [{\strong{roman = false}}] \textbf{\strong{\textbf{true}}} gives upright -(roman) \textbf{\strong{\textbf{d}}} and \textbf{\strong{\textbf{D}}} -\item [{\strong{d-delims = . |}}] delimiters which, when subscripted, indicate -the point of evaluation of an ordinary derivative -\item [{\strong{p-delims = ( )}}] delimiters which, when subscripted, indicate -variables held constant for partial derivatives -\item [{\strong{d-nudge = 0}}] adjustment for positioning the subscript to -the preceding delimiters -\item [{\strong{p-nudge = $-$6}}] adjustment for positioning the subscript -to the preceding delimiters -\item [{\strong{d-sep = 1}}] additional separation between the \textbf{$d$ -}and its superscript in the numerator of a second or higher order ordinary -derivative -\item [{\strong{p-sep = 1}}] additional separation between the \textbf{$\partial$} -and its superscript in the numerator of a second or higher order partial -derivative -\item [{\strong{sep = 2}}] additional separation between the terms in the denominator -of a mixed partial derivative -\end{description} +\begin{itemize} +\item and where it fails, either to calculate at all or to present the result +in a preferred form, offers the order-override option: +\end{itemize} +\begin{example} +\textbackslash diffp{[}m+(k+1),m+(k-1){]}{[}2(m+k+1){]}\{F(x,y,z,w)\}\{x,y,z,w\} -\subsection{Change history} +$\Longrightarrow{\displaystyle \diffp[m+(k+1),m+(k-1)][2(m+k+1)]{F(x,y,z,w)}{x,y,z,w}}.$ +\end{example} -Uploaded to CTAN 2016-06-27 +\begin{itemize} +\item I wished to avoid the unnecessary writing of superscripts, subscripts and +brace pairs. In the examples just given, no superscript tokens \texttt{\textasciicircum} +are written by the user despite the higher-order differentiation in $x$ +and $y$, and only the two inescapable brace pairs are required. +\item The use of a comma list for the second mandatory argument in a partial +derivative \textendash{} the list of variables \textendash{} makes differentiations +in super- or subscripted symbols (as occurs prolifically in tensor calculus) +easier to both write and read by avoiding unnecessary brace pairs. +\end{itemize} +\begin{example} +\textbackslash diffp\{A\_i\}\{ x\textasciicircum j,x\textasciicircum k +\} $\Longrightarrow\quad{\displaystyle \diffp{A_{i}}{x^{j},x^{k}}.}$ +\end{example} -2016-06-30 Removed the unused \texttt{extend} package option (a relic from -earlier experiments). +\begin{itemize} +\item Should a point of evaluation or variables held constant be considered part +of the derivative? Thermodynamic usage was decisive here. The partial derivative +alone is ambiguous \textendash{} the parentheses and subscript are essential +to understand what is being stated: +\[ +\diffp ST[V] +\] +Hence provision for these extra elements was included in the derivative +commands. +\item Given the position of the subscripted symbol in the displayed derivative, +it's positioning as the \emph{final} argument in the derivative commands +feels inevitable. +\item Version 1 of \texttt{diffcoeff} used braces for this argument to avoid +any possible confusion with a following mathematical expression. That use +of braces is now deprecated in \texttt{xparse}. Consequently version 2 +of \texttt{diffcoeff} uses square brackets, conforming with familiar \LaTeX{} +practice. The only special remembering needed is avoidance of a space before +the argument \textendash{} and if it does slip in, it won't cause a \LaTeX{} +error. It will be treated as part of a following mathematical expression +and displayed as such. +\item The star option also prompted the question: is it needed? After all, one +can always leave the first mandatory argument empty and append the differentiand +`by hand'. But once the provision for points of evaluation or variables +held constant was incorporated into the derivative commands, the star option +became the simplest way of handling appended differentiands since the parentheses +for a variable held constant must wrap around the differential operator +\emph{and} differentiand. Once available, it provides a simple way of switching +between (and comparing) the appearance of differentiand-in-the-numerator +and differentiand-appended. +\item The slash option was added to the derivative commands after seeing how +widely such forms are used in texts at all levels. The placement of the +slash, between the two mandatory arguments, seems more-or-less self-evident. +\item The final option added to \texttt{\textbackslash diff} (and not present +in version 1) was the dot-delimited name option. Once \texttt{xtemplate} +was used as the basis of the package this seemed the most straightforward +way of making available, ready to hand, the wealth of variants that \texttt{xtemplate} +makes possible. (It's just a pity that the second dot is needed, and a +single-dot naming scheme can't be used, but \texttt{xparse} forces my hand +here.) +\item Having added the dot-delimited name option, the use of a \texttt{.def} +file to store variants or preferred defaults is more-or-less forced, otherwise +one is faced with making these definitions anew for each new document (or +locating a previous document and copying from that to the new one). +\item To handle possible differences between display-style and text-style (and +script-style) derivatives (see Subsection~\ref{subsec:Text-and-script-style}) +I considered using \TeX 's \texttt{\textbackslash mathchoice} command. +This command takes four arguments, corresponding to display-, text-, script- +and scriptscript-styles and would require forming four derivatives each +time a derivative is used, `just in case'. In fact fraction-form derivatives +are used overwhelmingly in display-style expressions, the slash form being +used for inline use. Given the ease of defining a fraction-form variant +for text-style use, and the rareness of such use, employing variants seemed +the way to go. It is the one adopted and avoids the computational burden +associated with the use of \texttt{\textbackslash mathchoice}. +\end{itemize} -2018-10-25 v.1.1 Changed the handling of error messages. \end{document} -- cgit v1.2.3