%\iffalse
% quotepas.dtx generated using makedtx version 0.91b (c) Nicola Talbot
% Command line args:
%   -src "(quotepas\.sty)=>\1"
%   -doc "manual.tex"
%   -author "Nicola Talbot"
%   -dir "source"
%   quotepas
% Created on 2007/5/22 13:53
%\fi
%\iffalse
%<*package>
%% \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         \~}
%</package>
%\fi
% \iffalse
% Doc-Source file to use with LaTeX2e
% Copyright (C) 2007 Nicola Talbot, all rights reserved.
% \fi
% \iffalse
%<*driver>
\documentclass{ltxdoc}

\usepackage[colorlinks,bookmarks]{hyperref}
\usepackage{quotepas}

\newcommand{\sty}[1]{\textsf{#1}}
\newcommand{\env}[1]{\textsf{#1}}
\CheckSum{90}

\begin{document}
\DocInput{quotepas.dtx}
\end{document}
%</driver>
%\fi
%\title{quotepas.sty v1.0: \LaTeXe\ Package for 
%quoting predefined passages}
%\author{Nicola Talbot}
%\date{23rd Dec 2005}
%\maketitle
%\tableofcontents
%
%\section{Introduction}
%
%The \sty{quotepas} package was designed to allow you to quote
%predefined passages. It was originally designed to quote
%bible passages, but can be used for any quotations. The
%passages are stored in a database. The name of the database
%is specified using the command\DescribeMacro{\quotepasdatabase}:
%\par\vspace{10pt}\noindent
%\verb|\quotepasdatabase{|\meta{filename}\verb|}|
%\par\vspace{10pt}\noindent
%For example, if the database is contained in the file
%\texttt{sampledb.tex}, then the following should be placed
%in the preamble:
%\begin{verbatim}
%\quotepasdatabase{sampledb}
%\end{verbatim}
%
%Within the database file, individual passages are stored
%using the command\DescribeMacro{\newquotepas}:
%\par\vspace{10pt}\noindent
%\verb|\newquotepas{|\meta{label}\verb|}{|\meta{text}\verb|}|
%\par\vspace{10pt}\noindent
%For example:
%\begin{verbatim}
%\newquotepas{Gen1v1}{In the beginning God created
%the heavens and the earth.}
%\end{verbatim}
%
%Each passage can then be inserted into the document using the
%command\DescribeMacro{\quotepas}:
%\par\vspace{10pt}\noindent
%\verb|\quotepas{|\meta{label}\verb|}|
%\par\vspace{10pt}\noindent
%For example, to insert the above passage:
%\begin{verbatim}
%\quotepas{Gen1v1}
%\end{verbatim}
%You can combine passages by using a comma-separated list of
%labels. For example, if your database contains the 
%following:
%\begin{verbatim}
%\newquotepas{Gen1v1}{In the beginning God created
%the heavens and the earth.}
%                                                          
%\newquotepas{Gen1v2}{Now the earth was a formless
%void, there was darkness over the deep, and God's spirit
%hovered over the water.}
%                                                          
%\newquotepas{Gen1v3}{\qupar God said, `Let there
%be light', and there was light.}
%\end{verbatim}
%then the three verses can be inserted using
%\begin{verbatim}
%\quotepas{Gen1v1,Gen1v2,Gen1v3}
%\end{verbatim}
%The command \verb|\qupar|\DescribeMacro{\qupar} indicates
%that this verse should start a new paragraph if it is not
%the first one in the list used in \verb|\quotepas|. So,
%\begin{verbatim}
%\quotepas{Gen1v1,Gen1v2,Gen1v3}
%\end{verbatim}
%will have a paragraph break between verse~2 and verse~3, but
%the following won't:
%\begin{verbatim}
%\quotepas{Gen1v1} \quotepas{Gen1v2} \quotepas{Gen1v3}
%\end{verbatim}
%
%Of course, you could just define all three verses in one
%block:
%\begin{verbatim}
%\newquotepas{Gen1v1-3}{In the beginning God created
%the heavens and the earth.
%Now the earth was a formless
%void, there was darkness over the deep, and God's spirit
%hovered over the water.
%
%God said, `Let there be light', and there was light.}
%\end{verbatim}
%and use \verb|\quotepas{Gen1v1-3}|. It all depends on how many
%of your documents are using an individual database. The
%advantage in storing each verse singly is that one document
%my quote, say, verse~1, but another may quote verses~1 and~2.
%
%\section{Customising the Output}
%The quotation will be inserted within the 
%\env{qupformat}\DescribeEnv{qupformat} environment.
%This by default does nothing, but can be redefined. For example,
%to set the passage within double quotes:
%\begin{verbatim}
%\renewenvironment{qupformat}{``}{''}
%\end{verbatim}
%Using the passages defined in the previous section, note the
%difference between \verb|\quotepas{Gen1v1,Gen1v2,Gen1v3}|:
%``In the beginning God created
%the heavens and the earth.
%Now the earth was a formless
%void, there was darkness over the deep, and God's spirit
%hovered over the water.
%                                                                  
%God said, `Let there be light', and there was light.''
%and \verb|\quotepas{Gen1v1}| 
%\verb|\quotepas{Gen1v2}|
%\verb|\quotepas{Gen1v3}|:
%``In the beginning God created the heavens and the earth.''
%``Now the earth was a formless void, there was darkness over the 
%deep, and God's spirit hovered over the water.''
%``God said, `Let there be light', and there was light.''
%
%As noted earlier, \verb|\qupar| should be used in the
%quotation definition if there should be a paragraph break
%at that point, but only if this passage is not the first
%listed in the command \verb|\quotepas|. If you want a paragraph
%break to be inserted at that point even if it is the first
%listed, use the starred version of \verb|\quotepas|, e.g.\ 
%\verb|\quotepas*{Gen1v3}|. 
%
%The command \verb|\qupar| can be redefined it you want any
%additional text to occur at the start of the paragraph. For
%example, if you have redefined \env{qupformat} as
%\begin{verbatim}
%\renewenvironment{qupformat}{``}{''}
%\end{verbatim}
%it would also be advisable to redefine \verb|\qupar| so
%that inserts a new opening double quote at the start of the
%new paragraphs:
%\begin{verbatim}
%\renewcommand{\qupar}{\par``}
%\end{verbatim}
%
%The command \verb|\quotepassep| is inserted between each
%passage. By default this is a space, but can be redefined.
%
%\section{Quotepas.pl}
%
%As with BiB\TeX, you can have a large database, and use an
%application, in this case a Perl script called quotepas.pl,
%to select only the passages that have been referenced in the
%document. Each entry in this database should be entered
%in the form:
%\par\vspace{10pt}\noindent
%\verb|<|\texttt{quotepas}\verb|>|\\
%\verb|<label>|\meta{label}\verb|</label>|
%\verb|<block>|\meta{text}\verb|</block>|
%\verb|</|\texttt{quotepas}\verb|>|
%\par\vspace{10pt}\noindent
%For example:
%\par\vspace{10pt}\noindent
%\begin{ttfamily}\obeylines
%\verb|<|quotepas\verb!>!
%\verb+<+label\verb->- Gen1v1\verb|</|label\verb|>|
%<block>In the beginning God created
%the heavens and the earth.\verb|</|block\verb!>!
%\verb|</|quotepas\verb!>!
%\end{ttfamily}
%\par\vspace{10pt}\noindent
%The Perl script can either be called as:
%\begin{verbatim}
%quotepas.pl <aux file> <database>
%\end{verbatim}
%or
%\begin{verbatim}
%perl quotepas.pl <aux file> <database>
%\end{verbatim}
%depending on your system, where \meta{aux file} is the
%name of the auxiliary file and \meta{database} is the name
%of the database. The Perl script will determine the
%name of the output file (the file given in 
%\verb|\quotepasdatabase|) from the auxiliary file.
%
%For example, if your document is saved in \texttt{sample.tex},
%and the database is contained in \texttt{database.qup}, then
%do
%\begin{verbatim}
%latex sample
%quotepas.pl sample.aux database.qup
%latex sample
%\end{verbatim}
%
%If you have a very large database, this is recommended as
%it reduces the memory requirements of \TeX, since each
%\verb|\newquotepas| command defines a new command containing
%the given text.
%
%\section{Contact Details}
%\begin{tabular}{l}
%Dr Nicola Talbot\\
%School of Computing Sciences\\
%University of East Anglia\\
%Norwich. Norfolk. NR4 7TJ.\\
%United Kingdom\\
%\url{http://theoval.cmp.uea.ac.uk/~nlct/}
%\end{tabular}
%
%
%\StopEventually{}
%\section{The Code}
%\iffalse
%    \begin{macrocode}
%<*quotepas.sty>
%    \end{macrocode}
%\fi
% Declare package
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{quotepas}[2005/12/23 v1.0 (N.L.C. Talbot)]
%    \end{macrocode}
% Database name is specified by the command
% |\quotepasdatabase{|\meta{name}|}|\DescribeMacro{\quotepasdatabase}.
% This should go in the preamble, or at the very least before
% any instances of |\quotepas|
%    \begin{macrocode}
\newcommand*{\quotepasdatabase}[1]{%
\@bsphack
\protected@write\@auxout{}{\string\@quotepasdatabase{#1}}%
\@esphack
\InputIfFileExists{#1}{}{\PackageWarning{quotepas}{File
'#1' not found.}}}
\newcommand*{\@quotepasdatabase}[1]{}
%    \end{macrocode}
% Quotation is stored using the command 
%|\newquotepas{|\meta{label}|}{|\meta{text}|}|\DescribeMacro{\newquotepas}
% First argument is a label, the second is the text of the
% quotation.
% This defines a new command constructed from the label.
%    \begin{macrocode}
\newcommand{\newquotepas}[2]{%
\@ifundefined{@qup@#1}{%
\expandafter\long\expandafter\def\csname @qup@#1\endcsname{#2}}{%
\PackageError{quotepas}{Quote label '#1' already 
defined}{Each quote label must be unique.}}}
%    \end{macrocode}
% Quotation is displayed using the command 
%|\quotepas{|\meta{label list}|}|\DescribeMacro{\quotepas}
% The unstarred version will ignore any occurance of |\qupar|
% in the first item of the \meta{label list}. The starred
% version won't. First determine whether or not the starred form
% is being used:
%    \begin{macrocode}
\newcommand*{\quotepas}{\@ifstar\@squotepas\@uquotepas}
%    \end{macrocode}
% Starred version:
%    \begin{macrocode}
\newcommand*{\@squotepas}[1]{{\def\@qup@resetp@r{}%
\def\@qup@unsetp@r{}\@quotep@s{#1}}}
%    \end{macrocode}
% Unstarred version
%    \begin{macrocode}
\newcommand{\@uquotepas}[1]{{%
\def\@qup@resetp@r{\let\qupar\org@qupar}%
\def\@qup@unsetp@r{\let\org@qupar\qupar\let\qupar\relax}%
\@quotep@s{#1}}}
%    \end{macrocode}
% Do the general bits
%    \begin{macrocode}
\newcommand*{\@quotep@s}[1]{%
\begin{qupformat}%
\let\@qup@sp\relax
\@qup@unsetp@r
\@for\@qup:=#1\do{\@qup@sp\let\@qup@sp\quotepassep
\@bsphack
\protected@write\@auxout{}{\string\@quotepas{\@qup}}%
\@esphack
\@ifundefined{@qup@\@qup}{\PackageWarning{quotepas}{Quote 
label '\@qup' undefined}}{%
\csname @qup@\@qup\endcsname}%
\@qup@resetp@r
}\end{qupformat}}
\newcommand*{\@quotepas}[1]{}
%    \end{macrocode}
% The command |\qupar| can be used to indicate that a
% passage should start a new paragraph, if listed in a
% comma-separated list.
%    \begin{macrocode}
\newcommand{\qupar}{\par}
%    \end{macrocode}
% The command |\quotepassep| specifies what to put
% between passages if listed in a comma-separated list.
% The default is a space.
%    \begin{macrocode}
\newcommand*{\quotepassep}{ }
%    \end{macrocode}
% The environment |qupformat|\DescribeEnv{qupformat}
% determines how the quotation should be formatted. Does
% nothing by default, but can be redefined by the user.
%    \begin{macrocode}
\newenvironment{qupformat}{}{}
%    \end{macrocode}
%\iffalse
%    \begin{macrocode}
%</quotepas.sty>
%    \end{macrocode}
%\fi
%\Finale
\endinput
