Initial commit

1 files changed, 345 insertions, 0 deletions

diff --git a/macros/latex/contrib/embrac/embrac_en.tex b/macros/latex/contrib/embrac/embrac_en.tex
new file mode 100644
index 0000000000..ec1bfb379e
--- /dev/null
+++ b/macros/latex/contrib/embrac/embrac_en.tex
@@ -0,0 +1,345 @@
+% arara: pdflatex
+% !arara: biber
+% !arara: pdflatex
+% arara: pdflatex
+% --------------------------------------------------------------------------
+% the EMBRAC package
+% 
+%   Upright Brackets in Emphasized Text
+% 
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web:    https://bitbucket.org/cgnieder/embrac/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2012--2017 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.
+% --------------------------------------------------------------------------
+\documentclass[load-preamble+]{cnltx-doc}
+\usepackage[utf8]{inputenc}
+\usepackage[biblatex]{embrac}
+
+\setcnltx{
+  package = embrac ,
+  authors = Clemens Niederberger ,
+  email   = contact@mychemistry.eu ,
+  url     = https://bitbucket.org/cgnieder/embrac/ ,
+  quote-author-format = ,
+  add-cmds = {
+    AddEmph,
+    ChangeEmph,
+    DeleteEmph,
+    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{New}
+\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.
+\end{description}
+
+\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}
+
+\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\ 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{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}
+
+\end{document}