documentation almost completed

1 files changed, 269 insertions, 12 deletions

diff --git a/icite.dtx b/icite.dtx
index 35d314d..f977239 100644
--- a/icite.dtx
+++ b/icite.dtx
@@ -92,6 +92,52 @@ Running "make install" installs the files in the local TeX tree.
 \documentclass{ltxdoc}
 \usepackage{filecontents}
 \begin{filecontents*}{\jobname.bib}
+@Book{Bürgel2016,
+  shorttitle =   {Ärztliches Leben\ldots},
+  editortype =   {reviser},
+  editor =       {Käs, Fabian},
+  number =       135,
+  series =       {Islamic History and Civilization},
+  location =     {Leiden},
+  publisher =    {Brill},
+  date =         2016,
+  title =        {Ärztliches Leben und Denken im arabischen
+                  Mittelalter},
+  author =       {Bürgel, Johann Christoph}
+}
+
+@Article{Dols1987,
+  author =       {Dols, Michael W.},
+  title =        {The Origins of the Islamic Hospital: Myth and
+                  Reality},
+  shorttitle =   {The Origins of the Islamic Hospital},
+  journaltitle = {Bulletin of the History of Medicine},
+  date =         1987,
+  volume =       61,
+  pages =        {367--390}
+}
+
+@Book{Ullmann1970,
+  location =     {Leiden},
+  publisher =    {Brill},
+  title =        {Die Medizin im Islam},
+  date =         1970,
+  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}
+}
+
 @software{usebib,
   title = {The Usebib package},
   subtitle = {A simple bibliography processor},
@@ -109,6 +155,9 @@ Running "make install" installs the files in the local TeX tree.
 \usepackage{newunicodechar}
 \newunicodechar{ǧ}{ǧ} % Old Standard does not include ǧ/Ǧ
 \newunicodechar{Ǧ}{Ǧ} %
+\usepackage{arabluatex}
+\SetTranslitConvention{loc}
+\usepackage{varioref}
 \usepackage{hyperxmp}
 \usepackage{uri}
 \usepackage[numbered]{hypdoc}
@@ -126,12 +175,14 @@ Running "make install" installs the files in the local TeX tree.
   pdfmetalang={en-US}, pdftype={Text}, pdfkeywords={bibtex, biblatex,
     indexing}}
 \CodelineIndex
-\usepackage[citecmd=footcite,defaultindex]{\jobname}
+\usepackage[citecmd=autocite,defaultindex]{\jobname}
+\usepackage{cleveref}
 \bibinput{icite}
 \usepackage[nonewpage,xindy]{imakeidx}
 \indexsetup{level=\section}
-\makeindex[intoc]
-\makeindex[name=loccit, title=Modern Authors]
+\makeindex[columns=3]
+\makeindex[columns=3,name=loccit, title=Index of Passages Cited
+(modern authors)\label{ind:loccit}]
 \usepackage[scale=1.5]{ccicons}
 \usepackage{dox}
 \doxitem{Option}{option}{options}
@@ -143,7 +194,8 @@ Running "make install" installs the files in the local TeX tree.
 \usepackage[lot]{multitoc}
 \usepackage{nameref}
 \usepackage{csquotes}
