diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/sanitize-umlaut/sanitize-umlaut.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/sanitize-umlaut/sanitize-umlaut.tex | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/sanitize-umlaut/sanitize-umlaut.tex b/Master/texmf-dist/doc/latex/sanitize-umlaut/sanitize-umlaut.tex new file mode 100644 index 00000000000..653bb72f00a --- /dev/null +++ b/Master/texmf-dist/doc/latex/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} |