added a section on how to use the classics package with icite

1 files changed, 184 insertions, 44 deletions

diff --git a/icite.dtx b/icite.dtx
index 2b63455..95ec4d1 100644
--- a/icite.dtx
+++ b/icite.dtx
@@ -198,6 +198,17 @@ Running "make install" installs the files in the local TeX tree.
 (markup-locclass-list :open "\tabto{3.5cm}" :sep ", ")
 \end{filecontents*}
 \begin{filecontents*}{\jobname.bib}
+@Book{Aristotle:Politica,
+  title =        {Politica},
+  date =         1964,
+  author =       {Aristotle},
+  editor =       {Ross, W. D.},
+  origdate =     1957,
+  entrysubtype = {classical},
+  publisher =    {Clarendon Press},
+  location =     {Oxford}
+}
+
 @Book{Bürgel2016,
   shorttitle =   {Ärztliches Leben\ldots},
   editortype =   {reviser},
@@ -212,6 +223,16 @@ Running "make install" installs the files in the local TeX tree.
   author =       {Bürgel, Johann Christoph}
 }
 
+@Software{classics,
+  title =        {The Classics package},
+  subtitle =     {Cite classic works},
+  author =       {Lourenço de Lima, Eduardo C.},
+  publisher =    {CTAN},
+  url =          {http://www.ctan.org/pkg/classics},
+  date =         {2013-02-02},
+  version =      {0.1}
+}
+
 @Article{Dols1987,
   author =       {Dols, Michael W.},
   title =        {The Origins of the Islamic Hospital: Myth and
@@ -223,6 +244,19 @@ Running "make install" installs the files in the local TeX tree.
   pages =        {367--390}
 }
 
+@InBook{Endress1992,
+  title =        {Die Wissenschaftliche Literatur},
+  date =         1992,
+  author =       {Endress, Gerhard},
+  booktitle =    {Grundriß der arabischen Philologie},
+  editor =       {Fisher, Wolfdietrich},
+  volume =       3,
+  note =         {Supplement},
+  publisher =    {Reichert},
+  location =     {Wiesbaden},
+  pages =        {3--152}
+}
+
 @Book{IAUMuller,
   sortname =     {Ibn abi Usaybia},
   editor =       {Müller, August},
@@ -239,32 +273,19 @@ Running "make install" installs the files in the local TeX tree.
   volumes =      2
 }
 
-@MVBook{al-Nadim,
-  author =       {\prname{ibn al-nadIm}},
-  title =        {\arb[trans]{\uc{f}ihrist}},
-  sortname =     {Ibn al-Nadim},
-  date =         {1871/1872},
-  shorthand =    {\arb[trans]{\uc{f}ihrist}},
-  editor =       {Flügel, Gustav},
-  volumes =      2,
-  location =     {Leipzig},
-  entrysubtype = {classical}
-}
-
-@Book{al-Qifti,
-  sortname =     {Ibn al-Qifti},
-  entrysubtype = {classical},
-  shorthand =    {\prname{al-qif.tiyy}, \arb[trans]{\uc{t}a'rI_h}},
-  location =     {Leipzig},
-  editor =       {Lippert, Julius},
-  date =         1903,
-  title =        {\arb[trans]{\uc{t}a'rI_h al-.hukamA'}},
-  author =       {\prname{ibn al-qif.tiyy}}
+@Software{imakeidx,
+  title =        {The Imakeidx package},
+  subtitle =     {A package for producing multiple indexes},
+  author =       {Gregorio, Enrico and Beccari, Claudio},
+  publisher =    {CTAN},
+  url =          {http://www.ctan.org/pkg/imakeidx},
+  date =         {2016-10-15},
+  version =      {1.3e}
 }
 
 @Book{RaziShukuk,
-  author =       {\prname{al-rAziyy}, \prname{mu.hammad
-                  ibn zakariyyA'}},
+  author =       {\prname{al-rAziyy}, \prname{mu.hammad ibn
+                  zakariyyA'}},
   title =        {\arb[trans]{\uc{k}itAb al-^sukUk `al_A
                   \uc{^g}AlInUs}},
   indextitle =   {\arb[trans]{\uc{^s}ukUk}},
@@ -286,27 +307,37 @@ Running "make install" installs the files in the local TeX tree.
   author =       {Ullmann, Manfred},
 }
 
-@InBook{Endress1992,
-  title =        {Die Wissenschaftliche Literatur},
-  date =         1992,
-  author =       {Endress, Gerhard},
-  booktitle =    {Grundriß der arabischen Philologie},
-  editor =       {Fisher, Wolfdietrich},
-  volume =       3,
-  note =         {Supplement},
-  publisher =    {Reichert},
-  location =     {Wiesbaden},
-  pages =        {3--152}
+@MVBook{al-Nadim,
+  author =       {\prname{ibn al-nadIm}},
+  title =        {\arb[trans]{\uc{f}ihrist}},
+  sortname =     {Ibn al-Nadim},
+  date =         {1871/1872},
+  shorthand =    {\arb[trans]{\uc{f}ihrist}},
+  editor =       {Flügel, Gustav},
+  volumes =      2,
+  location =     {Leipzig},
+  entrysubtype = {classical}
+}
+
+@Book{al-Qifti,
+  sortname =     {Ibn al-Qifti},
+  entrysubtype = {classical},
+  shorthand =    {\prname{al-qif.tiyy}, \arb[trans]{\uc{t}a'rI_h}},
+  location =     {Leipzig},
+  editor =       {Lippert, Julius},
+  date =         1903,
+  title =        {\arb[trans]{\uc{t}a'rI_h al-.hukamA'}},
+  author =       {\prname{ibn al-qif.tiyy}}
 }
 
 @Software{usebib,
-  title = {The Usebib package},
-  subtitle = {A simple bibliography processor},
-  author = {Gregorio, Enrico},
-  publisher = {CTAN},
-  url = {http://www.ctan.org/pkg/usebib},
-  date = {2012-04-13},
-  version = {1.0a}
+  title =        {The Usebib package},
+  subtitle =     {A simple bibliography processor},
+  author =       {Gregorio, Enrico},
+  publisher =    {CTAN},
+  url =          {http://www.ctan.org/pkg/usebib},
+  date =         {2012-04-13},
+  version =      {1.0a}
 }
 \end{filecontents*}
 \usepackage[english]{babel}
@@ -347,11 +378,13 @@ Running "make install" installs the files in the local TeX tree.
 \makeindex
 \makeindex[name=loccit]
 \makeindex[name=primary]
+\usepackage{needspace}
 \usepackage{tabto}
 \usepackage{classics}
 \newclassic{iau}{\classicsRoman{#1}|, #1|.#1}
 \newclassic{razi}{#1|.#1}
 \newclassic{nadim}{\classicsRoman{#1}|.#1|, #1}
+\newclassic{aristotle}{#1|\textit{#1}|#1}
 \usepackage[scale=1.5]{ccicons}
 \usepackage{dox}
 \doxitem{Option}{option}{options}
@@ -874,9 +907,11 @@ Running "make install" installs the files in the local TeX tree.
 % those whose |entrysubtype| field does not match the string
 % |classical| should go into the default |loccit| index. As for those
 % whose |entrysubtype| matches |classical|, they should to into an
-% index named |primary|. Furthermore, the \package{classics} package
-% is used to format references in which a volume number is used. In
-% this way, \package{xindy} only has numbers to handle:--- %
+% index named |primary|. \label{ref:classics-pkg}Furthermore, the
+% \package{classics} package is used to format references in which a
+% volume number is used.\footnote{For more information, see below
+% \vref{sec:classics}.} In this way, \package{xindy} only has numbers
+% to handle:--- %
 % \iffalse
 %<*example>
 % \fi
@@ -965,6 +1000,109 @@ Running "make install" installs the files in the local TeX tree.
 % one can see, \prname{al-rAziyy} has been sorted under the letter R
 % and references to classical works have been formatted properly.
 %
+%
+% \subsection[The \textsf{classics} package]%
+% {The \package{classics} package} %
+% \label{sec:classics}
+% As said above \vpageref{ref:classics-pkg}, it is advisable to use
+% the \package{classics} package to format volume, page, column, line
+% numbers and the like which are inserted in the \meta{post} optional
+% argument of the \cs{icite} command\autocite{classics}. An example of
+% using \package{classics} to format references to Aristotle according
+% to Bekker pagination follows:\footnote{See \cite[2]{classics} for
+% more information.}--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % preamble:
+  \usepackage{classics}
+  \newclassic{aristotle}{#1|\textit{#1}|#1}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+  In \emph{Politics}, Aristotle says that man is by nature a political
+  animal in the following passages: \aristotle{1253}[a][2--9] (Book~1)
+  and again in \aristotle{1278}[b][19] (Book~3). The latter passage
+  shows that one should read the whole section of Book~1 concerning
+  household management and the control of slaves
+  (\aristotle*{1253}[b][1]{1253}[b][39]).
+\end{example}
+% \iffalse
+%</example>
+% \fi
+% The following prints the same body text while using \package{icite}
+% to have the passages cited inserted in the \emph{Index locorum
+% citatorum} (see below \vref{sec:index-loc-cit}):--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+  In \emph{Politics}, Aristotle says that man is by nature a political
+  animal in the following passages:
+  \icite[\aristotle{1253}[a][2--9]]{Aristotle:Politica}[notecite]
+  (Book~1) and again in \icite[\aristotle{1278}[b][19]]%
+  {Aristotle:Politica}[notecite] (Book~3). The latter passage shows
+  that one should read the whole section of Book~1 concerning
+  household management and the control of slaves
+  \icite[\aristotle*{1253}[b][1]{1253}[b][39]]%
+  {Aristotle:Politica}[pnotecite].
+\end{example}
+% \iffalse
+%</example>
+% \fi
+% As can be seen, the \cs{notecite} and \cs{pnotecite} commands have
+% been used to insert only the references in the body text.
+%
+% It is also advisable to use \package{xindy} to compile indices of
+% passages cited because \package{xindy}, unlike \package{makeindex}
+% or \package{xindex}, is able to sort numbers properly: for example,
+% with \package{xindy}, such a number as 81 will come before 100, but
+% will be sorted after 100 with the other two engines.
+% \begin{tcblisting}{text only, title=Caveat}
+%   \package{xindy} (actually |texindy|) is also designed to ignore
+%   \TeX\ commands by default. However, due to a missing line in
+%   |xindy/modules/base/tex.xdy|,\footnote{As the time of writing, in
+%   \package{xindy} v2.5.1.} this does not apply to so-called
+%   \enquote*{starred} \TeX\ commands, such as \cs{aristotle*} from
+%   the example above.
+% \end{tcblisting}
+% One easy way to get around this issue is to create a style file with
+% a single line that instructs \package{xindy} to ignore the asterisk
+% when processing the index, like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{minted language=lisp, listing only, title=icite.xdy}
+  (merge-rule "\*" "" :eregexp)
+\end{tcblisting}
+% \iffalse
+%</example>
+% \fi
+% 
+% The following example shows how this simple rule can be
+% applied:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % preamble:
+  \usepackage[xindy]{imakeidx}
+  \makeindex[name=loccit, options=-M icite.sty]
+  % document:
+  \printindex[loccit]
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% Of course, the document itself must be compiled with
+% |--shell-escape|.\footnote{See \cite[2--4]{imakeidx}.}
+%
 % \section{Appendix}
 % Designing the layout of indices is out of the scope of this
 % documentation. For information, the \package{tabto} package has been
@@ -985,7 +1123,9 @@ Running "make install" installs the files in the local TeX tree.
 % \label{ref:indices}
 % \subsubsection{Index of Passages Cited (modern authors)}
 % \printindex[loccit]
+% \needspace{8\baselineskip}
 % \subsubsection{\emph{Index locorum citatorum}}
+% \label{sec:index-loc-cit}
 % \printindex[primary]
 % 
 % \subsection{\texorpdfstring{\hologo{BibTeX}