From c81d0736dc576f983c5c03bd531caf782b2328f4 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 29 Jun 2019 21:06:31 +0000 Subject: backnaur (29jun19) git-svn-id: svn://tug.org/texlive/trunk@51505 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/backnaur/backnaur.dtx | 211 ++++++++++++++++----- 1 file changed, 159 insertions(+), 52 deletions(-) (limited to 'Master/texmf-dist/source/latex/backnaur') 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 %\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] %<*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{||}{||}| +% |\bnfprod{||}{||}|\\ +% |\bnfprod*{||}{||}| % \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{||}| +% |\bnfmore{||}|\\ +% |\bnfmore*{||}| % \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 & $\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} -- cgit v1.2.3