path: root/Master/texmf-dist/tex/latex/frankenstein/attrib.sty

%^^A* legal notices
% \iffalse
%
%   This program is part of the Frankenstein bundle for LaTeX.  
%
%   Copyright 1995-2001 Matt Swift <swift@alum.mit.edu>.
%
%   This file contains both the code and documentation for the
%   attrib LaTeX package.  It will work ONLY if it is placed in a
%   proper directory.  Files called README, INSTALL, attrib.tex
%   and attrib.ins should have also been distributed to you
%   with this file.  See them for more information on how to typeset
%   the documentation with LaTeX and how to generate a version of this
%   file that will work faster than this one.
%
%   This program is free software; you may redistribute it and/or
%   modify it under the conditions of the LaTeX Project Public
%   License, either version 1.2 or (at your option) any later version.
%   The latest version of this license is in
%   http://www.latex-project.org/lppl.txt, and version 1.2 or later is
%   part of all distributions of LaTeX version 1999/12/01 or later.
%
%   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
%   LaTeX Project Public License for more details.
%
% \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{89}
%
% \begin{abstract}
%   The \cs\attrib macro attributes block elements, for example when citing a
%   reference after a block quotation.
% \end{abstract}
% \tableofcontents
%
% \part{Discussion}
%
% \section{Attributions}
%
% FIX: maybe \cs\attrib when not in a block environment should do this, with
% appropriate hooks added, etc.: use the blkcntrl hooks. and Pre stuff.
% \begin{codeexample}
%  \def\attrib [1] {%
%    (\begingroup
%    \attribcitations
%    #1%
%    \endgroup
%    )%
%  }
% \end{codeexample}
% Here's an example of the kind that inspires the question: \code{({\attribcitations
% \citework{3}{unnam}, and see page~\pageref{q:aporia}})}.  This way
% \cs\attribcitations and \cs\normalcitations could still be defined only
% within \cs\attrib, which seems the most sensible.
%
% \DescribeMacro\attrib
%   I wrote \cs\attrib in order to have an abstract way to attribute the source
%   of quotations of prose or verse in an academic style.  The formatting is
%   that recommended by the \manual, except that attributions of block
%   quotations of prose are given flush right, to allow the reader to locate a
%   quotation more quickly when returning to the text.
%
%   Use \cs\attrib\marg{attribution} at the end of any block of text,
%   such as the \env{quote}, \env{quotation}, \env{verse}, and \env{dialogue}
%   environments (the last is defined in the \package{dialogue} package, also
%   part of the \Frankenstein bundle).
%
%   For \env{verse}, you ought to use either a blank line or a final \cs{\\}
%   before your attribution.  For \env{quote}, \env{quotation}, and
%   \env{dialgoue}, don't leave a blank line.
%
%   \cs\attrib will place the attribution flush right to the margins of the
%   block.  If there is enough room on the last line, the attribution will be
%   given on the last line, otherwise it moves down to a line of its own.
%
%   You can put pretty much anything as the text of the attribution, including
%   citations and footnotes.  
%
%   For those using the \package{achicago} and \package{abbrevs} packages (also
%   in the \Frankenstein bundle), \cs\citework works very well.  If you're
%   using regular \cs\cite or another package, I recommend using the FIX hook
%   below to remove the usual parens or braces around citations that occur
%   within the \cs\attrib argument.  It makes more sense to me that way.
% 
% \DescribeMacro\normalcitations
%   If parens are normally around citations, they are removed when citations
%   occur within attributions.  The idea is that you can simply write
%   \code{\attrib{\cite{key}}} and what normally surrounds the citation will be
%   replaced with \cs\PreTrib and \cs\PostTrib (which of course could be the
%   same thing, but doing it this way allows attributions to contain things
%   \emph{other} than just a citation and still everything will look right).
%
%   Whenever within an attribution you want the normal behavior of citations
%   back, write \cs\normalcitations.  \cs\normalcitations is automatically used
%   within footnotes within attributions; it's used in the \package{epigraph}
%   package; and occasionally a user will want to invoke it, when the
%   attribution is unusual.  I find that most attributions are either just a
%   citation, or they do not have a citation at all.  Sometimes I've wanted an
%   attribution consisting of a citation plus some other text, for which cases
%   I provided \cs\normalcitations as a user command.
%
%   \todo{Right now the only time there is any concept of ``normal'' or
%   altered behavior of \cs\cite commands is with the \package{achicago}
%   package.  I should make it so that \cs\attrib by default leaves off braces,
%   brackets, etc, around citations, for the standard definition of \cs\cite also.}
%
% \DescribeMacro\attribcitations
%
%   FIX: dox, example.
%
% \section{Examples}
%   Following are several examples that use \cs\attrib.  They should be
%   self-explanatory.
%
% \begin{bothexample}
%   \begin{quotation}
%     [My plays] deal with distress.  Some people object to this in my writing.
%
%     At a party an English intellectual---so called---asked me why I write always
%     about distress.  As if it were perverse to do so!  He wanted to know if my
%     father had beaten me or my mother had run away from home to give me an
%     unhappy childhood.  I told him no, that I had had a very happy childhood.
%     Then he thought me more perverse than ever.  I left the party as soon as
%     possible and got into a taxi.  On the glass partition between me and the
%     driver were three signs: one asked for help for the blind, another help for
%     orphans, and the third for relief for the war refugees.  One does not have to
%     look for distress.  It is screaming at you even in the taxis of London.
%     \attrib{\cite[24]{driver:beckett:madeleine}}
%   \end{quotation}
% \end{bothexample}
%
% \begin{bothexample}
%   \providelength\mtslen
%   \newcommand\makethisspace [1] {%
%     \settowidth{\mtslen}{#1}%
%     \hspace*{\mtslen}%
%   }
%   \begin{verse}
%     \makethisspace{Where Joy for ever dwells:} Hail horrours, hail \\
%     Infernal World, and thou profoundest Hell \\
%     Receive thy new Possessor: One who brings \\
%     A mind not to be chang'd by Place or Time. \\
%     The mind is its own place, and in it self \\
%     Can make a Heav'n of Hell, a Hell of Heav'n. \\
%     What matter where, if I be still the same, \\
%     And what I should be, all but less then he \\
%     Whom Thunder hath made greater?  Here at least \\
%     We shall be free; th' Almighty hath not built \\
%     Here for his envy, will not drive us hence: \\
%     Here we may reign secure, and in my choyce \\
%     To reign is worth ambition though in Hell: \\
%     Better to reign in Hell, then serve in Heav'n.
%
%     \attrib{\book{Paradise Lost} 1.250--63,
%             \cite{milton:riverside:paralost}}
%   \end{verse}
% \end{bothexample}
%
% You can have a footnote inside the attribution.  The boxed example below is
% meant to approximate a whole page (that is, the footnote appears at the
% bottom of the page, not directly underneath the quotation).
% \begin{bothexample}
%   \begin{verse}
%     Jacke boy, ho boy newes,\\
%     \quad the cat is in the well,\\
%     let us ring now for her Knell,\\
%     \quad ding dong ding dong Bell.
%
%     \attrib{\cite[149]{opie:nursery}\footnote {%
%   Perhaps more familiar is the nursery rhyme that begins ``Ding,
%   dong, bell, / Pussy's in the well,'' which Opie and Opie also cite.  It does
%   not seem clear in that rhyme, however, without contextual knowledge, that the
%   cat has died and the bell rings its knell.}}
%   \end{verse}
% \end{bothexample}
%
% Here is a quotation from \citeNP{beckett:watt}:
% \begin{bothexample}
%   \newwork\watt{Watt}
%   \begin{quote}
%     One day Watt, coming out from behind a bush, almost ran into Mr~Knott,
%     which for an instant troubled Watt greatly, for he had not quite finished
%     adjusting his dress.  But he need not have been troubled.  For Mr~Knott's
%     hands were behind his back, and his head bowed down, towards the ground.
%     Then Watt in his turn looking down at first saw nothing but the short green
%     grass, but when he had looked a little longer he saw a little blue flower
%     and close by a fat worm burrowing into the earth.  So this was what had
%     attracted Mr~Knott's attention, perhaps.  So there for a short time they
%     stood together, the master and the servant, the bowed heads almost touching
%     \lips, until the worm was gone and only the flower remained.  One day the
%     flower would be gone and only the worm remain, but on this particular day
%     it was the flower that remained, and the worm that went.  And then Watt,
%     looking up, saw that Mr~Knott's eyes were closed, and heard his breathing,
%     soft and shallow, like the breathing of a child asleep.
%     \attrib{\citework{145--46}{watt}}
%   \end{quote}
% \end{bothexample}
%
% Finally, here's a very simple example from the same book.  When the context
% is clear, you might just want page numbers in the attribution.
% \begin{bothexample}
%   \begin{quote}
%     For Watt now found himself in the midst of things which, if they
%     consented to be named, did so as it were with reluctance.\lips Looking at
%     a pot, for example, \lips it was in vain that Watt said, Pot, pot.  Well,
%     perhaps not quite in vain, but very nearly. \lips It resembled a pot, it
%     was almost a pot, but it was not a pot of which one could say, Pot, pot,
%     and be comforted.  It was in vain that it answered, with unexceptionable
%     adequacy, all the purposes, and performed all the offices, of a pot, it
%     was not a pot.  And it was just this hairbreadth departure from the
%     nature of a true pot that so excruciated Watt\lips.  For he could always
%     hope, of a thing of which he had never known the name, that he would
%     learn the name, some day, and so be tranquillized.
%
%     \attrib{81--82}
%   \end{quote}
% \end{bothexample}
%
% Here's an example of use with the \env{dialogue} environment.  Not much
% different than the others, but the quotes are nice, and I'll demonstrate a
% use of \cs\normalcitations.  \refer{b}'s speeches are interspersed through
% the play with \refer{a}'s and \refer{c}'s, but it's interesting to read them
% consecutively.
%\begin{bothexample}
%   \begin{dialogue}
%     \speak{b} on the stone together in the sun on the stone at the edge of the
%       little wood and as far as eye could see the wheat turning yellow vowing every
%       now and then you loved each other just a murmur not touching or anything of
%       that nature you one end of the stone she the other long low stone like
%       millstone no looks just there on the stone in the sun with the little wood
%       behind gazing at the wheat or eyes closed all still no sign of life not a
%       soul abroad no sound
%   
%     \speak{b} all still just leaves and ears and you too still on the stone in a
%       daze no sound not a word only every now and then to vow you loved each other
%       just a murmur one thing could ever bring tears till they dried up altogether
%       that thought when it came up among the others floated up that scene
%   
%     \speak{b} on the stone in the sun gazing at the wheat or the sky or the eyes
%       closed nothing to be seen but the wheat turning yellow and the blue sky
%       vowing every now and then you loved each other just a murmur tears without
%       fail till they dried up altogether suddenly there in whatever thoughts you
%       might be having whatever scenes perhaps way back in childhood or the womb
%       worst of all or that old Chinaman long before Christ born with long white
%       hair
%   
%     \speak{b} no sight of the face or any other part never turned to her nor she to
%       you always parallel like on an axle-tree never turned to each other just
%       blurs on the fringes of the field no touching or anything of that nature
%       always space between if only an inch no pawing in the manner of flesh and
%       blood no better than shades no worse if it wasn't for the vows
%   
%     \speak{b} \lips on the fringe of the field and every now and then in the great
%       peace like a whisper so faint she loved you
%
%     \attrib{\play{That Time}{} \normalcitations\cite{beckett:csp:that}}
% \end{dialogue}
% \end{bothexample}
%
% \section{Programmer's Interface}
%
% You might want to use \cs\attrib as part of some other command you define.
% For example, I wrote a command for epigraphs,
% \cs\epigraph\marg{text}{attribution}, which used \cs\attrib internally.  For
% this type of thing, and also in general I suppose, you might want to change
% the behavior of \cs\attrib.
%
% \DescribeMacro\AttribMinSkip
%   \cs\AttribMinSkip is a length, the minimum amount of horizontal space that
%   must come after any previous text and before the attribution.  The default
%   value is \code{2em}.
%
% \DescribeMacro\PreTrib
% \DescribeMacro\PostTrib
%   When you write \cs\attrib{attribution}, \cs\PreTrib will immediately
%   precede \meta{attribution} and \cs\PostTrib will immediately follow it.
%   Notice how the attributions in the examples above were in parentheses, but
%   we didn't have to write them.  The default value of \cs\PreTrib is a left
%   parenthesis and the default value of \cs\PostTrib is a right parenthesis.
%   \cs\PreTrib and \meta{attribution} are executed inside a group that doesn't
%   include \PostTrib, and \cs\PostTrib is executed in a group all by itself,
%   like this:  \code{{\PreTrib\relax#1}{\PostTrib}}.  Honestly I can't tell
%   you right now why it's done this way, but I'm sure I have some good reason
%   for it!
%
% \DescribeMacro\AttribInit
%   \cs\AttribInit is an hook, empty by default, that gets executed after some
%   standard setup but before the core of the \cs\attrib macro.  It is executed
%   within a group that includes \cs\PreTrib, \meta{attribution}, and
%   \cs\PostTrib, so perhaps it is appropriate for a font style change or
%   something (I haven't made use of it myself).
%
% \StopEventually{}
%
% \part{Implementation}
%
% \section{Version control}
%
%  \begin{macro}{\fileinfo}
%  \begin{macro}{\DoXUsepackagE}
%  \begin{macro}{\HaveECitationS}
%  \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{attribution of block elements (Frankenstein's hat)}
\def\DoXPackageS {attrib,dialogue}
\def\initelyHavECitationS {}
\def\fileversion{v1.3}
\def\filedate{2001/08/31}
\def\docdate{2001/08/31}
\edef\PPOptArg {%
  \filedate\space \fileversion\space \fileinfo
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% If we're loading this file from a \cs\ProcessDTXFile command (see the
% \package{compsci} package), then \cs\JusTLoaDInformatioN will be defined;
% othewise we assume it is not (that's why the FunkY NamE).
% 
% If we're loading from \cs\ProcessDTXFile, we want to load the packages listed
% in \cs\DoXPackageS (needed to typeset the documentation for this file) and
% then bail out.  Otherwise, we're using this file in a normal way as a
% package, so do nothing.  \cs\DoXPackageS, if there are any, are declared in
% the \ext{dtx} file, and, if you're reading the typeset documentation of this
% package, would appear just above.  (It's OK to call \cs\usepackage with an
% empty argument or \cs\relax, by the way.)
%    \begin{macrocode}
\makeatletter% A special comment to help create bst files.  Don't change!
\@ifundefined{JusTLoaDInformatioN} {%
  }{% ELSE (we know the compsci package is already loaded, too)
  \UndefineCS\JusTLoaDInformatioN
  \SaveDoXVarS
  \eExpand\csname DoXPackageS\endcsname\In {%use \csname in case it's undefined
    \usepackage{#1}%
  }%
  \RestoreDoXVarS
  \makeatother
  \endinput
}% A special comment to help create bst files.  Don't change!
%    \end{macrocode}
%
% Now we check for \LaTeX2e and declare the LaTeX package.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{attrib}[\PPOptArg]
%    \end{macrocode}^^A special comment to help create bst files.  Don't change!
%
% ^^A NOTE: We have to compensate for the above backslashes, which are not
% ^^A       actually in the .dtx file the author works on, by adding to the
% ^^A       CheckSum.
%%
% \AddToCheckSum{17}^^A `dtx-update-checksum' automatically handles this.
% \AddToCheckSum{7}^^A The half a macrocode env. at the top is missed, however...
% \AddToCheckSum{10}^^A ... and so are the 5 \defs from the .dtx file 
%                   ^^A     that precede it.
% \IfCitations {%
%   \AddToCheckSum{2}^^A When \initelyHavECitationS is defined in
% }                  ^^A the .dtx file, we need 2 more in the CheckSum.
%
%
%    \begin{macrocode}
\RequirePackage{moredefs}
%    \end{macrocode}
%
% \section{Macros}
%
% \begin{macro}{\AttribMinSkip}
% \begin{macro}{\PreTrib}
% \begin{macro}{\PostTrib}
%   \mbox{}
%    \begin{macrocode}
\newlength{\AttribMinSkip}
  \setlength{\AttribMinSkip}{2em}
\newcommand\PreTrib {%
  (%
}
\newcommand\PostTrib {%
  )%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\AttribInit}
% \begin{macro}{\at@init}
%   This heart of this code is from the \TeX book \cite[106]{knuth:texbook}.
%   If you contribute anything to the horizontal or vertical list before the
%   \cs\unskip, it will cancel the effect of the \cs\unskip.  You probably
%   don't want to do that.
%    \begin{macrocode}
\ReserveCS\AttribInit
\newcommand\at@init {%
  \SaveCS\footnote
  \def\footnote {%
    \normalcitations\MDSavedfootnote
  }%
  \attribcitations
%    \end{macrocode}
% If there's a blank line before the \cs\attrib, we want to leave \cs\parskip
% extra space above.
%    \begin{macrocode}
  \ifhmode
    \unskip
  \fi
  \AttribInit
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
% \begin{macro}{\attribcitations}
%    Sets up citations for within an attrib-like environment.  Should probably
%    be called within a group.
%    \begin{macrocode}
\newcommand\attribcitations {%
  \SaveCS\PreCiteWork
  \SaveCS\PostCiteWork
  \def\PreCiteWork {%
    \csname
  }%
  \def\PostCiteWork {%
    \relax\end{lrbox}\usebox{\sc@box@a}%
  }%
  \SaveCS\PreCite
  \SaveCS\PostCite
  \let\PreCite\ShortEmpty
  \let\PostCite\ShortEmpty
}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\normalcitations}
%% FIX
% Would you ever want this and \cs\attribcitations defined outside of the scope
% of an \cs\attrib?  Perhaps \cs\let it to a warning outside of \cs\attrib.
%    \begin{macrocode}
\newcommand* \normalcitations {%
  \RestoreCS\PreCite
  \RestoreCS\PostCite
  \RestoreCS\PreCiteWork
  \RestoreCS\PostCiteWork
}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\attrib}
%   Knuth says that \cs\vadjust is more efficient here than \cs\hbox, but I
%   don't understand why: I guess it's simply a trivial non-discardable item on
%   the horizontal list \cite[316]{knuth:texbook}.
% FIX: I can get a page break after the text and before the attribution; it's
%   happening with attribstar and when the attribution is dropped to the next
%   line, but not sure if that's the only case (first quote in ``impotence''
%   section of library copy of dissertation).  Also pages 53, 57 of same.
%    \begin{macrocode}
\newcommand\attrib [1] {%
  \begingroup
    \at@init
    \nobreak\hfil\penalty50%
    \hskip\AttribMinSkip
    \vadjust{}\nobreak\hfil
    {\PreTrib\relax#1}{\PostTrib}%
    \parfillskip\z@
    \nobreak
    \finalhyphendemerits0%
    \par
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \part{Something you can't use}
%
% \begin{macro}{\attribstar}
%   There is one macro, \cs\attribstar, in this package that you can't use
%   because you don't have a package that I haven't released yet.  I don't want
%   to release it because it still has a couple of small but significant
%   problems that can lead to mistakes.  If I took \cs\attribstar out of this
%   package, however, I'd have to maintain two different versions of
%   \package{attrib}.  So here is a glimpse of a future bright star.
%
% \code{\DescribeMacro\attribstar}\par
%   Use this instead of a standard footnote in an attribution when you want the
%   note to appear on the page of the quotation.  That is, it is not a 
%   substantive note, but something like ``italics mine'' or ``ellipses in 
%   original'' which belongs there on the page, not in endnotes, in case
%   footnotes are ever moved there.
% \begin{comment}
% \begin{bothexample}
%   \begin{quote}
%     My mother was deeply religious.  So was my brother.  He knelt down at his
%     bed as long as he could kneel\lips.  [They] got no value from their
%     religion when they died.  At the moment of crisis it had no more depth
%     than an old-school tie\lips.  When you pass a church on an Irish bus, all
%     the hands flurry in the sign of the cross.  One day the dogs of Ireland
%     will do that too and perhaps also the pigs.
%   
%     \attribstar{\cite[25]{driver:beckett:madeleine}}{Driver ``reconstructs''
%     Beckett's words ``from notes made immediately after'' their conversation
%     \cite[22]{driver:beckett:madeleine}.}
%   \end{quote}
% \end{bothexample}
% \end{comment}
%
%    \begin{macrocode}
\newcommand\attribstar [2] {%
  \begingroup
    \addto@macro\PostTrib {%
      \normalcitations
      \starnote{#2}%
    }%
    \attrib{#1}%
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \Finale