summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/lstfiracode
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-17 21:31:58 +0000
committerKarl Berry <karl@freefriends.org>2018-12-17 21:31:58 +0000
commitb3d70195571fd3e8127732f8d3d59f47e2805b8f (patch)
treed1b0ccb78f9f004a8846c9e227428b8b4cf6b40b /Master/texmf-dist/doc/latex/lstfiracode
parent255b2da802e19c1dae20b2d8fd1a050e0616b845 (diff)
lstfiracode (17dec18)
git-svn-id: svn://tug.org/texlive/trunk@49440 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/lstfiracode')
-rw-r--r--Master/texmf-dist/doc/latex/lstfiracode/README.md51
-rw-r--r--Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdfbin0 -> 51400 bytes
-rw-r--r--Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex274
3 files changed, 325 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/lstfiracode/README.md b/Master/texmf-dist/doc/latex/lstfiracode/README.md
new file mode 100644
index 00000000000..19a6a8a161b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/lstfiracode/README.md
@@ -0,0 +1,51 @@
+lstfiracode
+===========
+
+The `lstfiracode` package defines `FiraCodeStyle`, to be used as
+`\lstset{style=FiraCodeStyle}` with the [`listings`](https://ctan.org/pkg/listings)
+package. This style contains almost all ligatures in Nikita Prokopov’s
+[Fira Code](https://github.com/tonsky/FiraCode) family of fonts.
+A new key `moreliterate` to `\lstset` is added, allowing additional user ligatures.
+Additional support for source code listings using Fira Code
+in the `verbatim` environment is available.
+
+This package does NOT provide the Fira Code font files.
+The newest version of the font files can be downloaded at the
+[GitHub Fira Code Releases page](https://github.com/tonsky/FiraCode/releases).
+Here is a sample preamble of a document:
+
+ \documentclass{article}
+ \usepackage{fontspec}
+ \setmonofont{FiraCode-Regular.otf}[Ligatures=Common,Contextuals=Alternate]
+ \usepackage{listings}
+ \usepackage[verbatim]{lstfiracode}
+ \lstset{style=FiraCodeStyle,basicstyle=\ttfamily}
+
+Contributing
+------------
+
+This package is maintained at https://github.com/RuixiZhang42/lstfiracode
+
+Issues and pull requests are welcome.
+
+Copyright and Licence
+---------------------
+
+ Copyright (C) 2018 by Ruixi Zhang <ruixizhang42@gmail.com>
+
+ 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
+ https://www.latex-project.org/lppl.txt
+ and version 1.3c 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 Ruixi Zhang.
+
+ This work consists of the files lstfiracode.sty,
+ lstfiracode.tex,
+ README.md (this file)
+ and the derived file lstfiracode.pdf. \ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf
new file mode 100644
index 00000000000..42a8afc4e59
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..10ea18655ca
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex
@@ -0,0 +1,274 @@
+% !TeX program = XeLaTeX
+% !TeX encoding = UTF-8 Unicode
+%
+\documentclass[11pt]{article}
+\frenchspacing
+\setlength\parskip{1.5pt plus 1pt minus 0.5pt}
+\usepackage{fontspec}
+\setmainfont{TeX Gyre Pagella}
+\linespread{1.05}\selectfont
+\setsansfont{TeX Gyre Heros}[
+ Scale=MatchLowercase
+]
+\setmonofont{Fira Code}[
+ Scale=MatchLowercase,
+ Ligatures=Common,
+ Contextuals=Alternate
+]
+\newfontfamily\LMMono{Latin Modern Mono}[
+ Scale=MatchLowercase
+]
+\usepackage{microtype}
+\usepackage{xcolor}
+
+\usepackage{listings}
+\usepackage[verbatim]{lstfiracode}
+\lstset{
+ language=C++,
+ style=FiraCodeStyle,
+ basicstyle=\small\ttfamily,
+ commentstyle=\color{orange}
+}
+\makeatletter
+\lstnewenvironment{LaTeXlisting}{%
+ \DeactivateVerbatimLigatures
+ \lst@CCPutMacro
+ \lst@ProcessOther {"2D}{\lst@ttfamily{-{}}{-{}}}
+ \@empty\z@\@empty
+ \lstset{
+ style={},
+ literate={},
+ language=[LaTeX]{TeX},
+ basicstyle=\small\LMMono,
+ basewidth=0.525em,
+ commentstyle=\itshape
+ }%
+}{}
+\makeatother
+
+\usepackage{booktabs}
+\usepackage{hyperref}
+\hypersetup{
+ colorlinks=true
+}
+\usepackage{geometry}
+\geometry{
+ width=5.7in
+}
+
+\newcommand*\myemail{ruixizhang42@gmail.com}
+\newcommand*\dash{}
+\DeclareRobustCommand\dash{%
+ \unskip\nobreak\thinspace\textemdash\thinspace\ignorespaces
+}
+\title{The \texttt{lstfiracode} package}
+\author{Ruixi~Zhang\thanks{\href{mailto:\myemail}{\nolinkurl{\myemail}}.}}
+\date{2018/12/16\enskip v0.1a}
+
+\begin{document}
+
+\maketitle
+
+\microtypesetup{protrusion=false}
+\tableofcontents
+\microtypesetup{protrusion=true}
+
+\section{Introduction}
+
+The Fira Code\footnote{See \url{https://github.com/tonsky/FiraCode}.} family
+of fonts, created by Nikita Prokopov, is a monospaced typeface with
+programming ligatures.
+It is attempting for many people, me included, to use Fira Code for source
+code listings.
+However, the \verb|lstlisting| environment from the \verb|listings| package
+does not support ligatures naively. To produce the desired output, one must
+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|
+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|,
+to support source code listings using Fira Code
+in the \verb|verbatim| environment.
+
+This package does \emph{not} provide the Fira Code font files.
+The newest version of the fonts can be downloaded at
+\url{https://github.com/tonsky/FiraCode/releases}.
+
+\section{Usage}
+
+To access \verb|FiraCodeStyle|, simply load \verb|lstfiracode| \emph{after}
+\verb|listings|. Here is how you may setup your document:
+\begin{LaTeXlisting}
+ \documentclass{article}
+ \usepackage{fontspec}
+ \setmonofont{FiraCode-Regular.otf}[
+ BoldFont=FiraCode-Bold.otf,
+ Ligatures=Common, % Enable the liga feature
+ Contextuals=Alternate % Enable the calt feature
+ ]
+ \usepackage{xcolor}
+ \usepackage{listings}
+ \usepackage[verbatim]{lstfiracode} % Enable ligatures in verbatim
+ \lstset{
+ language=C++,
+ style=FiraCodeStyle, % Use predefined FiraCodeStyle
+ basicstyle=\ttfamily, % Use \ttfamily for source code listings
+ commentstyle=\color{orange}
+ }
+ \begin{document}
+ \begin{verbatim}
+ A<-www>>=B
+ \end{verbatim}
+ \begin{lstlisting}
+ /* A simple C++ program */
+ int main() {
+ cout << "Hello World"; // prints Hello World
+ return 0;
+ }
+ \end{lstlisting}
+ \end{document}
+\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
+and the following \verb|lstlisting| (observe the {\LMMono++}
+and the {\LMMono<<} ligatures):
+\begin{lstlisting}
+ /* A simple C++ program */
+ int main() {
+ cout << "Hello World"; // prints Hello World
+ return 0;
+ }
+\end{lstlisting}
+
+\section{Package features}
+
+\subsection{Package option and user commands}
+
+The \verb|lstfiracode| package provides one package option and two 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.
+\begin{LaTeXlisting}
+ % Enable Fira Code ligatures support 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.
+\begin{LaTeXlisting}
+ % Leave verbatim unaltered
+ \usepackage{lstfiracode}
+ % is the same as
+ \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:
+\begin{description}
+\item[\texttt{\textbackslash ActivateVerbatimLigatures}]
+enables Fira Code ligatures support in \verb|verbatim|.
+\item[\texttt{\textbackslash DeactivateVerbatimLigatures}]
+leaves the handling of \verb|verbatim| unaltered.
+\end{description}
+These two switches act \emph{locally}.
+
+\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
+\begin{LaTeXlisting}
+ \lstdefinestyle{FiraCodeStyle}{
+ basewidth=0.6em,
+ literate=
+ {www}{{www}}3
+ ... % All other necessary ligatures in Fira Code
+ }
+\end{LaTeXlisting}
+Thus, the \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|.
+\begin{LaTeXlisting}
+ \usepackage{listings}
+ \usepackage{lstfiracode}
+ % Assume that you have set Fira Code via \setmonofont
+ % Then don't forget 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:
+\begin{center}
+\LMMono
+\begin{tabular}{p{2.1em} p{2.1em} p{2.1em}}
+\toprule
+\multicolumn{3}{c}{\rmfamily ``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.
+
+Nevertheless, you can still \emph{append} these ligatures to the
+\verb|FiraCodeStyle| literate list.
+\emph{You cannot write}
+{\LMMono\textbackslash lstset\{style=FiraCodeStyle,%
+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:
+\begin{LaTeXlisting}
+ % Let's add more ligatures
+ \lstset{
+ language=C++,
+ style=FiraCodeStyle,
+ basicstyle=\ttfamily,
+ moreliterate=
+ {;;}{{;;}}2
+ {;;;}{{;;;}}3
+ }
+\end{LaTeXlisting}
+
+\section{Troubleshooting}
+
+The \verb|lstfiracode| package is maintained at GitHub. Please make each
+bug report with a \emph{minimal example} at
+\url{https://github.com/RuixiZhang42/lstfiracode/issues}.
+Pull requests are welcome.
+
+\end{document} \ No newline at end of file