summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/backnaur
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-06-29 21:06:31 +0000
committerKarl Berry <karl@freefriends.org>2019-06-29 21:06:31 +0000
commitc81d0736dc576f983c5c03bd531caf782b2328f4 (patch)
treee530b4b5e829d526ffaa0589f526a87a5ba11be5 /Master/texmf-dist/source/latex/backnaur
parent19ed7af30e1bd9150f038b5c421a73259952ef2d (diff)
backnaur (29jun19)
git-svn-id: svn://tug.org/texlive/trunk@51505 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/backnaur')
-rw-r--r--Master/texmf-dist/source/latex/backnaur/backnaur.dtx211
1 files changed, 159 insertions, 52 deletions
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}