% Copyright (C) 2013 Eduardo C. Lourenço de Lima
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license 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.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
\documentclass{ltxdoc}

\newcommand\fileversion{0.1}
\newcommand\filedate{February 2, 2013}

\usepackage{color}
\usepackage{classics}

\newpagination \books    {book}    {books}    { and }
\newpagination \parts    {part}    {parts}    { and }
\newpagination \sections {section} {sections} { and }
\newpagination \lines    {line}    {lines}    { and }

\newclassic[ to ]{Homer}  {\books{\classicsRoman{#1}}|, \lines{#1}}
\newclassic{Plato}        {#1|#1|#1}
\newclassic{Aristotle}    {#1|\textit{#1}|#1}
\newclassic{Stephanus}    {#1|\textit{#1}|#1}
\newclassic{Bekker}       {#1|\textit{#1}|#1}
\newclassic{Hume}         {#1|.#1|.#1}
\newclassic{HumeExample}  {\books{#1}|, \parts{#1}|, \sections{#1}}
\newclassic{HomerExample} {\books{\classicsRoman{#1}}|, \lines{#1}}

\definecolor{myblue}{rgb}{0,0.2,0.6}

\newenvironment     {Macros} {\begin{list}{}{\setlength\itemsep{0pt}\setlength\leftmargin{0pt}}}{\end{list}}
\newcommand\Macro        [2] {\item[\llap{\textsf{\color{myblue}\texttt{\char92}#1}}]#2}
\newcommand\MacroExample [2] {\item[\llap{\textsf{\texttt{\char92}#1}}]#2}
\newcommand\Note             {\par\textbf{Note:} }
\newcommand\etc              {\mbox{etc.}}
\newcommand\work         [1] {\textit{#1}}
\newcommand\badcite      [1] {\begingroup(\frenchspacing #1)\endgroup}

\begin{document}
\title{The \textsf{\color{myblue} classics} package,\thanks{This document
corresponds to \textsf{classics}~\fileversion, dated~\filedate.  I am grateful
to Joseph Wright and Scott \mbox{H.} for suggestions.}\\{or the end of
anachronism}}
\author{Eduardo C. Louren\c{c}o de Lima \\ \texttt{elourenco@phi.pro.br}}
\maketitle


        \begin{abstract}\noindent This package provides a basic framework to
        cite classic works in accordance with traditional pagination systems.
        It can also be used in conjunction with other citation
        packages.\end{abstract}

                           \section*{Introduction}

If you feel there is something wrong with ``Plato \badcite{1994: pp.  50--1}'',
``Aristotle \badcite{\work{Ethics}, 44}'' or ``Hume \badcite{2000: 303}'', this
package is for you.  The |classics| package provides a basic framework to cite
classic works in compliance with traditional pagination systems. For example:
        \begin{list}{}{\setlength\itemsep{0pt}\setlength\parskip{0pt}}
        \item[]\Stephanus [Theaetetus] {142}[d][4--5]
        \item[]\Bekker* [Nic. Eth.] {1179}[b][14]{1180}[a][29]
        \item[]\Hume[THN]{3}[1][2]
        \end{list}
Citation commands created by |classics| can also be used in conjunction with
other citations engines such as standard |\cite|, |biblatex|, |natbib|, \etc

                               \section{Synopsis}


\begin{Macros}
\Macro{newclassic}{\oarg{range separator} \marg{classic} \marg{list of formatting directives}}
\Macro{|<|classic|>| }{\oarg{work} \marg{page} \oarg{section}}
\Macro{|<|classic|>*|}{\oarg{work} \marg{page} \oarg{section} \marg{last page} \oarg{section}}
\Macro{newpagination}{\marg{pagination} \marg{singular} \marg{plural} \marg{conjunction}}
\Macro{|<|pagination|>|}{\marg{range}}
\Macro{DeclareClassicWorkFormat}{\marg{formatting directive}}

\end{Macros}

\newpage

                             \section{Basic usage}

\setlength\parindent{0pt}
\setlength\parskip{1ex}

        \begin{Macros}
        \Macro{newclassic}{\oarg{range separator} \marg{classic} \marg{list of formatting directives}}
        \end{Macros}

Creates a citation command |\|\meta{classic} based on a \meta{list of
formatting directives} separated by vertical bars. Each formatting directive
has its own |#1| and is used to declare the format in which to typeset the
reference to a subdivision of a classic work. There can be at most six such
directives. As an example:

        \begin{verbatim}\newclassic {Aristotle} {#1|\textit{#1}|#1}\end{verbatim}
would create a new citation command |\Aristotle|: 

        \begin{Macros}
        \MacroExample{Aristotle}{\oarg{work} \marg{page} \oarg{column} \oarg{line}}
        \MacroExample{Aristotle*}{\oarg{work} \marg{page} \oarg{column} \oarg{line} \marg{last page} \oarg{column} \oarg{line}}
        \end{Macros}
to typeset references in which letters for \meta{column} are printed in italic
type.  The starred version |\Aristotle*| is used to cite a range of two pages
separated by \meta{range separator}.

\Note |\Aristotle*| will not typeset \meta{last page} if \meta{page} and
\meta{last page} are the same.  However, \meta{last page} will be preserved if
|\Aristotle*| is created by the starred version |\newclassic*|.

        \begin{Macros}
        \Macro{newpagination} \marg{pagination} \marg{singular} \marg{plural} \marg{conjunction}
        \end{Macros}

Creates a command \meta{pagination} to typeset \meta{singular} or \meta{plural}
depending on whether subsequent arguments to \meta{pagination} are
singular or plural.  As an example:

\begin{verbatim}\newpagination {\pages} {page} {pages} { and }\end{verbatim}
would create the command |\pages|:
        \begin{Macros}
        \MacroExample{pages} \marg{range} 
        \end{Macros}

that automatically typesets |page| \meta{range} if \meta{range} is singular, or
|pages| \meta{range} if \meta{range} is plural, that is, if it contains a
comma, a hyphen, a dash, or \meta{conjunction}.

{\Note} \meta{conjunction} might need to be enclosed in spaces.

        \begin{Macros}
        \Macro{DeclareClassicWorkFormat}{\marg{formatting directive}}
        \end{Macros}
Defines the format to typeset classic titles in. The default \meta{formatting directive} is |\textit{#1}|.

\newpage

        \begin{Macros}
        \Macro{classicsalph}{\marg{integer}}
        \Macro{classicsAlph}{\marg{integer}}
        \Macro{classicsroman}{\marg{integer}}
        \Macro{classicsRoman}{\marg{integer}}
        \end{Macros}

These commands may come in handy if you want to typeset a subdivision as a
letter or Roman numeral, lowercase or uppercase.

                            \section{Advanced usage}

\begingroup
\DeclareClassicWorkFormat{\textit{#1},}

You may combine |\newclassic| and |\newpagination| to create complex
citation styles. For example:
        \begin{Macros}
        \Macro{Hume}{\oarg{work} \marg{book} \oarg{part} \oarg{section}}
        \end{Macros}
can be created by:
        \begin{verbatim}
\DeclareClassicWorkFormat{\textit{#1},}
\newpagination  {\books}    {book}    {books}    { and }
\newpagination  {\parts}    {part}    {parts}    { and }
\newpagination  {\sections} {section} {sections} { and }
\newclassic {Hume} {\books{#1}|, \parts{#1}|, \sections{#1}}
\end{verbatim}
so that: \begin{verbatim}\Hume[Treatise]{3}[1][2]\end{verbatim}would typeset
``\HumeExample[Treatise]{3}[1][2]''.

\begin{Macros}
\Macro{Homer}{\oarg{work} \marg{book} \oarg{lines}}
\end{Macros}
can be created by:

\begin{verbatim}
\DeclareClassicWorkFormat{\textit{#1},}
\newpagination {\books} {book} {books} { and }
\newpagination {\lines} {line} {lines} { and }
\newclassic {Homer} {\books{\classicsRoman{#1}}|, \lines{#1}}
\end{verbatim}
so that:
\begin{verbatim}\Homer[Odyssey]{3}[100--2]\end{verbatim}
will typeset: ``\HomerExample[Odyssey]{3}[100--2]''.
\endgroup


                               \subsection{Caveat}

Citation styles created by the |classics| package can also be used in
conjunction with standard |\cite|, |biblatex|, |natbib|, \etc

A simple |classics| pagination command created by |\newpagination| can be used
directly within the optional argument to |\cite|:

\begin{Macros}
\Macro{cite} |[\pages|\marg{number}|]| \marg{key}
\end{Macros}

However, a complex |classics| citation command created by |\newclassic| can be
used within the optional argument to |\cite| only if it is enclosed in braces.

\begin{Macros}
\Macro{cite} |[{\Homer|\marg{book}\oarg{line}|}]| \marg{key}
\end{Macros}

For example:
\begin{verbatim}
\documentclass{article}
\usepackage{classics}
\newclassic{Homer}{#1|:#1}
\begin{document}

\cite[{\Homer{3}[100--2]}]{Odyssey}

\begin{thebibliography}{10}
 \bibitem[Od.]{Odyssey} Homer. \textit{Odyssey}.
\end{thebibliography}

\end{document}
\end{verbatim}



                               \section{Examples}

\begingroup
\setlength\parindent{0pt}
\small

                               \subsection{Plato}


\verb=\newclassic{Plato}{#1|#1|#1}=

|\Plato {142}[a]                          |\Plato  {142}[a]\par
|\Plato {142}[a][3]                       |\Plato  {142}[a][3]\par
|\Plato {142}[a][3--4]                    |\Plato  {142}[a][3--4]\par
|\Plato*{142}[a][3]{142}[b]               |\Plato* {142}[a][3]{142}[b]\par
|\Plato*{142}[a][3]{142}[b][4]            |\Plato* {142}[a][3]{142}[b][4]\par
|\Plato*{142}[a][3]{143}[b]               |\Plato* {142}[a][3]{143}[b]\par
|\Plato*{142}[a][3]{143}[b][4]            |\Plato* {142}[a][3]{143}[b][4]\par
|\Plato [Theaet.]{142}[a][3]              |\Plato  [Theaet.]{142}[a][3]\par
|\Plato*[Theaet.]{142}[a][3]{143}[b][4]   |\Plato* [Theaet.]{142}[a][3]{143}[b][4]\par

                             \subsection{Aristotle}

\verb=\newclassic {Aristotle} {#1|\textit{#1}|#1}=\par\medskip

|\Aristotle        {185}                         |\Aristotle        {185}\par
|\Aristotle        {185}[a]                      |\Aristotle        {185}[a]\par
|\Aristotle*       {185}[a]{185}[b]              |\Aristotle*       {185}[a]{185}[b]\par
|\Aristotle*       {185}[a]{185}[b][2]           |\Aristotle*       {185}[a]{185}[b][2]\par
|\Aristotle*       {185}[a]{186}                 |\Aristotle*       {185}[a]{186}\par
|\Aristotle*       {185}[a]{186}[a]              |\Aristotle*       {185}[a]{186}[a]\par
|\Aristotle*       {185}[a]{186}[a][3]           |\Aristotle*       {185}[a]{186}[a][3]\par
|\Aristotle [Phys.]{}                            |\Aristotle [Phys.]{}\par
|\Aristotle [Phys.]{185}                         |\Aristotle [Phys.]{185}\par
|\Aristotle [Phys.]{185}[a]                      |\Aristotle [Phys.]{185}[a]\par
|\Aristotle*[Phys.]{185}[a]{185}[b]              |\Aristotle*[Phys.]{185}[a]{185}[b]\par
|\Aristotle*[Phys.]{185}[a]{185}[b][2]           |\Aristotle*[Phys.]{185}[a]{185}[b][2]\par
|\Aristotle*[Phys.]{185}[a]{186}                 |\Aristotle*[Phys.]{185}[a]{186}\par
|\Aristotle*[Phys.]{185}[a]{186}[a]              |\Aristotle*[Phys.]{185}[a]{186}[a]\par
|\Aristotle*[Phys.]{185}[a]{186}[a][3]           |\Aristotle*[Phys.]{185}[a]{186}[a][3]\par
|\Aristotle*[Phys.]{185}[a]{186}[a][3--5]        |\Aristotle*[Phys.]{185}[a]{186}[a][3--5]\par
|\Aristotle [Phys.]{185}[a][10]                  |\Aristotle [Phys.]{185}[a][10]\par
|\Aristotle [Phys.]{185}[a][10--2]               |\Aristotle [Phys.]{185}[a][10--2]\par
|\Aristotle*[Phys.]{185}[a][10]{185}[b]          |\Aristotle*[Phys.]{185}[a][10]{185}[b]\par
|\Aristotle*[Phys.]{185}[a][10]{185}[b][2]       |\Aristotle*[Phys.]{185}[a][10]{185}[b][2]\par
|\Aristotle*[Phys.]{185}[a][10]{186}             |\Aristotle*[Phys.]{185}[a][10]{186}\par
|\Aristotle*[Phys.]{185}[a][10]{186}[a]          |\Aristotle*[Phys.]{185}[a][10]{186}[a]\par
|\Aristotle*[Phys.]{185}[a][10]{186}[a][3]       |\Aristotle*[Phys.]{185}[a][10]{186}[a][3]\par
|\Aristotle*[Phys.]{185}[a][10]{186}[a][3--5]    |\Aristotle*[Phys.]{185}[a][10]{186}[a][3--5]\par

                               \subsection{Homer}

\begingroup
\DeclareClassicWorkFormat{\textbf{#1},}

\verb=\DeclareClassicWorkFormat{\textbf{#1},}=\par
\verb=\newclassic[ to ]{Homer}{\books{\classicsRoman{#1}}|, \lines{#1}}=\par

|\Homer {2}[100]                    |\Homer {2}[100]\par
|\Homer {2}[100--4]                 |\Homer {2}[100--4]\par
|\Homer*{2}[100]{3}[80]             |\Homer*{2}[100]{3}[80]\par
|\Homer [Iliad]{2}[100]             |\Homer [Iliad]{2}[100]\par
|\Homer*[Iliad]{2}[100]{3}[80]      |\Homer*[Iliad]{2}[100]{3}[80]\par
\endgroup

\endgroup

\end{document}
