summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/embrac/embrac_en.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/embrac/embrac_en.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/embrac/embrac_en.tex')
-rw-r--r--macros/latex/contrib/embrac/embrac_en.tex345
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}