From 144c4c8662089094eac38d906f571e3f5aefbee6 Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Mon, 4 Mar 2019 23:17:34 +0100 Subject: documentation almost completed --- icite.dtx | 281 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file 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[]{icite} +\end{code} +% \iffalse +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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{} % -- cgit v1.2.3