path: root/macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex

% \LaTeX-Main\
% !TeX encoding=UTF-8
% !TeX spellcheck=en_US
%%
%% The LaTeX package sanitize-umlaut - version 1.10 (2020/01/01)
%% sanitize-umlaut.tex: Manual
%%
%% -------------------------------------------------------------------------------------------
%% Copyright (c) 2016-2020 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
%% -------------------------------------------------------------------------------------------
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% 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.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `author-maintained'.
%%
%% This work consists of all files listed in README
%%
\documentclass[a4paper,11pt]{ltxdoc}

\usepackage{sanitize-umlaut.doc}
\usepackage{%
  sanitize-umlaut}

\def\version{1.10}%
\def\datum{2020/01/01}%

\hypersetup{
  pdftitle={Manual for the sanitize-umlaut package},
  pdfauthor={Thomas F. Sturm},
  pdfsubject={sanitize umlauts for makeindex},
  pdfkeywords={index, umlauts, makeindex, pdflatex}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}

\begin{center}
\begin{tcolorbox}[enhanced,hbox,tikznode,left=8mm,right=8mm,boxrule=0.4pt,
  colback=white,colframe=black!50!yellow,
  drop lifted shadow=black!50!yellow,arc is angular,
  before=\par\vspace*{5mm},after=\par\bigskip]
{\bfseries\LARGE The \texttt{sanitize-umlaut} package}\\[3mm]
{\large Manual for version \version\ (\datum)}
\end{tcolorbox}
{\large Thomas F.~Sturm%
  \footnote{Prof.~Dr.~Dr.~Thomas F.~Sturm, Institut f\"{u}r Mathematik und Informatik,
    Universit\"{a}t der Bundeswehr M\"{u}nchen, D-85577 Neubiberg, Germany;
     email: \href{mailto:thomas.sturm@unibw.de}{thomas.sturm@unibw.de}}\par\medskip
\normalsize\url{http://www.ctan.org/pkg/sanitize-umlaut}\par
\url{https://github.com/T-F-S/sanitize-umlaut}
}
\end{center}
\bigskip
\begin{absquote}
  \begin{center}\bfseries Abstract\end{center}
  The packages sanitizes umlauts to be used directly in index entries for
  MakeIndex and friends with |pdflatex|. This means, that inside |\index| an umlaut can
  be used as \texttt{"U} or \texttt{Ü}. In both cases, the letter is written
  as \texttt{"U} into the raw index file for correct processing with MakeIndex
  and |pdflatex|.
\end{absquote}

\begin{tcolorbox}[breakable,enhanced jigsaw,title={Contents},fonttitle=\bfseries\Large,
  colback=yellow!10!white,colframe=red!50!black,before=\par\bigskip\noindent,
  colbacktitle=red!50!yellow!75!black,
  enlargepage flexible=\baselineskip,pad at break*=3mm,
  attach boxed title to top center={yshift=-0.25mm-\tcboxedtitleheight/2,yshifttext=2mm-\tcboxedtitleheight/2},
  boxed title style={enhanced,boxrule=0.5mm,
    frame code={ \path[tcb fill frame] ([xshift=-4mm]frame.west) -- (frame.north west)
    -- (frame.north east) -- ([xshift=4mm]frame.east)
    -- (frame.south east) -- (frame.south west) -- cycle; },
    interior code={ \path[tcb fill interior] ([xshift=-2mm]interior.west)
    -- (interior.north west) -- (interior.north east)
    -- ([xshift=2mm]interior.east) -- (interior.south east) -- (interior.south west)
    -- cycle;}  },
  drop fuzzy shadow]
\makeatletter
\@starttoc{toc}
\makeatother
\end{tcolorbox}

\clearpage
\section{Purpose of the Package}%
The package sanitizes umlauts to be used directly in index entries for
|makeindex| and friends with |pdflatex|. This means, that inside |\index| an umlaut can
be used as \myverb{"U} or \myverb{Ü}. In both cases, the letter is written
as \myverb{"U} into the raw index file for correct processing with |makeindex|
and |pdflatex|.

The package is intended
\begin{itemize}
\item for documents in German language using the babel package with a setting
  identical or similar to \myverb{\usepackage[ngerman]{babel}}.
\item for documents which are processed by |latex| or |pdflatex| (not |lualatex| or |xelatex|).
\item for documents with an index which is processed using the
  MakeIndex program.
\item for authors who like to use \myverb{\index{Übermaß}} instead of
  \myverb{\index{"Uberma"s}}.
\end{itemize}

All these conditions are satisfiable by simply including the |sanitize-umlaut|
package.

An alternative would be to filter the resulting raw \myverb{.idx} index
\emph{before} |makeindex| is applied to create the final \myverb{.ind} index.
Another alternative is to replace MakeIndex by Xindy or another index
processor.


\section{Important Compatibility Informations}%

\subsection{Past}
Until 2018, the default encoding for \LaTeX\ files was 7-bit ASCII.
For other encodings, packages like |inputenc| had to be loaded.
Also, |inputenc| used to expand characters like umlauts during |\index| output.
The package |sanitize-umlaut| version 1.00 replaced this expansion code
for |\index| output to get \myverb{"U} instead of \myverb{Ü}, etc.

\subsection{Present}
Since April 2018, the default encoding for \LaTeX\ files has been changed to UTF-8.
This is done by preloading the UTF-8 settings of the package |inputenc|
by default \LaTeX, i.e. if you want to use UTF-8 (recommended!), you do not
longer need to load |inputenc| inside your preamble.
But, also the implementation of |inputenc| changed for UTF-8 (October 2019?).
Nowadays, characters like umlauts are not longer expanded during |\index| output,
but are preserved as is.
Therefore, |sanitize-umlaut| version 1.00 \textbf{is not compatible} to
|inputenc| with UTF-8 dating from 2019 or newer.

|sanitize-umlaut| version 1.10 (or newer) patches some UTF-8 code of
\LaTeX/|inputenc| to return and replace character expansion during |\index| output.
This patch \textbf{is not compatible} to older versions of \LaTeX/|inputenc| (before October 2019).
Therefore, if your \LaTeX\ distribution is not reasonable up to date, you
should stay at version 1.00 of |sanitize-umlaut|.

\subsection{Future}
As always, the future is dark and difficult to see. Further changes of
|inputenc| implementation may force further changes of |sanitize-umlaut|.
Hopefully, this will not happen too soon or too often.
Also, if some miracle happens, MakeIndex may be updated one day to
recognize UTF-8 properly to make |sanitize-umlaut| superfluous.


\section{Package Usage}%

\subsection{Prerequisites}
The source document may need some encoding by |inputenc| since |pdflatex|
is assumed as engine. For example:

\begin{dispListing}
\usepackage[latin1]{inputenc}
\end{dispListing}

For |utf8| (UTF-8), modern \LaTeX\ does not need this package inclusion any more!

Just some few encodings are supported by |sanitize-umlaut|.
These are the most important for German language texts:

\tcbox[center,size=minimal,enhanced,frame hidden,colback=red!10]{\begin{tabular}{>{\ttfamily}l>{\ttfamily}l}\toprule
\textnormal{\bfseries encoding} & \textnormal{\bfseries recognized as}\\\midrule
utf8 & utf8\\
utf8-2018 & utf8-2018\\
latin1, ansinew, cp1252 & latin1\\
applemac & applemac\\\bottomrule
\end{tabular}}

Further, the |babel| package with German settings is needed:

\begin{dispListing}
\usepackage[ngerman]{babel}
\end{dispListing}

\subsection{Package Application}
Now, the package application is simple. You just put

\begin{dispListing}
\usepackage{sanitize-umlaut}
\end{dispListing}

into your document preamble \emph{after} |inputenc| and, maybe, after |babel|.
That is all.


\subsection{Sanitized Characters}

The umlauts and the sharp s are replaced by their |babel| shorthand codes
which are written to the \myverb{.idx} file.

\tcbox[center,size=minimal,enhanced,frame hidden,colback=red!10]{\begin{tabular}{>{\ttfamily}l>{\ttfamily}l}\toprule
\textnormal{\bfseries character} & \textnormal{\bfseries replacement}\\\midrule
ä & "a\\
ö & "o\\
ü & "u\\
Ä & "A\\
Ö & "O\\
Ü & "U\\
ß & "s\\\bottomrule
\end{tabular}}


\subsection{Technical Information}

The package uses \myverb{\inputencodingname} (set by \LaTeX\ and the |inputencoding| package)
to determine the current encoding.

The package redefines the \myverb{\@sanitize} macro at the begin of the
document. It adds some encoding redefinitions to this macro.
\myverb{\@sanitize} is used inside \myverb{\index} in a local group.
If another package (besides |babel|) also changes this macro or uses it
outside \myverb{\index}, strange things may happen.


\clearpage
\section{Application Examples}%

\tcbinputlisting{docexample,listing file=german.ist,listing only,minted style=colorful,
  title={file |"german.ist"| for the examples}}


\begin{fullexample}{run arara}
% !TeX encoding=UTF-8
% arara: pdflatex
% arara: makeindex: { style: german.ist, german: true }
% arara: pdflatex
\documentclass[a4paper,12pt]{article}
\usepackage[T1]{fontenc}
%\usepackage[utf8]{inputenc}   % utf8 is default now
\usepackage[ngerman]{babel}
\usepackage{makeidx}
\usepackage{sanitize-umlaut}
\makeindex
\begin{document}
\section{Basic Example}
Test äöüÄÖÜß.
\index{Aber}   \index{Arg}   \index{Ärger}
\index{Ofen}   \index{Ö - wie schön}   \index{oberhalb}
\index{Ufer}   \index{Übermaß}
\index{Latex=\LaTeX}   \index{Ärger>Index}
Test äöüÄÖÜß.
\printindex
\end{document}
\end{fullexample}


\begin{fullexample}{run arara}
% !TeX encoding=UTF-8
% arara: pdflatex
% arara: makeindex: { style: german.ist, german: true }
% arara: pdflatex
\documentclass[a4paper,12pt]{article}
\usepackage[T1]{fontenc}
%\usepackage[utf8]{inputenc}   % utf8 is default now
\usepackage[ngerman]{babel}
\usepackage{makeidx}
\usepackage{sanitize-umlaut}
\usepackage[hyperindex,colorlinks]{hyperref}
\makeindex
\begin{document}
\section{Example with hyperref}
Test äöüÄÖÜß.
\index{Aber}   \index{Arg}   \index{Ärger}
\index{Ofen}   \index{Ö - wie schön}   \index{oberhalb}
\index{Ufer}   \index{Übermaß}
\index{Latex=\LaTeX}   \index{Ärger>Index}
Test äöüÄÖÜß.
\printindex
\end{document}
\end{fullexample}


\begin{fullexample}{run arara}
% !TeX encoding=UTF-8
% arara: pdflatex
\documentclass[a4paper,12pt]{article}
\usepackage[T1]{fontenc}
%\usepackage[utf8]{inputenc}   % utf8 is default now
\usepackage[ngerman]{babel}
\usepackage[makeindex]{imakeidx}
\makeindex[options=-s german.ist -g]
\usepackage{sanitize-umlaut}
\begin{document}
\section{Example with imakeidx}
Test äöüÄÖÜß.
\index{Aber}   \index{Arg}   \index{Ärger}
\index{Ofen}   \index{Ö - wie schön}   \index{oberhalb}
\index{Ufer}   \index{Übermaß}
\index{Latex=\LaTeX}   \index{Ärger>Index}
Test äöüÄÖÜß.
\printindex
\end{document}
\end{fullexample}


\begin{fullexample}{run arara}
% !TeX encoding=UTF-8
% arara: pdflatex
\documentclass[a4paper,12pt]{article}
\usepackage[T1]{fontenc}
%\usepackage[utf8]{inputenc}   % utf8 is default now
\usepackage[ngerman]{babel}
\usepackage[makeindex]{imakeidx}
\makeindex[options=-s german.ist -g]
\usepackage{sanitize-umlaut}
\usepackage[hyperindex,colorlinks]{hyperref}
\begin{document}
\section{Example with imakeidx and hyperref}
Test äöüÄÖÜß.
\index{Aber}   \index{Arg}   \index{Ärger}
\index{Ofen}   \index{Ö - wie schön}   \index{oberhalb}
\index{Ufer}   \index{Übermaß}
\index{Latex=\LaTeX}   \index{Ärger>Index}
Test äöüÄÖÜß.
\printindex
\end{document}
\end{fullexample}


\begin{fullexample}{run arara}
% !TeX encoding=UTF-8
% arara: pdflatex
\documentclass[a4paper,12pt]{article}
\usepackage[T1]{fontenc}
%\usepackage[utf8]{inputenc}   % utf8 is default now
\usepackage[ngerman]{babel}
\usepackage[makeindex]{imakeidx}
\indexsetup{level=\section*,noclearpage}
\makeindex[name=personen,title=Personenregister,options=-s german.ist -g]
\makeindex[name=allgemein,title=Allgemeines Register,options=-s german.ist -g]
\usepackage{sanitize-umlaut}
\begin{document}
\section{Example with multiple indexes}
Test äöüÄÖÜß.
\index[personen]{Huber, Hans}    \index[personen]{Hübner, Jörg}
\index[allgemein]{Aber}          \index[allgemein]{Arg}
\index[allgemein]{Ärger}         \index[allgemein]{Ofen}
\index[allgemein]{Ö - wie schön} \index[allgemein]{oberhalb}
\index[allgemein]{Ufer}          \index[allgemein]{Übermaß}
\index[allgemein]{Latex=\LaTeX}  \index[allgemein]{Ärger>Index}
Test äöüÄÖÜß.
\clearpage
\printindex[allgemein]
\printindex[personen]
\end{document}
\end{fullexample}


\end{document}