diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/soul/soul.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/soul/soul.dtx | 4520 |
1 files changed, 4520 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/soul/soul.dtx b/Master/texmf-dist/source/latex/soul/soul.dtx new file mode 100644 index 00000000000..064634cf111 --- /dev/null +++ b/Master/texmf-dist/source/latex/soul/soul.dtx @@ -0,0 +1,4520 @@ +% \iffalse +%% File: soul.dtx Copyright (C) 1998--2003 Melchior FRANZ +%% $Id: soul.dtx,v 1.128 2003/11/17 22:57:24 m Rel $ +%% $Version: 2.4 $ +% +%<*batchfile> +% +% on Unix/Linux just run "make" to get the style file and the documentation, +% else generate the driver soul.ins (if you don't already have it): +% +% $ latex soul.dtx +% +% You'll probably get an error message that you may ignore. Now generate +% the style file: +% +% $ tex soul.ins +% +% And finally to produce the documentation run LaTeX three times: +% +% $ latex soul.dtx +% +% +% +% +% DISCLAIMER: note that a Makefile could actually contain malign commands +% that erase your whole account, so having a look at it before won't hurt! +% I take no responsibility for any damage, but I do what I can to make +% using the original Makefile safe. +% +% COPYRIGHT NOTICE: +% This package is free software that can be redistributed and/or modified +% under the terms of the LaTeX Project Public License as specified +% in the file macros/latex/base/lppl.txt on any CTAN archive server, +% such as ftp://ftp.dante.de/. +% +%$ +%% ==================================================================== +%% @LaTeX-package-file{ +%% author = "Melchior FRANZ", +%% version = "2.4", +%% date = "17 November 2003", +%% filename = "soul.dtx", +%% address = "Melchior FRANZ +%% Rieder Hauptstrasse 52 +%% A-5212 SCHNEEGATTERN +%% AUSTRIA", +%% telephone = "++43 7746 3109", +%% URL = "http://www.unet.univie.ac.at/~a8603365/", +%% email = "a8603365@unet.univie.ac.at", +%% codetable = "ISO/ASCII", +%% keywords = "spacing out, letterspacing, underlining, striking out, +%% highlighting", +%% supported = "yes", +%% docstring = "This article describes the `soul' package, which +%% provides hyphenatable letterspacing (spacing out), +%% underlining, and some derivatives. +%% All features are based upon a common mechanism +%% that allows to typeset text syllable by syllable, +%% where the excellent TeX hyphenation algorithm is +%% used to find the proper hyphenation points. +%% Two examples show how to use the provided interface to +%% implement things such as `an-a-lyz-ing syl-la-bles'. +%% Although the package is optimized for LaTeX2e, +%% it works with Plain TeX and with other +%% packages, too.", +%% } +%% ==================================================================== +% +% +% +% +% +\begin{filecontents}{soul.ins} +\def\batchfile{soul.ins} +\input docstrip.tex +\askforoverwritefalse +\keepsilent % <-- this is for you, Christina ;-) +\generate{\file{soul.sty}{\from{soul.dtx}{package}}} +\endbatchfile +\end{filecontents} +%</batchfile> +% +% +% +% +% +%<*driver> +\def\fileversion{2.4} +\def\filedate{2003/11/17} +% +% +% +\documentclass{ltxdoc} +% +% +% +\makeatletter\let\SOUL@sethyphenchar\relax\makeatother +\IfFileExists{soul.sty}{% + \usepackage{soul}[2002/01/10] + \expandafter\ifx\csname sloppyword\endcsname\relax % old version? + \def\sloppyword{\textbf{?? [obsolete soul version]}} + \fi + \let\SOULSTYfound\active +}{% + \GenericWarning{soul.dtx}{% + Package file `soul.sty' couldn't be found. You should however find^^J^^A + a file `soul.ins' in the current directory. If you type "tex soul.ins"^^J^^A + on the command line, `soul.sty' will be generated. After that + run "latex soul.dtx" again and you won't see this message again. + }% +}% +% +% +% +\ifx\makehyperref\SOULundefined + \newcommand*\texorpdfstring[2]{#1} +\else ^^A for "make hyper" + \usepackage{hyperref} + \hypersetup{ + bookmarksopen, + colorlinks, + pdftitle={The soul package}, + pdfauthor={Melchior FRANZ}, + pdfsubject={${}$Id: soul.dtx,v 1.128 2003/11/17 22:57:24 m Rel ${}$}, + pdfkeywords={space out, letterspacing, underlining, overstriking, highlighting} + } + \usepackage[pdftex]{graphicx,color} +\fi +% +% +% +%\RecordChanges +% +\begin{document} +\setcounter{tocdepth}{2} +\DocInput{soul.dtx} +\end{document} +%</driver> +% \fi +% +% +% +% +% +% +% +% \CheckSum{2006} +% \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 \~} +% +% +% +% \title{The \texttt{soul} package} +% +% \author{Melchior \caps{FRANZ}} +% +% \date{November 17, 2003} +% +%^^A===================================================== +% +%^^A These messy macros allow to typeset the `example' sections +%^^A conveniently. You'd better ignore them. I do! :-) +% +% \makeatletter +% +% \def\squarebull{\rule[.2ex]{.8ex}{.8ex}} +% +% \newenvironment{examples} +% {\parindent\z@\small\fontencoding{OT1}\selectfont} +% {\rule{\hsize}{.4pt}} +% +% \def\soultest#1|{\bgroup\rule[.5ex]{\hsize}{.4pt}\par +% \parbox[t]{.34\hsize}{\raggedright\textit{#1\unskip.}}% +% \hspace{1.5em}$\vtop\bgroup\hb@xt@.4\hsize\bgroup +% \llap{\squarebull\hspace{.4em}}\soulttest} +% +% {\catcode`\|=13\gdef\soulttest{% +% \bgroup\def\do##1{\catcode`##1=12}\dospecials\ttfamily +% \catcode`\|=13\unskip\def|{\hss\egroup\egroup\soultttest}}} +% +% \def\soultttest#1{\hbox{\vtop{\hsize.4\hsize\hbadness\@M +% \leavevmode\llap{\squarebull\hspace{.4em}}#1\null}}% +% \egroup$\hspace{1.5em}\parbox[t]{1mm}{\hyphenpenalty-\@M +% \exhyphenpenalty-\@M\hbadness\@M\hfuzz\maxdimen +% \strut\llap{\squarebull\hspace{.4em}}#1\null}% +% \goodbreak\vspace{2ex} +% \egroup} +% +% \newcommand*\DescribeOption[1]{\marginpar{\raggedleft\textsf{#1}\ignorespaces}} +% +% +%^^A similar to the `description' environment +% +% \def\describemacro{^^A +% \bgroup +% \let\do\@makeother +% \dospecials +% \catcode`{=1 +% \catcode`}=2 +% \SOUL@@@descmacro +% } +% +% \def\SOUL@@@descmacro#1{^^A +% \texttt{#1}^^A +% \DescribeMacro{#1}^^A +% \expandafter\edef\expandafter\x\expandafter{\expandafter\@gobble#1}^^A +% \expandafter\label{cmd:\x}^^A +% \egroup +% } +% +% +% \def\SOUL@@@verbitem[#1: {^^A +% \bgroup +% \let\do\@makeother +% \dospecials +% \SOUL@@@verbscan{#1}^^A +% } +% +% \def\SOUL@@@verbscan#1#2]{^^A +% \egroup +% \goodbreak +% \def\@currentlabel{\S\,\the\SOUL@@@itemnr}^^A +% \label{par:#1}^^A +% \SOUL@@@item[\textbf{\@currentlabel\hskip.6em#1:}]\hfil\break +% Example: \texttt{#2}\hfil\break^^A +% \advance\SOUL@@@itemnr1 +% } +% +% \let\SOUL@@@item\item +% \newcount\SOUL@@@itemnr +% +% \newenvironment{verblist}[1]{^^A +% \SOUL@@@itemnr=#1 +% \list{}{^^A +% \settowidth{\labelwidth}{\indent\indent}^^A +% \leftmargin\labelwidth +% \advance\leftmargin\labelsep +% \def\makelabel##1{##1}^^A +% \let\item\SOUL@@@verbitem +% }^^A +% }{^^A +% \endlist +% } +% +% \newenvironment{labeling}[1]{^^A +% \list{}{^^A +% \settowidth{\labelwidth}{\textbf{#1}}^^A +% \leftmargin\labelwidth\advance\leftmargin\labelsep +% \def\makelabel##1{\textbf{##1}\hfil}^^A +% }^^A +% }{^^A +% \endlist +% } +% +% \newenvironment{syntax}{^^A +% \par\medskip\def\<##1>{$\langle$\syn{##1}$\rangle$}^^A +% \indent\begin{tabular}{l}^^A +% }{^^A +% \end{tabular}^^A +% \noindentafter\medbreak +% } +% +% +% \newenvironment{example}[1][.9\textwidth] +% {\par\medskip\indent\begin{tabular}{p{#1}l}} +% {\end{tabular}\noindentafter\medbreak} +% +% \newcommand*\noindentafter{^^A +% \global\everypar{{\setbox\z@\lastbox}\everypar{}}} +% +% \newcommand*\errsquare{\leavevmode\vrule height.8em depth.2em width1em\relax} +% +% +% \ifx\SOULSTYfound\active +%^^A analyze syllables---described somewhere below +% +% \DeclareRobustCommand*\sy{^^A +% \SOUL@setup +% \def\SOUL@preamble{\lefthyphenmin0\righthyphenmin0}^^A +% \def\SOUL@everysyllable{\the\SOUL@syllable}^^A +% \def\SOUL@everyspace##1{##1\space}^^A +% \def\SOUL@everyhyphen{^^A +% \discretionary{^^A +% \SOUL@setkern\SOUL@hyphkern +% \SOUL@sethyphenchar +% }{}{^^A +% \hbox{\kern1pt$\cdot$}^^A +% }^^A +% }^^A +% \def\SOUL@everyexhyphen##1{^^A +% \SOUL@setkern\SOUL@hyphkern +% \hbox{##1}^^A +% \discretionary{}{}{^^A +% \SOUL@setkern\SOUL@charkern +% }^^A +% }^^A +% \SOUL@} +% +%^^A analyze the engine---described somewhere below, too +% +% \DeclareRobustCommand*\an{^^A +% \def\SOUL@preamble{$^{^P}$}^^A +% \def\SOUL@everyspace##1{##1\texttt{\char`\ }}^^A +% \def\SOUL@postamble{$^{^E}$}^^A +% \def\SOUL@everyhyphen{$^{^-}$}^^A +% \def\SOUL@everyexhyphen##1{##1$^{^=}$}^^A +% \def\SOUL@everysyllable{$^{^S}$}^^A +% \def\SOUL@everytoken{\the\SOUL@token$^{^T}$}^^A +% \def\SOUL@everylowerthan{$^{^L}$}^^A +% \SOUL@} +% +%^^A magazine-like (truly awful) paragraphs +%^^A If you know what you're doing, you can copy it to your personal `soul.cfg' file. +% +% \DeclareRobustCommand*\magstylepar{\SOUL@sosetup +% \def\SOUL@preamble{^^A +% \edef\SOUL@soletterskip{\z@\@plus\fontdimen2\font\@minus\z@}^^A +% \edef\SOUL@soinnerskip{\the\fontdimen2\font +% \@plus\the\fontdimen3\font\@minus\the\fontdimen4\font}^^A +% \let\SOUL@soouterskip\SOUL@soinnerskip +% \SOUL@sopreamble}^^A +% \lefthyphenmin2\righthyphenmin2\SOUL@} +% +%\else +% +%^^A The package has not been found, so we're providing some dummies, just +%^^A to avoid all these `Undefined command sequence' messages. +% +% \def\SOUL@@@X#1{\textbf{??}}% +% \let\so\SOUL@@@X +% \let\textso\SOUL@@@X +% \let\caps\SOUL@@@X +% \let\textcaps\SOUL@@@X +% \let\ul\SOUL@@@X +% \let\textul\SOUL@@@X +% \let\st\SOUL@@@X +% \let\textst\SOUL@@@X +% \let\hl\SOUL@@@X +% \let\texthl\SOUL@@@X +% \let\sy\SOUL@@@X +% \let\an\SOUL@@@X +% \let\magstylepar\SOUL@@@X +% \let\sloppyword\SOUL@@@X +% \def\sodef#1#2#3#4{\let#1\relax\SOUL@@@X}% +% \fi +% +% \newcommand*\xpath{^^A +% \bgroup +% \let\do\@makeother +% \dospecials +% \catcode`\{=1 +% \catcode`\}=2 +% \def\{{\char"7B}^^A +% \def\}{\char"7D}^^A +% \SOUL@@@code +% } +% +% \newcommand*\SOUL@@@code[1]{\normalfont\texttt{#1}\egroup} +% +% \let\cs\xpath +% \let\option\textsf +% \def\package#1{{\normalfont\texttt{#1}}} +% \let\program\texttt +% \let\bibtitle\textit +% \let\syn\textit +% +% \sodef\person{\scshape}{0.06em}{0.45em}{0.4em} +% \sodef\SOUL@@@versal{\upshape}{0.125em}{0.4583em}{0.5833em} +% \DeclareRobustCommand*\versal[1]{^^A +% \MakeUppercase{\SOUL@@@versal{#1}}^^A +% } +% +% \def\ConTeXt{Con\TeX t} +% \def\CTAN{{\small\caps{CTAN}}} +% \def\soul{\package{soul}} +% +% ^^A set some parameters as used in Plain TeX +% \def\plainsetup{^^A +% \pretolerance100 +% \tolerance200 +% \hbadness1000 +% \linepenalty10 +% \hyphenpenalty50 +% \exhyphenpenalty50 +% \doublehyphendemerits10000 +% \finalhyphendemerits5000 +% \adjdemerits10000 +% \hfuzz.1pt +% \overfullrule5pt +% } +% +% \def\FIXME#1{\message{<FIXME>}#1} +% +% \makeatother +% +% +% \lefthyphenmin2 +% \righthyphenmin3 +% \hyphenation{Le-se-ty-po-gra-phie Ver-bin-dung fak-si-mi-le} +% +% +%^^A===================================================== +% +% +% \changes{v1.0}{1998/10/16}{Initial version}% +%^^A due to an error in the documentation of v1.0, there's no v1.1 :-( +% \changes{v1.1a}{1998/12/08}{fixed a bunch of bugs; `magstylepar command +% banned; `caps introduced; `so and `caps recognize following spaces; +% error message added; `so parameters are mandatory} +% +% \changes{v1.2}{1999/01/11}{fixed the newline bug; added the `\(>\) command} +% +% \changes{v1.3}{1999/05/15}{changed allowhyphen, preambles; added a paragraph +% in the `features' section} +% +% \changes{v2.0}{2002/01/03}{(almost) complete rewrite} +% +% \changes{v2.1}{2002/01/10}{Happy (64th) birthday, Don! +% ``The now-traditional fix for the +% now-traditional brown-paper-bag major release.'' +% as Eric S. RAYMOND commented on his CML2.0.1 release. ;-)} +% +% \changes{v2.2}{2002/05/12}{fixed a couple of bugs; added support for +% the Plain TeX color.sty wrapper} +% +% \changes{v2.3}{2002/05/29}{compatibility with cmbright/ccfonts} +% +% \changes{v2.4}{2003/11/17}{Fix the font bug. Fix a scanner bug. +% Other bugfixes; change caps set handling; add footnote and +% textsuperscript support} +% +% +% +% +% +% \maketitle +% +% +% +% \begin{abstract} +% This article describes the \soul\ package^^A +%^^A%% +% \footnote{This file has version number \fileversion, last revised \filedate.}, +%^^A%% +% which provides \so{hyphenatable letterspacing (spacing out),} \ul{underlining} +% and some derivatives such as \st{overstriking} and highlighting. +% Although the package is optimized for \LaTeXe, it also works with +% Plain \TeX\ and with other flavors of \TeX\ like, for instance, \ConTeXt. +% By the way, the package name |soul| is only a combination +% of the two macro names \cs{\so} (space out) and \cs{\ul} +% (underline)---nothing poetic at all.^^A :-( +% \end{abstract} +% +% +% {\setlength\parskip{0pt}\tableofcontents } +% \addtocontents{toc}{\protect\begin{multicols}{2}} +% +% +% +% +% +% +% +% +% +% \section{Typesetting rules} +% \label{sec:typesetting} +% +% There are several possibilities to emphasize parts of a paragraph, +% not all of which are considered good style. While underlining +% is commonly rejected, experts dispute about whether letterspacing +% should be used or not, and in which cases. If you are not interested +% in such debates, you may well skip to the next section. +% +% +% \subsection*{Theory \dots} +% \label{sec:theory} +% +% To understand the experts' arguments we have to know about the +% conception of \emph{page grayness.} The sum of all characters on +% a page represents a certain amount of grayness, provided that +% the letters are printed black onto white paper. +% +% \person{Jan Tschichold} \cite{Tschichold}, a well known and recognized +% typographer, accepts only forms of emphasizing, which do not disturb this +% grayness. This is only true of italic shape, caps, and +% caps-and-small-caps fonts, but not of ordinary letterspacing, underlining, +% bold face type and so on, all of which appear as either dark or light +% spots in the text area. In his opinion emphasized text shall not catch the eye when +% running over the text, but rather when actually reading the respective words. +% +% Other, less restrictive typographers \cite{Willberg} call this kind of emphasizing +% `integrated' or `aesthetic', while they describe `active' emphasizing apart from it, +% which actually \emph{has} to catch the reader's eye. To the latter group belong commonly +% despised things like letterspacing, demibold face type and even underlined and colored text. +% +% On the other hand, \person{Tschichold} suggests +% to space out caps and caps-and-small-caps fonts on title pages, headings and running headers from +% 1\,pt up to 2\,pt. +% Even in running text legibility of uppercase letters should be improved with slight +% letterspacing, since (the Roman) majuscules don't look right, if they are spaced +% like (the Carolingian) minuscules.\footnote{This suggestion is followed throughout this article, +% although Prof.~\person{Knuth} already considered slight letterspacing with his |cmcsc| fonts.} +% +% +% +%\subsection*{\dots\ and Practice} +% +% However, in the last centuries letterspacing was excessively used, +% underlining at least sometimes, because capitals and italic shape could +% not be used together with the \emph{Fraktur} font and other black-letter fonts, +% which are sometimes also called ``old German'' fonts. +% This tradition is widely continued until today. The same limitations apply still today +% to many languages with non-latin glyphs, which is why letterspacing has a strong +% tradition in eastern countries where Cyrillic fonts are used. +% +% The \person{Duden} \cite{Duden}, a well known German dictionary, explains how to space out properly: +% \emph{Punctuation marks are spaced out like letters, except quotation marks and periods. +% Numbers are never spaced out. The German syllable \mbox{\emph{-sche}} is not spaced +% out in cases like \emph{``der {\so{Virchow{sche}}} Versuch''}\footnote{the \person{Virchow} experiment}. +% In the old German \emph{Fraktur} fonts the ligatures \emph{|ch|, |ck|, |sz|~(\ss)} and~\emph{|tz|} are +% not broken within spaced out text.} +% +% While some books follow all these rules \cite{Muszynski}, others don't +% \cite{Reglement}. In fact, most books in my personal library do \emph{not} space out commas. +% +% +% +% +% +% +% +% +% +% \section{Short introduction and common rules} +% +% The \soul\ package provides five commands that are aimed at emphasizing +% text parts. Each of the commands takes one argument that can either be +% the text itself or the name of a macro that contains text (e.\,g.~|\so\text|)^^A +% ^^A +% \footnote{See~\ref{par:Unexpandable material in command sequences} for +% some additional information about the latter mode.}^^A +% ^^A +% . +% See table~\ref{tab:survey} for a complete command survey. +% +% {\catcode`\|=12 +% \begin{center} +% \begin{tabular}{r@{\hspace{1.5em}}l} +% \verb+\so{letterspacing}+&\so{letterspacing}\\ +% \verb+\caps{CAPITALS, Small Capitals}+&\caps{CAPITALS, Small Capitals}\\ +% \verb+\ul{underlining}+&\ul{underlining}\\ +% \verb+\st{overstriking}+&\st{overstriking}\\ +% \verb+\hl{highlighting}+&highlighting\footnotemark\\ +% \end{tabular} +% \end{center} +% \footnotetext{The look of highlighting is nowhere demonstrated +% in this documentation, because it requires a Postscript aware +% output driver and would come out as ugly black bars on other +% devices, looking very much like censoring bars. Think of it as +% the effect of one of those coloring text markers.} +% } +% +% \noindent +% The \cs{\hl} command does only highlight if the \package{color} package +% was loaded, otherwise it falls back to underlining.\footnote{Note that +% you can also use \LaTeX's \package{color} package with Plain \TeX. +% See~\ref{sec:plain} for details.} The highlighting +% color is by default yellow, underlines and overstriking lines are by +% default black. The colors can be changed using the following commands: +% +% {\catcode`\|=12 +% \begin{center} +% \begin{tabular}{r@{\hspace{1.5em}}l} +% \verb+\setulcolor{red}+&set underlining color\\ +% \verb+\setstcolor{green}+&set overstriking color\\ +% \verb+\sethlcolor{blue}+&set highlighting color\\ +% \end{tabular} +% \end{center} +% } +% +% \noindent +% |\setulcolor{}| and |\setstcolor{}| turn coloring off. +% There are only few colors predefined by the \package{color} +% package, but you can easily add custom color definitions. +% See the \package{color} package documentation~\cite{color} for further +% information. +% +% \begin{example} +% |\usepackage{color,soul}|\\ +% |\definecolor{lightblue}{rgb}{.90,.95,1}|\\ +% |\sethlcolor{lightblue}|\\ +% |...|\\ +% |\hl{this is highlighted in light blue color}|\\ +% \end{example} +% +% +% +% +% +% +% +% \subsection[Some things work]{Some things work \dots} +% +% The following examples may look boring and redundant, because they describe +% nothing else than common \LaTeX\ notation with a few exceptions, but this is +% only the half story: The \soul\ package has to pre-process the argument +% before it can split it into characters and syllables, and all described +% constructs are only allowed because the package explicitly implements them. +% +% \begin{verblist}{1} +% \item[Accents: \so{na\"\i ve}] +% Accents can be used naturally. +% Support for the following accents is built-in: |\`|, |\'|, |\^|, |\"|, |\~|, +% |\=|, |\.|, |\u|, |\v|, |\H|, |\t|, |\c|, |\d|, |\b|, and |\r|. Additionally, +% if the \package{german} package \cite{german} is loaded you can also use the |"| +% accent command and write |\so{na"ive}|. See section~\ref{sec:soulaccent} for how to add +% further accents. +% \item[Quotes: \so{``quotes''}] +% The \soul\ package recognizes the quotes ligatures |``|, |''| and |,,|. +% The Spanish ligatures |!`| and |?`| are not recognized and have, thus, +% to be written enclosed in braces like in |\caps{{!`}Hola!}|. +% \item[Mathematics: \so{foo$x^3$bar}] +% Mathematic formulas are allowed, as long as they are +% surrounded by~\texttt\$. Note that the \LaTeX\ +% equivalent |\(...\)| does not work. +% \item[Hyphens and dashes: \so{re-sent}] +% Explicit hyphens as well as en-dashes~(|--|), em-dashes~(|---|) +% and the |\slash| command work as usual. +% \item[Newlines: \so{new\\line}] +% The |\\|~command fills the current line with white space +% and starts a new line. Spaces or linebreaks afterwards are ignored. +% Unlike the original \LaTeX\ command \soul's version does not handle +% optional parameters like in |\\*[1ex]|. +% \item[Breaking lines: \so{foo\linebreak bar}] +% The \cs{\linebreak} command breaks the line without +% filling it with white space at the end. \soul's version +% does not handle optional parameters like in |\linebreak[1]|. +% \cs{\break} can be used as a synonym. +% \item[Unbreakable spaces: \so{don't~break}] +% The |~|~command sets an unbreakable space. +% \item[Grouping: \so{Virchow{sche}}] +% A pair of braces can be used to let a group of characters +% be seen as one entity, so that \soul\ does +% for instance not space it out. The contents must, however, +% not contain potential hyphenation points. (See~\ref{par:Protecting}) +% \item[Protecting: \so{foo \mbox{little} bar}] +% An \cs{\mbox} also lets \soul\ see the contents as one +% item, but these may even contain hyphenation points. \cs{\hbox} can +% be used as a synonym. +% \item[Omitting: \so{\soulomit{foo}}] +% The contents of \cs{\soulomit} bypass the soul core and are typeset +% as is, without being letterspaced or underlined. Hyphenation points are +% allowed within the argument. The current font remains active, but can be +% overridden with \cs{\normalfont} etc. +% \item[Font switching commands: \so{foo \texttt{bar}}] +% All standard \TeX\ and \LaTeX\ font switching commands are allowed, as +% well as the \package{yfonts} package \cite{yfonts} font commands like \cs{\textfrak} etc. +% Further commands have to be registered using the \cs{\soulregister} +% command (see section~\ref{sec:soulregister}). +% \item[Breaking up ligatures: \ul{Auf{}lage}] +% Use |{}| or \cs{\null} to break up ligatures like `fl' in \cs{\ul}, \cs{\st} and \cs{\hl} +% arguments. +% This doesn't make sense for \cs{\so} and \cs{\caps}, though, because they break up +% every unprotected (ungrouped\slash unboxed) ligature, anyway, and would +% then just add undesirable extra space around the additional item. +% \end{verblist} +% +% +% +% +% \subsection{\texorpdfstring{\dots\ }{... }others don't} +% +% Although the new \soul\ is much more robust and forgiving than +% versions prior to~2.0, there are +% still some things that are not allowed in arguments. +% This is due to the complex engine, which has to read and inspect every +% character before it can hand it over to \TeX's paragraph builder. +% +% \begin{verblist}{20} +% \item[Grouping hyphenatable material: \so{foo {little} bar}] +% Grouped characters must not contain hyphenation points. Instead of +% |\so{foo {little}}| write |\so{foo \mbox{little}}|. You get a +% \texttt{`Re\-con\-struction failed'} error and a black square like +% \errsquare\ in the \caps{DVI} file where you violated this rule. +% \item[Discretionary hyphens: \so{Zu\discretionary{k-}{}{c}ker}] +% The argument must not contain discretionary hyphens. Thus, you have to +% handle cases like the German word |Zu\discretionary{k-}{}{c}ker| by yourself. +% \item[Nested soul commands: \ul{foo \so{bar} baz}] +% \soul\ commands must not be nested. If you really +% need such, put the inner stuff in a box and use this box. It will, of +% course, not get broken then.\\ +% \null\qquad|\newbox\anyboxname|\\ +% \null\qquad|\sbox\anyboxname{ \so{the worst} }|\\ +% \null\qquad|\ul{This is by far{\usebox\anyboxname}example!}|\\ +% yields:\\ +% \newbox\anyboxname +% \sbox\anyboxname{ \so{the worst} } +% \null\qquad\ul{This is by far{\usebox\anyboxname}example!} +% \item[Leaking font switches: \def\foo{\bf bar} \so{\foo baz}] +% A hidden font switching command that leaks into its neighborship +% causes a \texttt{`Reconstruction failed'} error. To avoid this either +% register the `container' (|\soulregister{\foo}{0}|), or limit its +% scope as in |\def\foo{{\bf bar}}|. Note that both +% solutions yield slightly different results. +% \item[Material that needs expansion: \so{\romannumeral\year}] +% In this example \cs{\so} would try to put space between \cs{\romannumeral} +% and \cs{\year}, which can, of course, not work. +% You have to expand the argument before you feed it to \soul, or even better: +% Wrap the material up in a command sequence and let \soul\ expand it: +% |\def\x{\romannumeral\year}| |\so\x|. \soul\ tries hard to expand +% enough, yet not too much. +% \item[Unexpandable material in command sequences: \def\foo{\bar} \so\foo] +% Some macros might not be expandable in an \cs{\edef} definition^^A +% \footnote{Try \texttt{\string\edef\string\x\char`\{\string\copyright\char`\}}. +% Yet \texttt{\string\copyright} works in \soul\ arguments, because it is +% explicitly taken care of by the package} +% and have to be protected with \cs{\noexpand} in front. This is automatically done +% for the following tokens: |~|, \cs{\,}, \cs{\TeX}, \cs{\LaTeX}, +% \cs{\S}, \cs{\slash}, \cs{\textregistered}, \cs{\textcircled}, and \cs{\copyright}, +% as well as for all registered fonts and accents. Instead of putting \cs{\noexpand} +% manually in front of such commands, as in |\def\foo{foo {\noexpand\bar} bar}| |\so\foo|, +% you can also register them as special (see section \ref{sec:soulregister}). +% \item[Other weird stuff: \so{foo \verb|\bar| baz}] +% \soul\ arguments must not contain \LaTeX\ environments, command definitions, +% and fancy stuff like |\vadjust|. \soul's |\footnote| command replacement +% does not support optional arguments. As long as you are writing simple, +% ordinary `horizontal' material, you are on the safe side. +% \end{verblist} +% +% +% +% +% +% +% +% \begin{table} +% \begin{center} +% \catcode`\|=12 +% \newcommand*\pref[1]{{\footnotesize\pageref{cmd:#1}}} +% \newcommand*\Ast{\rlap{$^\ast$}} +% \let\m\cs +% \let\ti\textit +% \begin{tabular}{r@{\hspace{.6em}}c@{\hspace{.6em}}l} +% &\hbox to0pt{\hss\footnotesize page\hss}&\\[.5ex] +% \verb+\so{letterspacing}+& \pref{so} &\so{letterspacing}\\ +% \verb+\caps{CAPITALS, Small Capitals}+& \pref{caps} &\caps{CAPITALS, Small Capitals}\\ +% \verb+\ul{underlining}+& \pref{ul} &\ul{underlining}\\ +% \verb+\st{striking out}+& \pref{st} &\st{striking out}\\ +% \verb+\hl{highlighting}+& \pref{hl} &highlighting\\ +% \\ +% \verb+\soulaccent{\cs}+& \pref{soulaccent} &\ti{add accent} \cs{\cs} \ti{to accent list}\\ +% \verb+\soulregister{\cs}{0}+& \pref{soulregister} &\ti{register command} \m{\cs}\\ +% \verb+\sloppyword{text}+& \pref{sloppyword} &\ti{typeset} \m{text} \ti{with stretchable spaces}\\ +% \\ +% \verb+\sodef\cs{1em}{2em}{3em}+& \pref{sodef} &\ti{define new spacing command} \m{\cs}\\ +% \verb+\resetso+& \pref{resetso} &\ti{reset} \m{\so} \ti{dimensions}\\ +% \verb+\capsdef{////}{1em}{2em}{3em}+\Ast& \pref{capsdef} &\ti{define (default)} \m{\caps} \ti{data entry}\\ +% \verb+\capssave{name}+\Ast& \pref{capssave} &\ti{save} \m{\caps} \ti{database under name} \rlap{\texttt{name}}\\ +% \verb+\capsselect{name}+\Ast& \pref{capssave} &\ti{restore} \m{\caps} \ti{database of name} \rlap{\texttt{name}}\\ +% \verb+\capsreset+\Ast& \pref{capsreset} &\ti{clear caps database}\\ +% \verb+\setul{1ex}{2ex}+& \pref{setul} &\ti{set} \m{\ul} \ti{dimensions}\\ +% \verb+\resetul+& \pref{resetul} &\ti{reset} \m{\ul} \ti{dimensions}\\ +% \verb+\setuldepth{y}+& \pref{setuldepth} &\ti{set underline depth to depth of an} y\\ +% \verb+\setuloverlap{1pt}+& \pref{setuloverlap} &\ti{set underline overlap width}\\ +% \verb+\setulcolor{red}+& \pref{setulcolor} &\ti{set underline color}\\ +% \verb+\setstcolor{green}+& \pref{setstcolor} &\ti{set overstriking color}\\ +% \verb+\sethlcolor{blue}+& \pref{sethlcolor} &\ti{set highlighting color}\\ +% \end{tabular} +% \caption{List of all available commands. The number points to the +% page where the command is described. Those marked +% with a little asterisk are only available when the package +% is used together with \LaTeX, because they rely on the +% \emph{New Font Selection Scheme (NFSS)} used in \LaTeX.} +% \label{tab:survey} +% \end{center} +% \end{table} +% +% +% +% +% +% +% +% \subsection{Troubleshooting} +% +% Unfortunately, there's just one helpful error message provided by +% the \soul\ package, that actually describes the underlying problem. All other +% messages are generated directly by \TeX\ and show the low-level +% commands that \TeX\ wasn't happy with. They'll hardly point you +% to the violated rule as described in the paragraphs above. +% If you get such a mysterious error message for a line that contains +% a \soul\ statement, then comment that statement out and see if the message +% still appears. +% \texttt{`Incomplete }\cs{\ifcat}\texttt{'} is such a non-obvious message. +% If the message doesn't appear now, then check the argument for +% violations of the rules as listed in~\S\S\,20--26. +% +% +% +% \subsubsection{\texttt{`Reconstruction failed'}} +% +% This message appears, if \ref{par:Grouping hyphenatable material} or +% \ref{par:Leaking font switches} was +% violated. It is caused by the fact that the reconstruction pass +% couldn't collect tokens with an overall width of the syllable that +% was measured by the analyzer. This does either occur when you +% grouped hyphenatable text or used an unregistered command +% that influences the syllable width. Font switching commands belong +% to the latter group. See the above cited sections for how to fix +% these problems. +% +% +% +% \subsubsection{Missing characters} +% +% If you have redefined the internal font as described in section \ref{sec:internalfont}, +% you may notice that some characters are omitted without any error message +% being shown. This happens if you have chosen, let's say, a font with +% only 128~characters like the |cmtt10| font, but are using characters +% that aren't represented in this font, e.\,g.~characters with codes +% greater than~127. +% +% +% +% +% +% +% +% +% +% \section{\texorpdfstring{\so{Letterspacing}}{Letterspacing}} +% +% \subsection{How it works} +% \label{sec:so} +% +% The base macro for letterspacing is called \describemacro{\so}. +% It typesets the given argument with \syn{inter-letter space} +% between every two characters, \syn{inner space} between words +% and \syn{outer space} before and after the spaced out text. +% If we let ``$\cdot$'' stand for \syn{inter-letter space}, ``$\ast$'' +% for \syn{inner spaces} and ``$\bullet$'' for \syn{outer +% spaces,} then the input on the left side of the following table +% will yield the schematic output on the right side: +% +% \begin{center} +% \def\.{$\cdot$} +% \def\-{\kern1pt$\ast$\kern1pt} +% \def\*{$\bullet$} +% \def\_{\texttt{\char"20}} +% \begin{tabular}{ccc} +% 1.& \verb*|XX\so{aaa bbb ccc}YY|& \textsf{XXa\.a\.a\-b\.b\.b\-c\.c\.cYY}\\ +% 2.& \verb*|XX \so{aaa bbb ccc} YY|& \textsf{XX\*a\.a\.a\-b\.b\.b\-c\.c\.c\*\kern-1ptYY}\\ +% 3.& \verb*|XX {\so{aaa bbb ccc}} YY|& \textsf{XX\*a\.a\.a\-b\.b\.b\-c\.c\.c\*\kern-1ptYY}\\ +% 4.& \verb*|XX \null{\so{aaa bbb ccc}}{} YY|& \textsf{XX\_a\.a\.a\-b\.b\.b\-c\.c\.c\_YY}\\ +% \end{tabular} +% \end{center} +% ^^A* % fool vim (fixes syntax highlighting) +% +% \noindent +% Case~1 shows how letterspacing macros (\cs{\so} and \cs{\caps}) behave if +% they aren't following or followed by a space: they omit outer space around +% the \soul\ statement. Case~2 is what you'll mostly need---letterspaced +% text amidst running text. Following and leading space get replaced by +% \syn{outer space}. It doesn't matter if there are opening braces before +% or closing braces afterwards. \soul\ can see through both of them (case~3). +% Note that leading space has to be at least |5sp| wide to be recognized as +% space, because \LaTeX\ uses tiny spaces generated by |\hskip1sp| as marker. +% Case~4 shows how to enforce normal spaces instead of \syn{outer spaces:} +% Preceding space can be hidden by |\kern0pt| or \cs{\null} or any character. +% Following space can also be hidden by any token, but note that a typical macro name +% like \cs{\relax} or \cs{\null} would also hide the space thereafter. +% +% +% The values are predefined for typesetting facsimiles mainly with +% \emph{Fraktur} fonts. +% You can define your own spacing +% macros or overwrite the original \cs{\so} meaning using the macro +% \describemacro{\sodef}: +% +% \begin{syntax} +% |\sodef|\<cmd>|{|\<font>|}{|\<inter-letter space>|}{|\<inner space>|}{|\<outer space>|}| +% \end{syntax} +% +% The space dimensions, all of which are mandatory, should be defined in terms of |em| +% letting them grow and shrink with the respective fonts. +% +% \begin{example} +% |\sodef\an{}{.4em}{1em plus1em}{2em plus.1em minus.1em}| +% \end{example} +% +% After that you can type `|\an{example}|' to get +% {\sodef\an{}{.4em}{1em plus1em}{2em plus.1em minus.1em}^^A +% `\an{example}'.} +% The \describemacro{\resetso} command resets \cs{\so} +% to the default values. +% +% +% +% +% \subsection{Some examples} +% +%^^A===================================================== +% \begin{examples} +% +% \soultest{Ordinary text} +% |\so{electrical industry}| +% {\so{electrical industry}} +% +% \soultest{Use \texttt{\string\-} to mark hyphenation points} +% |\so{man\-u\-script}| +% {\so{man\-u\-script}} +% +% \soultest{Accents are recognized} +% |\so{le th\'e\^atre}| +% {\so{le th\'e\^atre}} +% +% \soultest{\texttt{\string\mbox} and \texttt{\string\hbox} protect material that +% contains hyphenation points. The contents are treated as one, unbreakable entity} +% |\so{just an \mbox{example}}| +% {\so{just an \mbox{example}}} +% +% \soultest{Punctuation marks are spaced out, if they are +% put into the group} +% |\so{inside.} \& \so{outside}.| +% {\so{inside.} \& \so{outside}.} +% +% \soultest{Space-out skips may be removed by typing \texttt{\string\<}. +% It's, however, desirable to put the quotation marks out of +% the argument} +% |\so{``\<Pennsylvania\<''}| +% {\so{``\<Pennsylvania\<''}} +% +% \soultest{Numbers should never be spaced out} +% |\so{1\<3 December {1995}}| +% {\so{1\<3 December {1995}}} +% +% \soultest{Explicit hyphens like |-|, |--| and |---| are recognized. +% \texttt{\string\slash} outputs a slash and enables \TeX\ to break the line +% afterwards} +% |\so{input\slash output}| +% {\so{input\slash output}} +% +% \soultest{To keep \TeX\ from breaking lines between the hyphen and `jet' +% you have to protect the hyphen. This is no \soul\ restriction +% but normal \TeX\ behavior} +% |\so{\dots and \mbox{-}jet}| +% {\so{\dots and \mbox{-}jet}} +% +% \soultest{The \texttt{\~} command inhibits line breaks} +% |\so{unbreakable~space}| +% {\so{unbreakable~space}} +% +% \soultest{\texttt{\string\\} works as usual. Additional arguments +% like \texttt{*} or vertical space are not accepted, though} +% |\so{broken\\line}| +% {\so{broken\\line}} +% +% \soultest{\texttt{\string\break} breaks the line without filling it with white space} +% |\so{pretty awful\break test}| +% {\so{pretty awful\break test}} +% +% \end{examples} +%^^A===================================================== +% +% +% +% +% +% +% +% +% +% +% +% \subsection[Typesetting \texorpdfstring{\caps{caps-and-small-caps}}{caps-and-small-caps} fonts] +% {Typesetting capitals-and-small-capitals fonts} +% +% There is a special letterspacing command called \describemacro{\caps}, +% which differs from \cs{\so} in that it switches to caps-and-small-caps +% font shape, defines only slight spacing and is able to select spacing +% value sets from a database. This is a requirement for high-quality +% typesetting \cite{Tschichold}. The following lines show the effect +% of \cs{\caps} in comparison with the normal textfont and with +% small-capitals shape: +% +% \def\sampletext{DONAUDAMPFSCHIFFAHRTSGESELLSCHAFT} +% \medskip\noindent +% \begin{tabular}{rl} +% |\normalfont|&\sampletext\\ +% |\scshape|&{\scshape\sampletext}\\ +% |\caps|&\caps\sampletext\\ +% ^^A|\person|&\person\sampletext\\ +% \end{tabular} +% +% \medbreak\noindent +% The \cs{\caps} font database is by default empty, i.\,e., it contains +% just a single default entry, which yields the result as shown in the +% example above. +% New font entries may be added \emph{on top} of this list using the \describemacro{\capsdef} +% command, which takes five arguments: The first argument describes the font with +% \emph{encoding, family, series, shape,} and \emph{size,}^^A +% \footnote{as defined by the \caps{NFSS}, the ``New Font Selection Scheme''} +% each optionally +% (e.\,g.~|OT1/cmr/m/n/10| for this very font, or only |/ppl///12| for all +% \emph{palatino} fonts at size 12\,pt). The \emph{size} entry may also contain +% a size range (\texttt{5-10}), where zero is assumed for an omitted lower +% boundary (\texttt{-10}) and a very, very big number for an omitted upper +% boundary (\texttt{5-}). The +% upper boundary is not included in the range, so, in the example below, all +% fonts with sizes greater or equal 5\,pt and smaller than 15\,pt are accepted +% ($5\,\mbox{pt}\le size<15\,\mbox{pt}$). +% The second argument may contain font switching commands such as \cs{\scshape}, +% it may as well be empty or contain debugging commands (e.\,g.~|\message{*}|). +% The remaining three, mandatory arguments are the spaces as described in +% section~\ref{sec:so}. +% +% \begin{example} +% |\capsdef{T1/ppl/m/n/5-15}{\scshape}{.16em}{.4em}{.2em}| +% \end{example} +% +% The \cs{\caps} command goes through the data list from top to bottom +% and picks up the first matching set, so the order of definition is essential. +% The last added entry is examined first, while the pre-defined default entry +% will be examined last and will match any font, if no entry was taken before. +% +% To override the default values, just define a new default entry using +% the identifier |{////}|. This entry should be defined first, because no +% entry after it can be reached. +% +% The \cs{\caps} database can be cleared with the \describemacro{\capsreset} +% command and will only contain the default entry thereafter. The +% \describemacro{\capssave} command saves the whole current database +% under the given name. \describemacro{\capsselect} restores such a database. +% This allows to predefine different groups of \cs{\caps} data sets: +% +% \begin{example} +% |\capsreset|\\ +% |\capsdef{/cmss///12}{}{12pt}{23pt}{34pt}|\\ +% |\capsdef{/cmss///}{}{1em}{2em}{3em}|\\ +% |...|\\ +% |\capssave{wide}|\\ +% \end{example} +% \indent +% \begin{example} +% |%---------------------------------------|\\ +% |\capsreset|\\ +% |\capsdef{/cmss///}{}{.1em}{.2em}{.3em}|\\ +% |...|\\ +% |\capssave{narrow}|\\ +% \end{example} +% \indent +% \begin{example} +% |%---------------------------------------|\\ +% |{\capsselect{wide}|\\ +% |\title{\caps{Yet Another Silly Example}}|\\ +% |}|\\ +% \end{example} +% +% See the `|example.cfg|' file for a detailed example. +% If you have defined a bunch of sets for different fonts and sizes, +% you may lose control over what fonts are used by the package. With the +% package option \DescribeOption{capsdefault}\option{capsdefault} selected, +% \cs{\caps} prints its argument underlined, if no set was specified for a +% particular font and the default set had to be used. +% +% +% +% +% +% +% +% +% +% +% +% \subsection{Typesetting Fraktur} +% \label{sec:fraktur} +% +% Black letter fonts^^A +%^^A%% +% \footnote{See the great black letter fonts, which \person{Yannis Haralambous} +% kindly provided, and the \package{oldgerm} and \package{yfonts} package~\cite{yfonts} +% as their \LaTeX\ interfaces.} +%^^A%% +% deserve some additional considerations. As stated in section~\ref{sec:typesetting}, +% the ligatures |ch|, |ck|, |sz|~(\cs{\ss}), and~|tz| have to remain unbroken in spaced out +% \emph{Fraktur} text. This may look strange at first glance, but you'll get used to it: +% +% \begin{example} +% |\textfrak{\so{S{ch}u{tz}vorri{ch}tung}}| +% \end{example} +% +% You already know that grouping keeps the |soul| mechanism from separating such ligatures. +% This is quite important for |s:|, |a*|, and~|"a|. As hyphenation is stronger than +% grouping, especially the |sz| may cause an error, if hyphenation happens to occur between +% the letters |s| and~|z|. (\TeX\ hyphenates the German word |auszer| wrongly like +% |aus-zer| instead of like |au-szer|, because the German hyphenation patterns +% do, for good reason, not see |sz| as `\cs{\ss}'.) In such cases you can protect tokens with the +% sequence e.\,g.~|\mbox{sz}| or a properly defined command. The \cs{\ss} command, +% which is defined by the \package{yfonts} package, and similar commands will suffice as well. +% +% +% +% +% +% +% +% \subsection{Dirty tricks} +% \label{sec:dirtytricks} +% +% Narrow columns are hard to set, because they don't allow much spacing +% flexibility, hence long words often cause overfull boxes. A macro +% could use \cs{\so} to insert stretchability between the single +% characters. Table~\ref{tab:dirtytricks} shows some text typeset with such +% a macro at the left side and under \emph{plain} conditions at +% the right side, both with a width of~6\,pc. +% +% \def\sampletext{Some magazines and newspapers prefer this kind of spacing +% because it reduces hyphenation problems to a minimum\<. Unfortunately\<, such +% paragraphs aren't especially beautiful\<.} +% \newbox\dirtytrick +% \setbox\dirtytrick\vbox{ +% \batchmode ^^A we don't want to see all these overfull boxes ... +% \leavevmode\hspace{0ptplus1fil} +% \hbox{\parindent0pt\plainsetup\let\<\relax +% \vtop{\hsize6pc\raggedright\sampletext}\hskip1em +% \vtop{\hsize6pc\magstylepar\sampletext}\hskip1em +% \vtop{\hsize6pc\sampletext}\hss} +% \errorstopmode} +% +% \begin{table} +% \begin{center} +% \overfullrule5pt +% \usebox\dirtytrick +% \caption{Ragged-right, magazine style (using \soul), and block-aligned +% in comparison. But, frankly, none of them is really acceptable. +% (Don't do this at home, children!)} +% \label{tab:dirtytricks} +% \end{center} +% \end{table} +% +% +% +% +% +% +% +% \section{\texorpdfstring{\ul{Underlining}}{Underlining}} +% +% The underlining macros are my answer to Prof.~\person{Knuth'{\normalfont s}} +% exercise 18.26 from his \TeX{}book~\cite{DEK}. \texttt{:-)} Most of what +% is said about the macro \describemacro{\ul} is also true of the +% striking out macro \describemacro{\st} and the highlighting macro \describemacro{\hl}, +% both of which are in fact derived from the former. +% +% +% +% +% \subsection{Settings} +% +% \subsubsection{Underline depth and thickness} +% +% The predefined \syn{underline depth} and \syn{thickness} +% work well with most fonts. They can be changed using the macro \describemacro{\setul}. +% +% \begin{syntax} +% |\setul{|\<underline depth>|}{|\<underline thickness>|}| +% \end{syntax} +% +% Either dimension can be omitted, in which case there has to be +% an empty pair of braces. +% Both values should be defined in terms of |ex|, letting them +% grow and shrink with the respective fonts. +% The \describemacro{\resetul} command restores the standard values. +% +% Another way to set the \syn{underline depth} is to use the macro +% \describemacro{\setuldepth}. It sets the depth such that the +% underline's upper edge lies 1\,pt beneath the given argument's +% deepest depth. If the argument is empty, all +% letters---i.\,e.\ all characters whose \cs{\catcode} currently +% equals 11---are taken. Examples: +% +% \begin{example} +% |\setuldepth{ygp}|\\ +% |\setuldepth\strut|\\ +% |\setuldepth{}|\\ +% \end{example} +% +% +% +% \subsubsection{Line color} +% +% The underlines are by default black. The color can be changed by +% using the \describemacro{\setulcolor} command. It takes one argument that can be any +% of the color specifiers as described in the |color| package. This package +% has to be loaded explicitly. +% +% \indent +% \begin{example} +% |\documentclass{article}|\\ +% |\usepackage{color,soul}|\\ +% |\definecolor{darkblue}{rgb}{0,0,0.5}|\\ +% |\setulcolor{darkblue}|\\ +% \end{example} +% +% \indent +% \begin{example} +% |\begin{document}|\\ +% |...|\\ +% |\ul{Cave: remove all the underlines!}|\\ +% |...|\\ +% |\end{document}|\\ +% \end{example} +% +% +% The colors for overstriking lines and highlighting are likewise set +% with \describemacro{\setstcolor} (default: black) and \describemacro{\sethlcolor} +% (default: yellow). If the \package{color} package wasn't loaded, +% underlining and overstriking color are black, while highlighting +% is replaced by underlining. +% +% +% +% +% +% +% +% \subsubsection{The \program{dvips} problem} +% \label{sec:dvips} +% +% \ul{Underlining}, \st{striking out} and highlighting build up +% their lines with many short line segments. If you used the `\program{dvips}' +% program with default settings, you would get little gaps on some places, because +% the \emph{maxdrift} parameter allows the single objects to drift +% this many pixels from their real positions. +% \bigbreak +% +% \noindent +% There are two ways to avoid the problem, where the \soul\ package +% chooses the second by default: +% \begin{enumerate} +% \item +% Set the \emph{maxdrift} value to zero, e.\,g.: |dvips -e 0 file.dvi|. +% This is probably not a good idea, since the letters may then no longer be +% spaced equally on low resolution printers. +% \item +% Let the lines stick out by a certain amount on each side so that they +% overlap. This overlap amount can be set using the \describemacro{\setuloverlap} +% command. It is set to 0.25\,pt by default. |\setuloverlap{0pt}| turns overlapping off. +% \end{enumerate} +% +% +% +% +% +% +% \subsection{Some examples} +% +%^^A===================================================== +% \begin{examples} +% +% \soultest{Ordinary text} +% |\ul{electrical industry}| +% {\ul{electrical industry}} +% +% \soultest{Use \texttt{\string\-} to mark hyphenation points} +% |\ul{man\-u\-script}| +% {\ul{man\-u\-script}} +% +% \soultest{Accents are recognized} +% |\ul{le th\'e\^atre}| +% {\ul{le th\'e\^atre}} +% +% \soultest{\texttt{\string\mbox} and \texttt{\string\hbox} protect material that +% contains hyphenation points. The contents are treated as one, unbreakable entity} +% |\ul{just an \mbox{example}}| +% {\ul{just an \mbox{example}}} +% +% \soultest{Explicit hyphens like |-|, |--| and |---| are recognized. +% \texttt{\string\slash} outputs a slash and enables \TeX\ to break the line +% afterwards} +% |\ul{input\slash output}| +% {\ul{input\slash output}} +% +% \soultest{To keep \TeX\ from breaking lines between the hyphen and `jet' +% you have to protect the hyphen. This is no \soul\ restriction +% but normal \TeX\ behavior} +% |\ul{\dots and \mbox{-}jet}| +% {\ul{\dots and \mbox{-}jet}} +% +% \soultest{The \texttt{\~} command inhibits line breaks} +% |\ul{unbreakable~space}| +% {\ul{unbreakable~space}} +% +% \soultest{\texttt{\string\\} works as usual. Additional arguments +% like \texttt{*} or vertical space are not accepted, though} +% |\ul{broken\\line}| +% {\ul{broken\\line}} +% +% \soultest{\texttt{\string\break} breaks the line without filling it with white space} +% |\ul{pretty awful\break test}| +% {\ul{pretty awful\break test}} +% +% \soultest{Italic correction needs to be set manually} +% |\ul{foo \emph{bar\/} baz}| +% {\ul{foo \emph{bar\/} baz}} +% +% \end{examples} +%^^A===================================================== +% +% +% +% +% +% +% +% +% +% +% +% +% +% \section{Customization} +% +% \subsection{Adding accents} +% \label{sec:soulaccent} +% +% The \soul\ scanner generally sees every input token separately. +% It has to be taught that some tokens belong together. For accents this is done +% by registering them via the \describemacro{\soulaccent} macro. +% +% \begin{syntax} +% |\soulaccent{|\<accent command>|}| +% \end{syntax} +% +% The standard accents, however, are already pre-registered: +% |\`|, |\'|, |\^|, |\"|, |\~|, |\=|, |\.|, |\u|, |\v|, |\H|, |\t|, +% |\c|, |\d|, |\b|, and |\r|. If used together with the \package{german} +% package, \soul\ automatically adds the |"| command. +% Let's assume you have defined |\%| to put some weird accent on +% the next character. Simply put the following line into your |soul.cfg| +% file (see section~\ref{sec:config}): +% +% \begin{example} +% |\soulaccent{\%}| +% \end{example} +% +% Note that active characters like the |"| command have already +% to be \cs{\active} when they are stored or they won't be recognized +% later. This can be done temporarily, as in |{\catcode\`"\active\soulaccent{"}}|. +% +% +% +% +% \subsection{Adding font commands} +% \label{sec:soulregister} +% +% To convince \soul\ not to feed font switching (or other) +% commands to the analyzer, but rather to execute them immediately, +% they have to be registered, too. The \describemacro{\soulregister} macro +% takes the name of a command name and either |0| or |1| for the number +% of arguments: +% +% \begin{syntax} +% |\soulregister{|\<command name>|}{|\<number of arguments>|}| +% \end{syntax} +% +% If \cs{\bf} and \cs{\emph} weren't already registered, you would +% write the following into your |soul.cfg| configuration file: +% +% \begin{example} +% |\soulregister{\bf}{0} % {\bf foo}| \\ +% |\soulregister{\emph}{1} % \emph{bar}|\\ +% \end{example} +% +% +% All standard \TeX\ and \LaTeX\ font commands, as well as the +% \package{yfonts} commands are already pre-registered: +% +% \begin{example} +% |\em, \rm, \bf, \it, \tt, \sc, \sl, \sf, \emph, \textrm,|\\ +% |\textsf, \texttt, \textmd, \textbf, \textup, \textsl,|\\ +% |\textit, \textsc, \textnormal, \rmfamily, \sffamily,|\\ +% |\ttfamily, \mdseries, \upshape, \slshape, \itshape,|\\ +% |\scshape, \normalfont, \tiny, \scriptsize, \footnotesize,|\\ +% |\small, \normalsize, \large, \Large, \LARGE, \huge, \Huge,|\\ +% |\MakeUppercase, \textsuperscript, \footnote,|\\ +% |\textfrak, \textswab, \textgoth, \frakfamily,|\\ +% |\swabfamily, \gothfamily|\\ +% \end{example} +% +% You can also register other commands as fonts, so the +% analyzer won't see them. This may be necessary for some +% macros that \soul\ refuses to typeset correctly. +% But note, that \cs{\so} and \cs{\caps} won't put their +% letter-skips around then. +% +% +% +% +% +% +% \subsection{Changing the internal font} +% \label{sec:internalfont} +% +% The \soul\ package uses the |ectt1000| font while it analyzes +% the syllables. This font is used, because it +% has 256~mono-spaced characters without any kerning. +% It belongs to \person{J\"org Knappen'\textrm{s}} +% \caps{EC}-fonts, which should be part of every modern \TeX\ installation. +% If \TeX\ reports ``\texttt{I can't find file `ectt1000'}'' you don't +% seem to have this font installed. It is recommended that +% you install at least the file |ectt1000.tfm| which has less than 1.4\,kB\null. +% Alternatively, you can let the \soul\ package use the |cmtt10| font that +% is part of any installation, or some other mono-spaced font: +% +% \begin{example} +% |\font\SOUL@tt=cmtt10| +% \end{example} +% +% Note, however, that \soul\ does only handle characters, +% for which the internal font has a character with the same +% character code. As |cmtt10| contains only characters with codes +% 0 to~127, you can't typeset characters with codes 128 to~255. +% These 8-bit character codes are used by many fonts with non-ascii +% glyphs. So the |cmtt10| font will, for example, not work for |T2A| +% encoded cyrillic characters. +% +% +% +% +% +% +% +% \subsection{The configuration file} +% \label{sec:config} +% +% If you want to change the predefined settings or add new features, +% then create a file named `|soul.cfg|' and put it in a directory, where \TeX\ +% can find it. This configuration file will then be loaded +% at the end of the |soul.sty| file, so you may redefine +% any settings or commands therein, select package options and even +% introduce new ones. But if you intend to give +% your documents to others, don't forget to give them the +% required configuration files, too! That's how such a file +% could look like: +% +% \indent +% \begin{example} +% |% define macros for logical markup|\\ +% |\sodef\person{\scshape}{0.125em}{0.4583em}{0.5833em}|\\ +% \\ +% |\sodef\SOUL@@@versal{\upshape}{0.125em}{0.4583em}{0.5833em}|\\ +% |\DeclareRobustCommand*\versal[1]{%|\\ +% | \MakeUppercase{\SOUL@@@versal{#1}}%|\\ +% |}|\\ +% \end{example} +% +% \indent +% \begin{example} +% |% load the color package and set|\\ +% |% a different highlighting color|\\ +% |\RequirePackage{color}|\\ +% |\definecolor{lightblue}{rgb}{.90,.95,1}|\\ +% |\sethlcolor{lightblue}|\\ +% |\endinput| +% \end{example} +% +% You can safely use the |\SOUL@@@| namespace for internal macros---it +% won't be used by the \soul\ package in the future. +% +% +% +% +% +% +% +% +% +% +% \section{Miscellaneous} +% +% \subsection{Using \texorpdfstring{\soul\ }{soul }with other flavors of \texorpdfstring{\TeX}{TeX}} +% \label{sec:plain} +% +% This documentation describes how to use \soul\ together +% with \LaTeXe, for which it is optimized. It works, however, with +% all other flavors of \TeX, too. There are just some minor restrictions +% for Non-\LaTeX\ use: +% +% The \cs{\caps} command doesn't use a database, it is only a dumb +% definition with fixed values. It switches to \cs{\capsfont}, which---unless +% defined explicitly like in the following example---won't really change +% the used font at all. The commands \cs{\capsreset} and \cs{\capssave} +% do nothing. +% +% \begin{example} +% |\font\capsfont=cmcsc10|\\ +% |\caps{Tschichold}|\\ +% \end{example} +% +% None of the commands are made `robust', so they have to be +% explicitly protected in fragile environments like in \cs{\write} +% statements. +% To make use of colored underlines or highlighting you have to +% use the \package{color} package wrapper from \caps{CTAN}^^A +% \footnote{\texttt{CTAN:/macros/plain/graphics/\char`\{miniltx.tex,color.tex\char`\}}}, +% instead of the \package{color} package directly: +% +% \begin{example} +% |\input color|\\ +% |\input soul.sty|\\ +% |\hl{highlighted}|\\ +% |\bye|\\ +% \end{example} +% +% The \option{capsdefault} package option is mapped to a simple command +% \describemacro{\capsdefault}. +% +% +% +% +% +% +% +% \subsection{Using \texorpdfstring{\soul\ }{soul }commands for logical markup} +% \label{sec:markup} +% +% It's generally a bad idea to use font style commands like \cs{\textsc} +% in running text. There should always be some reasoning behind changing +% the style, such as ``names of persons shall be typeset in a caps-and-small-caps +% font''. So you declare in your text just that some words are the name of a +% person, while you define in the preamble or, even better, in a separate +% style file how to deal with persons: +% +% \begin{example} +% |\newcommand*\person{\textsc}|\\ +% |...|\\ +% |``I think it's a beautiful day to go to the zoo and feed|\\ +% |the ducks. To the lions.'' --~\person{Brian Kantor}|\\ +% \end{example} +% +% It's quite simple to use \soul\ commands that way: +% +% \begin{example} +% |\newcommand\comment*{\ul} % or \let\comment=\ul|\\ +% |\sodef\person{\scshape}{0.125em}{0.4583em}{0.5833em}|\\ +% \end{example} +% +% Letterspacing commands like \cs{\so} and \cs{\caps} have to +% check whether they are followed by white space, in which case +% they replace that space by \syn{outer space}. Note that \soul\ +% does look through closing braces. Hence you can conveniently bury +% a \soul\ command within another macro like in the following +% example. Use any other token to hide following space if necessary, +% for example the \cs{\null} macro. +% +% \begin{example} +% |\DeclareRobustCommand*\versal[1]{%|\\ +% | \MakeUppercase{\SOUL@@@versal{#1}}%|\\ +% |}|\\ +% |\sodef\SOUL@@@versal{\upshape}{0.125em}{0.4583em}{0.5833em}|\\ +% \end{example} +% +% +% But what if the \soul\ command is for some reason not the last one +% in that macro definition and thus cannot look ahead at the following token? +% +% +% \begin{example} +% |\newcommand*\somsg[1]{\so{#1}\message{#1}}|\\ +% |...|\\ +% |foo \somsg{bar} baz % wrong spacing after `bar'!|\\ +% \end{example} +% +% In this case you won't get the following space replaced by \emph{outer space} +% because when \soul\ tries to look ahead, it only sees the token +% \cs{\message} and consequently decides that there is no space to replace. +% You can get around this by explicitly calling the space scanner again. +% +% \begin{example} +% |\newcommand*\somsg[1]{{%|\\ +% | \so{#1}%|\\ +% | \message{bar}%|\\ +% | \let\\\SOUL@socheck|\\ +% | \\%|\\ +% |}}|\\ +% \end{example} +% +% However, \cs{\SOUL@socheck} can't be used directly, because it would discard +% any normal space. \cs{\\} doesn't have this problem. +% The additional pair of braces avoids that its definition leaks out +% of this macro. In the example above you could, of course, simply +% have put \cs{\message} in front, so you hadn't needed to +% use the scanner macro \cs{\SOUL@socheck} at all. +% +% Many packages do already offer logical markup commands that default +% to some standard \LaTeX\ font commands or to \cs{\relax}. One example +% is the \package{jurabib} package~\cite{jurabib}, which makes the use of +% \soul\ a challenge. This package implements lots of +% formatting macros. Let's have a look at one of them, \cs{\jbauthorfont}, +% which is used to typeset author names in citations. +% The attempt to simply +% define |\let\jbauthorfont\caps| fails, because the macro isn't directly +% applied to the author name as in |\jbauthorfont{Don Knuth}|, but +% to another command sequence: |\jbauthorfont{\jb@@author}|. Not even +% \cs{\jb@@author} contains the name, but instead further commands that +% at last yield the requested name. That's why we have to expand +% the contents first. This is quite tricky, because we must not +% expand too much, either. Fortunately, we can offer the contents +% wrapped up in yet another macro, so that \soul\ knows that it has to +% use its own macro expansion mechanism: +% +% \begin{example} +% |\renewcommand*\jbauthorfont[1]{{%|\\ +% | \def\x{#1}%|\\ +% | \caps\x|\\ +% |}}|\\ +% \end{example} +% +% Some additional kerning after |\caps\x| wouldn't hurt, because +% the look-ahead scanner is blinded by further commands that follow +% in the \package{jurabib} package. Now we run into the next problem: +% cited names may contain commands +% that must not get expanded. We have to register them as special +% command: +% +% \begin{example} +% |\soulregister\jbbtasep{0}|\\ +% |...|\\ +% \end{example} +% +% But such registered commands bypass \soul's kernel and we don't +% get the correct spacing before and afterwards. So we end up +% redefining \cs{\jbbtasep}, whereby you should, of course, use +% variables instead of numbers: +% +% \begin{example} +% |\renewcommand*\jbbtasep{%|\\ +% | \kern.06em|\\ +% | \slash|\\ +% | \hskip.06em|\\ +% | \allowbreak|\\ +% |}|\\ +% \end{example} +% +% Another problem arises: bibliography entries that must not get +% teared apart are supposed to be enclosed in additional braces. +% This, however, won't work with \soul\ because of +% \ref{par:Grouping hyphenatable material}. A simple trick will +% get you around that problem: define a dummy command that only +% outputs its argument, and register that command: +% +% \begin{example} +% |\newcommand*\together[1]{#1}|\\ +% |\soulregister\together{1}|\\ +% \end{example} +% +% Now you can write ``|Author = {\together{Don Knuth}}|'' and +% \package{jurabib} won't dare to reorder the parts of the name. +% And what if some name shouldn't get letterspaced at all? Overriding +% a conventional font style like \cs{\textbf} that was globally +% set is trivial, you just have to specify the style that you +% prefer in that very bibliography entry. In our example, if we +% wanted to keep \soul\ from letterspacing a particular entry, +% although they are all formatted by our \cs{\jbauthorfont} +% and hence fed to \cs{\caps}, we'd use the following construction: +% +% \begin{example} +% |Author = {\soulomit{\normalfont\huge Donald E. Knuth}}|\\ +% \end{example} +% +% The \package{jurabib} package is probably one of the more +% demanding packages to collaborate with \soul. Everything else +% can just become easier. +% +% +% +% +% +% +% +% +% \subsection{Typesetting long words in narrow columns} +% \label{sec:sloppyword} +% +% Narrow columns are best set |flushleft|, because not even the best +% hyphenation algorithm can guarantee acceptable line breaks without +% overly stretched spaces. +% However, in some rare cases one may be \emph{forced} to typeset +% block aligned. When typesetting in languages like German, where +% there are really long words, the \describemacro{\sloppyword} macro +% might help a little bit. It adds enough stretchability between the +% single characters to make the hyphenation algorithm happy, but +% is still not as ugly as the example in section~\ref{sec:dirtytricks} +% demonstrates. In the following example the left column was typeset +% as ``|Die \sloppyword{Donau...novelle} wird ...|'': +% +% \begin{center} +% \def\word{Do\-nau\-dampf\-schiff\-fahrts\-ge\-sell\-schafts\-^^A +% ka\-pi\-t\"ans\-wit\-wen\-pen\-si\-ons\-ge\-setz\-no\-vel\-le} +% \begin{minipage}{1.5in} +% \plainsetup +% Die +% \expandafter\sloppyword\expandafter{\word} +% wird mit sofortiger Wirkung au\ss er Kraft gesetzt. +% \end{minipage} +% \hspace{1em} +% \batchmode +% \begin{minipage}{1.5in} +% \plainsetup +% Die \word\ wird mit sofortiger Wirkung au\ss er Kraft gesetzt. +% \end{minipage} +% \errorstopmode +% \end{center} +% +% +% +% +% +% +% +% \subsection{Using \texorpdfstring{\soul\ }{soul }commands in section headings} +% +% Letterspacing was often used for section titles in the past, +% mostly centered and with a closing period. The following example +% shows how to achieve this using the \package{titlesec} +% package \cite{titlesec}: +% +% \begin{example} +% |\newcommand*\periodafter[2]{#1{#2}.}|\\ +% |\titleformat{\section}[block]|\\ +% | {\normalfont\centering}|\\ +% | {\thesection.}|\\ +% | {.66em}|\\ +% | {\periodafter\so}|\\ +% |...|\\ +% |\section{Von den Maassen und Maassst\"aben}|\\ +% \end{example} +% +% \bigbreak +% This yields the following output: +% +% \bigskip +% \newbox\examplebox +% \sbox\examplebox{ +% \begin{minipage}{.9\textwidth} +% \small +% \bigskip +% \begin{center} +% \so{1\<. Von den Maassen und Maassst\"aben}. +% \bigskip +% \end{center} +% \end{minipage}} +% \fbox{\usebox\examplebox} +% \bigbreak +% +% \noindent +% The \cs{\periodafter} macro adds a period to the title, but not to +% the entry in the table of contents. It takes the name of a command as +% argument, that shall be applied to the title, for example~\cs{\so}. +% Here's a more complicated and complete example: +% +% \begin{example} +% |\documentclass{article}|\\ +% |\usepackage[latin1]{inputenc}|\\ +% |\usepackage[T1]{fontenc}|\\ +% |\usepackage{german,soul}|\\ +% |\usepackage[indentfirst]{titlesec}|\\ +% \end{example} +% +% \indent +% \begin{example} +% |\newcommand*\sectitle[1]{%|\\ +% | \MakeUppercase{\so{#1}.}\\[.66ex]|\\ +% | \rule{13mm}{.4pt}}|\\ +% |\newcommand*\periodafter[2]{#1{#2.}}|\\ +% \end{example} +% +% \indent +% \begin{example} +% |\titleformat{\section}[display]|\\ +% | {\normalfont\centering}|\\ +% | {\S. \thesection.}|\\ +% | {2ex}|\\ +% | {\sectitle}|\\ +% \end{example} +% +% \indent +% \begin{example} +% |\titleformat{\subsection}[block]|\\ +% | {\normalfont\centering\bfseries}|\\ +% | {\thesection.}|\\ +% | {.66em}|\\ +% | {\periodafter\relax}|\\ +% \end{example} +% +% \indent +% \begin{example} +% |\begin{document}|\\ +% |\section{Von den Maassen und Maassst\"aben}|\\ +% |\subsection{Das L\"angenmaass im Allgemeinen}|\\ +% \\ +% |Um L\"angen genau messen und vergleichen zu k\"onnen,|\\ +% |bedarf es einer gewissen, bestimmten Einheit, mit der|\\ +% |man untersucht, wie oft sie selbst, oder ihre Theile,|\\ +% |in der zu bestimmenden L\"ange enthalten sind.|\\ +% |...|\\ +% |\end{document}| +% \end{example} +% +% \bigbreak +% This example gives you roughly the following output, +% which is a facsimile from~\cite{Muszynski}. +% +% \bigskip +% \sbox\examplebox{ +% \begin{minipage}{.9\textwidth} +% \small +% \bigskip +% \begin{center} +% \S. 1.\\[2ex] +% \so{VON DEN MAASSEN UND MAASSST\"ABEN}.\\[.66ex] +% \rule{12mm}{.4pt}\\[1.66ex] +% \textbf{1. Das L\"angenmaass im Allgemeinen.}\\[.66em] +% \end{center} +% \leavevmode\qquad +% Um L\"angen genau messen und vergleichen zu k\"onnen, +% bedarf es einer gewissen, bestimmten Einheit, mit der +% man untersucht, wie oft sie selbst, oder ihre Theile, +% in der zu bestimmenden L\"ange enthalten sind. +% \bigskip +% \end{minipage}} +% \fbox{\usebox\examplebox} +% \bigbreak +% +% \noindent +% Note that the definition of \cs{\periodafter} decides if +% the closing period shall be spaced out with the title (1), or +% follow without space (2): +% +% \begin{example} +% 1.\qquad|\newcommand*\periodafter[2]{#1{#2.}}|\\ +% 2.\qquad|\newcommand*\periodafter[2]{#1{#2}.}|\\ +% \end{example} +% +% +% +% \noindent +% If you need to underline section titles, you can easily +% do it with the help of the \package{titlesec} package. The following +% example underlines the section title, but not the section +% number: +% +% \begin{example} +% |\titleformat{\section}|\\ +% | {\LARGE\titlefont}|\\ +% | {\thesection}|\\ +% | {.66em}|\\ +% | {\ul}|\\ +% \end{example} +% +% \noindent +% The \cs{\titlefont} command is provided by the \caps{``\small{KOMA}}~script'' +% package. You can write |\normalfont\sffamily\bfseries| instead. +% The following example does additionally underline the section number: +% +% \begin{example} +% |\titleformat{\section}|\\ +% | {\LARGE\titlefont}|\\ +% | {\ul{\thesection{\kern.66em}}}|\\ +% | {0pt}|\\ +% | {\ul}|\\ +% \end{example} +% +% +% +% +% +% +% +% +% +% +% +% \section{How the package works} +% +% \subsection{The kernel} +% \so{Letterspacing,} \ul{underlining}, \st{striking out} and highlighting +% use the same kernel. It lets a \emph{word scanner} run over the given argument, +% which inspects every token. If a token is a command registered via \cs{\soulregister}, +% it is executed immediately. Other tokens are only counted and trigger some action +% when a certain number is reached (quotes and dashes). Three subsequent `|-|', for example, +% trigger |\SOUL@everyexhyphen{---}|. A third group leads to special actions, +% like |\mbox| that starts reading-in a whole group to protect its contents and let them be +% seen as one entity. All other tokens, mostly characters and digits, are collected in +% a word register, which is passed to the analyzer, whenever a whole word was read in. +% +% The analyzer typesets the word in a 1\,sp ($=\frac1{65536}$\,pt) wide \cs{\vbox}, +% hence encouraging \TeX\ to break lines at every possible hyphenation point. It +% uses the mono-spaced \cs{\SOUL@tt} font (|ectt1000|), so as to avoid any inter-character +% kerning. Now the \cs{\vbox} is decomposed splitting off \cs{\hbox} after \cs{\hbox} +% from the bottom. All boxes, each of which contains one syllable, are pushed onto a +% stack, which is provided by \TeX's grouping mechanism. When returning from the +% recursion, box after box is fetched from the stack, its width measured and fed to the +%``reconstructor''. +% +% This reconstruction macro (\cs{\SOUL@dosyllable}) starts to read tokens +% from the just analyzed word until the given syllable +% width is obtained. This is repeated for each syllable. Every time the engine +% reaches a relevant state, the corresponding driver macro is executed +% and, if necessary, provided with some data. There is a macro that is +% executed for each token, one for each syllable, one for each space etc\null. +% +% The engine itself doesn't know how to letterspace or to underline. It +% just tells the selected driver about the structure of the given argument. +% There's a default driver (\cs{\SOUL@setup}) that does only set the +% interface macros to a reasonable default state, but doesn't really do anything. +% Further drivers can safely inherit these settings and only need to +% redefine what they want to change. +% +% +% +% +% +% \subsection{The interface} +% \label{sec:interface} +% +% \subsubsection{The registers} +% +% The package offers eight interface macros that can be used to define +% the required actions. Some of the macros receive data as macro parameter +% or in special \emph{token} or \emph{dimen} registers. Here is a list of +% all available registers: +% +% \begin{labeling}{\hspace{.36\hsize}} +% \item[\texttt{\string\SOUL@token}] +% This token register contains the current token. It has to be used as |\the\SOUL@token|. +% The macro \cs{\SOUL@gettoken} reads the next token into \cs{\SOUL@token} and +% can be used in any interface macro. If you don't want to lose the old meaning, +% you have to save it explicitly. \cs{\SOUL@puttoken} pushes the token +% back into the queue, without changing \cs{\SOUL@token}. You can only +% put one token back, otherwise you get an error message. +% \item[\texttt{\string\SOUL@lasttoken}] +% This token register contains the last token. +% \item[\texttt{\string\SOUL@syllable}] +% This token register contains all tokens that were already collected for +% the current syllable. When used in \cs{\SOUL@everysyllable}, it +% contains the \emph{whole} syllable. +% \item[\texttt{\string\SOUL@charkern}] +% This dimen register contains the kerning value between the current and the next character. +% Since most character pairs don't require a kerning value to be applied and the +% output in the logfile shouldn't be cluttered with |\kern0pt| it is +% recommended to write |\SOUL@setkern\SOUL@charkern|, which sets +% kerning for non-zero values only. +% \item[\texttt{\string\SOUL@hyphkern}] +% This dimen register contains the kerning value between the current character +% and the hyphen character or, when used in \cs{\SOUL@everyexhyphen}, the +% kerning between the last character and the explicit hyphen. +% \end{labeling} +% +% +% +% +% +% +% \subsubsection{The interface macros} +% +% The following list describes each of the interface macros and which +% registers it can rely on. The mark between label and description +% will be used in section \ref{sec:interfaceexamples} to show when +% the macros are executed. The addition |#1| means that the macro +% takes one argument. +% +% \begin{labeling}{\hspace{.36\hsize}} +% \def\m#1{\leavevmode\llap{\hbox to1em{\hss#1\hss}\hskip.7em}} +% \item[\texttt{\string\SOUL@preamble}]\m{$P$}^^A +% executed once at the beginning +% \item[\texttt{\string\SOUL@postamble}]\m{$E$}^^A +% executed once at the end +% \item[\texttt{\string\SOUL@everytoken}]\m{$T$}^^A +% executed after scanning a token; It gets that +% token in \cs{\SOUL@token} and has to care for inserting +% the kerning value \cs{\SOUL@charkern} between this and the next character. +% To look at the next character, execute \cs{\SOUL@gettoken}, which +% replaces \cs{\SOUL@token} by the next token. This token has to +% be put back into the queue using \cs{\SOUL@puttoken}. +% \item[\texttt{\string\SOUL@everysyllable}]\m{$S$}^^A +% This macro is executed after scanning a whole syllable. It gets the +% syllable in \cs{\SOUL@syllable}. +% \item[\texttt{\string\SOUL@everyhyphen}]\m{$-$}^^A +% This macro is executed at every implicit hyphenation point. +% It is responsible for setting the hyphen and will likely do this +% in a \cs{\discretionary} statement. It has to care about the +% kerning values. The registers \cs{\SOUL@lasttoken}, \cs{\SOUL@syllable}, +% \cs{\SOUL@charkern} and \cs{\SOUL@hyphkern} contain useful information. +% Note that \cs{\discretionary} inserts \cs{\exhyphenpenalty} +% if the first part of the discretionary is empty, and +% \cs{\hyphenpenalty} else. +% \item[\texttt{\string\SOUL@everyexhyphen\#1}]\m{$=$}^^A +% This macro is executed at every explicit hyphenation point. The +% hyphen `character' (one of hyphen, en-dash, em-dash or \cs{\slash}) +% is passed as parameter |#1|. A minimal implementation +% would be |{#1\penalty\exhyphenpenalty}|. The kerning value +% between the last character and the hyphen is passed in \cs{\SOUL@hyphkern}, +% that between the hyphen and the next character in \cs{\SOUL@charkern}. +% The last syllable can be found in \cs{\SOUL@syllable}, the last +% character in \cs{\SOUL@lasttoken}. +% \item[\texttt{\string\SOUL@everyspace\#1}]\m{\texttt{\char`\ }}^^A +% This macro is executed between every two words. It is responsible for +% setting the space. The engine submits a \cs{\penalty} setting as +% parameter |#1| that should be put in front of the space. The +% macro should at least do |{#1\space}|. Further information can be found in +% \cs{\SOUL@lasttoken} and \cs{\SOUL@syllable}. Note that this macro does not +% care for the leading and trailing space. This is the job of +% \cs{\SOUL@preamble} and \cs{\SOUL@postamble}. +% \end{labeling} +% +% +% +% +% +% +% \subsubsection{Some examples} +% \label{sec:interfaceexamples} +% +% The above list's middle column shows a mark that indicates in the +% following examples, when the respective macros are executed:\nopagebreak +% +% \begin{labeling}{\hspace{.36\hsize}} +% \item[\normalfont\an{word}] +% \cs{\SOUL@everytoken}$^T$ is executed for every token. \cs{\SOUL@everysyllable}$^S$ +% is \emph{additionally} executed for every syllable. You will mostly just +% want to use either of them. +% \item[\normalfont\an{one two}] +% The macro |\SOUL@everyspace| is executed at every space within +% the \soul\ argument. It has to take one argument, that can either +% be empty or contain a penalty, that should be applied to the space. +% \item[\normalfont\an{example}\kern-1em] +% The macro |\SOUL@everyhyphen| is executed at every possible +% implicit hyphenation point. +% \item[\normalfont\an{beta-test}] +% Explicit hyphens trigger \cs{\SOUL@everyexhyphen}. +% \end{labeling} +% +% +% +% \bigbreak +% \noindent +% It's only natural that these examples, too, +% were automatically typeset by the |soul| package +% using a special driver: +% +% \begin{example} +% |\DeclareRobustCommand*\an{%|\\ +% | \def\SOUL@preamble{$^{^P}$}%|\\ +% | \def\SOUL@everyspace##1{##1\texttt{\char`\ }}%|\\ +% | \def\SOUL@postamble{$^{^E}$}%|\\ +% | \def\SOUL@everyhyphen{$^{^-}$}%|\\ +% | \def\SOUL@everyexhyphen##1{##1$^{^=}$}%|\\ +% | \def\SOUL@everysyllable{$^{^S}$}%|\\ +% | \def\SOUL@everytoken{\the\SOUL@token$^{^T}$}%|\\ +% | \def\SOUL@everylowerthan{$^{^L}$}%|\\ +% | \SOUL@}|\\ +% \end{example} +% +% +% +% +% +% +% +% +% \subsection{A driver example} +% +% Let's define a \soul\ driver that allows to typeset text +% with a \cs{\cdot} at every potential hyphenation point. The name of +% the macro shall be \cs{\sy} (for \emph{syllables}). +% Since the \soul\ mechanism is highly fragile, we use the \LaTeX\ +% command \cs{\DeclareRobustCommand}, so that the \cs{\sy} macro +% can be used even in section headings etc. The \cs{\SOUL@setup} +% macro sets all interface macros to reasonable default definitions. +% This could of course be done manually, too. As we won't +% make use of \cs{\SOUL@everytoken} and \cs{\SOUL@postamble} +% and both default to \cs{\relax}, anyway, we don't have to +% define them here. +% +% \begin{example} +% |\DeclareRobustCommand*\sy{%|\\ +% | \SOUL@setup|\\ +% \end{example} +% +% We only set \cs{\lefthyphenmin} and \cs{\righthyphenmin} to zero +% at the beginning. All changes are restored automatically, +% so there's nothing to do at the end. +% +% \begin{example} +% | \def\SOUL@preamble{\lefthyphenmin=0 \righthyphenmin=0 }%|\\ +% \end{example} +% +% We only want simple spaces. Note that these are not provided +% by default! \cs{\SOUL@everyspace} may get a penalty to be +% applied to that space, so we set it before. +% +% \begin{example} +% | \def\SOUL@everyspace##1{##1\space}%|\\ +% \end{example} +% +% There's nothing to do for \cs{\SOUL@everytoken}, we rather let +% \cs{\SOUL@everysyllable} handle a whole syllable at once. +% This has the advantage, that we don't have to deal with +% kerning values, because \TeX\ takes care of that. +% +% \begin{example} +% | \def\SOUL@everysyllable{\the\SOUL@syllable}|\\ +% \end{example} +% +% The \TeX\ primitive \cs{\discretionary} +% takes three arguments: 1.~pre-hyphen material +% 2.~post-hyphen material, and 3.~no-hyphenation material. +% +% \begin{example} +% | \def\SOUL@everyhyphen{%|\\ +% | \discretionary{%|\\ +% | \SOUL@setkern\SOUL@hyphkern|\\ +% | \SOUL@sethyphenchar|\\ +% | }{}{%|\\ +% | \hbox{\kern1pt$\cdot$}%|\\ +% | }%|\\ +% | }%|\\ +%\end{example} +% +% Explicit hyphens like dashes and slashes shall be set normally. +% We just have to care for kerning. The hyphen has to be put in +% a box, because, as \cs{\hyphenchar}, it would yield its own, internal +% \cs{\discretionary}. We need to set ours instead, though. +% +% \begin{example} +% | \def\SOUL@everyexhyphen##1{%|\\ +% | \SOUL@setkern\SOUL@hyphkern|\\ +% | \hbox{##1}%|\\ +% | \discretionary{}{}{%|\\ +% | \SOUL@setkern\SOUL@charkern|\\ +% | }%|\\ +% | }|%\\ +% \end{example} +% +% Now that the interface macros are defined, we can start the scanner. +% +% \begin{example} +% | \SOUL@|\\ +% |}|\\ +% \end{example} +% +% \hyphenation{al-go-rithm lin-guists ex-cel-lent} ^^A correct? +% \noindent +% \emph{\sy{This little macro will hardly be good enough +% for linguists, although it uses {\TeX's} excellent hyphenation algorithm, +% but it is at least a nice alternative to the}} \cs{\showhyphens} \emph{\sy{command}.} +% +% +% +% +% +% +% +% \section*{Acknowledgements} +% +% A big thank you goes to \person{Stefan Ulrich} for his tips and bug reports +% during the development of versions 1.\lower2pt\hbox{*} and for his lessons on high quality +% typesetting. The \cs{\caps} mechanism was very much influenced by his +% suggestions. Thanks to \person{Alexander Shibakov} and \person{Frank Mittelbach,} +% who sent me a couple of bug reports and feature requests, and finally encouraged +% me to (almost) completely rewrite \soul. \person{Thorsten Manegold} contributed +% a series of bug reports, helping to fix \soul's macro expander and hence making +% it work together with the \package{jurabib} package. +% Thanks to \person{Axel Reichert, Anshuman Pandey,} and \person{Peter Kreynin} for +% detailed bug reports. +% \person{Rowland McDonnel} gave useful hints for how to improve the documentation, +% but I'm afraid he will still not be satisfied, and rightfully so. If only documentation +% writing weren't that boring.~~\texttt{;-)} +% +% +% +% +% +% +% +% \begin{thebibliography}{00} +% \raggedright +% +% \bibitem{jurabib}{\person{Berger, Jens:} \bibtitle{The jurabib package.} \CTAN-Archive, 2002, v0.52h.} +% +% \bibitem{titlesec}{\person{Bezos, Javier:} \bibtitle{The titlesec and titletoc package.} +% \CTAN-Archive, 1999, v2.1.} +% +% \bibitem{color}{\person{Carlisle, D. P.:} \bibtitle{The color package.} \CTAN-Archive, 1997, v1.0d.} +% +% \bibitem{Duden}{Duden, Volume 1. \bibtitle{Die Rechtschreibung.} Bibliographisches Institut, +% Mann\-heim--\hskip0pt Wien--Z\"urich, 1986, 19th~edition.} +% +% \bibitem{DEK}{\person{Knuth, Donald E.:} \bibtitle{The \TeX book.} +% Addison--Wesley Publishing Company, Reading/Massachusetts, 1989, 16th~edition.} +% +% \bibitem{Muszynski}{\person{Muszynski, Carl} and \person{P\v rihoda, Eduard:} +% \bibtitle{Die Terrainlehre in Verbindung mit der Darstellung, Beurtheilung und +% Beschreibung des Terrains vom milit\"arischen +% Standpunkte.} +% L.\,W.~Seidel \&\ Sohn, Wien, 1872.} +% +% \bibitem{Reglement}{Normalverordnungsblatt f\"ur das k.\,u.\,k.~Heer. +% \bibtitle{Exercier-Reglement f\"ur die k.\,u.\,k.~Cavallerie, I. Theil.} +% Wien, k.\,k.~Hof- und Staatsdruckerei, 1898, 4th~edition.} +% +% \bibitem{german}{\person{Raichle, Bernd:} \bibtitle{The german package.} \CTAN-Archive, 1998, v2.5e.} +% +% \bibitem{yfonts}{\person{Schmidt, Walter:} \bibtitle{Ein Makropaket f\"ur die gebrochenen +% Schriften.} \CTAN-Archive, 1998, v1.2.} +% +% \bibitem{Tschichold}{\person{Tschichold, Jan:} \bibtitle{Ausgew\"ahlte Aufs\"atze \"uber Fragen +% der Gestalt des Buches und der Typographie.} Birkh\"auser, Basel, +% 1987, 2nd~edition.} +% +% \bibitem{Willberg}{\person{Willberg, Hans Peter} and \person{Forssmann, Friedrich:} +% \bibtitle{Lesetypographie.} H. Schmidt, Mainz, 1997.} +% +% \end{thebibliography} +% +% +% \StopEventually{\addtocontents{toc}{\protect\end{multicols}}} +% +% +% +% +% +% +% +% +%^^A max 72 columns +%^^A-------------------------------------------------------------------- +% +% +% +% +% \section{The implementation} +% +% \subsection*{The package preamble} +% +% This piece of code makes sure that the package is only loaded +% once. While this is guaranteed by \LaTeX, we have to do it +% manually for all other flavors of \TeX. +% +% \begin{macrocode} +\expandafter\ifx\csname SOUL@\endcsname\relax\else + \expandafter\endinput +\fi +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \noindent +% Fake some of the \LaTeX\ commands if we were loaded by another flavor +% of \TeX. This might break some previously loaded packages, though, +% if e.\,g.~\cs{\mbox} was already in use. But we don't care \dots +% +% \begin{macrocode} +\ifx\documentclass\SOULundefined + \chardef\atcode=\catcode`@ + \catcode`\@=11 + \def\DeclareRobustCommand*{\def} + \let\newcommand\DeclareRobustCommand + \def\DeclareOption#1#2{\expandafter\def\csname#1\endcsname{#2}} + \def\PackageError#1#2#3{{% + \newlinechar`^^J% + \errorcontextlines\z@ + \edef\\{\errhelp{#3}}\\% + \errmessage{Package #1 error: #2}% + }} + \def\@height{height} + \def\@depth{depth} + \def\@width{width} + \def\@plus{plus} + \def\@minus{minus} + \font\SOUL@tt=ectt1000 + \let\@xobeysp\space + \let\linebreak\break + \let\mbox\hbox +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \noindent +% \soul\ tries to be a good \LaTeX\ citizen if used under \LaTeX\ and +% declares itself properly. Most command sequences in the package +% are protected by the |SOUL@| namespace, all other macros are first +% defined to be empty. This will give us an error message \emph{now} +% if one of those was already used by another package. +% +% \begin{macrocode} +\else + \NeedsTeXFormat{LaTeX2e} + \ProvidesPackage{soul} + [2003/11/17 v2.4 letterspacing/underlining (mf)] + \newfont\SOUL@tt{ectt1000} + \newcommand*\sodef{} + \newcommand*\resetso{} + \newcommand*\capsdef{} + \newcommand*\capsfont{} + \newcommand*\setulcolor{} + \newcommand*\setuloverlap{} + \newcommand*\setul{} + \newcommand*\resetul{} + \newcommand*\setuldepth{} + \newcommand*\setstcolor{} + \newcommand*\sethlcolor{} + \newcommand*\so{} + \newcommand*\ul{} + \newcommand*\st{} + \newcommand*\hl{} + \newcommand*\caps{} + \newcommand*\soulaccent{} + \newcommand*\soulregister{} + \newcommand*\soulfont{} + \newcommand*\soulomit{} +\fi +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \noindent +% Other packages wouldn't be happy if we reserved piles of \cs{\newtoks} and +% \cs{\newdimen}, so we try to get away with their \cs{\...def} counterparts +% where possible. +% Local registers are always even, while global ones are odd---this is a +% \TeX\ convention. +% +% \begin{macrocode} +\newtoks\SOUL@word +\newtoks\SOUL@lasttoken +\toksdef\SOUL@syllable\z@ +\newtoks\SOUL@cmds +\newtoks\SOUL@buffer +\newtoks\SOUL@token +\dimendef\SOUL@syllgoal\z@ +\dimendef\SOUL@syllwidth\tw@ +\dimendef\SOUL@charkern=4 +\dimendef\SOUL@hyphkern=6 +\countdef\SOUL@minus\z@ +\countdef\SOUL@comma\tw@ +\countdef\SOUL@apo=4 +\countdef\SOUL@grave=6 +\newskip\SOUL@spaceskip +\newif\ifSOUL@ignorespaces +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% ^^A\FIXME{\newpage} +% \begin{macro}{\soulomit} +% \begin{macro}{\SOUL@ignorem} +% \begin{macro}{\SOUL@ignore} +% \begin{macro}{\SOUL@stopm} +% \begin{macro}{\SOUL@stop} +% \begin{macro}{\SOUL@relaxm} +% \begin{macro}{\SOUL@lowerthanm} +% \begin{macro}{\SOUL@hyphenhintm} +% These macros are used as markers. To be able to check for such a +% marker with \cs{\ifx} we have also to create a macro that contains +% the marker. \cs{\SOUL@spc} shall contain a normal space with a +% \cs{\catcode} of~10. +% +% \begin{macrocode} +\def\soulomit#1{#1} +\def\SOUL@stopM{\SOUL@stop} +\let\SOUL@stop\relax +\def\SOUL@lowerthan{} +\def\SOUL@lowerthanM{\<} +\def\SOUL@hyphenhintM{\-} +\def\SOUL@n*{\let\SOUL@spc= }\SOUL@n* % +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The kernel} +% +% \begin{macro}{\SOUL@} +% This macro is the entry to \soul. Using it does only make +% sense after setting up a \soul\ driver. The next token after +% the \soul\ command will be assigned to \cs{\SOUL@@}. This can be +% some text enclosed in braces, or the name of a macro that contains text. +% +% \begin{macrocode} +\def\SOUL@{% + \futurelet\SOUL@@\SOUL@expand +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@expand} +% If the first token after the \soul\ command was an opening +% brace we start scanning. Otherwise, +% if the first token was a macro name, we expand that macro and +% call \cs{\SOUL@} with its contents again. Unfortunately, we have to +% exclude some macros therein from expansion. +% +% \begin{macrocode} +\def\SOUL@expand{% + \ifcat\bgroup\noexpand\SOUL@@ + \let\SOUL@n\SOUL@start + \else + \bgroup + \def\\##1##2{\def##2{\noexpand##2}}% + \the\SOUL@cmds + \SOUL@buffer={% + \\\TeX\\\LaTeX\\\soulomit\\\mbox\\\hbox\\\textregistered + \\\slash\\\textcircled\\\copyright\\\S\\\,\\\<\\\>\\~% + \\\\% + }% + \def\\##1{\def##1{\noexpand##1}}% + \the\SOUL@buffer + \let\protect\noexpand + \xdef\SOUL@n##1{\noexpand\SOUL@start{\SOUL@@}}% + \egroup + \fi + \SOUL@n +} +\long\def\SOUL@start#1{{% + \let\<\SOUL@lowerthan + \let\>\empty + \def\soulomit{\noexpand\soulomit}% + \gdef\SOUL@eventuallyexhyphen##1{}% + \let\SOUL@soeventuallyskip\relax + \SOUL@spaceskip=\fontdimen\tw@\font\@plus\fontdimen\thr@@\font + \@minus\fontdimen4\font + \SOUL@ignorespacesfalse + \leavevmode + \SOUL@preamble + \SOUL@lasttoken={}% + \SOUL@word={}% + \SOUL@minus\z@ + \SOUL@comma\z@ + \SOUL@apo\z@ + \SOUL@grave\z@ + \SOUL@do{#1}% + \SOUL@postamble +}} +\long\def\SOUL@do#1{% + \SOUL@scan#1\SOUL@stop +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The scanner} +% +% \begin{macro}{\SOUL@scan} +% This is the entry point for the scanner. It calls \cs{\SOUL@eval} +% and will in turn be called by \cs{\SOUL@eval} again for every +% new token to be scanned. +% +% \begin{macrocode} +\def\SOUL@scan{% + \futurelet\SOUL@@\SOUL@eval +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@eval} +% And here it is: the scanner's heart. It cares for quotes and dashes +% ligatures and handles all commands that must not be fed to the +% analyzer. +% +% \begin{macrocode} +\def\SOUL@eval{% + \def\SOUL@n*##1{\SOUL@scan}% + \if\noexpand\SOUL@@\SOUL@spc + \else + \SOUL@ignorespacesfalse + \fi + \ifnum\SOUL@minus=\thr@@ + \SOUL@flushminus + \else\ifnum\SOUL@comma=\tw@ + \SOUL@flushcomma + \else\ifnum\SOUL@apo=\tw@ + \SOUL@flushapo + \else\ifnum\SOUL@grave=\tw@ + \SOUL@flushgrave + \fi\fi\fi\fi + \ifx\SOUL@@-\else\SOUL@flushminus\fi + \ifx\SOUL@@,\else\SOUL@flushcomma\fi + \ifx\SOUL@@'\else\SOUL@flushapo\fi + \ifx\SOUL@@`\else\SOUL@flushgrave\fi + \ifx\SOUL@@-% + \advance\SOUL@minus\@ne + \else\ifx\SOUL@@,% + \advance\SOUL@comma\@ne + \else\ifx\SOUL@@'% + \advance\SOUL@apo\@ne + \else\ifx\SOUL@@`% + \advance\SOUL@grave\@ne + \else + \SOUL@flushminus + \SOUL@flushcomma + \SOUL@flushapo + \SOUL@flushgrave + \ifx\SOUL@@\SOUL@stop + \def\SOUL@n*{% + \SOUL@doword + \SOUL@eventuallyexhyphen\null + }% + \else\ifx\SOUL@@\par + \def\SOUL@n*\par{\par\leavevmode\SOUL@scan}% + \else\if\noexpand\SOUL@@\SOUL@spc + \SOUL@doword + \SOUL@eventuallyexhyphen\null + \ifSOUL@ignorespaces + \else + \SOUL@everyspace{}% + \fi + \def\SOUL@n* {\SOUL@scan}% + \else\ifx\SOUL@@\\% + \SOUL@doword + \SOUL@eventuallyexhyphen\null + \SOUL@everyspace{\unskip\nobreak\hfil\break}% + \SOUL@ignorespacestrue + \else\ifx\SOUL@@~% + \SOUL@doword + \SOUL@eventuallyexhyphen\null + \SOUL@everyspace{\nobreak}% + \else\ifx\SOUL@@\slash + \SOUL@doword + \SOUL@eventuallyexhyphen{/}% + \SOUL@exhyphen{/}% + \else\ifx\SOUL@@\mbox + \def\SOUL@n*{\SOUL@addprotect}% + \else\ifx\SOUL@@\hbox + \def\SOUL@n*{\SOUL@addprotect}% + \else\ifx\SOUL@@\soulomit + \def\SOUL@n*\soulomit##1{% + \SOUL@doword + {\spaceskip\SOUL@spaceskip##1}% + \SOUL@scan + }% + \else\ifx\SOUL@@\break + \SOUL@doword + \break + \else\ifx\SOUL@@\linebreak + \SOUL@doword + \SOUL@everyspace{\linebreak}% + \else\ifcat\bgroup\noexpand\SOUL@@ + \def\SOUL@n*{\SOUL@addgroup{}}% + \else\ifcat$\noexpand\SOUL@@ + \def\SOUL@n*{\SOUL@addmath}% + \else + \def\SOUL@n*{\SOUL@dotoken}% + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \fi\fi\fi\fi + \SOUL@n*% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@flushminus} +% \begin{macro}{\SOUL@flushcomma} +% \begin{macro}{\SOUL@flushapo} +% \begin{macro}{\SOUL@flushgrave} +% As their names imply, these macros flush special tokens or token +% groups to the word register. They don't do anything if the respective +% counter equals zero. \cs{\SOUL@minus} does also flush the word +% register, because hyphens disturb the analyzer. +% +% \begin{macrocode} +\def\SOUL@flushminus{% + \ifcase\SOUL@minus + \else + \SOUL@doword + \SOUL@eventuallyexhyphen{-}% + \ifcase\SOUL@minus + \or + \SOUL@exhyphen{-}% + \or + \SOUL@exhyphen{--}% + \or + \SOUL@exhyphen{---}% + \fi + \SOUL@minus\z@ + \fi +} +\def\SOUL@flushcomma{% + \ifcase\SOUL@comma + \or + \edef\x{\SOUL@word={\the\SOUL@word,}}\x + \or + \edef\x{\SOUL@word={\the\SOUL@word{{,,}}}}\x + \fi + \SOUL@comma\z@ +} +\def\SOUL@flushapo{% + \ifcase\SOUL@apo + \or + \edef\x{\SOUL@word={\the\SOUL@word'}}\x + \or + \edef\x{\SOUL@word={\the\SOUL@word{{''}}}}\x + \fi + \SOUL@apo\z@ +} +\def\SOUL@flushgrave{% + \ifcase\SOUL@grave + \or + \edef\x{\SOUL@word={\the\SOUL@word`}}\x + \or + \edef\x{\SOUL@word={\the\SOUL@word{{``}}}}\x + \fi + \SOUL@grave\z@ +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@dotoken} +% Command sequences from the \cs{\SOUL@cmds} list are handed over +% to \cs{\SOUL@docmd}, everything else is added to \cs{\SOUL@word}, +% which will be fed to the analyzer every time a word is completed. +% Since \emph{robust} commands come with an additional space, we +% have also to examine if there's a space variant. Otherwise we +% couldn't detect pre-expanded formerly robust commands. +% +% \begin{macrocode} +\def\SOUL@dotoken#1{% + \def\SOUL@@{\SOUL@addtoken{#1}}% + \def\\##1##2{% + \edef\SOUL@x{\string#1}% + \edef\SOUL@n{\string##2}% + \ifx\SOUL@x\SOUL@n + \def\SOUL@@{\SOUL@docmd{##1}{#1}}% + \else + \edef\SOUL@n{\string##2\space}% + \ifx\SOUL@x\SOUL@n + \def\SOUL@@{\SOUL@docmd{##1}{#1}}% + \fi + \fi + }% + \the\SOUL@cmds + \SOUL@@ +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@docmd} +% Here we deal with commands that were registered with \cs{\soulregister} +% or \cs{\soulaccent} or were already predefined in \cs{\SOUL@cmds}. +% Commands with identifier |9| are accents that are put in a +% group with their argument. Identifier |8| is reserved for the \cs{\footnote} +% command, and |7| for the \cs{\textsuperscript} or similar commands. +% The others are mostly (but not necessarily) +% font switching commands, which may (|1|) or may not (|0|) take +% an argument. A registered command leads to the current word +% buffer being flushed to the analyzer, after which the command +% itself is executed. +% +% Font switching commands which take an argument need special +% treatment: They need to increment the level counter, so that +% \cs{\SOUL@eval} knows where to stop scanning. Furthermore the +% scanner has to be enabled to see the next token after the opening +% brace. +% +% +% \begin{macrocode} +\def\SOUL@docmd#1#2{% + \ifx9#1% + \def\SOUL@@{\SOUL@addgroup{#2}}% + \else\ifx8#1% + \SOUL@doword + \def\SOUL@@##1{% + \SOUL@token={\footnotemark}% + \SOUL@everytoken + \SOUL@syllable={\footnotemark}% + \SOUL@everysyllable + \footnotetext{##1}% + \SOUL@doword + \SOUL@scan + }% + \else\ifx7#1% + \SOUL@doword + \def\SOUL@@##1{% + \SOUL@token={#2{##1}}% + \SOUL@everytoken + \SOUL@syllable={#2{##1}}% + \SOUL@everysyllable + \SOUL@doword + \SOUL@scan + }% + \else\ifx1#1% + \SOUL@doword + \def\SOUL@@##1{% + #2{\protect\SOUL@do{##1}}% + \SOUL@scan + }% + \else + \SOUL@doword + #2% + \let\SOUL@@\SOUL@scan + \fi\fi\fi\fi + \SOUL@@ +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@addgroup} +% \begin{macro}{\SOUL@addmath} +% \begin{macro}{\SOUL@addprotect} +% \begin{macro}{\SOUL@addtoken} +% The macro names say it all. Each of these macros adds some +% token to the word buffer \cs{\SOUL@word}. Setting \cs{\protect} +% is necessary to make things like |\so{{a\itshape b}}| work. +% +% \begin{macrocode} +\def\SOUL@addgroup#1#2{% + {\let\protect\noexpand + \edef\x{\global\SOUL@word={\the\SOUL@word{{\noexpand#1#2}}}}\x}% + \SOUL@scan +} +\def\SOUL@addmath$#1${% + {\let\protect\noexpand + \edef\x{\global\SOUL@word={\the\SOUL@word{{\hbox{$#1$}}}}}\x}% + \SOUL@scan +} +\def\SOUL@addprotect#1#2{% + {\let\protect\noexpand + \edef\x{\global\SOUL@word={\the\SOUL@word{{\hbox{#2}}}}}\x}% + \SOUL@scan +} +\def\SOUL@addtoken#1{% + \edef\x{\SOUL@word={\the\SOUL@word\noexpand#1}}\x + \SOUL@scan +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@exhyphen} +% Dealing with explicit hyphens can't be done before we know the +% following character, because we need to know if a kerning value +% has to be inserted, hence we delay the \cs{\SOUL@everyexhyphen} call. +% Unfortunately, the word scanner has no look-ahead mechanism. +% +% \begin{macrocode} +\def\SOUL@exhyphen#1{% + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@hyphkern}{#1}% + \gdef\SOUL@eventuallyexhyphen##1{% + \SOUL@getkern{#1}{\SOUL@charkern}{##1}% + \SOUL@everyexhyphen{#1}% + \gdef\SOUL@eventuallyexhyphen####1{}% + }% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@cmds} +% Here is a list of pre-registered commands that the analyzer +% cannot handle, so the scanner has to look after them. Every +% entry consists of a handle (\cs{\\}), an identifier and the +% macro name. The class identifier can be |9| for accents, +% |8| for the \cs{\footnote} command, |7| for the +% \cs{\textsuperscript} command, +% |0| for commands without arguments and |1| for commands that +% take one argument. Commands with two or more arguments are +% not supported. +% +% \begin{macrocode} +\SOUL@cmds={% + \\9\`\\9\'\\9\^\\9\"\\9\~\\9\=\\9\.% + \\9\u\\9\v\\9\H\\9\t\\9\c\\9\d\\9\b\\9\r + \\1\emph\\1\textrm\\1\textsf\\1\texttt\\1\textmd\\1\textbf + \\1\textup\\1\textsl\\1\textit\\1\textsc\\1\textnormal + \\0\rmfamily\\0\sffamily\\0\ttfamily\\0\mdseries\\0\upshape + \\0\slshape\\0\itshape\\0\scshape\\0\normalfont + \\0\em\\0\rm\\0\bf\\0\it\\0\tt\\0\sc\\0\sl\\0\sf + \\0\tiny\\0\scriptsize\\0\footnotesize\\0\small + \\0\normalsize\\0\large\\0\Large\\0\LARGE\\0\huge\\0\Huge + \\1\MakeUppercase\\7\textsuperscript\\8\footnote + \\1\textfrak\\1\textswab\\1\textgoth + \\0\frakfamily\\0\swabfamily\\0\gothfamily +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\soulregister} +% \begin{macro}{\soulfont} +% \begin{macro}{\soulaccent} +% Register a font switching command (or some other command) for the +% scanner. The first argument is the macro name, the second is +% the number of arguments (|0|~or~|1|). Example: |\soulregister{\bold}{0}|. +% \cs{\soulaccent} has only one argument---the accent macro name. +% Example: |\soulaccent{\~}|. It is a shortcut for |\soulregister{\~}{9}|. +% The \cs{\soulfont} command is a synonym for \cs{\soulregister} +% and is kept for compatibility reasons. +% +% \begin{macrocode} +\def\soulregister#1#2{{% + \edef\x{\global\SOUL@cmds={\the\SOUL@cmds + \noexpand\\#2\noexpand#1}}\x +}} +\def\soulaccent#1{\soulregister{#1}9} +\let\soulfont\soulregister +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The analyzer} +% +% \begin{macro}{\SOUL@doword} +% The only way to find out, where a given word can be broken into +% syllables, is to let \TeX\ actually typeset the word under conditions +% that enforce every possible hyphenation. The result is a paragraph with one +% line for every syllable. +% +% \begin{macrocode} +\def\SOUL@doword{% + \edef\x{\the\SOUL@word}% + \ifx\x\empty + \else + \SOUL@buffer={}% + \setbox\z@\vbox{% + \SOUL@tt + \hyphenchar\font`\- + \hfuzz\maxdimen + \hbadness\@M + \pretolerance\m@ne + \tolerance\@M + \leftskip\z@ + \rightskip\z@ + \hsize1sp + \everypar{}% + \parfillskip\z@\@plus1fil + \hyphenpenalty-\@M + \noindent + \hskip\z@ + \relax + \the\SOUL@word}% + \let\SOUL@errmsg\SOUL@error + \let\-\relax + \count@\m@ne + \SOUL@analyze + \SOUL@word={}% + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \noindent +% We store the hyphen width of the |ectt1000| font, +% because we will need it in |\SOUL@doword|. (|ectt1000| is a mono-spaced +% font, so every other character would have worked, too.) +% +% \begin{macrocode} +\setbox\z@\hbox{\SOUL@tt-} +\newdimen\SOUL@ttwidth +\SOUL@ttwidth\wd\z@ +\def\SOUL@sethyphenchar{% + \ifnum\hyphenchar\font=\m@ne + \else + \char\hyphenchar\font + \fi +} +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@analyze} +% This macro decomposes the box that |\SOUL@doword| has built. +% Because we have to start at the bottom, we put every +% syllable onto the stack and execute ourselves recursively. If there +% are no syllables left, we return from the recursion and pick syllable +% after syllable from the stack again---this time from top to bottom---and +% hand the syllable width |\SOUL@syllgoal| over to |\SOUL@dosyllable|. +% All but the last syllable end with the hyphen character, hence +% we subtract the hyphen width accordingly. After processing a +% syllable we calculate the hyphen kern (i.\,e.~the kerning amount +% between the last character and the hyphen). This might be needed +% by \cs{\SOUL@everyhyphen}, which we call now. +% +% \begin{macrocode} +\def\SOUL@analyze{{% + \setbox\z@\vbox{% + \unvcopy\z@ + \unskip + \unpenalty + \global\setbox\@ne=\lastbox}% + \ifvoid\@ne + \else + \setbox\@ne\hbox{\unhbox\@ne}% + \SOUL@syllgoal=\wd\@ne + \advance\count@\@ne + \SOUL@analyze + \SOUL@syllwidth\z@ + \SOUL@syllable={}% + \ifnum\count@>\z@ + \advance\SOUL@syllgoal-\SOUL@ttwidth + \SOUL@dosyllable + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@hyphkern}% + {\SOUL@sethyphenchar}% + \SOUL@everyhyphen + \else + \SOUL@dosyllable + \fi + \fi +}} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@dosyllable} +% This macro typesets token after token from \cs{\SOUL@word} +% until \cs{\SOUL@syllwidth} has reached +% the requested width \cs{\SOUL@syllgoal}. Furthermore the kerning +% values are prepared in case \cs{\SOUL@everytoken} needs them. +% The \cs{\<} command used by \cs{\so} and \cs{\caps} needs some +% special treatment: It has to be checked for, even before +% we can end a syllable. +% +% \begin{macrocode} +\def\SOUL@dosyllable{% + \SOUL@gettoken + \SOUL@eventuallyexhyphen{\the\SOUL@token}% + \edef\x{\the\SOUL@token}% + \ifx\x\SOUL@hyphenhintM + \let\SOUL@n\SOUL@dosyllable + \else\ifx\x\SOUL@lowerthanM + \SOUL@gettoken + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@charkern} + {\the\SOUL@token}% + \SOUL@everylowerthan + \SOUL@puttoken + \let\SOUL@n\SOUL@dosyllable + \else\ifdim\SOUL@syllwidth=\SOUL@syllgoal + \SOUL@everysyllable + \SOUL@puttoken + \let\SOUL@n\relax + \else\ifx\x\SOUL@stopM + \SOUL@errmsg + \global\let\SOUL@errmsg\relax + \let\SOUL@n\relax + \else + \setbox\tw@\hbox{\SOUL@tt\the\SOUL@token}% + \advance\SOUL@syllwidth\wd\tw@ + \global\SOUL@lasttoken=\SOUL@token + \SOUL@gettoken + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@charkern} + {\the\SOUL@token}% + \SOUL@puttoken + \global\SOUL@token=\SOUL@lasttoken + \SOUL@everytoken + \edef\x{\SOUL@syllable={\the\SOUL@syllable\the\SOUL@token}}\x + \let\SOUL@n\SOUL@dosyllable + \fi\fi\fi\fi + \SOUL@n +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@gettoken} +% Provide the next token in \cs{\SOUL@token}. If there's already one +% in the buffer, use that one first. +% +% \begin{macrocode} +\def\SOUL@gettoken{% + \edef\x{\the\SOUL@buffer}% + \ifx\x\empty + \SOUL@nexttoken + \else + \global\SOUL@token=\SOUL@buffer + \global\SOUL@buffer={}% + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@puttoken} +% The possibility to put tokens back makes the scanner design much +% cleaner. There's only room for one token, though, so we issue +% an error message if \cs{\SOUL@puttoken} is told to put a token +% back while the buffer is still in use. Note that \cs{\SOUL@debug} +% is actually undefined. This won't hurt as it can only happen +% during driver design. No user will ever see this message. +% +% \begin{macrocode} +\def\SOUL@puttoken{% + \edef\x{\the\SOUL@buffer}% + \ifx\x\empty + \global\SOUL@buffer=\SOUL@token + \global\SOUL@token={}% + \else + \SOUL@debug{puttoken called twice}% + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@nexttoken} +% \begin{macro}{\SOUL@splittoken} +% If the word buffer \cs{\SOUL@word} is empty, deliver a \cs{\SOUL@stop}, +% otherwise take the next token. +% +% \begin{macrocode} +\def\SOUL@nexttoken{% + \edef\x{\the\SOUL@word}% + \ifx\x\empty + \SOUL@token={\SOUL@stop}% + \else + \expandafter\SOUL@splittoken\the\SOUL@word\SOUL@stop + \fi +} +\def\SOUL@splittoken#1#2\SOUL@stop{% + \global\SOUL@token={#1}% + \global\SOUL@word={#2}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@getkern} +% Assign the kerning value between the first and the third argument +% to the second, which has to be a \cs{\dimen} register. +% |\SOUL@getkern{A}{\dimen0}{V}| will assign the kerning value +% between `A' and `V' to |\dimen0|. +% +% \begin{macrocode} +\def\SOUL@getkern#1#2#3{% + \setbox\tw@\hbox{#1#3}% + #2\wd\tw@ + \setbox\tw@\hbox{#1\null#3}% + \advance#2-\wd\tw@ +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@setkern} +% Set a kerning value if it doesn't equal 0\,pt. Of course, we could +% also set a zero value, but that would needlessly clutter the +% logfile. +% +% \begin{macrocode} +\def\SOUL@setkern#1{\ifdim#1=\z@\else\kern#1\fi} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@error} +% This error message will be shown once for every word that couldn't +% be reconstructed by \cs{\SOUL@dosyllable}. +% +% \begin{macrocode} +\def\SOUL@error{% + \vrule\@height.8em\@depth.2em\@width1em + \PackageError{soul}{Reconstruction failed}{% + I came across hyphenatable material enclosed in group + braces,^^Jwhich I can't handle. Either drop the braces or + make the material^^Junbreakable using an \string\mbox\space + (\string\hbox). Note that a space^^Jalso counts as possible + hyphenation point. See page 4 of the manual.^^JI'm leaving + a black square so that you can see where I am right now.% + }% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@setup} +% This is a null driver, that will be used as the basis for +% other drivers. These have then to redefine only interface commands +% that shall differ from the default. +% +% \begin{macrocode} +\def\SOUL@setup{% + \let\SOUL@preamble\relax + \let\SOUL@postamble\relax + \let\SOUL@everytoken\relax + \let\SOUL@everysyllable\relax + \def\SOUL@everyspace##1{##1\space}% + \let\SOUL@everyhyphen\relax + \def\SOUL@everyexhyphen##1{##1}% + \let\SOUL@everylowerthan\relax +} +\SOUL@setup +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The \texorpdfstring{\so{letterspacing}}{letterspacing} driver} +% +% \begin{macro}{\SOUL@sosetletterskip} +% A handy helper macro that sets the inter-letter skip with a +% draconian \cs{\penalty}. +% +% \begin{macrocode} +\def\SOUL@sosetletterskip{\nobreak\hskip\SOUL@soletterskip} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@sopreamble} +% If letterspacing (\cs{\so} or \cs{\caps}) follows a white space, we +% replace it with our \syn{outer space}. \LaTeX\ uses |\hskip1sp| as +% marker in tabular entries, so we ignore tiny skips. +% +% \begin{macrocode} +\def\SOUL@sopreamble{% + \ifdim\lastskip>5sp + \unskip + \hskip\SOUL@soouterskip + \fi + \spaceskip\SOUL@soinnerskip +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@sopostamble} +% Start the look-ahead scanner \cs{\SOUL@socheck} outside the \cs{\SOUL@} +% scope. That's why we make the \syn{outer space} globally available in +% \cs{\skip@}. +% +% \begin{macrocode} +\def\SOUL@sopostamble{% + \global\skip@=\SOUL@soouterskip + \aftergroup\SOUL@socheck +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@socheck} +% \begin{macro}{\SOUL@sodoouter} +% Read the next token after the \soul\ command into \cs{\SOUL@@} +% and examine it. If it's some kind of space, replace it with +% \syn{outer space} and the appropriate penalty, else if it's +% a closing brace, continue scanning. If it is neither: do nothing. +% +% \begin{macrocode} +\def\SOUL@socheck{% + \futurelet\SOUL@@\SOUL@sodoouter +} +\def\SOUL@sodoouter{% + \def\SOUL@n*##1{\hskip\skip@}% + \ifcat\egroup\noexpand\SOUL@@ + \unkern + \egroup + \def\SOUL@n*{\afterassignment\SOUL@socheck\let\SOUL@x=}% + \else\ifx\SOUL@spc\SOUL@@ + \def\SOUL@n* {\hskip\skip@}% + \else\ifx~\SOUL@@ + \def\SOUL@n*~{\nobreak\hskip\skip@}% + \else\ifx\ \SOUL@@ + \else\ifx\space\SOUL@@ + \else\ifx\@xobeysp\SOUL@@ + \else + \def\SOUL@n*{}% + \let\SOUL@@\relax + \fi\fi\fi\fi\fi\fi + \SOUL@n*% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@soeverytoken} +% Typeset the token and put an unbreakable inter-letter skip +% thereafter. If the token is \cs{\<} then remove the last skip instead. +% Gets the character kerning value between the actual and the +% next token in \cs{\SOUL@charkern}. +% +% \begin{macrocode} +\def\SOUL@soeverytoken{% + \edef\x{\the\SOUL@token}% + \ifx\x\SOUL@lowerthanM + \else + \global\let\SOUL@soeventuallyskip\SOUL@sosetletterskip + \the\SOUL@token + \SOUL@gettoken + \edef\x{\the\SOUL@token}% + \ifx\x\SOUL@stopM + \else + \SOUL@setkern\SOUL@charkern + \SOUL@sosetletterskip + \SOUL@puttoken + \fi + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@soeveryspace} +% This macro sets an \syn{inner space}. The argument may contain +% penalties and is used for the |~| command. This construction was +% needed to make colored underlines work, without having to put +% any of the coloring commands into the core. |\kern\z@| prevents +% in subsequent \cs{\so} commands that the second discards the +% \syn{outer space} of the first. To remove the space simply +% use |\unkern\unskip|. +% +% \begin{macrocode} +\def\SOUL@soeveryspace#1{#1\space\kern\z@} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@soeveryhyphen} +% Sets implicit hyphens. The kerning value between the current token +% and the hyphen character is passed in \cs{\SOUL@hyphkern}. +% +% \begin{macrocode} +\def\SOUL@soeveryhyphen{% + \discretionary{% + \unkern + \SOUL@setkern\SOUL@hyphkern + \SOUL@sethyphenchar + }{}{}% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@soeveryexhyphen} +% Sets the explicit hyphen that is passed as argument. +% \cs{\SOUL@soeventuallyskip} equals \cs{\SOUL@sosetletterskip}, +% except when a \cs{\<} had been detected. This is necessary because +% \cs{\SOUL@soeveryexhyphen} wouldn't know otherwise, that it +% follows a~\cs{\<}. +% +% \begin{macrocode} +\def\SOUL@soeveryexhyphen#1{% + \SOUL@setkern\SOUL@hyphkern + \SOUL@soeventuallyskip + \hbox{#1}% + \discretionary{}{}{% + \SOUL@setkern\SOUL@charkern + }% + \SOUL@sosetletterskip + \global\let\SOUL@soeventuallyskip\relax +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@soeverylowerthan} +% Let \cs{\<} remove the last inter-letter skip. Set the kerning value +% between the token before and that after the \cs{\<} command. +% +% +% \begin{macrocode} +\def\SOUL@soeverylowerthan{% + \unskip + \unpenalty + \global\let\SOUL@soeventuallyskip\relax + \SOUL@setkern\SOUL@charkern +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@sosetup} +% Override all interface macros by our letterspacing versions. The +% only unused macro is \cs{\SOUL@everysyllable}. +% +% \begin{macrocode} +\def\SOUL@sosetup{% + \SOUL@setup + \let\SOUL@preamble\SOUL@sopreamble + \let\SOUL@postamble\SOUL@sopostamble + \let\SOUL@everytoken\SOUL@soeverytoken + \let\SOUL@everyspace\SOUL@soeveryspace + \let\SOUL@everyhyphen\SOUL@soeveryhyphen + \let\SOUL@everyexhyphen\SOUL@soeveryexhyphen + \let\SOUL@everylowerthan\SOUL@soeverylowerthan +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@setso} +% A handy macro for internal use. +% +% \begin{macrocode} +\def\SOUL@setso#1#2#3{% + \def\SOUL@soletterskip{#1}% + \def\SOUL@soinnerskip{#2}% + \def\SOUL@soouterskip{#3}% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\sodef} +% This macro assigns the letterspacing skips as well as an optional +% font switching command to a command sequence name. \cs{\so} itself +% will be defined using this macro. +% +% \begin{macrocode} +\def\sodef#1#2#3#4#5{% + \DeclareRobustCommand*#1{\SOUL@sosetup + \def\SOUL@preamble{% + \SOUL@setso{#3}{#4}{#5}% + #2% + \SOUL@sopreamble + }% + \SOUL@ + }% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\resetso} +% Let \cs{\resetso} define reasonable default values for letterspacing. +% +% \begin{macrocode} +\def\resetso{% + \sodef\textso{}{.25em}{.65em\@plus.08em\@minus.06em}% + {.55em\@plus.275em\@minus.183em}% +} +\resetso +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\sloppyword} +% Set up a letterspacing macro that inserts slightly stretchable +% space between the characters. This can be used to typeset long +% words in narrow columns, where ragged paragraphs are undesirable. +% See section~\ref{sec:sloppyword}. +% +% \begin{macrocode} +\sodef\sloppyword{% + \linepenalty10 + \hyphenpenalty10 + \adjdemerits\z@ + \doublehyphendemerits\z@ + \finalhyphendemerits\z@ + \emergencystretch.1em}% + {\z@\@plus.1em}% + {.33em\@plus.11em\@minus.11em}% + {.33em\@plus.11em\@minus.11em} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection[The \texorpdfstring{\caps{caps}}{caps} driver]{The caps driver} +% +% \begin{macro}{\caps} +% Unless run under \LaTeX, make \cs{\caps} just another simple letterspacing +% macro that selects a font \cs{\capsfont} (defaulting to \cs{\relax}) but +% doesn't have any special capabilities. +% +% \begin{macrocode} +\ifx\documentclass\@undefined +\let\capsfont\relax +\let\capsreset\relax +\def\capsdef#1#2#3#4#5{} +\def\capssave#1{} +\def\capsselect#1{} +\sodef\textcaps{\capsfont} + {.028em\@plus.005em\@minus.01em}% + {.37em\@plus.1667em\@minus.111em}% + {.37em\@plus.1em\@minus.14em} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\capsreset} +% \dots\ else, if run under \LaTeX\ prepare a set of macros that +% maintain a database with certain letterspacing values for different +% fonts. \cs{\capsreset} clears the database and inserts a default rule. +% +% \begin{macrocode} +\else +\DeclareRobustCommand*\capsreset{% + \let\SOUL@capsbase\empty + \SOUL@capsdefault +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\capsdef} +% Add an entry to the database, which is of course nothing else than +% a \TeX\ macro. See section ``List macros'' of appendix~D in the +% \TeX{}book~\cite{DEK} for details. +% +% \begin{macrocode} +\def\capsdef#1#2#3#4#5{{% + \toks\z@{\\{#1/#2/#3/#4/#5}}% + \toks\tw@=\expandafter{\SOUL@capsbase}% + \xdef\SOUL@capsbase{\the\toks\z@\the\toks\tw@}% +}} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\capssave} +% \begin{macro}{\capsselect} +% Save the current database in a macro within the |SOUL@| namespace +% and let |\capsselect| restore this database. +% +% \begin{macrocode} +\DeclareRobustCommand*\capssave[1]{% + \expandafter\global\expandafter\let + \csname SOUL@db@#1\endcsname\SOUL@capsbase +} +\DeclareRobustCommand*\capsselect[1]{% + \expandafter\let\expandafter\SOUL@capsbase + \csname SOUL@db@#1\endcsname +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@capsfind} +% \begin{macro}{\SOUL@caps} +% Go through the database entries and pick the first entry that matches +% the currently active font. Then define an internal macro that uses +% the respective spacing values in a macro that is equivalent to the +% \cs{\textso} command. +% +% \begin{macrocode} +\def\SOUL@capsfind#1/#2/#3/#4/#5/#6/#7/#8/#9/{% + \let\SOUL@match=1% + \SOUL@chk{#1}\f@encoding + \SOUL@chk{#2}\f@family + \SOUL@chk{#3}\f@series + \SOUL@chk{#4}\f@shape + \SOUL@dimchk{#5}\f@size + \if\SOUL@match1% + \let\\\@gobble + \gdef\SOUL@caps{% + \SOUL@sosetup + \def\SOUL@preamble{\SOUL@setso{#7}{#8}{#9}#6% + \SOUL@sopreamble}% + \SOUL@}% + \fi +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@chk} +% Sets the \cs{\SOUL@match} flag if both parameters are equal. +% This is used for all \caps{\small NFSS} elements except the font size. +% +% \begin{macrocode} +\def\SOUL@chk#1#2{% + \if$#1$% + \else + \def\SOUL@n{#1}% + \ifx#2\SOUL@n\else\let\SOUL@match=0\fi + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@dimchk} +% \begin{macro}{\SOUL@rangechk} +% We do not only want to check if a given font size |#1| matches |#2|, +% but also if it fits into a given range. An omitted lower boundary +% is replaced by \cs{\z@} and an omitted upper boundary by \cs{\maxdimen}. +% The first of a series of \cs{\SOUL@chk} and \cs{\SOUL@dimchk} +% statements, which detects that the arguments don't match, sets the +% \cs{\SOUL@match} flag to zero. A value of~1 indicates that an +% entry in the font database matches the currently used font. +% +% \begin{macrocode} +\def\SOUL@dimchk#1#2{\if$#1$\else\SOUL@rangechk{#2}#1--\@ne\@@\fi} +\def\SOUL@rangechk#1#2-#3-#4\@@{% + \count@=#4% + \ifnum\count@>\z@ + \ifdim#1\p@=#2\p@\else\let\SOUL@match=0\fi + \else + \dimen@=\if$#2$\z@\else#2\p@\fi + \ifdim#1\p@<\dimen@\let\SOUL@match=0\fi + \dimen@=\if$#3$\maxdimen\else#3\p@\fi + \ifdim#1\p@<\dimen@\else\let\SOUL@match=0\fi + \fi +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\textcaps} +% Find a matching entry in the database and start the letterspacing +% mechanism with the given spacing values. +% +% \begin{macrocode} +\DeclareRobustCommand*\textcaps{{% + \def\\##1{\expandafter\SOUL@capsfind##1/}% + \SOUL@capsbase + \aftergroup\SOUL@caps +}} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@capsdefault} +% Define a default database entry and a default font. +% +% \begin{macrocode} +\def\SOUL@capsdefault{% + \capsdef{////}% + \SOUL@capsdfltfnt + {.028em\@plus.005em\@minus.01em}% + {.37em\@plus.1667em\@minus.1em}% + {.37em\@plus.111em\@minus.14em}% +} +\let\SOUL@capsdfltfnt\scshape +\capsreset +\fi +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The \texorpdfstring{\ul{underlining}}{underlining} driver} +% +% \begin{macro}{\SOUL@ulleaders} +% This macro sets the underline under the following \cs{\hskip}. +% +% \begin{macrocode} +\newdimen\SOUL@uldp +\newdimen\SOUL@ulht +\def\SOUL@ulleaders{% + \leaders\hrule\@depth\SOUL@uldp\@height\SOUL@ulht\relax +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@ulunderline} +% Set an underline under the given material. It draws the line first, +% and the given material afterwards. This is needed for highlighting, +% but gives less than optimal results for colored overstriking, which, +% however, will hardly ever be used, anyway. +% +% \begin{macrocode} +\def\SOUL@ulunderline#1{{% + \setbox\z@\hbox{#1}% + \dimen@=\wd\z@ + \dimen@i=\SOUL@uloverlap + \advance\dimen@2\dimen@i + \rlap{% + \null + \kern-\dimen@i + \SOUL@ulcolor{\SOUL@ulleaders\hskip\dimen@}% + }% + \unhcopy\z@ +}} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@ulpreamble} +% Just set up the line dimensions and the space skip. Normally, +% \cs{\spaceskip} is unset and not used by \TeX. We need it, though, +% because we feed it to the \cs{\leaders} primitive. +% +% \begin{macrocode} +\def\SOUL@ulpreamble{% + \SOUL@uldp=\SOUL@uldepth + \SOUL@ulht=-\SOUL@uldp + \advance\SOUL@uldp\SOUL@ulthickness + \spaceskip\SOUL@spaceskip +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@uleverysyllable} +% By using \cs{\SOUL@everysyllable} we don't have to care about +% kerning values and get better results for highlighting, where +% negative kerning values would otherwise cut off characters. +% +% \begin{macrocode} +\def\SOUL@uleverysyllable{% + \SOUL@ulunderline{% + \the\SOUL@syllable + \SOUL@setkern\SOUL@charkern + }% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@uleveryspace} +% Set a given penalty and an underlined \cs{\space} equivalent. +% The \cs{\null} prevents a nasty gap in |\textfrak| |{a \textswab{b}}|, +% while it doesn't seem to hurt in all other cases. I didn't investigate +% this. +% +% \begin{macrocode} +\def\SOUL@uleveryspace#1{% + \SOUL@ulcolor{% + #1% + \SOUL@ulleaders + \hskip\spaceskip + }% + \null +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@uleveryhyphen} +% If hyphenation takes place, output an underlined hyphen with the +% required hyphen kerning value. +% +% \begin{macrocode} +\def\SOUL@uleveryhyphen{% + \discretionary{% + \unkern + \SOUL@ulunderline{% + \SOUL@setkern\SOUL@hyphkern + \SOUL@sethyphenchar + }% + }{}{}% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@uleveryexhyphen} +% Underline the given hyphen, en-dash, em-dash or \cs{\slash} and care +% for kerning. +% +% \begin{macrocode} +\def\SOUL@uleveryexhyphen#1{% + \SOUL@setkern\SOUL@hyphkern + \SOUL@ulunderline{#1}% + \discretionary{}{}{% + \SOUL@setkern\SOUL@charkern + }% +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@ulcolor} +% \begin{macro}{\setulcolor} +% Define the underline color or turn off coloring, in which case the lines are not +% just colored black, but remain uncolored. This makes them appear +% black, nevertheless, and has the advantage, that no Postscript +% \cs{\specials} are cluttering the output. +% +% \begin{macrocode} +\let\SOUL@ulcolor\relax +\def\setulcolor#1{% + \if$#1$ + \let\SOUL@ulcolor\relax + \else + \def\SOUL@ulcolor{\textcolor{#1}}% + \fi +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\setuloverlap} +% \begin{macro}{\SOUL@uloverlap} +% Set the overlap amount, that helps to avoid gaps on sloppy output +% devices. +% +% \begin{macrocode} +\def\setuloverlap#1{\def\SOUL@uloverlap{#1}} +\setuloverlap{.25pt} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@ulsetup} +% The underlining driver is quite simple. No need for \cs{\SOUL@postamble} +% and \cs{\SOUL@everytoken}. +% +% \begin{macrocode} +\def\SOUL@ulsetup{% + \SOUL@setup + \let\SOUL@preamble\SOUL@ulpreamble + \let\SOUL@everysyllable\SOUL@uleverysyllable + \let\SOUL@everyspace\SOUL@uleveryspace + \let\SOUL@everyhyphen\SOUL@uleveryhyphen + \let\SOUL@everyexhyphen\SOUL@uleveryexhyphen +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@textul} +% Describing self-explanatory macros is \emph{so} boring! +% +% \begin{macrocode} +\DeclareRobustCommand*\textul{\SOUL@ulsetup\SOUL@} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\setul} +% \begin{macro}{\SOUL@uldepth} +% \begin{macro}{\SOUL@ulthickness} +% Set the underlining dimensions. Either value may be omitted and +% lets the respective macro keep its current contents. +% +% \begin{macrocode} +\def\setul#1#2{% + \if$#1$\else\def\SOUL@uldepth{#1}\fi + \if$#2$\else\def\SOUL@ulthickness{#2}\fi +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\resetul} +% Set reasonable default values that fit most latin fonts. +% +% \begin{macrocode} +\def\resetul{\setul{.65ex}{.1ex}} +\resetul +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\setuldepth} +% This macro sets all designated ``letters'' (\cs{\catcode=11}) or the +% given material in a box and sets the underlining dimensions according +% to the box depth. +% +% \begin{macrocode} +\def\setuldepth#1{{% + \def\SOUL@n{#1}% + \setbox\z@\hbox{% + \tracinglostchars\z@ + \ifx\SOUL@n\empty + \count@\z@ + \loop + \ifnum\catcode\count@=11\char\count@\fi + \ifnum\count@<\@cclv + \advance\count@\@ne + \repeat + \else + #1% + \fi + }% + \dimen@\dp\z@ + \advance\dimen@\p@ + \xdef\SOUL@uldepth{\the\dimen@}% +}} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The \texorpdfstring{\st{overstriking}}{overstriking} driver} +% +% \begin{macro}{\SOUL@stpreamble} +% Striking out is just underlining with a raised line of a different +% color. Hence we only need to define the preamble accordingly and +% let the underlining preamble finally do its job. Not that colored +% overstriking was especially useful, but we want at least to keep +% it black while we might want to set underlines in some fancy color. +% +% \begin{macrocode} +\def\SOUL@stpreamble{% + \dimen@\SOUL@ulthickness + \dimen@i=-.5ex + \advance\dimen@i-.5\dimen@ + \edef\SOUL@uldepth{\the\dimen@i}% + \let\SOUL@ulcolor\SOUL@stcolor + \SOUL@ulpreamble +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@stsetup} +% We re-use the whole underlining setup and just replace the preamble +% with our modified version. +% +% \begin{macrocode} +\def\SOUL@stsetup{% + \SOUL@ulsetup + \let\SOUL@preamble\SOUL@stpreamble +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\textst} +% These pretzels are making me thirsty \dots +% +% \begin{macrocode} +\DeclareRobustCommand*\textst{\SOUL@stsetup\SOUL@} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@stcolor} +% \begin{macro}{\setstcolor} +% Set the overstriking color. This won't be used often, but is required +% in cases, where the underlines are colored. You wouldn't want to +% overstrike in the same color. Note that overstriking lines are +% drawn \emph{beneath} the text, hence bright colors won't look good. +% +% \begin{macrocode} +\let\SOUL@stcolor\relax +\def\setstcolor#1{% + \if$#1$ + \let\SOUL@stcolor\relax + \else + \def\SOUL@stcolor{\textcolor{#1}}% + \fi +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection{The highlighting driver} +% +% \begin{macro}{\SOUL@hlpreamble} +% This is nothing else than overstriking with very thick lines. +% +% \begin{macrocode} +\def\SOUL@hlpreamble{% + \setul{}{2.5ex}% + \let\SOUL@stcolor\SOUL@hlcolor + \SOUL@stpreamble +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\SOUL@hlsetup} +% No need to re-invent the wheel. Just use the overstriking setup +% with a different preamble. +% +% \begin{macrocode} +\def\SOUL@hlsetup{% + \SOUL@stsetup + \let\SOUL@preamble\SOUL@hlpreamble +} +% \end{macrocode} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \begin{macro}{\texthl} +% \begin{macro}{\sethlcolor} +% \begin{macro}{\SOUL@hlcolor} +% Define the highlighting macro and the color setting macro with a +% simple default color. Yellow isn't really pleasing, but it's already +% predefined by the \package{color} package. +% +% \begin{macrocode} +\DeclareRobustCommand*\texthl{\SOUL@hlsetup\SOUL@} +\def\sethlcolor#1{\if$#1$\else\def\SOUL@hlcolor{\textcolor{#1}}\fi} +\sethlcolor{yellow} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \subsection*{The package postamble} +% +% \begin{macro}{\so} +% \begin{macro}{\ul} +% \begin{macro}{\st} +% \begin{macro}{\hl} +% \begin{macro}{\caps} +% OK, I lied. The short macro names are just abbreviations for their +% longer counterpart. Some people might be used to |\text*| style commands +% to select a certain font. And then it doesn't hurt to reserve +% these early enough. +% +% \begin{macrocode} +\let\so\textso +\let\ul\textul +\let\st\textst +\let\hl\texthl +\let\caps\textcaps +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \noindent +% When used in an environment other than \LaTeX\ and the \package{german} +% package was already loaded, define the double quotes as accent. +% +% \begin{macrocode} +\ifx\documentclass\@undefined + \ifx\mdqoff\@undefined + \else + \soulaccent{"}% + \fi + \catcode`\@=\atcode +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \noindent +% If we have been loaded by a \LaTeX\ environment and the \package{color} +% package wasn't also loaded, we disable all colors. Then we add the umlaut accent +% |"| if the \package{german} package is present. The quotes character has to +% be \cs{\catcode}'d \cs{\active} now, or it won't get recognized later. +% The \option{capsdefault} +% option overrides the \cs{\caps} driver and lets \cs{\SOUL@} set an underline. +% Finally load the local configuration, process the |capsdefault| +% option and exit. +% +% \begin{macrocode} +\else + \bgroup + \catcode`\"\active + \AtBeginDocument{% + \@ifundefined{color}{% + \let\SOUL@color\relax + \let\setulcolor\@gobble + \let\setstcolor\@gobble + \let\sethlcolor\@gobble + \let\hl\ul + }{} + \@ifundefined{mdqoff}{}{\soulaccent{"}} + } + \egroup + \DeclareOption{capsdefault}{% + \AtBeginDocument{% + \def\SOUL@capsdfltfnt#1{% + \SOUL@ulsetup + \SOUL@ulpreamble + \scshape + }% + }% + } + \InputIfFileExists{soul.cfg}% + {\PackageInfo{soul}{Local config file soul.cfg used}}{} + \ProcessOptions +\fi +\endinput +% \end{macrocode} +% +% +% +% +%^^A-------------------------------------------------------------------- +% +% +% +% +% \vspace{2explus1fill} +%\begin{verbatim} +%$Id: soul.dtx,v 1.128 2003/11/17 22:57:24 m Rel $ +%\end{verbatim} +% \Finale +% +% +% ^^A.E.I.O.U.^^ +%^^A vim:ts=4:sw=4:et |