lstfiracode (20dec18)

git-svn-id: svn://tug.org/texlive/trunk@49462 c570f23f-e606-0410-a88d-b1316a301751

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
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