backnaur (29jun19)

git-svn-id: svn://tug.org/texlive/trunk@51505 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 172 insertions, 61 deletions

diff --git a/Master/texmf-dist/doc/latex/backnaur/backnaur.pdf b/Master/texmf-dist/doc/latex/backnaur/backnaur.pdf
index 1e102939dc2..88a03028331 100644
--- a/Master/texmf-dist/doc/latex/backnaur/backnaur.pdf
+++ b/Master/texmf-dist/doc/latex/backnaur/backnaur.pdf
diff --git a/Master/texmf-dist/source/latex/backnaur/backnaur.dtx b/Master/texmf-dist/source/latex/backnaur/backnaur.dtx
index 0a9554899ea..14a9264b4f6 100644
--- a/Master/texmf-dist/source/latex/backnaur/backnaur.dtx
+++ b/Master/texmf-dist/source/latex/backnaur/backnaur.dtx
@@ -1,7 +1,7 @@
 % \iffalse meta-comment
 %
 % backnaur.dtx
-% 14 April 2019
+% 7 June 2019
 %
 %    Documented LaTeX file for the backnaur package.
 %
@@ -34,7 +34,7 @@
 % \iffalse
 %<package>\NeedsTeXFormat{LaTeX2e}[2011/06/27]
 %<package>\ProvidesPackage{backnaur}
-%<package>[2019/04/14 2.0 Typesetting for Backus-Naur Form (BNF) definitions]
+%<package>[2019/06/18 3.1 Typesetting for Backus-Naur Form (BNF) definitions]
 %<*driver>
 \documentclass[10pt,a4paper]{ltxdoc}
 \usepackage{backnaur}
@@ -66,12 +66,19 @@
 %^^A 3 December 2012
 %^^A Add tstt option and generally rewrite documentation.
 %    \changes{v1.1}{2012/12/12}
-%            {Improved documentation.}
+%            {Updated and improved documentation.}
+%
+%^^A
+%^^A 7 June 2019
+%^^A Remove tstt option, add line number management, add altpo option 
+%^^A and updated and improve documentation.
+%    \changes{v3.0}{2019/06/07}
+%            {Updated and improved documentation.}
 %
 %^^A-------------------------------------------------------------------
 % 
-%^^A \CheckSum{0} %^^A no checksum for development
-% \CheckSum{62}
+% \CheckSum{0} %^^A no checksum for development
+%^^A \CheckSum{80}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -93,7 +100,7 @@
 %
 % \title{The \texttt{backnaur} package}
 % \author{Adrian P. Robson\thanks{\texttt{adrian.robson@nepsweb.co.uk}}}
-% \date{Version 2.0\\[0.5ex]14 April 2019}
+% \date{Version 3.1\\[0.5ex]18 June 2019}
 %
 % \maketitle
 %
@@ -180,19 +187,21 @@
 % |perp|   \>The empty string symbol is $\perp$\\
 % |epsilon| \>  The empty string symbol is $\epsilon$\\
 % |tsrm| \>  Terminal string typeface is roman\\
-% |tstt| \>  Terminal string typeface is typewriter (default)
+% |altpo| \> Production operator is $::=$
+%^^A |tstt| \>  Terminal string typeface is typewriter (default)
 % \end{tabbing}
 % \vspace{-1ex}
 %
 % \noindent
 % The defaults are: the empty string symbol is $\lambda$, 
+% the production operator is $\models$,
 % and the terminal string typeface is typewriter.
 % 
 % \subsection{Environments}
 %
 % \DescribeEnv{bnf} 
 % BNF productions are defined in a |bnf| or |bnf*| environment, 
-% which respectively  give numbered and unnumbered lists of productions.
+% which respectively  give numbered or unnumbered lists of productions.
 % \DescribeEnv{bnf*}
 % \begin{quote}
 % \begin{minipage}{0.5\linewidth}
@@ -210,15 +219,25 @@
 % \subsection{Productions}
 %
 % \DescribeMacro{\bnfprod}