-\usepackage[style=oxnotes]{biblatex}
+\usepackage[style=oxnotes, hyperref=false]{biblatex}
+\DeclareFieldFormat{postnote}{\mkpageprefix[pagination][\mknormrange]{#1}}
 \addbibresource{icite.bib}
 \usepackage{hologo,metalogox}
 \usepackage{relsize}
@@ -155,8 +207,8 @@ Running "make install" installs the files in the local TeX tree.
 \usepackage[breakable, skins, xparse, minted]{tcolorbox}
 \tcbset{colback=white, boxrule=.15mm, colframe=red!50!white, left=6mm,
   breakable}
-\newtcblisting{iexample}{minted options=linenos}
-\newtcblisting{icode}{minted options=linenos, listing only}
+\newtcblisting{example}{minted options=linenos}
+\newtcblisting{code}{minted options=linenos, listing only}
 \usepackage{etoc}
 \etocsettocdepth{paragraph}
 \newcommand{\icitetableofcontents}{%
@@ -178,9 +230,9 @@ Running "make install" installs the files in the local TeX tree.
   \tableofcontents
   \endgroup}
 \EnableCrossrefs
-%\CodelineIndex
+ %\CodelineIndex
 \RecordChanges
-%\OnlyDescription
+ %\OnlyDescription
 \begin{document}
  \DocInput{\jobname.dtx}
  \PrintChanges
@@ -330,12 +382,217 @@ Running "make install" installs the files in the local TeX tree.
 % The \package{icite} package is but a modest piece of software which
 % addresses this situation. It relies on citation commands, but does
 % not require Bib\LaTeX. Instead, \hologo{BibTeX} can be used as
-% \package{icite} uses the \package{usebib} package\icite{usebib} to
-% build the indices by drawing directly from the bibliographic
-% database.
+% \package{icite} uses the \package{usebib}
+% package\footnote{\cite{usebib}} to build the indices by drawing
+% directly from the bibliographic database.
+%
+%
+% \section[The \package{icite} package]{The \textsf{icite} package}
+% The \package{icite} package is loaded as usual like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  \usepackage[<options>]{icite}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% \package{icite} may be loaded with two optional \enquote*{named
+% arguments} either of which is set using the syntax
+% \meta{key}$=$\meta{value}. The description of the optional arguments
+% follows:---
+%
+% \DescribeOption{citecmd}
+% |citecmd|$=$\meta{command}\hfill\tcboxverb{Default: cite}\\
+% \meta{command} may be any citation command accepted by
+% \hologo{BibTeX} or Bib\LaTeX. This option is used by the \cs{icite}
+% command that is described below. By default, \cs{icite} uses the
+% \cs{cite} command to insert citations in the body text.
+%
+% \DescribeOption{defaultindex}
+% |defaultindex|$=$|none|\verb+|+\meta{index\_name}\hfill%
+% \tcboxverb{Default: not set}\\
+% \meta{index\_name} is the name of the index in which all passages
+% cited with the \cs{icite} command are to be found by default. As
+% this option is not initally set, \cs{icite} naturally inserts cited
+% passages in the default general index, unless |defaultindex| is set
+% to the value |none|, in which case indexing is disabled. It must be
+% noted that this named argument does not need a value as it defaults
+% to |loccit| if it is used alone. This is an easy way to have all
+% passages cited indexed in a separate index named |loccit|.
+%
+% \paragraph{Bibliographic database}
+% \DescribeMacro{\bibinput} Once \package{icite} is loaded, it must be
+% connected to at least one bibliographic |.bib| file. To that end,
+% \package{icite} uses the same \cs{bibinput} command as
+% \package{usebib}.\footnote{Please refer to \cite[1]{usebib} for more
+% detailed information on how to use this command.} An example
+% follows:---
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % load icite, have \icite use \autocite by default, and insert cited
+  % passages in a separate index named 'loccit':
+  \usepackage[citecmd=autocite, defaultindex]{icite}
+  % note that the .bib file must be stripped of its extension:
+  \usebib{bibliography} % that is: load bibliography.bib
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Styling the titles}
+% \DescribeMacro{\SetTitleStyle} By default, \package{icite} prints
+% the titles of the works in
+% italics. \cs{SetTitleStyle}\marg{for\-matting directives} can be used
+% in the preamble only to customize the way titles are displayed in
+% the indices, like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  \SetTitleStyle{\textbf{#1}}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% As this example shows, |#1| is the token that is replaced with the
+% actual title in the formatting directives of the \cs{SetTitleStyle}
+% command.
+%
+% \subsection{Entry fields}
+% \subsubsection{Author names}
+% To process author names, \package{icite} uses the following entry
+% fields:
+% \begin{description}
+% \item[author] As for example in |author = {Ullmann, Manfred}|, which
+% is satisfactory in most cases.
+% \item[indexauthor] This field is not set by Bib\LaTeX. However, it
+% may be used as a fallback field for multiple or complex names.
+% \item[sortname] This standard Bib\LaTeX\ which is never printed may
+% be used to modify the sorting order of the index entries.
+% \end{description}
+%
+% \paragraph{Example}
+% From a given entry such as: \\[1ex]%
+% |author = {|\prname{.hunayn ibn 'is.hAq al-`ibAdiyy, 'abU
+% zayd}|}|\\[1ex]%
+% it may prove useful to define an additional |indexauthor| field to
+% have printed in the index only the relevant part of the name, like
+% so: \\[1ex]%
+% |indexauthor = {|\prname{.hunayn ibn 'is.hAq}|}|\\[1ex]
+% But in the end, the |sortname| field is also needed because the name
+% must be sorted without the diacritics:\\[1ex]%
+% |sortname = {|Hunayn ibn Ishaq|}|
+%
+% \subsection{Titles}
+% To process titles, \package{icite} uses the following entry fields:
+% \begin{description}
+% \item[title] The full title of the work.
+% \item[shorttitle] The title in an abbriged form. If this entry is
+% set, it takes precedence over the |title| field in the printed index.
+% \item[indextitle] This field may be used to have a title such as
+% \emph{The {\TeX}Book} printed in the index as \emph{{\TeX}Book, The}.
+% \item[indexsorttitle] Like |sortname| for author names, this field is
+% used for sorting only and is never printed. From the previous
+% example, it may be used like so: \\%
+% |indexsorttitle = {TEXBook}|
+% \end{description}
+% 
+% \section{Basic use}
+% \DescribeMacro{\icite} \package{icite} provides the \cs{icite}
+% command which both inserts a formatted citation in the body text and
+% an entry corresponding to the passage cited in the index. This
+% command is to be used in place of any \hologo{BibTeX} or Bib\LaTeX\
+% citation command the syntax of which is
+% \cs{command}\oarg{pre}\oarg{post}\marg{key}. It must be noted that
+% only standard citation commands are supported, with the exception of
+% those mentioned as qualified citation lists or so-called
+% \enquote*{multicite} commands. The full syntax of \cs{icite}
+% follows:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  \icite[pre][post]{key}[command]
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% Where \oarg{command} can be used as a further optional argument to
+% specify a standard citation command that \cs{icite} should emulate
+% instead of the default \cs{cite} command or any other command set as
+% default in the preamble by means of the |citecmd| global option.
+%
+% \paragraph{Example} The following example illustrates how
+% \package{icite} can be used in combination with Bib\LaTeX\ and the
+% \package{imakeidx} package to have the passages cited sorted and
+% printed in a separate, specific \enquote*{Index of Passages
+% Cited}:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+  % preamble
+  % load icite, have \icite use \autocite by default, and insert cited
+  % passages in a separate index named 'loccit':
+  \usepackage[citecmd=autocite, defaultindex]{icite}
+  % load bibliography.bib
+  \usebib{bibliography}
+
+ % load biblatex (with oxnotes, \autocite acts as \footcite)
+ \usepackage[style=oxnotes]{biblatex}
+ \addbibresource{bibliography.bib} % mind the extension here
+
+ % load imakeidx and use xindy to have the numbers sorted properly
+ \usepackage[xindy]{imakeidx}
+ \makeindex[name=loccit, title=Index of passages cited]
+\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}
+
+  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
+%
+% The resulting \emph{Index of passages cited} can be found below
+% (\vref{ind:loccit} \vpageref{ind:loccit}). 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
+% preamble, the \enquote*{oxnotes} Bib\LaTeX\ option of
+% \package{biblatex-oxref} style package makes \cs{autocite} behave
+% like \cs{footcite}. Finally, the page numbers in the index are
+% sorted properly: for example, two-digit numbers, like 81, are listed
+% before 123.
+%
+% \section{Refined use}
+% 
 %
 % \printindex[loccit]
-% \printbibliography[heading=bibnumbered]
 % 
 %\StopEventually{}
 %