summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-20 23:33:18 +0000
committerKarl Berry <karl@freefriends.org>2018-12-20 23:33:18 +0000
commit0d829fbbe1e39d04cd4ceef43f58b0a52f4d6e03 (patch)
tree3b85f6997d4fc5978aff400e99d169a8add93e80 /Master/texmf-dist/doc/latex
parentabaa7495cdb0085d22d3b04bb5a1f19bdd132fd9 (diff)
lstfiracode (20dec18)
git-svn-id: svn://tug.org/texlive/trunk@49462 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r--Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdfbin51400 -> 53414 bytes
-rw-r--r--Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex155
2 files changed, 103 insertions, 52 deletions
diff --git a/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf
index 42a8afc4e59..dc1e9d741df 100644
--- a/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf
+++ b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex
index 10ea18655ca..df5f81d7e9b 100644
--- a/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex
+++ b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex
@@ -26,19 +26,19 @@
\lstset{
language=C++,
style=FiraCodeStyle,
- basicstyle=\small\ttfamily,
+ basicstyle=\ttfamily,
commentstyle=\color{orange}
}
\makeatletter
\lstnewenvironment{LaTeXlisting}{%
- \DeactivateVerbatimLigatures
+ \RestoreVerbatimBehavior
\lst@CCPutMacro
\lst@ProcessOther {"2D}{\lst@ttfamily{-{}}{-{}}}
\@empty\z@\@empty
\lstset{
style={},
literate={},
- language=[LaTeX]{TeX},
+ language=[LaTeX]TeX,
basicstyle=\small\LMMono,
basewidth=0.525em,
commentstyle=\itshape
@@ -61,9 +61,13 @@
\DeclareRobustCommand\dash{%
\unskip\nobreak\thinspace\textemdash\thinspace\ignorespaces
}
+\newcommand\versionhistory[3]{%
+ % #1: version number, #2: date, #3: description
+ \item[#1]#3\hfill#2%
+}
\title{The \texttt{lstfiracode} package}
\author{Ruixi~Zhang\thanks{\href{mailto:\myemail}{\nolinkurl{\myemail}}.}}
-\date{2018/12/16\enskip v0.1a}
+\date{2018/12/20\enskip v0.1b}
\begin{document}
@@ -86,15 +90,16 @@ specify all necessary ligatures via the \verb|literate| key
of \verb|\lstset|, which can be tedious.
The \verb|lstfiracode| package defines a ready-to-use \verb|listings| style,
-\verb|FiraCodeStyle|, which pre-specifies 137 ligatures
-(note that Fira Code v1.206 has 146 ligatures in total).
-You may \emph{append} the 9 remaining ligatures to the \verb|FiraCodeStyle|
+\verb|FiraCodeStyle|, which pre-specifies 125 ligatures
+(note that Fira Code v1.206 has 130 ligatures in total).
+You may \emph{append} the remaining 5 ligatures to the \verb|FiraCodeStyle|
literate list via a new key \verb|moreliterate|, without unintentionally
erasing all existing ligatures via \verb|literate|.
The \verb|lstfiracode| package also provides a package option,
-\verb|verbatim|, along with two switches,
-\verb|\ActivateVerbatimLigatures| and \verb|\DeactivateVerbatimLigatures|,
+\verb|verbatim|, along with three switches
+\verb|\ActivateVerbatimLigatures|, \verb|\DeactivateVerbatimLigatures|
+and \verb|\RestoreVerbatimBehavior|
to support source code listings using Fira Code
in the \verb|verbatim| environment.
@@ -111,12 +116,12 @@ To access \verb|FiraCodeStyle|, simply load \verb|lstfiracode| \emph{after}
\usepackage{fontspec}
\setmonofont{FiraCode-Regular.otf}[
BoldFont=FiraCode-Bold.otf,
- Ligatures=Common, % Enable the liga feature
- Contextuals=Alternate % Enable the calt feature
+ Ligatures=Common, % Activate the liga feature
+ Contextuals=Alternate % Activate the calt feature
]
\usepackage{xcolor}
\usepackage{listings}
- \usepackage[verbatim]{lstfiracode} % Enable ligatures in verbatim
+ \usepackage[verbatim]{lstfiracode} % Activate ligatures in verbatim
\lstset{
language=C++,
style=FiraCodeStyle, % Use predefined FiraCodeStyle
@@ -138,13 +143,9 @@ To access \verb|FiraCodeStyle|, simply load \verb|lstfiracode| \emph{after}
\end{LaTeXlisting}
which produces the following \verb|verbatim| (observe the {\LMMono<-},
the {\LMMono www} and the {\LMMono>>=} ligatures):
-\begingroup
-\fontsize{10}{12}\selectfont
\begin{verbatim}
A<-www>>=B
-\end{verbatim}%
-\endgroup
-\noindent
+\end{verbatim}
and the following \verb|lstlisting| (observe the {\LMMono++}
and the {\LMMono<<} ligatures):
\begin{lstlisting}
@@ -159,21 +160,21 @@ and the {\LMMono<<} ligatures):
\subsection{Package option and user commands}
-The \verb|lstfiracode| package provides one package option and two user
+The \verb|lstfiracode| package provides one package option and three user
commands, described below.
-You may load the \verb|lstfiracode| package with the option \verb|verbatim|
-or, equivalently, \verb|verbatim=true|. This enables the support to use
-Fira Code ligatures in the \verb|verbatim| environment.
+You may load the \verb|lstfiracode| package with the option \verb|verbatim|,
+or equivalently \verb|verbatim=true|. This activates all Fira Code ligatures
+in the \verb|verbatim| environment.
\begin{LaTeXlisting}
- % Enable Fira Code ligatures support in verbatim
+ % Activate Fira Code ligatures in verbatim
\usepackage[verbatim]{lstfiracode}
% is the same as
\usepackage[verbatim=true]{lstfiracode}
\end{LaTeXlisting}
-Loading the package without any option (the default) or, equivalently, with
-the option \verb|verbatim=false| leaves the handling of the \verb|verbatim|
-environment unaltered.
+Loading the package without any option (the default), or equivalently with
+the option \verb|verbatim=false|, \emph{does not alter} how the
+\verb|verbatim| environment is handled.
\begin{LaTeXlisting}
% Leave verbatim unaltered
\usepackage{lstfiracode}
@@ -181,23 +182,58 @@ environment unaltered.
\usepackage[verbatim=false]{lstfiracode}
\end{LaTeXlisting}
-You may change your mind in the middle of your document, so there are two
-switches for such purpose:
+You may change your mind in the middle of your document, so there are
+three switches for such purpose:
\begin{description}
\item[\texttt{\textbackslash ActivateVerbatimLigatures}]
-enables Fira Code ligatures support in \verb|verbatim|.
+Activate all Fira Code ligatures in \verb|verbatim|. This is executed
+automatically with the package option \verb|verbatim=true|.
\item[\texttt{\textbackslash DeactivateVerbatimLigatures}]
-leaves the handling of \verb|verbatim| unaltered.
+Suppress \emph{almost all} Fira Code ligatures in \verb|verbatim|.
+Currently, it cannot break the {\LMMono\#\{} and the {\LMMono|\}} ligatures.
+\item[\texttt{\textbackslash RestoreVerbatimBehavior}]
+Restore how \verb|verbatim| is originally handled by \LaTeX.
\end{description}
-These two switches act \emph{locally}.
+These switches can overwrite each other and they act \emph{locally}.
+For instance, the following three \verb|verbatim| environments
+\begin{LaTeXlisting}
+ \begingroup
+ \ActivateVerbatimLigatures
+ \begin{verbatim}
+ A<-www>>=B % Fira Code ligatures activated
+ \end{verbatim}
+ \DeactivateVerbatimLigatures
+ \begin{verbatim}
+ A<-www>>=B % Fira Code ligatures deactivated
+ \end{verbatim}
+ \RestoreVerbatimBehavior
+ \begin{verbatim}
+ A<-www>>=B % Hmm...
+ \end{verbatim}
+ \endgroup
+\end{LaTeXlisting}
+produce, respectively,
+\begingroup
+\ActivateVerbatimLigatures
+\begin{verbatim}
+ A<-www>>=B % Fira Code ligatures activated
+\end{verbatim}
+\DeactivateVerbatimLigatures
+\begin{verbatim}
+ A<-www>>=B % Fira Code ligatures deactivated
+\end{verbatim}
+\RestoreVerbatimBehavior
+\begin{verbatim}
+ A<-www>>=B % Hmm...
+\end{verbatim}
+\endgroup
\subsection{The \texttt{FiraCodeStyle} listings style}
The ligatures of Fira Code are treated as literate programming by the
\verb|lstfiracode| package. These ligatures are specified via the
\verb|literate| key in defining \verb|FiraCodeStyle|.
-
-The definition of \verb|FiraCodeStyle| looks like this
+The definition of \verb|FiraCodeStyle| looks like this:
\begin{LaTeXlisting}
\lstdefinestyle{FiraCodeStyle}{
basewidth=0.6em,
@@ -206,52 +242,52 @@ The definition of \verb|FiraCodeStyle| looks like this
... % All other necessary ligatures in Fira Code
}
\end{LaTeXlisting}
-Thus, the \verb|FiraCodeStyle| specifies \verb|basewidth| explicitly and
-lists \emph{almost} all literate replacements.
+
+Thus, \verb|FiraCodeStyle| specifies \verb|basewidth| explicitly and
+lists \emph{almost all} literate replacements.
\emph{It does not contain any font changing commands because users may load
Fira Code according to their preferences.}
In the case that \verb|\ttfamily| corresponds to Fira Code,
-be sure to specify \verb|basicstyle=\ttfamily| in addition to
-\verb|style=FiraCodeStyle|.
+be sure to specify \verb|basicstyle=\ttfamily| \emph{in addition to}
+\verb|style=FiraCodeStyle|, i.e.,
\begin{LaTeXlisting}
\usepackage{listings}
\usepackage{lstfiracode}
% Assume that you have set Fira Code via \setmonofont
- % Then don't forget to also specify basicstyle
+ % Then remember to also specify basicstyle
\lstset{style=FiraCodeStyle,basicstyle=\ttfamily}
\end{LaTeXlisting}
\subsection{The missing ligatures and the new key \texttt{moreliterate}}
You may notice that some ligatures in Fira Code are still missing. Well,
-there are 9 such ligatures\dash strictly speaking, they \emph{are} listed
-as literate replacements in the definition of \verb|FiraCodeStyle|, but are
-simply commented out:
+there are 5 such ligatures\dash strictly speaking, they \emph{are} listed
+as literate replacements in the definition of \verb|FiraCodeStyle|,
+but are simply commented out:
\begin{center}
\LMMono
-\begin{tabular}{p{2.1em} p{2.1em} p{2.1em}}
+\begin{tabular}{c c c c c}
\toprule
-\multicolumn{3}{c}{\rmfamily ``Missing'' ligatures} \\
+\multicolumn{5}{c}{\rmfamily The ``missing'' ligatures} \\
\midrule
- /* & \{- & -\} \\
- /** & ;; & ;;; \\
-{}*/ & // & /// \\
+/* & */ & // & /// & ;; \\
\bottomrule
\end{tabular}
\end{center}
These particular combinations of characters usually indicate comment mode.
If they were to be implemented as literate replacements, they would break
-how the \verb|listings| package handles syntax highlighting.
+how the \verb|listings| package handles comment highlighting.
Nevertheless, you can still \emph{append} these ligatures to the
\verb|FiraCodeStyle| literate list.
-\emph{You cannot write}
+Say, you want to activate the {\LMMono;;} ligature in your
+{\LMMono C++} code. \emph{But you cannot simply write}
{\LMMono\textbackslash lstset\{style=FiraCodeStyle,%
-literate=\{/*\}\{\{/*\}\}2\}}
+literate=\{;;\}\{\{;;\}\}2\}}
\emph{because this will erase all predefined ligatures, leaving only the}
-{\LMMono/*} \emph{ligature}.
-Instead, the \verb|lstfiracode| package provides a new key\dash
-\verb|moreliterate|\dash for this purpose:
+{\LMMono;;} \emph{ligature}.
+Instead, you should use the new key\dash
+\verb|moreliterate|\dash to add more literate replacements:
\begin{LaTeXlisting}
% Let's add more ligatures
\lstset{
@@ -260,7 +296,7 @@ Instead, the \verb|lstfiracode| package provides a new key\dash
basicstyle=\ttfamily,
moreliterate=
{;;}{{;;}}2
- {;;;}{{;;;}}3
+ {///}{{///}}3
}
\end{LaTeXlisting}
@@ -271,4 +307,19 @@ bug report with a \emph{minimal example} at
\url{https://github.com/RuixiZhang42/lstfiracode/issues}.
Pull requests are welcome.
+\section*{Version history}
+
+\begin{description}
+\versionhistory{v0.1b}{2018/12/20}{%
+ Updated \texttt{FiraCodeStyle} literate list.
+ Added \texttt{\textbackslash RestoreVerbatimBehavior}.
+ Re-implemented
+ \texttt{\textbackslash Activate}/%
+ \texttt{\textbackslash DeactivateVerbatimLigatures}.%
+}
+\versionhistory{v0.1a}{2018/12/16}{%
+ Initial release.%
+}
+\end{description}
+
\end{document} \ No newline at end of file