path: root/macros/latex/contrib/embrac/embrac_en.tex

% arara: pdflatex: { interaction: nonstopmode }
% arara: biber
% arara: pdflatex: { interaction: nonstopmode }
% arara: pdflatex: { interaction: nonstopmode }
% --------------------------------------------------------------------------
% the EMBRAC package
% 
%   Upright Brackets in Emphasized Text
% 
% --------------------------------------------------------------------------
% Clemens Niederberger
% Web:    https://github.com/cgnieder/embrac/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2012--2021 Clemens Niederberger
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% 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.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Clemens Niederberger.
% --------------------------------------------------------------------------
\documentclass[load-preamble+]{cnltx-doc}
\usepackage[biblatex]{embrac}

\setcnltx{
  package = embrac ,
  authors = Clemens Niederberger ,
  email   = contact@mychemistry.eu ,
  url     = https://github.com/cgnieder/embrac/ ,
  quote-author-format = ,
  add-cmds = {
    AddEmph,
    ChangeEmph,
    DeleteEmph,
    emb,embbracket,embparen,
    EmbracMakeKnown,
    EmbracOff,
    EmbracOn,
    printbibliography,
    RenewEmph
  }
}

\usepackage{csquotes}
\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}

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

\RenewEmph{[}[-0.045em,.02em]{]}[.055em,-.09em]
\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]

