From da60a4f5c772acb67e5ed681d2335651d1dbbcd6 Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Tue, 5 Mar 2019 21:16:48 +0100
Subject: done documenting icite

---
 icite.dtx | 392 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 367 insertions(+), 25 deletions(-)

(limited to 'icite.dtx')

diff --git a/icite.dtx b/icite.dtx
index f977239..3772420 100644
--- a/icite.dtx
+++ b/icite.dtx
@@ -4,17 +4,119 @@
 \iffalse
 %</internal>
 %<*readme>
-|
--------:| -----------------------------------------------------------------
-  icite:| Make Indices locorum citatorum
- Author:| Robert Alessi
- E-mail:| alessi@robertalessi.net
-License:| Released under the GNU General Public License v3 or later
-    See:| http://www.gnu.org/licenses/
+---
+author:
+- Robert Alessi
+title: 'The icite package – README file'
+---
 
+Overview
+========
+
+`icite` is designed to produce from BibTeX or BibLaTeX bibliographical
+databases the different indices of authors and works cited which are
+called \emph{indices locorum citatorum}. It relies on a specific
+`\icite` command and can operate with either BibTeX or BibLaTeX.
+
+License and disclamer
+=====================
+
+icite – Indices locorum citatorum
+
+Copyright ⓒ 2019 Robert Alessi
+
+Please send error reports and suggestions for improvements to Robert
+Alessi:
+
+-   email: <alessi@robertalessi.net>
+
+-   website: <http://www.robertalessi.net/icite>
+
+-   comments, feature requests, bug reports:
+    <https://gitlab.com/ralessi/icite/issues>
+
+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 3 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, see &lt;http://www.gnu.org/licenses/&gt;.
+
+This release of icite consists of the following source files:
+
+-   `icite.dtx`
+
+-   `icite.ins`
+
+-   `Makefile`
+
+License applicable to the documentation 
+---------------------------------------
+
+Copyright ⓒ 2019 Robert Alessi
+
+The documentation file `icite.pdf` that is generated from the
+`icite.dtx` source file is licensed under the Creative Commons
+Attribution-ShareAlike 4.0 International License. To view a copy of this
+license, visit <http://creativecommons.org/licenses/by-sa/4.0/> or send
+a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+Installation 
+============
+
+1.  Run `'latex icite.ins'` to produce the `icite.sty`
+    file;
+
+2.  To finish the installation you have to move the `icite.sty` file into
+    a directory where LaTeX can find them. See the FAQ on `texfaq.org`
+    at <https://texfaq.org/FAQ-inst-wlcf> for more on this.
+
+
+Development, Git Repository 
+===========================
+
+Browse the code 
+---------------
+
+You can browse icite repository on the web:
+<http://git.robertalessi.net/icite>
+
+From this page, you can download all the releases of `icite`. For
+instructions on how to install `icite`, please see above.
+
+Comments, Feature requests, Bug Reports 
+---------------------------------------
+
+<https://gitlab.com/ralessi/icite/issues>
+
+Download the repository 
+-----------------------
+
+`icite` development is facilitated by git, a distributed version
+control system. You will need to install git (most GNU/Linux
+distributions package it in their repositories).
+
+Use this command to download the repository
+
+    git clone http://git.robertalessi.net/icite
+
+A new directory named icite will have been created, containing
+`icite`.
+
+Git hosting 
+-----------
+
+Make an account on <https://gitlab.com> and navigate (while logged in)
+to <https://gitlab.com/ralessi/icite>. Click *Fork* and you will
+have in your account your own repository of `icite` where you will
+be able to make whatever changes you like to.
 
-Short description:
-Some text about the package: probably the same as the abstract.
 %</readme>
 %<*internal>
 \fi
@@ -48,8 +150,8 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see
 <http://www.gnu.org/licenses/>.
 
-This work consists of the file icite.dtx and a Makefile.
-Running "make" generates the derived files README, icite.pdf and icite.sty.
+This work consists of the file icite.dtx, icite.ins and a Makefile.
+Running "make" generates the derived files README.md, icite.pdf and icite.sty.
 Running "make inst" installs the files in the user's TeX tree.
 Running "make install" installs the files in the local TeX tree.
 
