%^^A* copyright
% \iffalse
%
%   This program is part of the Frankenstein bundle for LaTeX2e.
%
%   Copyright (C) 1995 Matt Swift <swift@bu.edu>
%
%   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.
%
%^^A* to do
%
%^^A NOTE:  \DocInput will start reading after this \fi.
% \fi  
%
%^^A* checks
%
%^^A NOTE:  The character table, with two %'s, will get written to all files.
%% \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         \~}
%
% \CheckSum{248}
%
%^^A** abstract
% \begin{abstract}
%   Provides \cs\Wrapquotes, a command that typesets titles of books, journals,
%   etc. with intelligent management of nesting and following punctuation and
%   spacing.  This macro is particularly useful for bibliography databases. 
% \end{abstract}
%
% \part{Discussion}
%
%  \DescribeMacro\Wrapquotes
%    \cs\Wrapquotes\marg{text} wraps \meta{text} in quotes.  Single quotes are
%    used if the \option{singlequotes} option is given to the package, and
%    double quotes if no option or the \option{doublequotes} option is given to
%    the package.
%     
%    Spacing and punctuation following the closing quotes are handled
%    intelligently.  That is, if what follows is a comma or period, it is
%    pulled inside the quotes (following American practice).  A space is
%    inserted after the closing quotes unless what follows is in the set
%    |;?:!-)]'{|, in which case no space is inserted.
%
%    \cs\Wrapquotes nests properly, switching from single to double or vice
%    versa for each level of nesting.  When quotation marks are doubled up,
%    proper space is inserted between them.
%
%    \caveat{You should \cs\let user commands to \cs\Wrapquotes instead of
%    using a \cs\def-like defining command.}
%
%   \caveat{
%   The question of when to insert an italic correction is not nearly as simple
%   as it might seem.  I cannot figure good rules which cover all cases, and I
%   do not trust the behavior of the kernel's macros as a guide.  So I
%   can not tell you whether this package handles italic corrections properly.}
%
% \begin{warning}
%   Right now there is a small bug in cases where closing quotes fall at the end
%   of italic text, such as
%   \begin{bothexample}
%     \normalfont
%     \booktitle{My love of \poemtitle{Daffodils}}, by H.~Moneysworth.
%   \end{bothexample}
%   These cases loose because the closing quotation marks and any sucked-in
%   punctuation are going to be in roman, not italic, or italic, not roman.
%   Only the more obsessive will notice this flaw.  I'm sure I will come up
%   with a way to handle this for a future version of this package.
% \end{warning}
%
% \StopEventually{}
%
% \part{Implementation}
%
% \section{Version control}
%
%  \begin{macro}{\fileinfo}
%  \begin{macro}{\fileversion}
%  \begin{macro}{\filedate}
%  \begin{macro}{\docdate}
%  \begin{macro}{\PPOptArg}
% These definitions must be the first ones in the file.
%    \begin{macrocode}
\def\fileinfo{title macros (Frankenstein's references)}
\def\fileversion{v0.9}
\def\filedate{1996/03/22}
\def\docdate{1996/03/22}
\edef\PPOptArg {%
  \filedate\space \fileversion\space \fileinfo
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% Stop right here if we're just loading the file's information, and don't want
% to load this code for typesetting its documentation (only makes sense for
% certain packages).  The |JuStLaAdInFoRmAtIoN| flag will be set by the
% documentation driver; the |DoXNeeDME| flag will be set in the
% \ext{dtx} file, and will appear above if it's set.
%    \begin{macrocode}
\makeatletter
\@ifundefined{JuStLoAdInFoRmAtIoN} {%
  }{%
  \@ifundefined{DoXNeeDME} {%
    }{%
    \usepackage{titles}%
  }
  \makeatother
  \endinput
}
%    \end{macrocode}
%
% Now we check for \LaTeX2e and declare the package.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{titles}[\PPOptArg]
%    \end{macrocode}
%
% ^^A NOTE: We have to compensate for the above backslashes, which are not
% ^^A actually in the doctex file I work on.
%%
% \AddToCheckSum{24}
% 
% \makeatletter
%   \@ifundefined{DoXNeeDME} {} {\AddToCheckSum{2}}
% \makeatother
%
%
% \section{Requirements}
%
%    \begin{macrocode}
\RequirePackage{moredefs}
%    \end{macrocode}
%
% \section{Options}
% 
% \begin{macro}{\if@ti@double@}
% \begin{macro}{\@ti@double@true}
% \begin{macro}{\@ti@double@false}
%   This boolean is |true| when the next \cs\Wrapquotes should use double
%   quotes, and |false| when it should use single quotes.
%    \begin{macrocode}
\newboolean{@ti@double@}

\DeclareOption{singlequotes}{
  \@ti@double@false
}
\DeclareOption{doublequotes}{
  \@ti@double@true
}
\ExecuteOptions{doublequotes}
\ProcessOptions
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \section{Top level command}
%
% \begin{macro}{\Wrapquotes}
%   The lookahead mechanism would handle the \cs\endgroup, but I think it is
%   more efficient to skip it immediately here by using \cs\aftergroup.  The
%   group here is necessary to scope the \cname{@ti@double@} boolean.
%    \begin{macrocode}
\newcommand*\Wrapquotes [1] {%
%  \typeout{Starting wrapquote}%
  \begingroup
    \if@ti@double@
      \@ti@double@false
      \def\sc@t@a {\ti@open@double #1\ti@aftergroup@close@double}%
    \else
      \@ti@double@true
      \def\sc@t@a {\ti@open@single #1\ti@aftergroup@close@single}%
    \fi
    \sc@t@a
  \endgroup
}
%    \end{macrocode}
%  \end{macro}
%
% \section{Quotation marks}
%
% \begin{macro}{\ti@open@double}
% \begin{macro}{\ti@open@single}
% \begin{macro}{\sc@openquote}
%   We start by putting an opening mark in scratch |f|.
%    \begin{macrocode}
\newcommand\ti@open@double {%
  \gdef\sc@t@f {``}%                           '' for emacs
  \sc@openquote
}
\newcommand\ti@open@single {%
  \gdef\sc@t@f {`}%
  \sc@openquote
}
%    \end{macrocode}
% Then we look ahead with scratch |a|.
%    \begin{macrocode}
\newcommand\sc@openquote {% 
  \futurelet\sc@t@a\sc@@openquote
}
%    \end{macrocode}
% If we are about to open another quote, insert a small space.
%    \begin{macrocode}
\newcommand\sc@@openquote {%
  \sc@t@f
  \ifx\sc@t@a\Wrapquotes
    \,%
  \fi
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ti@close@double}
% \begin{macro}{\ti@close@single}
% \begin{macro}{\sc@closequote}
%   To close the quotes, we again start with the closing mark in scratch |f|.
%    \begin{macrocode}
\newcommand\ti@close@double {%
  \gdef\sc@t@f {''}%
  \sc@closequote
}
\newcommand\ti@close@single {%
  \gdef\sc@t@f {'}%
  \sc@closequote
}
\newcommand\ti@aftergroup@close@double {%
  \aftergroup\ti@close@double
}
\newcommand\ti@aftergroup@close@single {%
  \aftergroup\ti@close@single
}
%    \end{macrocode}
% Then we use \cname{sc@q@ifnextcharin} to look as far ahead as necessary for a
% significant character.  
%    \begin{macrocode}
\newcommand\GobbleTypeout [1] {%
%  \typeout{Gobbling [\meaning#1]}%
}
\newcommand\sc@closequote {%
%  \typeout{Starting closequote}%
  \sc@q@ifnextcharin {.,} {%
%      \typeout{Found a comma or period.}%
      \sc@t@c\sc@t@f\GobbleTypeout % This gobbles the original punctuation.
    }{% ELSE
    \sc@q@ifnextcharin {;?:!-)]'\bgroup} {%
%        \typeout{Found a no-spacer}%
        \sc@t@f
      }{% ELSE
%      \typeout{Found a spacer}%
      \sc@t@f\space
    }%
  }%
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% \begin{macro}{\sc@q@ifnextcharin}
% \begin{macro}{\sc@q@check}
% \begin{macro}{\sc@q@ifnch}
%   These macros are modeled after the definition of \cname{@ifnextchar} which
%   skips spaces.  While looking ahead for the next significant char, these
%   macros skip spaces, \cs\egroup, \cs\endgroup, \cname{check@icr},
%   \cname{ti@close@double} and \cname{ti@close@single} while doing the right thing
%   after each.
%
%   The first argument should expand to a list of chars.  If the next
%   significant char is in the list, then the |true| clause is executed,
%   otherwise the |false| clause is executed.  The next significant char
%   is left in \cname{sc@t@c} so it can be accessed by the clauses.
%
%   The three arguments to \cname{sc@q@ifnextcharin} are saved in global
%   variables because while looking ahead we must continue past the ends of
%   groups.
%    \begin{macrocode}
\newcommand\sc@q@ifnextcharin [3] {% args: charlist true false
  \xdef\sc@t@e {#1}%
  \gdef\sc@t@a {#2}%
  \gdef\sc@t@b {#3}%
  \sc@q@check
}
%    \end{macrocode}
% Having saved the arguments, we look ahead with scratch |c|.  This step is not
% in the macro above so that we can look back to \cname{sc@q@check} whenever we
% want to look ahead another character.
%    \begin{macrocode}
\newcommand\sc@q@check {%
  \futurelet\sc@t@c\sc@q@ifnch
}
%    \end{macrocode}
% Scratch |c| contains the current char.  Scratch |d| is the action to take at
% the end of this macro.  We order these possibilities to make \cs\Wrapquotes
% most efficient, though it is a guess which items will be encountered most
% frequently.
%    \begin{macrocode}
\newcommand\sc@q@ifnch {%
  \ifx\sc@t@c\check@icr
%    \typeout{Handling check@icr}%
%    \end{macrocode}
% \cname{check@icr} either expands to nothing or to \code{\aftergroup\maybe@ic}.
% We want to allow the italic correction check and \emph{then} continue with
% our own lookahead.  So we want to put \code{\aftergroup\sc@q@check}
% \emph{after} expanding \cname{check@icr}.  So we gobble it, reissue it, then
% do our own \cs\aftergroup.
%    \begin{macrocode}
    \def\sc@t@d##1{%
%      \typeout{check@icr handler: gobbling [\meaning##1]}%
      ##1\aftergroup\sc@q@check
    }%
  \else
    \ifx\sc@t@c\endgroup 
%      \typeout{Handling endgroup}%
      \def\sc@t@d {\aftergroup\sc@q@check}%
    \else
      \ifx\sc@t@c\@sptoken
%        \typeout{Handling space}%
        \let\sc@t@d\sc@q@handle@space
      \else
        \ifx\sc@t@c\egroup
%          \typeout{Handling egroup}%
          \def\sc@t@d {\aftergroup\sc@q@check}%
        \else
          \ifx\sc@t@c\ti@aftergroup@close@double
%            \typeout{Handling ti@aftergroup@close@quote}%
            \let\sc@t@d\sc@q@handle@double
          \else
            \ifx\sc@t@c\ti@aftergroup@close@single
%              \typeout{Handling ti@aftergroup@close@single}%
              \let\sc@t@d\sc@q@handle@single
            \else
%    \end{macrocode}
% We've handled all the lookahead cases, so now we are left with the simple
% comparison of the next char with the charlist.
%    \begin{macrocode}
            \@tempswafalse
%    \end{macrocode}
% Beware: |\Expand|...|\In| uses scratch variables. ^^A FIX can't do \lips?
%    \begin{macrocode}
              \expandafter   \@tfor
                \expandafter \sc@t@g
                \expandafter :%
                \expandafter =\sc@t@e \do {%
                  \if\sc@t@c\sc@t@g
%                    \typeout{We have a match of [\meaning\sc@t@c] with [\meaning\sc@t@g]}%
                    \@tempswatrue
                    \@break@tfor
                  \else
%                    \typeout{We have NO match between [\meaning\sc@t@c] with [\meaning\sc@t@g]}%
                  \fi
                }%
              \if@tempswa
%                \typeout{Choosing true clause [\meaning\sc@t@a]}%
                \let\sc@t@d\sc@t@a % the ``true'' clause
              \else
%                \typeout{Choosing false clause [\meaning\sc@t@b]}%
                \let\sc@t@d\sc@t@b % the ``false'' clause
              \fi
            \fi
          \fi
        \fi
      \fi
    \fi
  \fi
  \sc@t@d
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% \begin{macro}{\sc@q@handle@space}
%   Handle the case of a following space: gobble the space and call
%   \cname{sc@q@check}.
%
%   This little bit of trickery sneaks a space in as the \cs\def template,
%   thereby causing a space following \cname{sc@q@handle@space} to get gobbled.
%   We use the control character \cname{:} and restore its value.
%    \begin{macrocode}
\ReserveCS\sc@q@handle@space
\let\sc@t@a\:
\def\:{\sc@q@handle@space} \expandafter\def\: {\sc@q@check}
\let\:\sc@t@a
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\sc@q@handle@single}
% \begin{macro}{\sc@q@handle@double}
%   Handle the quote-closing cases: gobble the closequotes token with a \cs\def
%   template, add some stuff to scratch |f| and call \cname{sc@q@check}.
%   These are put in their own macros only to avoid clutter above.
%    \begin{macrocode}
\newcommand*\sc@q@handle@double [1] {%
%  \typeout{handle double: gobbling [\meaning#1]}%
%  \typeout{scratch f before: [\meaning\sc@t@f]}%
  \g@addto@macro\sc@t@f {\,''}%
%  \typeout{scratch f after: [\meaning\sc@t@f]}%
  \sc@q@check
}
\newcommand*\sc@q@handle@single [1] {%
%  \typeout{handle single: gobbling [\meaning#1]}%
%  \typeout{scratch f before: [\meaning\sc@t@f]}%
  \g@addto@macro\sc@t@f {\,'}%
%  \typeout{scratch f after: [\meaning\sc@t@f]}%
  \sc@q@check
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
% \section{Configuration}
%
% The main user commands are deferred to a configuration file.
%    \begin{macrocode}
\InputIfFileExists{titles.cfg}{}{}
%    \end{macrocode}
%
%  The contents of the distributed configuration file are below.
%
% \InputIfFileExists{titles.cfg}{}{}
%
% \Finale