-% A production is defined by |\bnfprod|, which takes two arguments: 
+% \DescribeMacro{\bnfprod*}
+% A production is defined by |\bnfprod| or |\bnfprod*|, 
+% which respectively give a numbered or unnumbered line in the {\tt bnf} environment.
+% They have identical unnumbered behaviour in the {\tt bnf*} enviromment.
+% They take two arguments:
 % \begin{quote}
-%   |\bnfprod{|<production name>|}{|<production definition>|}|
+%   |\bnfprod{|<production name>|}{|<production definition>|}|\\
+%   |\bnfprod*{|<production name>|}{|<production definition>|}|
 % \end{quote}	
 %
 % \DescribeMacro{\bnfmore}
-% A production can be continued on addition lines by |\bnfmore|, which takes one argument: 
+% \DescribeMacro{\bnfmore*}
+% A production can be continued on addition lines by |\bnfmore| or |\bnfmore*|, 
+% which respectively give a numbered or unnumbered line in the {\tt bnf} environment.
+% They are treated the same in the {\tt bnf*} environment.
+% They take one arguments:
 % \begin{quote}
-%   |\bnfmore{|<production definition>|}|
+%   |\bnfmore{|<production definition>|}|\\
+%   |\bnfmore*{|<production definition>|}|
 % \end{quote}	
 %
 % \subsection{Production definitions}\label{prodef}
@@ -247,7 +266,8 @@
 % The |\bnftd| command generates a descriptive phrase, as an alternative to a literal string.  
 % \DescribeMacro{\bnfes}
 % The |\bnfes| command generates a token that represents the empty string. 
-% This is normally $\bnfes$, but it can be changed as a package option (see \S\ref{packopts}).
+% This is normally $\bnfes$, but it can be changed to $\epsilon$ or $\perp$ as a package option 
+% (see \S\ref{packopts}).
 % \begin{quote}
 % \begin{minipage}{0.6\linewidth}
 %   |\bnfts{terminal}|\\
@@ -276,7 +296,7 @@
 % \end{quote}
 %
 % \DescribeMacro{\bnfor}
-% All items are separated by an OR or a space. 
+% All items should be separated by an OR or a space. 
 % The |\bnfor| command generates the OR symbol, and the |\bnfsp| command introduces a space.
 % \DescribeMacro{\bnfsp} 
 % A space can be considered equivalent to an AND operator.
@@ -292,15 +312,16 @@
 % \end{quote}
 %
 % \subsection{Inline expressions}
-%
+% The |\bnfprod| and |\bnfmore| macros cannot be used inline, so the |\bnfpn| and |\bnfpo| macros
+%   are provided to support typeseting productions  inline using maths mode.
 % \DescribeMacro{\bnfpn}
-% The package's definition commands can be typeset inline using maths mode, 
-% so the expression |$\bnfpn{name}$| will give $\bnfpn{name}$.
-%
 % \DescribeMacro{\bnfpo}
-% The |\bnfpo| command is provided so that the production operator $\bnfpo$ 
-% can be printed independently from the |bnf| environment if required.
-% The |\bnfprod| command cannot be used inline.
+% The production's name can be typeset with |\bnfpn{name}| and the production operator with
+% |\bnfpo|.
+% By default the production operator is $\bnfpo$, but it can be changed to $::=$ with 
+% a package option (see \S\ref{packopts}).
+% The right side of the production can be defined with the usual macros (see \S\ref{prodef}). 
+% So |$\bnfpn{name} \bnfpo \bnftd{description}$| gives $\bnfpn{name} \bnfpo \bnftd{description}$.
 %
 % \subsection{Command summary}
 %
@@ -312,13 +333,15 @@
 % \hline
 % Command         & Operator             & Outcome               \bigstrut \\
 % \hline
-% |\bnfpn{}| & production name      & $\bnfpn{name}$        \bigstrut[t] \\
-% |\bnfor|   & OR operator          & $\bnfor$               \\
-% |\bnfsk|   & skip                 & $\bnfsk$               \\
-% |\bnfsp|   & space/AND operator   & $\bnfsp$ \\
+% |\bnprod|   & production line       & <name> $\bnfpo$ {\it def}           \bigstrut[t]  \\
+% |\bnmore|   & extra  line &  \hspace{38.8pt} $\bnfpo$ {\it def}              \\[1ex]
+% |\bnfor|   & OR operator          & $\bnfor$              \\
+% |\bnfsk|   & skip                 & $\bnfsk$              \\
+% |\bnfsp|   & space/AND operator   & $\bnfsp$              \\
 % |\bnfes|   & empty string         & $\bnfes$              \\
