From b3d70195571fd3e8127732f8d3d59f47e2805b8f Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 17 Dec 2018 21:31:58 +0000 Subject: lstfiracode (17dec18) git-svn-id: svn://tug.org/texlive/trunk@49440 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/lstfiracode/README.md | 51 ++++ .../doc/latex/lstfiracode/lstfiracode.pdf | Bin 0 -> 51400 bytes .../doc/latex/lstfiracode/lstfiracode.tex | 274 +++++++++++++++++++++ 3 files changed, 325 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/lstfiracode/README.md create mode 100644 Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf create mode 100644 Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.tex (limited to 'Master/texmf-dist/doc/latex') 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 + + 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/lstfiracode/lstfiracode.pdf 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 -- cgit v1.2.3