\newnote*\added[2]{Version~#1: added #2}

\begin{document}

\section{License and Requirements}
\license

\embrac\ needs the the \bnd{l3kernel}~\cite{bnd:l3kernel} and
\bnd{l3packages}~\cite{bnd:l3packages}.

\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{About}\label{sec:about}
\begin{cnltxquote}[{\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{cnltxquote}

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\ answering a question on
\href{http://tex.stackexchange.com}{TeX.sx}~\cite{lefloch11}.

\embrac\ tries to redefine \cs{emph}, \cs{textit} and
\cs{textsl}\added{0.6}{\cs{textsl}} 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{example}
  \emph{This is emphasized [sic] text.} \par
  \emph{This is emphasized text (as you can see).}
\end{example}

\section{How it Works}
The commands \cs{emph}, \cs{textit} and \cs{textsl} are redefined:
\begin{commands}
  \command{emph}[\sarg\marg{emphasized text}]
    Emphasizing text.
  \command{textit}[\sarg\marg{text in italics}]
    Italicizing text,
  \command{textsl}[\sarg\marg{slanted text}]
    Slanting text,
  \command{textsi}[\sarg\marg{text in italic small caps}]
    This command is only defined and thus redefined if you loaded
    \pkg{fontspec}, \ie, if you're compiling your document with \XeLaTeX{} or
    \LuaLaTeX.
\end{commands}
They now have a \sarg\ argument that restores the original behaviour.
Otherwise they're used just as before.

Let's see the example again:
\begin{example}
  \emph{This is emphasized [sic] text.} \par
  \emph{This is emphasized text (as you can see).}
\end{example}
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{example}
  \emph{This is (just) emphasized text.} \par
  \emph{This is (\kern.1em just) emphasized text.}
\end{example}
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.

\section{Adding More Brackets \&\ 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{commands}
  \command{AddEmph}[\marg{o}\Oarg{\meta{io-kern},\meta{oo-kern}}%
    \marg{c}\Oarg{\meta{ic-kern},\meta{oc-kern}}]
    Add a pair of brackets to be left upright in italic text.
  \command{ChangeEmph}[\marg{o}\Oarg{\meta{io-kern},\meta{oo-kern}}%
    \marg{c}\Oarg{\meta{ic-kern},\meta{oc-kern}}]
    Change the kerning values for a given pair of brackets.
  \command{RenewEmph}[\marg{o}\Oarg{\meta{io-kern},\meta{oo-kern}}%
    \marg{c}\Oarg{\meta{ic-kern},\meta{oc-kern}}]
    Renew the kerning values for a given pair of brackets.  See below for the
    difference to \cs{ChangeEmph}.
  \command{DeleteEmph}[\marg{o}\marg{c}]
    Remove a pair of brackets from treatment.
\end{commands}
In the above descriptions \meta{o} means \emph{opening bracket} and \meta{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 \cs{AddEmph} and
\cs{RenewEmph} insert \code{0pt} and \cs{ChangeEmph} uses the value stored by
\cs{AddEmph} or \cs{RenewEmph} before.

\sinceversion{0.4}To each of these commands there are two variants that are
only semantically different\footnote{They're also using different lists
  internally but you shouldn't concern yourself with this.}.  They are all
called \cs*{\meta{base}OpEmph} or \cs*{\meta{base}ClEmph} where \meta{base} is
either \code{Add}, \code{Change}, \code{Renew} or \code{Delete}.  Their
arguments are all the same: the half of what the main commands have for either
modifying the opening or the closing symbols.
\begin{commands}
  \command{AddOpEmph}[\marg{o}\Oarg{\meta{io-kern},\meta{oo-kern}}]
    An an opening bracket to the treatment.
  \command{AddClEmph}[\marg{c}\Oarg{\meta{ic-kern},\meta{oc-kern}}]
    An a closing bracket to the treatment.
\end{commands}
They allow you to add single symbols to \embrac's mechanism instead of adding
pairs.

In all these commands the optional argument \meta{io-kern} is inserted after
the opening bracket (inner opening), \meta{oo-kern} is inserted before it
(outer opening). \meta{ic-kern} is inserted before the closing bracket (inner
closing), \meta{oc-kern} after it (outer closing).

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

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{sourcecode}
  \RenewEmph{[}[-0.045em,.02em]{]}[.055em,-.09em]
  \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
\end{sourcecode}

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{example}
  \ChangeEmph{(}[.1em]{)}[.1em]
  \emph{This is (just) emphasized text.} \par % looks OK, kind of
  \emph{This is emphasized text (as you can see).} % looks bad
\end{example}

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 its kerning values will be lost.  So if you
want the effects to be temporary use grouping.
\begin{example}
  \DeleteEmph{[}{]}
  \emph{This is emphasized [sic] text.} \par
  \emph{This is emphasized text (as you can see).}
\end{example}

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.

\section{Adding More Commands}
If\sinceversion{0.9} you like to add additional macros to \embrac's treatment
(in addition to the already known \cs*{emph}, \cs*{textit}, \cs*{textsl}, and
\cs*{textsi}) then you can use the following command
\begin{commands}
  \command{EmbracMakeKnown}[\marg{command}]
    Redefine the command \meta{command} to replace brackets and parentheses by
    upright ones. \meta{command} is the name of the command \emph{without} the
    leading backslash!
\end{commands}
\embrac\ does this:  
\begin{sourcecode}
  \EmbracMakeKnown{emph}
  \EmbracMakeKnown{textit}
  \EmbracMakeKnown{textsl}
\end{sourcecode}

\section{biblatex Compatibility}
This is \embrac's only package option:
\begin{options}
  \keychoice{biblatex}{\default{true},on,parens,false,off,none}\Default{false}
    If set to \code{true} (or one of its aliases) parentheses and squared
    brackets as defined by \pkg{biblatex} with \cs{bibleftparen},
    \cs{bibrightparen}, \cs{bibleftbracket} and \cs{bibrightbracket} are
    treated the same way (if not removed from the treatment with \cs{DeleteEmph}).
   
    The command \cs*{blx@imc@mkbibemph} is patched to use the original definition
    of \cs{emph}.
\end{options}

\begin{example}
  % this document uses \usepackage[biblatex]{embrac}
  \emph{Let's cite Bringhurst again:~\cite{bringhurst04}}.
\end{example}

\section{Turn \embrac\ Temporarily Off}
Redefining \cs{emph}, \cs{textit} and \cs{textsl} 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{commands}
  \command{EmbracOff}
    Turn \embrac's treatment off.
  \command{EmbracOn}
    Turn \embrac's treatment on.
\end{commands}
Both commands are local.

\section{Watch out!}
Please be aware that \embrac\ does not affect \cs{itshape} nor \cs{em} (nor
\cs{it} which you shouldn't use in a \LaTeX{} document, anyway).
\begin{example}
  \itshape This is italic [sic] text.
\end{example}
In cases like this one of the following commands could be used:
\begin{commands}
  \command{emb}[\marg{op}\marg{cl}\marg{text}]
    Encloses\sinceversion{0.8} \meta{text} with \meta{op} and \meta{cl}. Both
    \meta{op} and \meta{cl} must be brackets known to \embrac.
  \command{embparen}[\marg{text}]
    Encloses\sinceversion{0.8} \meta{text} with upright parentheses.  This is
    the same as \cs{emb}\Marg{(}\Marg{)}\marg{text}.
  \command{embbracket}[\marg{text}]
    Encloses\sinceversion{0.8} \meta{text} with upright brackets.  This is
    the same as \cs{emb}\Marg{[}\Marg{]}\marg{text}.
\end{commands}
\begin{example}
  \itshape This is italic \embbracket{sic} text.
\end{example}

\section{Version History}
\begin{description}
  \item[v0.1a] The command \cs{RenewEmph} has been renamed into
    \cs{ChangeEmph} and a new slightly different \cs{RenewEmph} has been added.
  \item[v0.2] Improved interaction with \pkg{biblatex}.
  \item[v0.3] Added support for \pkg*{fontspec}'s \cs{textsi}.
  \item[v0.5] Don't replace brackets in math mode.
  \item[v0.6] Added support for \cs{textsl}.
  \item[v0.7] Added support for symbols with a catcode other than~12.
  \item[v0.8] Added \cs{embparen}, \cs{embbracket} and \cs{emb}.
  \item[v0.9] Added \cs{EmbracMakeKnown}
\end{description}

\end{document}