summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/embrac/embrac_en.tex
blob: 608fa510a7a9ccf47da32222a0f9ed2003c20f39 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
% arara: pdflatex
% arara: makeindex: { sort: true, style: embrac_en.ist }
% arara: biber
% arara: pdflatex
% arara: pdflatex
% --------------------------------------------------------------------------
% the EMBRAC package
% 
%   Upright Brackets in Emphasized Text
% 
% 2012/06/29
% --------------------------------------------------------------------------
% Clemens Niederberger
% Web:    https://bitbucket.org/cgnieder/embrac/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2012 Clemens Niederberger
% 
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
% 
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Clemens Niederberger.
% --------------------------------------------------------------------------
% The embrac package consists of the files
%  - embrac.sty, embrac_en.tex, embrac_en.pdf, embrac_kerning_test.tex and
%    README
% --------------------------------------------------------------------------
% If you have any ideas, questions, suggestions or bugs to report, please
% feel free to contact me.
% --------------------------------------------------------------------------
%
% if you want to compile this documentation you'll need the document class
% `cnpkgdoc' which you can get here:
%    https://bitbucket.org/cgnieder/cnpkgdoc/
% the class is licensed LPPL 1.3 or later
%
\documentclass[DIV10,toc=index,toc=bib]{cnpkgdoc}
\docsetup{
  pkg      = [biblatex]embrac,
  code-box = {
    backgroundcolor  = gray!7!white ,
    skipbelow        = .6\baselineskip plus .5ex minus .5ex ,
    skipabove        = .6\baselineskip plus .5ex minus .5ex ,
    roundcorner      = 3pt ,
  } ,
  gobble   = 1
}
\usepackage[osf]{libertine}
\usepackage{fnpct}
\cnpkgcolors{
  main   => cnpkgred ,
  key    => yellow!40!brown ,
  module => cnpkgblue ,
  link   => black!90
}

\renewcommand*\othersectionlevelsformat[3]{%
  \textcolor{main}{#3\autodot}\enskip}
\renewcommand*\partformat{%
  \textcolor{main}{\partname~\thepart\autodot}}


\ExplSyntaxOn
\NewDocumentCommand \Default {g}
  {
    \hfill\llap
      {
        \IfNoValueTF { #1 }
          {(initially~empty)}
          {Default:~\code{#1}}
      }
    \newline
  }
\ExplSyntaxOff

\addcmds{
  AddEmph,
  DeleteEmph,
  EmbracOff,
  EmbracOn,
  printbibliography,
  ChangeEmph
}

\usepackage[backend=biber,style=alphabetic]{biblatex}
\addbibresource{\jobname.bib}
\usepackage{filecontents}
\begin{filecontents}{\jobname.bib}
@book{bringhurst04,
  title     = {The Elements of Typographic Style},
  author    = {Robert Bringhurst},
  year      = {2004},
  version   = {3.2},
  isbn      = {978-0-88179-205-5},
  publisher = {Hartley \&\ Marks, Canada}
}
@article{dtk12-dw,
  author  = {Dominik Waßenhoven},
  title   = {Aufrechte Klammern in kursivem Text},
  journal = {Die \TeX{}nische Komödie},
  volume  = {2},
  year    = {2012},
  pages   = {51--53}
}
@online{lefloch11,
  author  = {Bruno Le Floch},
  title   = {Upright parentheses in italic text},
  url     = {http://tex.stackexchange.com/a/13057/5049},
  date    = {2011-03-09},
  urldate = {2012-06-28}
}
\end{filecontents}

% index:
\usepackage{makeidx}
\begin{filecontents}{\jobname.ist}
 heading_prefix "{\\bfseries "
 heading_suffix "\\hfil}\\nopagebreak\n"
 headings_flag  1
 delim_0 "\\dotfill "
 delim_1 "\\dotfill "
 delim_2 "\\dotfill "
 delim_r "\\textendash"
 suffix_2p "\\nohyperpage{\\,f.}"
 suffix_3p "\\nohyperpage{\\,ff.}"
\end{filecontents}
\makeindex

\usepackage{fixfoot}
\DeclareFixedFootnote\manythanks{Many thanks again for his kind permission to use it!}

\ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
\begin{document}

\section{License and Requirements}\secidx{License}\secidx{Requirements}
\embrac is placed under the terms of the LaTeX Project Public License,
version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}).
It has the status ``maintained.''

\embrac loads and needs the packages \paket{expl3}, \paket{xparse} and
\paket{l3keys2e}, the first is part of the \paket{l3kernel} and the others are
part of the \paket{l3packages}.
\secidx*{License}\secidx*{Requirements}

\section{Acknowledgements}
I like to thank both Dominik Waßenhoven for inspiration~\cite{dtk12-dw} and
Bruno Le Floch for providing code~\cite{lefloch11}. Without either of them this
package probably wouldn't exist.

\section{New}
\begin{description}
 \item[v0.1a] The command \cmd{RenewEmph} has been renamed into
 \cmd{ChangeEmph} and a new slightly different \cmd{RenewEmph} has been added.
\end{description}

\section{About}\label{sec:about}\secidx{About}
\begin{zitat}[{\cite[85]{bringhurst04}}]
 Parentheses and brackets are not letters, and it makes little sense to speak of
 them as roman or italic. There are vertical parentheses and sloped ones, and
 the parentheses on italic fonts are almost always sloped, but vertical parentheses
 are generally to be preferred. That means they must come from the roman font,
 and may need extra spacing when used with italic letterforms.
 
 The sloped square brackets usually found on italic fonts are, if anything, even
 less useful than sloped parentheses. If, perish the thought, there were a book
 or film entitled \emph*{The View from My [sic] Bed}, sloped brackets might be
 useful as a way of indicating that the brackets and their contents are actually
 part of the title. Otherwise, vertical brackets should be used, no matter whether
 the text is roman or italic: \textquote{The View from My \emph{[sic]} Bed} and
 \textquote{\emph{the view from my [sic] bed}.\kern.05em}
\end{zitat}

\noindent
Both this quote from~\citetitle{bringhurst04} by Robert Bringhurst and the
article \citetitle{dtk12-dw} by Dominik Waßenhoven~\cite{dtk12-dw} inspired
this package. Indeed, \embrac heavily borrows from the code \citeauthor{dtk12-dw}
provided in his article\manythanks. The code was originally provided by Bruno
Le~Floch\manythanks\ as an answer to a question on \{TeX.SE\}~\cite{lefloch11}.

\embrac tries to redefine \cmd{emph} and \cmd{textit} in a way that neither
parentheses nor square brackets are sloped. In an ideal world you of course
wouldn't need this package because the italic font you're using would have
vertical parentheses and brackets by itself.

\begin{beispiel}
 \emph{This is emphasized [sic] text.} \\
 \emph{This is emphasized text (as you can see).}
\end{beispiel}
\secidx*{About}

\section{How it Works}\secidx{How it Works}
Both the commands \cmd{emph} and \cmd{textit} are redefined:
\begin{beschreibung}
 \Befehl{emph}*{<emphasized text>}
 \Befehl{textit}*{<text in italics>}
\end{beschreibung}
They now both have a \code{*} argument that restores the original behaviour.
Otherwise they're used just as before.

Let's see the example again:
\begin{beispiel}
 \emph{This is emphasized [sic] text.} \\
 \emph{This is emphasized text (as you can see).}
\end{beispiel}
As you can see you don't have to do anything apart from loading \embrac in your
preamble. Well -- that's actually not entirely true. You have to take care of the
kerning of the parentheses and brackets. Otherwise things could look worse with
\embrac than without.

The following example demonstrates one point why you have to be very careful
when using \embrac. Certain parenthesis-letter combinations might need adjustments
of the kerning:
\begin{beispiel}
 \emph{This is (just) emphasized text.} \\
 \emph{This is (\kern.1em just) emphasized text.}
\end{beispiel}
This of course strongly depends on the font you've chosen. Kerning is a very
important aspect when using this package and you shouldn't use it without giving
it a certain amount of attention. See the next section for more details.
\secidx*{How it Works}

\section{Adding More Brackets \&\ Adjusting the Kerning}
\secidx{Adding More Brackets}\secidx{Adjusting the Kerning}
If you want you can change the behaviour of \embrac. Maybe it should only affect
squared brackets? Or curly braces, too? This can be done with the following
commands. They all work locally which means if used inside a group outside of it
everything stays what it was.
\begin{beschreibung}
 \Befehl{AddEmph}{<o>}\oa{<io-kern>,<oo-kern>}\ma{<c>}\oa{<ic-kern>,<oc-kern>}
 \Befehl{ChangeEmph}{<o>}\oa{<io-kern>,<oo-kern>}\ma{<c>}\oa{<ic-kern>,<oc-kern>}
 \Befehl{RenewEmph}{<o>}\oa{<io-kern>,<oo-kern>}\ma{<c>}\oa{<ic-kern>,<oc-kern>}
 \Befehl{DeleteEmph}{<o>}\ma{<c>}
\end{beschreibung}
Here \code{<o>} means \emph{opening bracket} and \code{<c>} means \emph{closing
bracket}. The kerning arguments are all four optional and require -- if given --
to be a length. If they're not given \cmd{AddEmph} and \cmd{RenewEmph} insert
\code{0pt} and \cmd{ChangeEmph} uses the value stored by \cmd{AddEmph} or
\cmd{RenewEmph} before.

\code{<io-kern>} is inserted after the opening bracket (inner opening),
\code{<oo-kern>} is inserted before it (outer opening). \code{<ic-kern>} is
inserted before the closing bracket (inner closing), \code{<oc-kern>} after it
(outer closing).

\embrac initially makes these definitions:
\begin{beispiel}[code only]
 % add some defaults:
 \AddEmph{[}{]}[.04em,-.12em]
 \AddEmph{(}[-.04em]{)}[,-.15em]
\end{beispiel}

This document however uses ``Linux Libertine O''\footnote{\url{http://www.linuxlibertine.org/}}
both for the roman and the italic font and redefines them in this way (still not
sure these are the best values):
\begin{beispiel}[code only]
 \ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
 \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
\end{beispiel}

You can change them as you wish, but be careful with the kerning! What's too less
for one letter might be too much for others:
\begin{beispiel}
 \ChangeEmph{(}[.1em]{)}[.1em]
 \emph{This is (just) emphasized text.} \\ % looks ok
 \emph{This is emphasized text (as you can see).} % looks bad
\end{beispiel}

To see why it is important to pay attention to the kerning values let's look at
how \embrac's features look without kerning (\ie, \code{0pt} for each value),
with the default settings and with the settings for this document:

\begin{center}
 \begin{minipage}{.5\linewidth}
  \textbf{No Kerning:}
  
  \RenewEmph{[}{]}\RenewEmph{(}{)}
  \emph{This is emphasized [sic] text.} \\
  \emph{This is emphasized text [as you can see].} \\
  \emph{This is emphasized (sic) text.} \\
  \emph{This is emphasized text (as you can see).}
 \end{minipage}\bigskip
 
 \begin{minipage}{.5\linewidth}
  \textbf{\embrac's Default Kerning:}
  
  \RenewEmph{[}{]}[.04em,-.12em]\RenewEmph{(}[-.04em]{)}[,-.15em]
  \emph{This is emphasized [sic] text.} \\
  \emph{This is emphasized text [as you can see].} \\
  \emph{This is emphasized (sic) text.} \\
  \emph{This is emphasized text (as you can see).}
 \end{minipage}\bigskip
 
 \begin{minipage}{.5\linewidth}
  \textbf{Adjusted Kerning:}
  
  \emph{This is emphasized [sic] text.} \\
  \emph{This is emphasized text [as you can see].} \\
  \emph{This is emphasized (sic) text.} \\
  \emph{This is emphasized text (as you can see).}
 \end{minipage}
\end{center}

Deleting a pair removes it completely from \embrac's mechanism. All information
about the pair and it's kerning values will be lost. So if you want the effects
to be temporary use grouping.
\begin{beispiel}
 \DeleteEmph[]
 \emph{This is emphasized [sic] text.} \\
 \emph{This is emphasized text (as you can see).}
\end{beispiel}

By the way: this packages provides a simple file \code{embrac\_kerning\_test.tex}
for testing kerning values. You should find it in the same directory as this
documentation.
\secidx*{Adding More Brackets}\secidx*{Adjusting the Kerning}

\section{biblatex Compatibility}\secidx{biblatex Compatibility}
This is \embrac's only package option:
\begin{beschreibung}
 \Option{biblatex}{\default{true}|false}\Default{false} If set to true parentheses
 and squared brackets as defined by \paket{biblatex} with \cmd{bibleftparen},
 \cmd{bibrightparen}, \cmd{bibleftbracket} and \cmd{bibrightbracket} are treated
 the same way (if not removed from the treatment with \cmd{DeleteEmph}).
\end{beschreibung}

\begin{beispiel}
 % this document uses \usepackage[biblatex]{embrac}
 \emph{Let's cite the quote from section~\ref{sec:about} again:~\cite{bringhurst04}}.
\end{beispiel}
\secidx*{biblatex Compatibility}

\section{Turn \embrac Temporarily Off}\secidx{Turn \embrac Temporarily Off}
Redefining \cmd{emph} and \cmd{textit} is not without danger. Sometimes you might
find that you'd want to keep the original definition for a small portion of your
document. You can use the following commands whose functions are obvious, I guess:
\begin{beschreibung}
 \Befehl{EmbracOff}
 \Befehl{EmbracOn}
\end{beschreibung}
Both commands are local.

This document for example uses the following lines because \paket{biblatex}
complained when it tried to typeset the entry for~\cite{bringhurst04}. Using
\cmd{DeleteEmph}[] would have worked as well.
\begin{beispiel}[code only]
 \EmbracOff
 \printbibliography
\end{beispiel}
\secidx*{Turn \embrac Temporarily Off}

\section{Watch out!}\secidx{Watch Out}
Please be aware that \embrac does not affect \cmd{itshape} nor the commands
\cmd{em} or \cmd{it} (which you shouldn't use in a \LaTeX\ document, anyway).
\begin{beispiel}
 \itshape This is italic [sic] text.
\end{beispiel}
\secidx*{Watch Out}

\EmbracOff
\printbibliography


\setindexpreamble{Section titles are indicated \textbf{bold}, packages
\textsf{sans serif}, commands \code{\textbackslash\textcolor{code}{brown}}
 and options \textcolor{key}{\code{yellow}}.\par\bigskip}
\printindex
\end{document}