syntax.dtx: Allow decorative material following nonterminal name in `grammar'.

[mdwtools] / cmtt.dtx

% \begin{meta-comment}
%
% $Id: cmtt.dtx,v 1.3 2003/09/05 16:12:04 mdw Exp $
%
% Nicer handling of the Computer Modern Typewriter font
%
% (c) 1996 Mark Wooding
%
% \end{meta-comment}
%
% \begin{meta-comment} <general public licence>
%%
%% mdwlist package -- various list-related things
%% Copyright (c) 1996 Mark Wooding
%%
%% This program is free software; you can redistribute it and/or modify
%% it under the terms of the GNU General Public License as published by
%% the Free Software Foundation; either version 2 of the License, or
%% (at your option) any later version.
%%
%% This program is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%% GNU General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%%
% \end{meta-comment}
%
%
% \begin{meta-comment} <Package preambles>
%<+sty>\NeedsTeXFormat{LaTeX2e}
%<+sty>\ProvidesPackage{cmtt}
%<+fd>\ProvidesFile{mttcmtt.fd}
%<+def>\ProvidesFile{mttcmtt.def}
%<+sty|fd|def>         [1996/05/25 1.1 Handing of the cmtt font]
% \end{meta-comment}
%
% \CheckSum{174}
%% \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
%%   Lower-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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
% \begin{meta-comment}
%
%<*driver>
\input{mdwtools}
\describespackage{cmtt}
\mdwdoc
%</driver>
%
% \end{meta-comment}
%
%^^A-------------------------------------------------------------------------
% \section{Introductory note}
%
% \LaTeX\ has a rather cunning encoding handling system, which makes funny
% commands like accents work properly independent of the current font's
% actual layout.  While this works rather well most of the time, the standard
% \mtt{tt} font has been rather left out of things.  \LaTeX\ assumes that
% the Computer Modern Typewriter fonts have exactly the same layout as the
% more normal Computer Modern Roman family (i.e., that both conform to the
% \mtt{OT1} encoding).  This plainly isn't true, since the Typewriter font
% contains a bunch of standard ASCII characters which are omitted from the
% standard Computer Modern fonts, such as curly braces \mtt{\{} and \mtt{\}},
% and the backslash \mtt{\\}; these are usually dug up from the maths fonts,
% which looks fine in normal text, but looks really odd in monospace text.
% Compare `\texttt{\textbackslash begin\{document\}}' to
% `\mtt{\\begin\{document\}}', for example.
%
% There are two possibilities for dealing with this problem.  One is to use
% the \mtt{\\verb} command, which works since all the extra characters in
% the Typewriter font are in the correct places, or use the DC~fonts, which
% have a proper encoding set up which contains all of these special
% characters anyway.
%
% Neither of these solutions is perfect.  Using \mtt{\\verb} causes all
% manner of little niggly problems: you can't use it in footnotes or
% section headings, for example.  (There are of course workarounds for this
% sort of thing: the author's \package{footnote} package provides a
% \env{footnote} environment which will allow verbatim text, and verbatim
% text in section headings can be achieved if one is sufficiently
% \TeX nical.)  Using the DC~fonts is fine, although you actually lose a
% glyph or two.  As far as the author is aware, the character \mtt{\'} (an
% `unsexed' single quote) is not present in the \mtt{T1}-encoded version of
% Computer Modern Typewriter, although it is hidden away in the original
% version.  The author has found a need for this character in computer
% listings, and was horrified to discover that it was replaced by a German
% single quote character (\mtt{\\quotesinglbase}).
%
% This package defines a special encoding for the Computer Modern Typewriter
% font, so that documents can take advantage of its ASCII characters without
% resorting to verbatim text.  (The main advantage of the DC~fonts, that
% words containing accents can be hyohenated, doesn't really apply to the
% Typewriter font, since it doesn't allow hyphenation by default anyway.)
%
% There are several files you'll need to create:
% \begin{description} \def\makelabel#1{\hskip\labelsep\mttfamily#1\hfil}
%
% \item [cmtt.sty] tells \LaTeX\ that there's a new encoding.  It also
%       provides some options for customising some aspects of the
%       encoding, and defines some useful commands.
%
% \item [mttenc.def] describes the encoding to \LaTeX: it sets up all the
%       appropriate text commands so that they produce beautiful results.
%
% \item [mttcmtt.fd] describes the re-encoded version of the font.  this
%       is more or less a copy of the file \mtt{ot1cmtt.fd}.
%
% \end{description}
%
% The package accepts some options which may be useful:
% \begin{description} \def\makelabel#1{\hskip\labelsep\sffamily#1\hfil}
%
% \item [override] overrides the meaning of the \mtt{\\ttfamily} command
%       (and therefore also the \mtt{\\texttt} command too), making it the
%       same as the new \mtt{\\mttfamily} command.  This isn't the default
%       just in case the change breaks something in an unexpected way.
%
% \item [t1] informs the package that you're using the \mtt{T1} encoding,
%       and therefore can borrow some accented characters from the DC~version
%       of Computer Modern Typewriter.  This will probably be unnecessary,
%       since the package attempts to work out what to do all by itself.
%
% \item [ot1] forces the package \emph{not} to use the DC~version of the
%       Computer Modern Typewriter font for funny accents.  Only use this
%       option if the package thinks it should use the DC~Typewriter font
%       when it shouldn't.
%
% \end{description}
%
% \DescribeMacro{\mttfamily}
% The command \mtt{\\mttfamily} selects the properly-encoded Typewriter
% font.  It's a declaration which works just like the \mtt{\\ttfamily}
% command, except that comamnds like \mtt{\\\}} and \mtt{\\\_} use the
% characters from the font rather than choosing odd-looking versions from
% the maths fonts.  All of the accent commands still work properly.  In fact,
% some accent commands which didn't work before have been fixed.  For
% example, saying `\mtt{\\texttt\{P\\'al Erd\\H os\}}' would produce
% something truly appalling like `\texttt{P\'al Erd\H os}', which is
% obviously ghastly.  The new encoding handles this properly, and produces
% `\textmtt{P\'al Erd\H os}'.\footnote{
%   This isn't quite perfect.  The accent, which isn't actually present in
%   the Typewriter font, is taken from the Computer Modern bold font, but
%   it doesn't look too bad.  However, if you pass the option \textsf{t1}
%   to the \package{cmtt} package when you load it, the accent will be taken
%   from the DC~Typewriter font, and it will look totally wonderful.}
%
% \DescribeMacro{\textmtt}
% Font changing commands are much more convenient than th declarations,
% so a command \mtt{\\textmtt} is provided: it just typesets its argument
% in the re-encoded Typewriter font.
%
% \DescribeMacro{\mtt}
% Rather more excitingly, the \mtt{\\mtt} command allows you to generate
% almost-verbatim text very easily, without any of the restrictions of
% the \mtt{\\verb} command.  This command was inspired by something which
% David Carlisle said to me in an email correspondence regarding the
% overuse of verbatim commands.
%
% \mtt{\\mtt} redefines several `short' commands to typeset the obvious
% characters.  The complete list is shown below: there are some oddities,
% so watch out.
%
% ^^A This is an evil table.  See if I care.  (This is based on lots of
% ^^A hacking I did in glyphs.tex, but a good deal less horrible.)
%
% \medskip
% \hbox to \hsize\bgroup
% \hfil\vbox\bgroup
% \def\ex#1#2{\strut
%   \enskip
%   \mtt{\\\char`#2}\quad\hfil%
%   \mtt{#2}\enskip}
% \def\h{\noalign{\hrule}}
% \def\v{height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr}
% \let~\relax
% \offinterlineskip
% \ialign\bgroup&\vrule#&\ex#\cr        \h\v
% &~\\&&~\{&&~\}&&~\_&&~\^&\cr        \v\h\v
% &~\$&&~\%&&~\&&&~\#&&~\~&\cr        \v\h\v
% &~\"&&~\'&&~\ &&~\|&&\omit\hfil&\cr \v\h
% \egroup\egroup
% \hfil\egroup
% \medskip
%
% As well as redefining these commands, \mtt{\\mtt} will endeavour to make
% single special characters display themselves in a verbatim-like way.  This
% only works on `active' characters (like \mtt{~}), and \mtt{\\mtt} makes
% no attempt to change the category codes of any characters.
%
% Among other things, you'll probably noticed that several accent-making
% commands have been redefined.  You can still use these accents through
% the \mtt{\\a} command, by saying \mtt{\\a'}, \mtt{\\a\^} and so on,
% as in the \env{tabbing} environment.
%
% There are also some oddities in the table: \mtt{\|} and \mtt{\"} can be
% accessed easily without playing with silly commands.  Well, that's almost
% the case: these two characters are both often used as `short' verbatim
% commands, so they are forced back to their normal meanings so you can
% type them.
%
% Finally, a word on spacing.  The \mtt{\\\ } command has been hijacked
% to produce a funny `visible space' character.  You can still produce
% multiple spaces by saying something like `\mtt{\ \{\}\ \{\}}\dots\mtt{\ }',
% which is a bit contrived, but that's tough.  Also, \mtt{~} has been stolen
% so that you can type \mtt{~} characters (e.g., in URLs), so the only
% way you can tpye a nonbreaking space is by using the \mtt{\\nobreakspace}
% command, which is a bit of a mouthful.  There's an abbreviation, though:
% \mtt{\\nbsp} now means exactly the same thing.
%
% Was that not all supremely useful?  Oh, just a note: this document doesn't
% use a single verbatim command or environment (except in the listings,
% where it's unavoidable) -- it's all done with \mtt{\\mtt}.
%
% \implementation
%
% \section{Implementation}
%
% \subsection{The package}
%
%    \begin{macrocode}
%<*sty>
%    \end{macrocode}
%
% I'll start with some options handling.
%
%    \begin{macrocode}
\newif\ifcmtt@override
\newif\ifcmtt@dcfonts
\def\@tempa{T1}\ifx\encodingdefault\@tempa
  \cmtt@dcfontstrue
\fi
\DeclareOption{override}{\cmtt@overridetrue}
\DeclareOption{t1}{\cmtt@dcfontstrue}
\DeclareOption{ot1}{\cmtt@dcfontsfalse}
\ProcessOptions
%    \end{macrocode}
%
% This bit is really trivial.  I'll just declare the font encoding.  Oh, that
% was easy.
%
%    \begin{macrocode}
\DeclareFontEncoding{mTT}{}{}
%    \end{macrocode}
%
% Wait: there's a problem.  \LaTeX\ will now complain bitterly that it can't
% find the font \mtt{mTT/cmr/m/n}, which is reasonable, since I haven't
% declared any such font.  The following line should sort this out,
%
%    \begin{macrocode}
\DeclareFontSubstitution{mTT}{cmtt}{m}{n}
%    \end{macrocode}
%
% Now I'd better load all the text commands I'll need when in this funny
% font variant.
%
%    \begin{macrocode}
\input{mttenc.def}
%    \end{macrocode}
%
% \begin{macro}{\mttfamily}
% \begin{macro}{\textmtt}
%
% Finally, I'll need to define a command which switches to this funny font,
% and a \mtt{\\text}\dots\ command for it.
%
%    \begin{macrocode}
\DeclareRobustCommand{\mttfamily}{%
  \fontencoding{mTT}\fontfamily{\ttdefault}\selectfont%
}
\DeclareTextFontCommand{\textmtt}{\mttfamily}
%    \end{macrocode}
%
% \end{macro}
% \end{macro}
%
% If an override was requested, make \mtt{\\ttfamily} the same as
% \mtt{\\mttfamily}.
%
%    \begin{macrocode}
\ifcmtt@override
  \let\ttfamily\mttfamily
\fi
%    \end{macrocode}
%
% Well, that's all that's needed for the font definition.  Here's a command
% which will typeset its argument in the typewriter font, allowing easy
% access to all the funny characters, and printing them properly in the
% correct font (which \mtt{\\\{} doesn't do, for example).
%
% \begin{macro}{\mtt@setchar}
%
% This macro assigns the given meaning to the given control sequence.  Also,
% if the character named in the control sequence is currently set active,
% it will set the active meaning of the character to the same value.
%
%    \begin{macrocode}
\def\mtt@setchar#1#2{%
  \ifx#1#2\chardef#1`#1\else\let#1#2\fi%
  \ifnum\catcode`#1=13%
    \begingroup%
      \lccode`\~=`#1%
    \lowercase{\endgroup\let~#1}%
  \fi%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\mtt@chars}
%
% This macro lists the various control sequences which should be set up,
% so that they can be easily added to.
%
%    \begin{macrocode}
\def\mtt@chars{%
  \do\#\#%
  \do\%\%%
  \do\&\&%
  \do\^\^%
  \do\~\~%
  \do\'\textquotesingl%
  \do\"\textquotedbl%
  \do\|\textbar%
  \do\$\textdollar%
  \do\_\textunderscore%
  \do\{\textbraceleft%
  \do\}\textbraceright%
  \do\\\textbackslash%
  \do\ \textvisiblespace%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\mtt@do}
%
% This just sets up all the special characters listed above.  It's a simple
% abbreviation, really.
%
%    \begin{macrocode}
\def\mtt@do{\let\do\mtt@setchar\mtt@chars}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\mtt}
%
% And finally, the macro itself.  Ta-da!
%
%    \begin{macrocode}
\DeclareRobustCommand\mtt[1]{\textmtt{\mtt@do#1}}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\@tabacckludge}
%
% The otherwise almost totally perfect \mtt{\\@tabacckludge} gets very
% upset when its argument is an active character.  (If you're wondering,
% this is the command which is responsible for the behaviour of the \mtt{\\a}
% command.)  Adding a \mtt{\\string} makes everything work perfectly.
%
%    \begin{macrocode}
\def\@tabacckludge#1{%
  \expandafter\@changed@cmd\csname\string#1\endcsname\relax%
}
\let\a\@tabacckludge
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\nbsp}
%
% Make an abbreviation for \mtt{\\nobreakspace}.
%
%    \begin{macrocode}
\let\nbsp\nobreakspace
%    \end{macrocode}
%
% \end{macro}
%
% I think that's all that I have to do for the package.  If there's any
% more to do, I'll add it later.
%
%    \begin{macrocode}
%</sty>
%    \end{macrocode}
%
%
% \subsection{The font definition file}
%
% This is obviously copied almost verbatim from the file \mtt{OT1cmtt.fd}.
%
%    \begin{macrocode}
%<*fd>
\DeclareFontFamily{mTT}{cmtt}{\hyphenchar\font\m@ne}
\DeclareFontShape{mTT}{cmtt}{m}{n}{
  <5> <6> <7> <8> cmtt8
  <9> cmtt9
  <10> <10.95> cmtt10
  <12> <14.4> <17.28> <20.74> <24.88> cmtt12
}{}
\DeclareFontShape{mTT}{cmtt}{m}{it}{
  <5> <6> <7> <8> <9> <10> <10.95> <12> <14.4> <17.28> <20.74> <24.88>
  cmitt10
}{}
\DeclareFontShape{mTT}{cmtt}{m}{sl}{
  <5> <6> <7> <8> <9> <10> <10.95> <12> <14.4> <17.28> <20.74> <24.88>
  cmsltt10
}{}
\DeclareFontShape{mTT}{cmtt}{m}{sc}{
  <5> <6> <7> <8> <9> <10> <10.95> <12> <14.4> <17.28> <20.74> <24.88>
  cmtcsc10
}{}
\DeclareFontShape{mTT}{cmtt}{m}{ui}  {<->sub * cmtt/m/it} {}
\DeclareFontShape{mTT}{cmtt}{bx}{n}  {<->sub * cmtt/m/n}  {}
\DeclareFontShape{mTT}{cmtt}{bx}{it} {<->sub * cmtt/m/it} {}
\DeclareFontShape{mTT}{cmtt}{bx}{ui} {<->sub * cmtt/m/it} {}
%</fd>
%    \end{macrocode}
%
%
% \subsection{The encoding definitions file}
%
% I've saved the trickiest bit until last.  This file defines the mappings
% from text commands to glyphs in the font.
%
%    \begin{macrocode}
%<*def>
%    \end{macrocode}
%
% First for some fun with accents.  The |cmtt| font doesn't contain all of
% the accents which the other Computer Modern fonts do, because those slots
% contain the standard ASCII characters which usually have to be `borrowed'
% from the maths fonts.
%
% Anyway, there's a load which don't need any special treatment.  These are
% chosen from the \mtt{OT1} encoding by default anyway, so I needn't
% bother unless I'm really bothered about speed.  I'm not, so I'll save
% the memory.
%
% Following the example of the \TeX book, I'll use the bold roman font
% for accents, so that they don't look really spindly.  This is actually
% remarkably difficult to do, because the \textsf{NFSS} keeps getting in
% the way.  I'll look after the old font name in a macro (it's handy that
% \textsf{NFSS} maintains this for me) and change to a known font, do the
% accent, change font back again, do the argument to the accent, and then
% close the group I did all of this in, so that no-one else notices what a
% naughty chap I am, really.  This is startlingly evil.
%
%    \begin{macrocode}
\def\cmtt@accent#1#2{{%
  \let\@old@font\font@name%
  \ifcmtt@dcfonts%
    \fontencoding{T1}\selectfont%
  \else%
    \usefont{OT1}{cmr}{bx}{n}%
  \fi%
  #1{\@old@font#2}%
}}
%    \end{macrocode}
%
% And now for the actual offending accents.
%
%    \begin{macrocode}
\DeclareTextCommand{\H}{mTT}{\cmtt@accent\H}
\DeclareTextCommand{\.}{mTT}{\cmtt@accent\.}
%    \end{macrocode}
%
% The `under' accents are all OK, so I shan't bother to define them either.
% Similarly, lots of the text symbol commands are fine as they are by
% default and I don't need to try and define them again.
%
% This, then, is the remaining commands which really need sorting out.
% (By the way, the only reason I've redefined \mtt{\\textellipsis} is
% because otherwise it will mess up the nice monospacing.)
%
%    \begin{macrocode}
\DeclareTextSymbol{\textbackslash}{mTT}{92}
\DeclareTextSymbol{\textbar}{mTT}{124}
\DeclareTextSymbol{\textbraceleft}{mTT}{123}
\DeclareTextSymbol{\textbraceright}{mTT}{125}
\DeclareTextSymbol{\textless}{mTT}{60}
\DeclareTextSymbol{\textgreater}{mTT}{62}
\DeclareTextSymbol{\textunderscore}{mTT}{95}
\DeclareTextSymbol{\textvisiblespace}{mTT}{32}
\DeclareTextCommand{\textellipsis}{mTT}{...}
\DeclareTextSymbol{\textquotedbl}{mTT}{34}
\DeclareTextSymbol{\textquotesingl}{mTT}{13}
%    \end{macrocode}
%
% That's all there is.  Please return to your homes.
%
% \Finale
%
\endinput