-% |\bnfts{}| & terminal string      & $\bnfts{terminal}$     \\
-% |\bnftd{}| & terminal description & $\bnftd{description}$ \\
+% |\bnfts{}| & terminal string      & $\bnfts{terminal}$    \\
+% |\bnftd{}| & terminal description & $\bnftd{description}$ \\[1ex]
+% |\bnfpn{}| & production name      & $\bnfpn{name}$        \\
 % |\bnfpo|   & production operator  & $\bnfpo$              \bigstrut[b] \\
 % \hline
 % \end{tabular}
@@ -352,7 +375,7 @@
 %       \bnfts{z} \bnfor \bnfts{0} \bnfsk \bnfts{9} \bnfor 
 %       \bnfts{\textquotesingle}}\\
 %   \bnfprod{ichar}  
-%      {-}\\
+%      {\bnfts{-}}
 %   \bnfprod{schar}
 %      {\bnfts{`\hspace{1em}'} \bnfor \bnfts{!} \bnfor \bnfts{"} 
 %       \bnfor \bnfts{(}  \bnfor \bnfts{)} \bnfor \bnfts{\{} 
@@ -365,7 +388,7 @@
 %
 % \noindent
 % This creates the following BNF definition:
-%\begin{bnf*}
+%\begin{bnf}
 %   \bnfprod{sentence}
 %      {\bnfpn{start} \bnfsp \bnfpn{rest} \bnfsp \bnfts{.}}\\
 %   \bnfprod{start}  
@@ -382,16 +405,63 @@
 %   \bnfprod{cchar}
 %      {\bnfts{A} \bnfsk \bnfts{Z} \bnfor \bnfts{a} \bnfsk 
 %       \bnfts{z} \bnfor \bnfts{0} \bnfsk \bnfts{9} \bnfor 
-%       \bnfts{\textquotesingle} }\\
+%      \bnfts{\textquotesingle} }\\
 %   \bnfprod{ichar}  
-%      {-}\\
-%   \bnfprod{schar}
-%      {\bnfts{`\hspace{1em}'} \bnfor \bnfts{!} \bnfor \bnfts{"} 
+%      {\bnfts{-}}\\
+%   \bnfprod*{schar}
+%      {\textrm{`\hspace{1em}'} \bnfor \bnfts{!} \bnfor \bnfts{"} 
 %       \bnfor \bnfts{(}  \bnfor \bnfts{)} \bnfor \bnfts{\{} 
 %       \bnfor \bnfts{\}} \bnfor }\\
 %   \bnfmore{\bnfts{:} \bnfor \bnfts{;} \bnfor \bnfts{?} \bnfor
 %            \bnfts{,} }
-%\end{bnf*}
+%\end{bnf}
+%
+% \noindent
+%^^A Notice the kludge in production 9: \verb|\textrm{`\hspace{1em}'}|.
+% Notice the kludge in production 9. 
+% We use \verb|\textrm{`\hspace{1em}'}| to typeset a representation for a space 
+% character.
+% This is needed because we do not want to print in typewriter font, 
+% which would imply the quotes were part of an actual terminal string.
+% The \verb|\textrm| is needed because are in maths mode.
+%
+%^^AT \appendix
+% \section{Terminal string characters}
+%
+% The characters used with \verb|\bnfts{}| (terminal string) are just standard
+% LaTeX that is typeset in either a roman or typewriter font. 
+% This means we might have to use some escape pairs and a few special characters.
+% Apostrophes and speech marks can be confusing. There are some of the possibilities:
+%
+% \begin{tabbing}
+% xxxxxxxx \= xxxxxxxxxxxxxxxxxxxxxxxxxx  \= xxxxxxxxxxxxxxxxx\=  \kill
+% alpha \> \verb|\bnfts{abcdABCD}| \> $\texttt{abcdABCD}$ \> $\textrm{abcdABCD}$\\
+% numeric \> \verb|\bnfts{01234}| \> $\texttt{01234}$ \> $\textrm{01234}$\\
+%
+% simple \> \verb|\bnfts{<>[]()*+-=}| \> $\texttt{<>[]()*+-=}$ \> $\textrm{<>[]()*+-=}$\\
+% simple \> \verb|\bnfts{@!?/,.;:}| \> $\texttt{@!?/,.;:}$ \> $\textrm{@!?/,.;:}$\\
+%
+% escaped \> \verb|\bnfts{\{\}\$\%\&\_\#}| \> $\texttt{\{\}\$\%\&\_\#}$ 
+%                                          \> $\textrm{\{\}\$\%\&\_\#}$\\
+%
+% quotes \> \verb|\bnfts{' ` " `` ''}| \> $\texttt{' ` " `` ''}$ 
+%                                      \> $\textrm{' ` " `` ''}$\\
+% quotes \> \verb|\bnfts{\textquotesingle}| \> $\texttt{\textquotesingle}$ 
+%                                           \> $\textrm{\textquotesingle}$\\
+%
+% pound \> \verb|\bnfts{\pounds}| \> $\texttt{\pounds}$ \> $\textrm{\pounds}$\\
+% hat \> \verb|\bnfts{\textasciicircum}| \> $\texttt{\textasciicircum}$ 
+%                                        \> $\textrm{\textasciicircum}$\\
+% backslash \> \verb|\bnfts{\textbackslash}| \> $\texttt{\textbackslash}$  
+%                                            \> $\textrm{\textbackslash}$\\
+% tilde \> \verb|\bnfts{\textasciitilde}| \> $\texttt{\textasciitilde}$ \> 
+%             $\textrm{\textasciitilde}$
+% \end{tabbing}
+%
+%
+% \noindent
+% The \verb|\textquotesingle| symbol needs the {\tt textcomp} package, which provides 
+% lots of other interesting symbols. Consult the excellent \emph{The Comprehensive LATEX Symbol List} by Scott Pakin for more information.
 %
 %^^A-------------------------------------------------------------------
 %^^A Start code implementation
@@ -443,8 +513,9 @@
 %
 % \begin{macro}{\bnfpn}
 %    Production name / nonterminal.
+%    \changes{v3.1}{2019/06/18}{Fix font handling}
 %    \begin{macrocode}
-\newcommand{\bnfpn}[1]{\langle \textnormal{#1} \rangle}
+\newcommand{\bnfpn}[1]{\langle \textrm{#1} \rangle}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -456,7 +527,7 @@
 % \end{macro}
 %
 % \begin{macro}{\bnfsp}
-%    Space.
+%    Space or AND operator.
 %    \begin{macrocode}
 \newcommand{\bnfsp}{\;}
 %    \end{macrocode}
@@ -471,21 +542,23 @@
 %
 % \begin{macro}{\bnfts}\label{codebnfts}
 %    \changes{v1.1}{2012/12/12}{Support for {\tt tstt} option added}
+%    \changes{v3.1}{2019/06/18}{Fix font handling}
 % \begin{macro}{\bnf@tsfont}
 %    Terminal string. The font is controlled by the |\bnf@tsfont| macro,
 %    and this macro can be redefined by the |tsrm| option (see \S\ref{codeoptions}).
 %    The default is typewriter font.
 %    \begin{macrocode}
-\newcommand\bnf@tsfont[1]{\texttt{#1}}
-\newcommand{\bnfts}[1]{\textnormal{\bnf@tsfont{#1}}}
+\newcommand{\bnf@tsfont}[1]{\texttt{#1}}
+\newcommand{\bnfts}[1]{\bnf@tsfont{#1}}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 %
 % \begin{macro}{\bnfpo}
 %    Terminal description.
+%    \changes{v3.1}{2019/06/18}{Fix font handling}
 %    \begin{macrocode}
-\newcommand{\bnftd}[1]{\textnormal{\it #1}}
+\newcommand{\bnftd}[1]{\textit{#1}}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -505,39 +578,63 @@
 %
 % \subsection{Production Commands}
 %
+%^^A \newcommand{\bnfprod}{\@ifstar{\bnf@prodnn}{\bnf@prodyn}}
+%^^A \newcommand{\bnf@prodyn}[2]{\bnfpn{#1} & \bnfpo & #2}
+%^^A \newcommand{\bnf@prodnn}[2]{\nonumber \bnfpn{#1} & \bnfpo & #2}
+%^^A \newcommand{\bnfmore}{\@ifstar{\bnf@morenn}{\bnf@moreyn}}
+%^^A \newcommand{\bnf@moreyn}[1]{ &  & #1}
+%^^A \newcommand{\bnf@morenn}[1]{\nonumber &  & #1}
+%
 % \begin{macro}{\bnfprod}
+% \begin{macro}{\bnfprod*}
+%    \changes{v3.0}{2019/06/07}{Added {\tt *} version of the macro.}
+% \begin{macro}{\bnf@prodyn}
+% \begin{macro}{\bnf@prodnn}
 %    A Backus-Naur Form production. 
 %    This command is designed to exploit the behaviour the |equarray| used in 
 %    the |bnf| and |bnf*| environments. 
 %    In particular, the |\bnfpo| character will be vertically aligned. 
-%    \begin{macrocode}
-\newcommand{\bnfprod}[2]{\bnfpn{#1} & \bnfpo & #2}
+%    The {\tt *} version suppresses the line number%    \begin{macrocode}
+\newcommand{\bnfprod}{\@ifstar{\bnf@prodnn}{\bnf@prodyn}}
+\newcommand{\bnf@prodyn}[2]{\bnfpn{#1} & \bnfpo & #2}
+\newcommand{\bnf@prodnn}[2]{\nonumber \bnfpn{#1} & \bnfpo & #2}
 %    \end{macrocode}
 % \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\bnfmore}
-%    \changes{v2.0}{2019/04/07}
-%            {Added macro.}
+%    \changes{v2.0}{2019/04/07}{Added macro.}
+% \begin{macro}{\bnfmore*}
+%    \changes{v3.0}{2019/06/07}{Added {\tt *} version of the macro.}
+% \begin{macro}{\bnf@moreyn}
+% \begin{macro}{\bnf@morenn}
 %    A continuation of a Backus-Naur Form production. 
 %    This command is designed to exploit the behaviour the |equarray| used in 
 %    the |bnf| and |bnf*| environments to correctly align with preceding 
 %    |\bnfprod| and |\bnfmore| macros. 
+%    The {\tt *} version suppresses the line number.
 %    \begin{macrocode}
-\newcommand{\bnfmore}[1]{ &  & #1}
+\newcommand{\bnfmore}{\@ifstar{\bnf@morenn}{\bnf@moreyn}}
+\newcommand{\bnf@moreyn}[1]{ &  & #1}
+\newcommand{\bnf@morenn}[1]{\nonumber &  & #1}
 %    \end{macrocode}
 % \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \subsection{Options}\label{codeoptions}
 %
-% \begin{macro}{tstt}
+%\begin{macro}{tstt}
 %    \changes{v1.1}{2012/12/12}{New option}
 %    \changes{v2.0}{2019/04/14}{Changed to be default}
-%    The |tstt| option is the default, so it does nothing. 
-%    This option is provided for compatibility with previous versions. 
-%    \begin{macrocode}
-\DeclareOption{tstt}{}    
-%    \end{macrocode}
-% \end{macro}
+%    \changes{v3.0}{2019/06/07}{Option removed but still default}
+%    The |tstt| option is depreciated and can no longer be used.
+%    Nevertheless, typewriter font for terminal stings, which it selected,
+%    is still the package's default.
+%\end{macro}
 %
 % \begin{macro}{tsrm}
 %    \changes{v2.0}{2019/04/14}{New option}
@@ -545,7 +642,7 @@
 %    The |tsrm| option redefines |\bnf@tsfont| to change the 
 %    terminal string font used in the |\bnfts| command (see \S\ref{codebnfts}) to roman font.
 %    \begin{macrocode}
-\DeclareOption{tsrm}{\renewcommand\bnf@tsfont[1]{\textrm{#1}}}
+\DeclareOption{tsrm}{\renewcommand{\bnf@tsfont}[1]{\textrm{#1}}}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -563,6 +660,16 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{altpo}
+%    \changes{v3.0}{2019/06/07}{New option}
+% \begin{macro}{\bnfpo}
+%    The |altpo| option redefines |\bnfpo|  
+%    which prints the production operator:
+%    \begin{macrocode}
+\DeclareOption{altpo}{\renewcommand{\bnfpo}{::=}}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
 %\noindent
 % Finally, the options that have been selected are executed:
 %    \begin{macrocode}
diff --git a/Master/texmf-dist/tex/latex/backnaur/backnaur.sty b/Master/texmf-dist/tex/latex/backnaur/backnaur.sty
index 5f863c0dbd8..aba486f18bc 100644
--- a/Master/texmf-dist/tex/latex/backnaur/backnaur.sty
+++ b/Master/texmf-dist/tex/latex/backnaur/backnaur.sty
@@ -25,28 +25,32 @@
 %% 
 \NeedsTeXFormat{LaTeX2e}[2011/06/27]
 \ProvidesPackage{backnaur}
-[2019/04/14 2.0 Typesetting for Backus-Naur Form (BNF) definitions]
+[2019/06/18 3.1 Typesetting for Backus-Naur Form (BNF) definitions]
 \newenvironment{bnf}%
 {\begin{eqnarray}}%
 {\end{eqnarray}\ignorespacesafterend}
 \newenvironment{bnf*}%
 {\begin{eqnarray*}}%
 {\end{eqnarray*}\ignorespacesafterend}
-\newcommand{\bnfpn}[1]{\langle \textnormal{#1} \rangle}
+\newcommand{\bnfpn}[1]{\langle \textrm{#1} \rangle}
 \newcommand{\bnfor}{\; \mid \;}
 \newcommand{\bnfsp}{\;}
 \newcommand{\bnfes}{\lambda}
-\newcommand\bnf@tsfont[1]{\texttt{#1}}
-\newcommand{\bnfts}[1]{\textnormal{\bnf@tsfont{#1}}}
-\newcommand{\bnftd}[1]{\textnormal{\it #1}}
+\newcommand{\bnf@tsfont}[1]{\texttt{#1}}
+\newcommand{\bnfts}[1]{\bnf@tsfont{#1}}
+\newcommand{\bnftd}[1]{\textit{#1}}
 \newcommand{\bnfsk}{\dots}
 \newcommand{\bnfpo}{\models}
-\newcommand{\bnfprod}[2]{\bnfpn{#1} & \bnfpo & #2}
-\newcommand{\bnfmore}[1]{ &  & #1}
-\DeclareOption{tstt}{}
-\DeclareOption{tsrm}{\renewcommand\bnf@tsfont[1]{\textrm{#1}}}
+\newcommand{\bnfprod}{\@ifstar{\bnf@prodnn}{\bnf@prodyn}}
+\newcommand{\bnf@prodyn}[2]{\bnfpn{#1} & \bnfpo & #2}
+\newcommand{\bnf@prodnn}[2]{\nonumber \bnfpn{#1} & \bnfpo & #2}
+\newcommand{\bnfmore}{\@ifstar{\bnf@morenn}{\bnf@moreyn}}
+\newcommand{\bnf@moreyn}[1]{ &  & #1}
+\newcommand{\bnf@morenn}[1]{\nonumber &  & #1}
+\DeclareOption{tsrm}{\renewcommand{\bnf@tsfont}[1]{\textrm{#1}}}
 \DeclareOption{perp}{\renewcommand{\bnfes}{\perp}}
 \DeclareOption{epsilon}{\renewcommand{\bnfes}{\epsilon}}
+\DeclareOption{altpo}{\renewcommand{\bnfpo}{::=}}
 \ProcessOptions\relax
 \endinput
 %%