summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex')
-rw-r--r--macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex316
1 files changed, 316 insertions, 0 deletions
diff --git a/macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex b/macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex
new file mode 100644
index 0000000000..653bb72f00
--- /dev/null
+++ b/macros/latex/contrib/sanitize-umlaut/sanitize-umlaut.tex
@@ -0,0 +1,316 @@
+% \LaTeX-Main\
+% !TeX encoding=UTF-8
+% !TeX spellcheck=en_US
+%%
+%% The LaTeX package sanitize-umlaut - version 1.00 (2016/05/28)
+%% sanitize-umlaut.tex: Manual
+%%
+%% --------------------------------------------------------------------------------------
+%% Copyright (c) 2016 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.00}%
+\def\datum{2016/05/28}%
+
+\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 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 \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{Package Usage}%
+
+\subsection{Prerequisites}
+The source document needs some encoding by |inputenc| since |pdflatex|
+is assumed as engine. For example:
+
+\begin{dispListing}
+\usepackage[utf8]{inputenc}
+\end{dispListing}
+
+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\\
+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 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}
+\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}
+\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}
+\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}
+\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}
+\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}