highlightlatex_doc.tex

\documentclass{ltxdoc}

\usepackage[margin=2.54cm]{geometry}
\usepackage{graphicx}
\usepackage{parskip}
\usepackage{listings}
\usepackage{adjustbox}
\usepackage{soul}
\usepackage{hyperref}
\usepackage{xcolor}

\expandafter\newif\csname ifuseownpackage\endcsname
\useownpackagetrue

\ifuseownpackage
    \usepackage{highlightlatex}
    \updatehighlight{
    	name = default,
    	add = {
    		\defaultgobble, \colorlet, \includegraphics, \maketitle, \mycommand,
			\tableofcontents, \figref, \color
	    },
		%
    	name = hll,
    	color = orange!90!black,
    	add = {
    		\hll, highlightblock
    	},
		%
    	name = hllOth,
    	color = red!90!black,
    	add = {
    		\useblock, \consumeblock, \updatehighlight, saveblock
    	},
		% 	
    	name = vert,
    	color = red,
    	add = {
    		|
	    }
	}   
\else
    \let\hll\lstinline
    \lstnewenvironment{highlightblock}[1][]
    {%
        \lstset{#1}%
    }{}%
    \lstset{tabsize=2,escapeinside=~~}
\fi

\newcommand\fhref[2]{%
	\href{#1}{#2}\;\footnote{\,\url{#1}}\,%
}

\newlength\centerlabelledwidth
\newlength\centerlabelledminleft
\def\centerlabelledlabel{}
\setlength\centerlabelledminleft{5em}
\expandafter\newif\csname ifshowcasecenter\endcsname

\makeatletter
\define@key{centerlabelled}{label}{%
	\def\centerlabelledlabel{#1}%
}

\define@key{centerlabelled}{width}{%
	\setlength\centerlabelledwidth{\dimexpr #1\relax}%
}

\define@key{centerlabelled}{frac}{%
	\setlength\centerlabelledwidth{\dimexpr #1\textwidth\relax}%
}

\define@key{centerlabelled}{left}[]{%
	\showcasecenterfalse
}

\define@key{centerlabelled}{center}[]{%
	\showcasecentertrue
}

\define@key{centerlabelled}{minleft}{%
	\setlength\centerlabelledminleft{#1}%
}
\makeatother

\newlength\showcaseleft

\newenvironment{centerlabelled}[1][]{%
	\setlength\centerlabelledwidth{\linewidth}%
	\setkeys{centerlabelled}{#1}%
	\setlength\showcaseleft{\dimexpr(\linewidth-\centerlabelledwidth)/2\relax}%
	\ifshowcasecenter
		\ifdim\centerlabelledminleft>\showcaseleft\relax
			\showcasecenterfalse
		\fi
	\fi
	%
	\unless\ifshowcasecenter
		\setlength\showcaseleft\centerlabelledminleft
		\ifdim\dimexpr\textwidth-\centerlabelledminleft\relax<\centerlabelledwidth\relax
			\setlength\centerlabelledwidth{\dimexpr\linewidth-\centerlabelledminleft\relax}%
		\fi
	\fi
	%
	\par\penalty 10000%
	\hspace{\showcaseleft}%
	\adjustbox{raise=-6pt,lap=-\width-1em}{\setulcolor{red}%
	\expandafter\ul\expandafter{\expandafter\textsc\expandafter{\centerlabelledlabel}}}%
	\begin{minipage}[t]{\centerlabelledwidth}%
	\lstset{framexleftmargin=0.25em}%
}{%
	\end{minipage}\par%
}

\newenvironment{showcase}{%
	\begin{centerlabelled}%
}
{%
	\end{centerlabelled}
}

\def\sectionautorefname{Section}
\def\subsectionautorefname{Subsection}

\begin{document}

\newbox\cmdintitle
\setbox\cmdintitle=\hbox{\hll|highlightlatex|}
\setbox\cmdintitle=\hbox{\adjustbox{height=2.0\height}{\usebox\cmdintitle}}
\def\defaultgobble{8}

\title{Package \usebox\cmdintitle{} manual}
\author{
	Vincent Kuhlmann\\
	\texttt{vincent.kuhlmann@hotmail.com}
}


\maketitle
\begin{abstract}
	This package provides colored syntax highlighting for \LaTeX{} source code, without aid from
	outside \LaTeX. This is in response to the general trend that people often fall back to verbatim
	for displaying code. This package aims to make typesetting good looking \LaTeX{} source code accessible.
	For this, it builds further on the generic `listings' package. An example output is
	shown in \autoref{fig:demoOutput}\,.
\end{abstract}

\bigskip

\begin{center}
	{\small\textbf{Repository}}

	\url{https://github.com/vkuhlmann/highlight-latex}
\end{center}

\vspace{5\baselineskip}

\begin{figure}[htbp]
	\centering
	\rule{2cm}{1pt}

	\bigskip
	\includegraphics[width=\textwidth,trim=1cm 1cm 1cm 1cm, clip]{demo.pdf}
	\caption{Output of `demo.tex'.}\label{fig:demoOutput}
	\bigskip
	\rule{2cm}{1pt}
\end{figure}

\vfil

\pagebreak
\tableofcontents
\pagebreak

\section{Getting started}

After having added the package, you can add LaTeX in two ways.

\subsection{Inline style}

\begin{showcase}[label=example]
	\begin{highlightblock}
		Your file begins with a line of the form \hll~{}~|\documentclass[]{}|. The
		square brackets ...
	\end{highlightblock}
\end{showcase}

The first non-space character following \lstinline|\hll| delimits the argument to
this command.

\subsection{Block style}


\begin{showcase}[label=example]
	\begin{highlightblock}
		Your basic document now looks like
		\begin{highlightblock}[gobble=4]
			\documentclass[a4paper]{article}
			
			\begin{document}
				Hello world!
			\end{document}
		\end{~{}~highlightblock}
	\end{highlightblock}
\end{showcase}

To prevent indentation of our \hll|highlightblock| (here one tab) to be shown as part of the code,
the \hll|gobble| parameter strips them off. Play around with it until everything looks right. I
recommend to set this value globally using \hll|\def\defaultgobble{2}|. You can still override it on
a per-block basis, if necessary.

There are situations the block could run out of the page, for example you need to save the block for use in a beamer document (see \autoref{sec:frag}). In that case, the normal full-width of a slide is assumed, but you might want to use it in a slide with multiple columns. Set the \hll|linewidth| on the
\hll|highlightblock|. This can be a fraction of the total slide width available, \hll|0.6\textwidth|
is 60\% of the width, or an absolute value, like \hll|10em|, which seems to equal 20 characters.

There are more keys you can provide. Check the
\fhref{https://www.ctan.org/pkg/listings}{\hll|listings| package
	documentation} for options
available to the \hll|lstlisting|-environment and \hll|lstset| command.

\newbox\uphbox
\setbox\uphbox=\hbox{\hll|\updatehighlight|}
\setbox\uphbox=\hbox{\adjustbox{height=1.4\height}{\usebox\uphbox}}

\section[Macro \textbackslash updatehighlight]{\ignorespaces
  Macro \texorpdfstring{\usebox\uphbox}{\textbackslash updatehighlight}}
\subsection{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
\hll|\tableofcontents| and \hll|\figref|, update the highlighting rules:
\begin{showcase}[label=use]
	\begin{highlightblock}
		\updatehighlight{
			name = default,
			add = {
				\tableofcontents, \figref
			}
		}
	\end{highlightblock}
\end{showcase}

The change will only affect code after it. I recommend issuing \hll|updatehighlight| in your
preamble (before the \hll|\begin{document}|). In some situations you might want to change things
mid-document. That's possible too.

\subsection{Custom highlighting rules}
\subsubsection{Example}

As shown in \hll|demo.tex|, you can put any command or keyword you want to highlight in a different
color. You do this with
\begin{showcase}[label=example]
	\begin{highlightblock}
		\updatehighlight{
			% The name allows you to modify the style later.
			name = spotlight,
			color = orange,
			add = {
				\tableofcontents
			}
		}
	\end{highlightblock}
\end{showcase}

You can use the \hll|xcolor| syntax for describing colors as well. If you find the orange too
bright, you can replace it with \hll|orange!90!black|: 90\% orange, remaining is black. For more
information on color definitions and name, refer to
\fhref{https://en.wikibooks.org/wiki/LaTeX/Colors}{LaTeX/Colors on Wikibooks}.


\subsubsection{Specification}

The argument to \hll|\updatehighlight| is a key-value list. Keys are processed sequentially. For
example, use \hll|color| before \hll|add| rather than after it, and a key can appear multiple times.
Each one will be processed. You can merge any two \hll|\updatehighlight| in one. No need to close
and reopen \hll|\updatehighlight| for each highlighting rule.

You might be tempted to add a blank line for clarity; that means a new paragraph to LaTeX, don't do
it. Instead, just put a line with only a \hll|\%| sign. Spacing within the argument is often
irrelevant. If you need a comma in the value, surround your value with braces.

\begin{list}{}{
		\itemindent-\leftmargin
		\setlength{\itemsep}{10pt}
	}
	\item\textbf{name}\par\nobreak

	Creates or modifies a named rule. This key is optional.

	The default keys are \hll|default|, which includes a bunch of basic commands, and has by default
	a dark blue color, and \hll|structure|, which consists of \hll|\begin| and \hll|\end| and prints
	them in light blue.


	\item\textbf{classoffset}\par\nobreak

	Sets the \hll|listings| classoffset manually. Try to avoid this. Use \textbf{name} to refer to
	existing rules instead.


	\item\textbf{add}\par\nobreak

	Adds a command (\hll|\mycommand|) or keyword (\hll|Hi!|) to the current rule. The value can
	contain multiple values by opening braces, and comma separating values within them.


	\item\textbf{remove}\par\nobreak

	Removes a commands or keywords from the current rule. The value
	can contain multiple values by opening braces, and comma separating values
	within them.


	\item\textbf{clear}\par\nobreak

	Removes all commands and keywords from the current rule. Use
	without value, for example
	\begin{showcase}[label=example]
		\begin{highlightblock}[gobble=12]
			\updatehighlight{
				name = default,
				clear
			}
		\end{highlightblock}
	\end{showcase}


	\item\textbf{color}\par\nobreak

	Specifies a color for the rule. Equivalent to specifying \hll|style|
	instead, with value \hll|\color{value}| where \hll|value| is the value for the
	\textbf{color} key. So \hll|color=red| and \hll|style=\color{red}| are equivalent.


	\item\textbf{style}\par\nobreak

	Specifies a style for the rule. A rule can have only one style. If
	you specify a style after \hll|add| or \hll|remove|, this starts a new (unnamed)
	rule. In practice, the only style which will probably work for you is just a
	color. For that, using the `color' key is just a bit easier and neater. But
	hey, you have the option to set whatever style you want. :)

\end{list}

\section{Global settings}

There are some global parameters involved in the appearance:
\begin{showcase}[label=overview]
	\begin{highlightblock}[gobble=8]
		\colorlet{curlyBrackets}{red!50!blue}
		\colorlet{squareBrackets}{blue!50!white}
		\colorlet{codeBackground}{gray!10!white}
		\colorlet{comment}{green!40!black}
		\def\defaultgobble{0}
	\end{highlightblock}
\end{showcase}

Each line can be set independent of each other, and each shows its default
value.

There are package options you can use as well:

\begin{list}{}{
		\itemindent-\leftmargin
		\setlength{\itemsep}{10pt}
	}
	\item\textbf{frame} (default: \hll|lines|)\par\nobreak

	Specifies the frame you want around code. My
	favorites are \hll|lines| and \hll|none|. Check the
	\fhref{https://www.ctan.org/pkg/listings}{listings package documentation} for all
	possibilities.


	\item\textbf{noframe} (use without value)\par\nobreak

	Equivalent to \hll|frame=none|.


	\item\textbf{styleanywhere} (use without value)\par\nobreak

	Overrides the default behavior that \hll|style| starts a new style after commands like \hll|add| and \hll|remove|.

\end{list}


\section{Fragile breaking situations (like beamer frames)}
\label{sec:frag}

When passing command arguments around, or storing environment content, LaTeX interprets all
characters. This includes seeing \hll|\maketitle| in \hll!\hll|\maketitle|! as a real command. To
prevent this behavior, everything from \hll|\verb|, \iffalse|\fi to the \hll|verbatim|-environment,
to the \hll|listings| package (which this package depends on) temporarily changes the interpretation
of characters that are still to be read. The blackslash before maketitle in \hll!\hll|\maketitle|!
will be read as `just text' (a \textit{letter} technically).

When content gets interpreted early, like the \hll|frame|-environment in \hll|beamer| does,
this trick can't be done anymore. Instead, you either need to \emph{escape} code, or
\emph{pre-process} the code outside a fragile breaking situation.

Escaping is done by preceding special characters with a backslash. For example,
\hll!\hll|\documentclass[]{}|! becomes \hll!\hll|\\!\hll!documentclass[]\{\}|!.

For large code blocks, this is undesirable. Therefore, the package provides for a companion to the
\hll|highlightblock|-environment: surround it with a \hll|saveblock|-environment which takes a
single argument: a name to assign it. For example:
\begin{showcase}[label=example]
	\begin{highlightblock}[gobble=8]
		\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}
	\end{highlightblock}
\end{showcase}


Do this outside a fragile breaking situation. (For the \hll|frame|-environment example, that means
just before the \hll|frame| for example.) Then, where you want to use it, use
\hll|\useblock{basicfigure}|, where the argument
is the name used during saving.
There is also a variant \hll|\consumeblock{basicfigure}|. If you save
many blocks, these will all remain loaded in memory till your PDF has fully generated. The
\hll|\consumeblock| works like \hll|\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 \hll|\useblock| when you can't
guarantee the last use of a block.

There is a separate demo for fragile breaking situations. You can find it at
\hll|deamerdemo/deamerdemo.tex|.

\section{Adding extra space}

By default, \hll|highlightlatex| follows an approach where it minimizes spacing. This gives you full
control over how tight or spacious your document looks. Just use commands like \hll|\medskip| to add
extra spacing. The package doesn't currently include an option to do it everywhere automatically.

\section{License \& Credits}

The package is available under MIT License. See \textsc{license}.txt.

Thanks for minor fixes:

gemmaro

\rule{5cm}{0.4pt}

For any bug, feature request, unclarity, or whatever else related to this package, you're welcome to
open an issue or pull-request. Issues can be opened on

\begin{showcase}[label=url]
	\begin{highlightblock}[gobble=8]
		~\url{https://github.com/vkuhlmann/highlight-latex/issues}~
	\end{highlightblock}
\end{showcase}

Thanks for contributing!

\end{document}