path: root/macros/latex/contrib/corridx/corridx.dtx

% \iffalse meta-comment
%
% Copyright (C) Johannes Fink
% -----------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% 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.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{corridx}
%<package> [2005/05/05 v1.0 Chemical Index]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{corridx}

\EnableCrossrefs

\CodelineIndex

\RecordChanges

%\OnlyDescription

\begin{document}
\DocInput{corridx.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{2005/05/05}{Initial version}
%
% \GetFileInfo{corridx.sty}
%
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\@ne}
% \DoNotIndex{\advance,\begingroup,\catcode,\closein}
% \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup}
% \DoNotIndex{\bgroup,\egroup,\newcommand}
% \DoNotIndex{\ifx,\fi}
% \DoNotIndex{\let}
%
% \title{The \textsf{corridx} package
% \thanks{This document corresponds to \textsf{corridx}~\fileversion,
% dated \filedate.}}
% \author{Johannes Fink\\ \texttt{fink@unileoben.ac.at}}
%
% \maketitle
%
% \begin{abstract}
%
% The package introduces a sort entry for chemical names that are
% preceded by numbers and other prefixes to ensure a correct
% ordering in the index.
%
% \end{abstract}
%
% \section{Introduction}
%
% Chemical Names often have preceding numbers or other prefiexes
% that do not contribute to the alphabetic sorting of the respective
% index entry. This drawback can be circumvented by introducing sort
% keys into the index entry. Such as
% \verb"\index{dimethylbenzene@1,3-Dimethylbenzene}". The
% \textit{corridx} package does this automatically.
%
% Previously a Pascal program entitled \textit{CorrIdx} was used as a
% preprocessor for the \textit{makeindex} program to insert these
% key entries into the index entry.
%
% Now a \LaTeX\space macro package is available. This package includes all the
% necessary modifications directly in the |*.idx| file.
%
%
%
% \subsection{Clashes}
% The package |corridx| has a different approach
% in comparison to the package |index| and will
% not work with this package and maybe also with
% other similar packages.
% A package error
% is forced when the package |index| is loaded.
% The package works together with |makeidx|.
%
% \section{Usage}
%
% \subsection{Predefined Index Types}
%
% There are always the forms |\ia| and |\noia|, |\ib| and |\noib|,
% |\ic| and |\noic|, |\ig| and |\noig|.
% The |\no..| form places an index in the |*.idx| file, whereas the |\i.| form places both text and
% index.
%
% \DescribeMacro{\ia}
%  The command |\ia| (index acronym) is used as
% |\ia{1,2-butanediol}{1,2-BD}|
% and places in the text "1,2-butanediol (1,2-BD)"
% and in the index |*.idx|
% \newline
% |\indexentry{acr bd@1,2-BD!\nopagebreak 1,2-Butanediol}{1}|
%
% \DescribeMacro{\ic}
% % The command |\ic| is used as |\ic{1,2-butanediol}| and places in the text
%  "1,2-butanediol"  and in the index |*.idx| \newline
%     |\indexentry{chem butanediol@1,2-Butanediol}{1}|.
%
% \DescribeMacro{\ib}
% The command |\ib| (\textbf{both} acronym and chemical index )
% is used as \newline |\ib{1,2-butanediol}{1,2-BD}| and places in
% the text
% "1,2-butanediol (1,2-BD)"  and in the index |*.idx|
%
% \begin{verbatim}
% \indexentry{chem butanediol@\begin{crrdxchem}1,2-Butanediol\end{crrdxachem}}{1}
% \indexentry{acr bd@1,2-BD\nopagebreak!\begin{crrdxacr}1,2-Butanediol\end{crrdxacr}}{1}
% \end{verbatim}
%
% \DescribeMacro{\ig}
% |\ig| (index general) places both in the index and the text, The macro has two arguments,
% the first being optional.
% The first optional argument is appended in the index to the second
% and is suppressed in the text for |\ig|.
% |\ig[!unsaturated]{polyester}| places in the text "polyester" and
% in the index
% |\indexentry{gen polyester@Polyester!unsaturated}{2}|.
% To use |\ig| with one argument, |\ig{polyester}| places places in the text "polyester"
% and in the index |*.idx| |\indexentry{gen polyester@Polyester}{2}|
%
% \StopEventually{\PrintIndex}
%
% \subsection{Define Yourself an Index Entry Type}
% The index entry is structured by several variables to have freedom
% in the output. A typical definition of an index looks like
%
% \begin{verbatim}
% \newcommand{\myindex}[x]{%
% \bgroup%
% \def\crrdx@key@prefix{keyprefix}%
% % here is the key inserted
% \def\crrdx@key@ostfix{keypostfix}%
% \def\crrdx@sep@@{@separator@}%
% \def\crrdx@entry@prefix{entryprefix}%
% % here is the entry inserted,
% % with the first letter capitalized
% \def\crrdx@entry@postfix{entrypostfix}%
% \def\crrdx@fmt@page{formatpage}%
% \def\crrdx@sfc@prerun{\crrdx@sfc@prerun@default}
% \def\crrdx@key@prerun{\crrdx@key@prerun@default}
% \crrdx@fmt@index@entry{thekey}{thecapitalizedentry}%
% \egroup%
% \end{verbatim}
%  In the foregoing definition we give the variables in the order as
%  they are placed by the macro \verb"\crrdx@fmt@index@entry".
% There are more macros to be defined by the user, as are really
% necessary in most cases, but this kind of structuring may be
% helpful to achieve the desired result more easily.
%
% Look for the definitions of \verb"\noia", \verb"\noic",
% \verb"\noig" to have a feeling how to use the variables.
%
% \subsection{Auxiliary Commands}
%
%
% \DescribeMacro{\crrdxformatpage} This macro sets a postfix in the index
% entry for page formatting. Use the command \newline
% \verb"\crrdxformatpage{chem}{|textit}" \newline to get in the chemical
% index the page number in italic. To make the page number for a
% chemical index in boldface, place the command
% \verb"\crrdxformatpage{chem}{|textbf}". This holds for all subsequent
% entries, if placed in the main text. However, you can redefine the
% environment |figure|, by including the |\crrdxformatpage| command to
% get a special page formatting only there.
%
% For example, the definition
% \begin{verbatim}
%   \renewenvironment{figure}%
%   {\@float{figure}\crrdxformatpage{chem}{|textit}}%
%   {\end@float}%
% \end{verbatim}
% causes chemical index entries to be \textit{italic} only in the figure environment,
% of course, if switched off outside.
% Do not use |\ic| within the caption, but use |\noic| outside the caption.
%
% Similarly use the commands \newline |\crrdxformatpage{acr}{}| and \newline |\crrdxformatpage{gen}{}|,
% or \newline \verb"\crrdxformatpage{gen}{|textbf}".
%
% You can also use your own defined formats.
%
% \DescribeMacro{crrdxenvchem} \DescribeMacro{crrdxenvacr} We define empty environments that can be later used
% for special settings in the index. For example, you can define some characters as active there.
% In my personal copy I use to define this environment
% \verb"\selectlanguage{chemical}".
% The \verb"chemical" package is not available from the \LaTeX\space mirrors.
% You can download it from \verb"http://www.unileoben.ac.at/~fink/papers/welcome.html"
% somewhat downwards, in the \LaTeX section.
%
% \subsection{Index Sectioning}
%
% \begin{macro}{\sectioncrrdx}
%  This macro can be used to place an index heading that is included without
% numbering into the table of contents. Example:
%\begin{verbatim*}
%\index{acr  @\sectioncrrdx{Acronyms}\swallow|swallow}%
%\index{chem  @\sectioncrrdx{Chemicals}\swallow|swallow}%
%\index{gen  @\sectioncrrdx{General}\swallow|swallow}%
%\end{verbatim*}
% |\swallow| ensures that no comma and page number will come into the entry.
% Take care to place the section entry at the top of the other entries,
% by placing one space more behind \verb*+chem  +, etc. than in the other
% related entries.
% \end{macro}
%
% \section{Implementation}
% \subsection{Main Entries}
%
% \begin{macro}{\ic}
% |\ic{1,2-chemname}| places |1,2-chemname| in the text and
% places an index entry, formatted as |chem chemname@1,2-chename|.
%    \begin{macrocode}
\newcommand{\ic}[1]{\begin{crrdxchem}#1\end{crrdxchem}\noic{#1}}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\noic}
% |\noic{1,2-chemname}| places an index entry, formatted as \newline
% |chem chemname@1,2-chename|.
% We encapsule the whole macro by grouping.
%    \begin{macrocode}
\newcommand{\noic}[1]{%
\bgroup%
\def\crrdx@key@prefix{chem }%
\def\crrdx@key@ostfix{}%
\def\crrdx@sep@@{@}%
\def\crrdx@entry@prefix{\string\begin{crrdxchem}}%
\def\crrdx@entry@postfix{\string\end{crrdxchem}}%
\def\crrdx@fmt@page{\crrdx@fmtpage@chem}%
\def\crrdx@sfc@prerun{\crrdx@sfc@prerun@default}%
\def\crrdx@key@prerun{\crrdx@key@prerun@default}%
\crrdx@fmt@index@entry{#1}{#1}%
\egroup%
}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ia} This is the acronym entry.
% It places the acronym in the text and in the index
%    \begin{macrocode}
\newcommand{\ia}[2]{#1 \mbox{(#2)}\noia{#1}{#2}}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\noia} This places the acronym in the index.
%    \begin{macrocode}%
\newcommand{\noia}[2]{%
\bgroup%
\def\crrdx@key@prefix{acr }%
\def\crrdx@key@ostfix{}%
\def\crrdx@sep@@{@}%
\def\crrdx@entry@prefix{#2\string\nopagebreak!\string\begin{crrdxacr}}%
\def\crrdx@entry@postfix{\string\end{crrdxacr}}%
\def\crrdx@fmt@page{\crrdx@fmtpage@acr}%
\def\crrdx@sfc@prerun{\crrdx@sfc@prerun@default}%
\def\crrdx@key@prerun{\crrdx@key@prerun@default}%
\crrdx@fmt@index@entry{#2}{#1}%
\egroup%
}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ib \noib}
% |\ib| and |\noib| are macros to place both a chemical index and an
% acronym. |\ib| places both the index and the text, whereas |\noib|
% places only both index entries. The macros have two arguments,
% e.g., |\ib{1,2-chemname}{CN}|.
%    \begin{macrocode}
\newcommand{\noib}[2]{\noic{#1}\noia{#1}{#2}}%
\newcommand{\ib}[2]{\ic{#1}\noia{#1}{#2}}%
%    \end{macrocode}
% \end{macro}
% |\ig| and |\noig| are macros to place a general index.
% \begin{macro}{\ig}
%    \begin{macrocode}
\newcommand{\ig}[2][]{%
#2%
\noig[#1]{#2}%
}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\noig}
% This macro formats a general index entry.
%    \begin{macrocode}
\newcommand{\noig}[2][]{%
\bgroup%
\def\crrdx@key@prefix{gen }%
\def\crrdx@key@ostfix{}%
\def\crrdx@sep@@{@}%
\def\crrdx@entry@prefix{}%
\def\crrdx@entry@postfix{#1}%
\def\crrdx@fmt@page{\crrdx@fmtpage@gen}%
\def\crrdx@sfc@prerun{\crrdx@sfc@prerun@default}%
\def\crrdx@key@prerun{\crrdx@key@prerun@default}%
\crrdx@fmt@index@entry{#2}{#2}%
\egroup%
}%
%    \end{macrocode}
% \end{macro}
%
% \subsection{Auxiliary Commands}
% \begin{macro}{\crrdxformatpage} This macro set a postfix for page formatting.
%    \begin{macrocode}
\newcommand{\crrdxformatpage}[2]{\@namedef{crrdx@fmtpage@#1}{#2}}%
\crrdxformatpage{chem}{\@empty}%
\crrdxformatpage{acr}{\@empty}%
\crrdxformatpage{gen}{\@empty}%
%    \end{macrocode}
% \end{macro}
% The |makeindex| program describes the following
% commands for page formatting:
% \begin{verbatim}
% \providecommand{\ii}[1]{{\it#1}}%
% \providecommand{\bb}[1]{{\bf#1}}%
% \end{verbatim}
% e.g., for index boldface pagenumber as last entry in the
% |\index| command \verb"|bb".
% However we not use this type,
% we use rather%
% \verb"|textit}" or \verb"|textbf".
% \begin{environment}{crrdxchem} We define an empty environment that can be later used
% for special chemical language settings.
%    \begin{macrocode}
\newenvironment{crrdxchem}{}{}%
%    \end{macrocode}
% \end{environment}
% \begin{environment}{crrdxacr} We define an empty environment that can be later used
% for special settings for acronyms.
%    \begin{macrocode}
\newenvironment{crrdxacr}{}{}%
%    \end{macrocode}
% \end{environment}
%
% \subsection{Formatting the Key}
%
% \begin{macro}{\crrdx@key} This macro scans the entry and removes
% every non-letter character. The key is placed in the index
% before the |@| as sorting aid.
%    \begin{macrocode}
\newcommand{\crrdx@key}[1]{%
\crrdx@key@prerun%
\edef\crrdx@key@temp{#1}%
\edef\crrdx@key@var{\@empty}%
\let\end\@empty%
\expandafter\crrdx@key@loop\crrdx@key@temp\end%
}%
%    \end{macrocode}
%    \begin{macrocode}
\newcommand{\crrdx@key@loop}[1]{%
\let\next=\crrdx@key@loop%
\ifx#1\end\let\next=\relax\fi%
\ifcat\noexpand#1a\lowercase{\edef\crrdx@key@var{\crrdx@key@var#1}}\fi%
\next}%
%    \end{macrocode}
% The following text formats are skipped in the key:
%    \begin{macrocode}
\newcommand{\crrdx@key@prerun@default}%
{%
\renewcommand{\textrm}[1]{{\noexpand\textrm{##1}}}%
\renewcommand{\textbf}[1]{{\noexpand\textbf{##1}}}%
\renewcommand{\textsf}[1]{{\noexpand\textsf{##1}}}%
\renewcommand{\texttt}[1]{{\noexpand\texttt{##1}}}%
\renewcommand{\textmd}[1]{{\noexpand\textmd{##1}}}%
\renewcommand{\textit}[1]{{\noexpand\textit{##1}}}%
\renewcommand{\textsc}[1]{{\noexpand\textsc{##1}}}%
\renewcommand{\textsl}[1]{{\noexpand\textsl{##1}}}%
\renewcommand{\textup}[1]{{\noexpand\textup{##1}}}%
\def~{\string~}%
}%
%    \end{macrocode}
% If you want to skip a normal text in the key, then format it as |\textup|.
% \subsection{Formatting the Entry}
% \end{macro}
% \begin{macro}{\crrdx@sfc@prerun}
% After scanning the key, we want to use the formats again
% with a different expansion than when doing the key.
%    \begin{macrocode}
\newcommand{\crrdx@sfc@prerun@default}%
{%
\renewcommand{\textrm}{\string\textrm}%
\renewcommand{\textbf}{\string\textbf}%
\renewcommand{\textsf}{\string\textsf}%
\renewcommand{\texttt}{\string\texttt}%
\renewcommand{\textmd}{\string\textmd}%
\renewcommand{\textit}{\string\textit}%
\renewcommand{\textsc}{\string\textsc}%
\renewcommand{\textsl}{\string\textsl}%
\renewcommand{\textup}{\string\textup}%
\def~{\string~}%
}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\crrdx@fmt@index@entry}
% This macro formats the input into the index.
%    \begin{macrocode}
\newcommand{\crrdx@fmt@index@entry}[2]{%
\crrdx@key{#1}%
\crrdx@sfc{#2}%
\edef\crrdx@fmt@index@entry@var{%
\crrdx@key@prefix%
\crrdx@key@var%
\crrdx@key@ostfix%
\crrdx@sep@@%
\crrdx@entry@prefix%
\crrdx@sfc@var%
\crrdx@entry@postfix%
\crrdx@fmt@page}%
\index{\crrdx@fmt@index@entry@var}%
}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\crrdx@sfc@loop}
% We want to capitalize the first letter automatically. We start to declare the loop
% used in |\crrdx@sfc|.
% We scan the entry to find the first letter. This we are capitalizing
% and then we switch to scan what is left over from |#1|.
%    \begin{macrocode}
\newcommand{\crrdx@sfc@loop}[1]{%
\crrdx@sfc@prerun%
\let\next=\crrdx@sfc@loop%
\ifx#1\end\let\next=\relax\fi%
\ifcat\noexpand#1a%
%    \end{macrocode}
% A letter is found
%    \begin{macrocode}
\uppercase{\edef\crrdx@sfc@var{\crrdx@sfc@var#1}}%
%    \end{macrocode}
% make it uppercase.
% We scan now the rest what is left over in |#1| and add it to the |\crrdx@sfc@var|.
%    \begin{macrocode}
\let\next=\crrdx@sfc@loop@leftover%
\else%
\edef\crrdx@sfc@var{\crrdx@sfc@var#1}%
\fi%
\next}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\crrdx@sfc@loop@leftover} Collects the stack |#1| after finding a letter.
%    \begin{macrocode}
\newcommand{\crrdx@sfc@loop@leftover}[1]{%
\let\next=\crrdx@sfc@loop@leftover%
\ifx#1\end\let\next=\relax\fi%
\edef\crrdx@sfc@var{\crrdx@sfc@var#1}%
\next%
}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\crrdx@sfc} This is the main macro to \textbf{S}et the \textbf{F}irst letter as \textbf{C}apital, i.e.,
% what is behind the |@| in the |\index| command.
% We presume that before a possible space in the entry there is a letter
% that can be capitalized.
%    \begin{macrocode}
\newcommand{\crrdx@sfc}[1]{%
\edef\crrdx@sfc@var{\@empty}%
\let\end\@empty%
\crrdx@split{#1}%
\expandafter\crrdx@sfc@loop\crrdx@beforespace\end%
\ifx\crrdx@afterspace\@empty\else%
\edef\crrdx@sfc@var{\crrdx@sfc@var\space\crrdx@afterspace}%
\fi%
}%
%    \end{macrocode}
% \end{macro}
% Scanning the loop, normally spaces are lost. Therefore we split the
% entry when a space is there at the first space and glue it together in the final part of
% |\crrdx@sfc|.
%    \begin{macrocode}
\def\crrdx@ss#1 #2\stop{\edef\crrdx@beforespace{#1}\edef\crrdx@afterspace{#2}}%
%    \end{macrocode}
%    \begin{macrocode}
\newcommand{\crrdx@split}[1]{%
\edef\test{\@empty}%
%    \end{macrocode}
% We test for no space there with a space and |\test| as last entry.
%    \begin{macrocode}
\crrdx@ss#1 \test\stop%
\ifx\crrdx@afterspace\test%
%    \end{macrocode}
% there is no space%
%    \begin{macrocode}
\edef\crrdx@beforespace{#1}\edef\crrdx@afterspace{\@empty}%
\else%
%    \end{macrocode}
% there is a space
%    \begin{macrocode}
\crrdx@ss#1\stop%
\fi%
}%
%    \end{macrocode}
%
% \subsection{Index Sectioning}
% We use here |providecommand| because it may be defined in some classes too
% (at least in classes that I developed for personal use).
%
% \begin{macro}{\swallow} Swallows the next item (no operation)
%    \begin{macrocode}
\providecommand\swallow[1]{\relax}%
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sectioncrrdx} Makes an index, added to
% table of contents at level 1 (section) without number.
%    \begin{macrocode}
\providecommand{\sectioncrrdx}[1]%
{\section*{#1}\addcontentsline{toc}{section}{#1}}%
%    \end{macrocode}
% \end{macro}
%
% \subsection{Clashes Check}
%    \begin{macrocode}
\AtBeginDocument{ \@ifpackageloaded{index}%
{\PackageError{corridx}%
{This package is not compatible with package index}{}}}%
%    \end{macrocode}
%
%
% \PrintChanges
% \Finale
\endinput