highlightlatex (15mar21)

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

3 files changed, 288 insertions, 0 deletions

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:
+
+<img src="assets/demoshowoff.png" width="600"
+alt="highlight demo" title="Highlight demo">
+
+## 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 <kbd>Start</kbd>+<kbd>R</kbd> 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
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/highlightlatex/highlightlatex-manual.pdf