@@ -69,7 +171,7 @@ Running "make install" installs the files in the local TeX tree.
 \nopreamble\nopostamble
 \usedir{doc/latex/icite}
 \generate{
-  \file{README.txt}{\from{\jobname.dtx}{readme}}
+  \file{README.md}{\from{\jobname.dtx}{readme}}
 }
 \ifx\fmtname\nameofplainTeX
   \expandafter\endbatchfile
@@ -91,6 +193,9 @@ Running "make install" installs the files in the local TeX tree.
 %<*driver>
 \documentclass{ltxdoc}
 \usepackage{filecontents}
+\begin{filecontents*}{\jobname.xdy}
+(markup-locclass-list :open "\tabto{3.5cm}" :sep ", ")
+\end{filecontents*}
 \begin{filecontents*}{\jobname.bib}
 @Book{Bürgel2016,
   shorttitle =	 {Ärztliches Leben\ldots},
@@ -117,6 +222,61 @@ Running "make install" installs the files in the local TeX tree.
   pages =	 {367--390}
 }
 
+@Book{IAUMuller,
+  sortname =	 {Ibn abi Usaybia},
+  editor =	 {Müller, August},
+  author =	 {\prname{ibn 'abI 'u.saybi`aT}},
+  shorteditor =	 {Müller},
+  date =	 {1882/1884},
+  title =	 {\arb[trans]{\uc{`u}yUn al-'anbA' fI .tabaqAt
+                  al-'a.tibbA'}},
+  shorttitle =	 {\arb[trans]{\uc{`u}yUn al-'anbA'}},
+  shorthand =	 {\prname{ibn 'abI 'u.saybi`aT},
+                  \arb[trans]{\uc{`u}yUn al-'anbA'}},
+  entrysubtype = {classical},
+  location =	 {Königsberg and Cairo},
+  volumes =	 2
+}
+
+@MVBook{al-Nadim,
+  author =	 {\prname{ibn al-nadIm}},
+  title =	 {\arb[trans]{\uc{f}ihrist}},
+  sortname =	 {Nadim},
+  date =	 {1871/1872},
+  shorthand =	 {\arb[trans]{\uc{f}ihrist}},
+  editor =	 {Flügel, Gustav},
+  volumes =	 2,
+  location =	 {Leipzig},
+  entrysubtype = {classical}
+}
+
+@Book{al-Qifti,
+  sortname =	 {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}}
+}
+
+@Book{RaziShukuk,
+  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}},
+  sortname =	 {Razi},
+  date =	 1993,
+  shorthand =	 {\prname{al-rAziyy}, \arb[trans]{\uc{^s}ukUk}},
+  editor =	 {Mehdi Mohaghegh},
+  publisher =	 {International Institute of Islamic Thought and
+                  Civilization},
+  location =	 {Tehran},
+  entrysubtype = {classical}
+}
+
 @Book{Ullmann1970,
   location =	 {Leiden},
   publisher =	 {Brill},
@@ -138,7 +298,7 @@ Running "make install" installs the files in the local TeX tree.
   pages =	 {3--152}
 }
 
-@software{usebib,
+@Software{usebib,
   title = {The Usebib package},
   subtitle = {A simple bibliography processor},
   author = {Gregorio, Enrico},
@@ -177,12 +337,21 @@ Running "make install" installs the files in the local TeX tree.
 \CodelineIndex
 \usepackage[citecmd=autocite,defaultindex]{\jobname}
 \usepackage{cleveref}
+\IndexSubtypeAs{classical}{primary}
 \bibinput{icite}
 \usepackage[nonewpage,xindy]{imakeidx}
-\indexsetup{level=\section}
-\makeindex[columns=3]
-\makeindex[columns=3,name=loccit, title=Index of Passages Cited
-(modern authors)\label{ind:loccit}]
+\indexsetup{level=\subsubsection*}
+\makeindex
+\makeindex[name=loccit, title=Index of Passages Cited (modern authors)]
+\makeindex[name=primary, title=\emph{Index locorum citatorum}]
+\usepackage{idxlayout}
+\idxlayout{hangindent=3.5cm, subindent=1em, font=footnotesize,
+  totoc=true}
+\usepackage{tabto}
+\usepackage{classics}
+\newclassic{iau}{\classicsRoman{#1}|, #1|.#1}
+\newclassic{razi}{#1|.#1}
+\newclassic{nadim}{\classicsRoman{#1}|.#1|, #1}
 \usepackage[scale=1.5]{ccicons}
 \usepackage{dox}
 \doxitem{Option}{option}{options}
@@ -563,23 +732,24 @@ Running "make install" installs the files in the local TeX tree.
   \section*{\cs{icite} in action}
   Let us start with four citations of the same reference, to make sure
   that they are all indexed and sorted properly:
-  one\icite[123]{Ullmann1970}, two,\icite[231]{Ullmann1970}
-  three,\icite[81]{Ullmann1970} and four.\icite[18]{Ullmann1970}
+  one\icite[123]{Ullmann1970}, two\icite[231]{Ullmann1970},
+  three\icite[81]{Ullmann1970} and four\icite[18]{Ullmann1970}.
 
   Let us continue with four other citations out of two other
-  references: one,\icite[90]{Bürgel2016} two,\icite[370]{Dols1987}
-  three,\icite[205]{Bürgel2016} and four.\icite[380]{Dols1987}
+  references: one\icite[90]{Bürgel2016}, two\icite[370]{Dols1987},
+  three\icite[205]{Bürgel2016} and four\icite[380]{Dols1987}.
 
   Finally, let us have \cs{icite} use \cs{textcite} to cite
   \icite[123]{Endress1992}[textcite], and again, this time in a
-  footnote.\icite[86]{Endress1992}
+  footnote\icite[86]{Endress1992}.
 \end{example}
 % \iffalse
 %</example>
 % \fi
 %
-% The resulting \emph{Index of passages cited} can be found below
-% (\vref{ind:loccit} \vpageref{ind:loccit}). As can be seen from the
+% All indices and the contents of the \hologo{BibTeX} file that has
+% been used can be found below in the appendix (\vref{ref:indices}
+% and \vref{ref:icite-bib} respectively). As can be seen from the
 % bibliography generated in the footnotes, \package{icite} prints as
 % expected the abbridged forms of the titles when they are
 % available. Furthermore, as a default citation command set in the
@@ -590,10 +760,182 @@ Running "make install" installs the files in the local TeX tree.
 % before 123.
 %
 % \section{Refined use}
+% When references are made not only to modern authors but also to
+% authors and works from classical antiquity or from the Middle Ages,
+% it is commonly agreed that at least two separate indices of passages
+% cited should be made. Another option is not to index passages cited
+% from modern authors at all.
+%
+% \DescribeMacro{\IndexSubtypeAs} \package{icite} is able to
+% differentiate between sources by drawing from the bibliographical
+% database the exact string that may be found in the |entrysubtype|
+% entry field. To that end, the \cs{IndexSubtypeAs} command is
+% provided. It takes to madatory arguments, like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  \IndexSubtypeAs{<subtype>}{<index_name>}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% Where |<subtype>| is any given string used to specify an
+% |entrysubtype| in the bibliographical database, and |<index_name>|
+% the name of the index which the authors matching that subtype must
+% go into. This command is to be found in the preamble only.
+%
+% Of course different subtypes can be associated with a single index
+% or with different indices. That said, one should keep in mind that
+% any entry the actual subtype of which is not associated with an
+% index is processed as if it had no subtype at all. Examples
+% follow:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % load icite, and have cited authors indexed in an index named
+  % 'secondary':
+  \usepackage[defaultindex=secondary]{icite}
+  % except for authors whose 'entrysubtype' field matches the string
+  % 'classical': have them indexed in an index named 'primary':
+  \IndexSubtypeAs{classical}{primary}
+  % authors whose 'entrysubtype' field matches the string 'medieval'
+  % should go into the same index:
+  \IndexSubtypeAs{medieval}{primary}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% Or:
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % load icite, but do not index passages cited with \icite:
+  \usepackage[defaultindex=none]{icite}
+  % except for authors whose 'entrysubtype' field matches the string
+  % 'classical': have them indexed in an index named 'primary':
+  \IndexSubtypeAs{classical}{primary}
+  % authors whose 'entrysubtype' field matches the string 'medieval'
+  % should go into the same index:
+  \IndexSubtypeAs{medieval}{primary}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Example} In the following example, modern authors, namely
+% 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:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % preamble
+  \usepackage[style=oxnotes]{biblatex}
+  \addbibresource{bibliography.bib}
+
+  \usepackage[xindy]{imakeidx}
+  \makeindex[name=loccit, title=Index of passages cited (modern
+  authors)]
+  \makeindex[name=primary, title=\emph{Index locorum citatorum}]
+
+  \usepackage{classics}
+  \newclassic{iau}{\classicsRoman{#1}|, #1|.#1}
+  \newclassic{razi}{#1|.#1}
+  \newclassic{nadim}{\classicsRoman{#1}|.#1|, #1}
+  
+  \usepackage[citecmd=autocite,defaultindex]{icite}
+  \IndexSubtypeAs{classical}{primary}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% 
+% Then \cs{icite} can be used like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+  \section*{\cs{icite} in action}
+  Let us start with four citations of the same reference, to make sure
+  that they are all indexed and sorted properly:
+  one\icite[123]{Ullmann1970}, two\icite[231]{Ullmann1970},
+  three\icite[81]{Ullmann1970} and four\icite[18]{Ullmann1970}.
+
+  Let us continue with four other citations out of two other
+  references: one\icite[90]{Bürgel2016}, two\icite[370]{Dols1987},
+  three\icite[205]{Bürgel2016} and four\icite[380]{Dols1987}.
+
+  Before concluding, let us insert a few references to medieval Arabic
+  authors: one\icite[\iau{1}[81][32]]{IAUMuller},
+  two\icite[\razi{5}[7--10]]{RaziShukuk}, three\icite[133]{al-Qifti},
+  four\icite[\nadim{3}[7][286]]{al-Nadim},
+  five\icite[\iau{2}[214][20]]{IAUMuller},
+  six\icite[\razi{1}[6--20]]{RaziShukuk},
+  seven\icite[126.15--20]{al-Qifti} and
+  eight\icite[\nadim{3}[7][291]]{al-Nadim}.
+
+  Finally, let us have \cs{icite} use \cs{textcite} to cite
+  \icite[123]{Endress1992}[textcite], and again, this time in a
+  footnote\icite[86]{Endress1992}.
+\end{example}
+% \iffalse
+%</example>
+% \fi
 % 
+% As already said above, all indices and the contents of the
+% \hologo{BibTeX} file that has been used can be found below in the
+% appendix (\vref{ref:indices} and \vref{ref:icite-bib}
+% respectively). As one can see, \prname{ibn al-nadIm}, \prname{ibn
+% al-qif.tiyy} and \prname{al-rAziyy} have been sorted under the
+% letters N, Q and R respectively and references to classical works
+% have been formatted properly.
+%
+% \section{Appendix}
+% Designing the layout of indices is out of the scope of this
+% documentation. For information, the \package{idxlayout} and
+% \package{tabto} packages have been used in the preamble like
+% so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+\usepackage{idxlayout}
+\idxlayout{hangindent=3.5cm, subindent=1em, font=footnotesize,
+  totoc=true}
+\usepackage{tabto}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% In combination with the following |xindy| style file:---
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{minted language=lisp, listing only, title=icite.xdy}
+(markup-locclass-list :open "\tabto{3.5cm}" :sep ", ")
+\end{tcblisting}
+% \iffalse
+%</example>
+% \fi
 %
+% \subsection{Indices}
+% \label{ref:indices}
 % \printindex[loccit]
+% \printindex[primary]
 % 
+% \subsection{\texorpdfstring{\hologo{BibTeX}
+% file used in this document}{BibTeX file used in this document}}
+% \label{ref:icite-bib}
+% \tcbinputlisting{minted options={linenos}, minted language=bibtex,
+% listing file=icite.bib, listing only}
+%
 %\StopEventually{}
 %
 % \section{Implementation}
@@ -651,7 +993,7 @@ Running "make install" installs the files in the local TeX tree.
 % \DescribeMacro{\IndexSubtypeAs} \cs{IndexSubtypeAs} takes two
 % mandatory arguments: 1. Any given keyword used to specify an
 % \enquote*{entrysubtype} in the bibliographical database and 2. The
-% index in which the authors matching that subtype must go. This
+% index which the authors matching that subtype must go into. This
 % command is to be found in the preamble only.
 %    \begin{macrocode}
 \NewDocumentCommand{\IndexSubtypeAs}{m m}{%
-- 
cgit v1.2.3

