From ec4f77d5218a6cd250b3e8ba4b368f6d3ba813e8 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 15 Mar 2021 22:02:45 +0000 Subject: highlightlatex (15mar21) git-svn-id: svn://tug.org/texlive/trunk@58392 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/highlightlatex/LICENSE.txt | 21 ++ .../texmf-dist/doc/latex/highlightlatex/README.md | 267 +++++++++++++++++++++ .../latex/highlightlatex/highlightlatex-manual.pdf | Bin 0 -> 231500 bytes 3 files changed, 288 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/highlightlatex/LICENSE.txt create mode 100644 Master/texmf-dist/doc/latex/highlightlatex/README.md create mode 100644 Master/texmf-dist/doc/latex/highlightlatex/highlightlatex-manual.pdf (limited to 'Master/texmf-dist/doc/latex/highlightlatex') diff --git a/Master/texmf-dist/doc/latex/highlightlatex/LICENSE.txt b/Master/texmf-dist/doc/latex/highlightlatex/LICENSE.txt new file mode 100644 index 00000000000..74e1b58f1b6 --- /dev/null +++ b/Master/texmf-dist/doc/latex/highlightlatex/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2021 Vincent Kuhlmann + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/Master/texmf-dist/doc/latex/highlightlatex/README.md b/Master/texmf-dist/doc/latex/highlightlatex/README.md new file mode 100644 index 00000000000..e6d0e6f2a12 --- /dev/null +++ b/Master/texmf-dist/doc/latex/highlightlatex/README.md @@ -0,0 +1,267 @@ +# Highlight LaTeX: Pretty LaTeX code within LaTeX + +Teaching other people LaTeX is great fun, and I've seen plenty of slides and +readers doing so. You show what you achieve, and how you achieve it. However, +while the LaTeX you achieve might look splendid, showing code is often done +using very rudimentary solutions (like plain old verbatim). + +They're not to blame: I didn't find pretty colored LaTeX highlighting either. I +sure want it, and if you're reading this, you probably too, so I've made a +package for it! It builds further on the generic `listings` package to provide +colored highlighting for LaTeX. The file `demo.tex` achieves this: + + + +## Manual installation + +1. Download the `.sty` file, e.g. +[right click here and select 'save as'](https://github.com/vkuhlmann/highlight-latex/raw/main/highlightlatex.sty). +2. Copy the file to the directory where your `.tex` file is at... +3. ... or make it available for all your `.tex` files by placing the file in + your TEXMF root. + + **Locating TEXTMF root** + + Note the following default locations: + + MiKTeX on Windows: + global installation: C:\Program Files\MiKTeX\tex\latex + local installation: %AppData%\..\Local\Programs\MiKTeX\tex\latex + + TeX Live on Linux or Mac: + /usr/share/texmf-texlive/tex/latex + /usr/local/texlive/texmf-local/tex/latex + + On Windows you can open a path by pasting the address in the Windows Explorer + address bar, or pressing Start+R and pasting the + address there. One of these directories should contain a long list of + packages you have installed. If you can't it, and you use MiKTeX, open MiKTeX + Console and open the directories listed under `Settings > Directories` with + `Purpose` set to `Install`. Doesn't it exist? Append a `tex` or `latex` + directory to the path. + + **Adding the package** + + Add a new directory called `highlightlatex` and place the `.sty` file in it. + Then refresh the file name database: + * For MiKTeX on Windows open MiKTeX Console and execute `Tasks > Refresh file + name database`. + * For TeX Live on Linux or Mac, execute in a terminal `sudo texhash`. +4. Add `\usepackage{highlightlatex}` to your `.tex` file. +5. For usage of this package, consult the demo files, or read the + documentation below. + +## Getting started + +After having added the package, you can add LaTeX in two ways: +* Inline style: + + Your file begins with a line of the form \hll|\documentclass[]{}|. The + square brackets ... + + The first non-space character following `\hll` is delimits the argument to + this command. + +* Block style: + + Your basic document now looks like + \begin{highlightblock}[gobble=2] + \documentclass[a4paper]{article} + \begin{document} + Hello world! + \end{document} + \end{highlightblock} + + To prevent indentation of our `highlightblock` (here one tab), to be shown as + part of the code, the `gobble` parameters strips them off. Play around with + it until everything looks right. I recommend to set this value globally using + `\def\defaultgobble{2}`. You can still override that, if necessary. + + There are situations where width of the block could run out of the page. For + example, when using beamer and storing a block as described in the section + 'Fragile breaking situations', the normal full-width of a slide is assumed. + If you use multiple columns, set the `linewidth` on the `highlightblock`. + This can be a fraction of the total slide width available, `0.6\textwidth` + is 60% of the width, or an absolute value, like `10em`, which seems to equal + 20 characters. + + There are more keys you can provide. Check the + [listings package documentation](https://www.ctan.org/pkg/listings) for + options available to the `lstlisting`-environment and `lstset` command. + +## Adding a command to a highlighting rule + +By default, only some LaTeX commands will be highlighted in blue. If there are +others you need, like `\tableofcontents` and `\figref`, update the highlighting +rules: +``` +\updatehighlight{ + name = default, + add = { + \tableofcontents, \figref + } +} +``` + +The changes will affect only code after it. For a use as this example, I +recommend putting it in your preamble (before the `\begin{document}`). + +## Custom highlighting rules + +As shown `demo.tex`, you can put any command or keyword you want to highlight on +in a different color. You do this with +``` +\updatehighlight{ + % A name like 'focus' or 'orange' would be more descriptive, + % this is just to show you can make up the name yourself. + name = orangejuice, + color = orange + add = { + \tableofcontents + } +} +``` + +You can use the `xcolor` syntax for describing colors as well. If you find the +orange too bright, you can replace it with `orange!90!black`: 90% orange, +remaining is black. For more information on color definitions and name, refer to +[LaTeX/Colors on Wikibooks](https://en.wikibooks.org/wiki/LaTeX/Colors). + +--- + +The argument to `\updatehighlight` is a key-value list. Keys are processed +sequentially. For example, use `color` before rather than after the `add`, and +a key can appear multiple times. Each one will be processed. You can merge any +two `\updatehighlight` in one. No need to close and reopen `\updatehighlight` +for each highlighting rule. + +You might be tempted to add a blank line for clarity; that means a new paragraph +too LaTeX, don't do it. Instead, just put a line with only a `%` sign. Spacing +within the argument is often irrelevant. If you need a comma in the value, +surround your value with braces. + +The possible keys are: +* **name**: Create or modify a named rule. This key is optional. + + The default keys are `default`, which includes a bunch of basic commands, + and has by default a dark blue color, and `structure`, which consists of + `\begin` and `\end` and prints them in light blue. + + _Deprecated alias: label_ + +* **classoffset**: Set the `listings` classoffset manually. Try to avoid this. + Use **name** to refer to existing rules instead. + +* **add**: Add a commands (`\mycommand`) oor keywords (`Hi!`) to the current + rule. The value can contain multiple values by opening braces, and comma + separating values within them. + + _Deprecated aliases: macros (only for commands), commands (only for commands), + and keywords (only for keywords)_ + +* **remove**: Remove a commands or keywords from the current rule. The value can + contain multiple values by opening braces, and comma separating values within + them. + +* **clear**: Remove all commands and keywords from the current rule. Use without + value, for example + + \updatehighlight{ + name = default, + clear + } + +* **color**: Specify a color for the rule. Equivalent to specifying **style** + instead, with value `\color{value}` where `value` is the value for the + **color** key. So `color=red` and `style=\color{red}` are equivalent. + +* **style**: Specify a style for the rule. A rule can only have one style. If + you specify a style after `add`, `remove`, `keywords` (deprecated), `macros` + (deprecated) or `commands` (deprecated), this starts a new (unnamed) rule. + In practice, the only style which will probably work for you is only a color, + so just use it instead. But hey, you have the option if you want to. :) + +## Global settings +There are some global parameters involved in the appearance: +``` +\colorlet{curlyBrackets}{red!50!blue} +\colorlet{squareBrackets}{blue!50!white} +\colorlet{codeBackground}{gray!10!white} +\colorlet{comment}{green!40!black} +\def\defaultgobble{0} +``` + +Each line can be set independent of eachother, and each shows its default value. + +There are package options you can use as well: +* **frame** (default `lines`): specify the frame you want around code. My + favorites are `lines` and `none`. Check the + [listings package documentation](https://www.ctan.org/pkg/listings) for all + possibilities. + +* **noframe** (use without value): equivalent to `frame=none`. + +* **styleanywhere** (use without value): override the default behavior that + `style` starts a new style after commands like `add` and `remove`. + +## Fragile breaking situations (like beamer frames) + +When passing command arguments around, or storing environment content, LaTeX +interprets all characters. This includes seeing `\maketitle` in `\hll|\maketitle|` +as a real command. To prevent this behavior, everything from `\verb`, to the +`verbatim`-environment, to the `listings` package the highlight LaTeX package +uses temporarily changes the interpretation of characters that are still to be +read. The blackslash before maketitle in `\hll|\maketitle|` will be read as +`just text' (a _letter_ technically). + +When content has already been interpreted, like the `frame`-environment in +`beamer` does, this trick can't be done anymore. Instead, you either need to +_escape_ code, or _pre-process_ the code outside a fragile breaking situation. + +Escaping is done by preceding the special character with a backslash. For +example, `\hll|\documentclass[]{}|` becomes `\hll|\\documentclass[]\{\}|`. + +For large code blocks, this is undesirable. Therefore, the package provides for +a companion to the `highlightblock`-environment: surround it with a `saveblock` +environment which takes a single argument: a name to assign it. We use it to +refer to it later. For example: +```latex +\begin{saveblock}{basicfigure} + \begin{highlightblock}[linewidth=0.6\textwidth] + \begin{figure} + \includegraphics + [width=0.9\linewidth] + {myPlot.pdf} + + \caption{My plot} + \label{fig:myplot} + \end{figure} + \end{highlightblock} +\end{saveblock} +``` + +Do this outside a fragile breaking situation. (For the `frame`-environment +example, that means just before the `frame` for example.) Then, where you want +to use it, use `\useblock{basicfigure}`. There is also a variant +`\consumeblock{basicfigure}`. If you save many blocks, these will all remain +loaded in memory till your PDF has fully generated. The `\consumeblock` works +like `\useblock`, except the saved block is deleted from memory after its use. +Note this can also result in unexpected behavior, for example animations in a +beamer frame might need the code line to be executed multiple times. Use +`\useblock` when you can't make the guarantee this is the last use. + +For this special, but very important, situation, I've created a separate demo, +which you find at `deamerdemo/deamerdemo.tex`. + +## Adding extra space + +By default, highlight-latex follows an approach where it minimizes spacing. +This gives you full control over how tight or spacious your document looks. +Just use commands like `\medskip` to add extra spacing. The package doesn't +currently include an option to have that done everywhere automatically. + +## License + +The package is available under MIT License. See LICENSE.txt + diff --git a/Master/texmf-dist/doc/latex/highlightlatex/highlightlatex-manual.pdf b/Master/texmf-dist/doc/latex/highlightlatex/highlightlatex-manual.pdf new file mode 100644 index 00000000000..5050bc29c1c Binary files /dev/null and b/Master/texmf-dist/doc/latex/highlightlatex/highlightlatex-manual.pdf differ -- cgit v1.2.3