\documentclass{ltxdoc}

\setcounter{tocdepth}{4}
\setcounter{secnumdepth}{4}

\EnableCrossrefs
\CodelineIndex
\RecordChanges

\usepackage{mdframed}
\usepackage{minted}
\usepackage{multicol}
\usepackage{luacode}
\usepackage{farbe}

\usemintedstyle{friendly}
\BeforeBeginEnvironment{minted}{\begin{mdframed}}
\AfterEndEnvironment{minted}{\end{mdframed}}
\setminted{
  breaklines=true,
  fontsize=\footnotesize,
  style=manni,
}
\def\lua#1{\mintinline{lua}|#1|}
\def\latex#1{\mintinline{latex}|#1|}

\NewDocumentCommand { \InputLatex } { O{} m } {
  \begin{mdframed}
  \inputminted[linenos=false,#1]{latex}{examples/#2}
  \end{mdframed}
}

\NewDocumentCommand { \InputLua } { O{} m } {
  \begin{mdframed}
  \inputminted[linenos=false,#1]{lua}{examples/#2}
  \end{mdframed}
}

\begin{document}

\providecommand*{\url}{\texttt}

\title{The \textsf{farbe} package}
\author{%
  Josef Friedrich\\%
  \url{josef@friedrich.rocks}\\%
  \href{https://github.com/Josef-Friedrich/farbe}
       {github.com/Josef-Friedrich/farbe}%
}
\date{0.2.0 from 2025/06/08}

\maketitle

\newpage

\tableofcontents

\newpage

% \section{Einführung}
\section{Introduction}

Color management (conversion, names) for Lua\TeX{} implemented in Lua.

\emph{farbe} is mainly a Lua library for converting and manipulating
colors. It is based on Lua module
\href{https://luarocks.org/modules/Firanel/lua-color}{lua-color}.

% CTAN stellt eine Übersichtsseite zum Thema bereit.
CTAN provides an overview page on the subject of
\href{https://www.ctan.org/topic/colour}
{Colour: packages to typesetting in colour}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Lua interface / API}

\subsection{Class “Color”}

\subsubsection{Fields}

\paragraph{Color.r}

Red component.

\paragraph{Color.g}

Green component.

\paragraph{Color.b}

Blue component.

\paragraph{Color.a}

Alpha component.

\subsubsection{Methods}

\paragraph{Color:clone ()}

Clone color

\paragraph{Color:set (value)}

Set color to value.

\paragraph{Color:rgb ()}

Get rgb values.

\paragraph{Color:rgba ()}

Get rgba values.

\paragraph{Color:hsv ()}

Get hsv values.

\paragraph{Color:hsva ()}

Get hsv values.

\paragraph{Color:hsl ()}

Get hsl values.

\paragraph{Color:hsla ()}

Get hsl values.

\paragraph{Color:hwb ()}

Get hwb values.

\paragraph{Color:hwba ()}

Get hwb values.

\paragraph{Color:cmyk ()}

Get cmyk values.

\paragraph{Color:rotate (value)}

Rotate hue of color.

\paragraph{Color:invert ()}

Invert the color.

\paragraph{Color:grey ()}

Reduce saturation to 0.

\paragraph{Color:blackOrWhite (lightness)}

Set to black or white depending on lightness.

\paragraph{Color:mix (other, strength)}

Mix two colors together.

\paragraph{Color:complement ()}

Generate complementary color.

\paragraph{Color:analogous ()}

Generate analogous color scheme.

\paragraph{Color:triad ()}

Generate triadic color scheme.

\paragraph{Color:tetrad ()}

Generate tetradic color scheme.

\paragraph{Color:compound ()}

Generate compound color scheme.

\paragraph{Color:evenlySpaced (n, r)}

Generate evenly spaced color scheme.

\paragraph{Color:tostring (format)}

Get string representation of color.

\paragraph{Color:band (a, b)}

Apply rgb mask to color, providing backwards compatibility for Lua 5.1 and LuaJIT 2.1.0-beta3

\paragraph{Color:isColor (color)}

Check whether color is a Color.

\section{\TeX{} interface}

\begin{minted}{latex}
\documentclass{article}
\usepackage{color}
\usepackage{farbe}
\begin{document}
\definecolor{my-test-color}{rgb}{.2,0.85,1}

% Not a valid color: my-test-color
% \FarbeTextColor{my-test-color}{This text is set in my test color.}

\FarbeImport{my-test-color}

\FarbeTextColor{my-test-color}{This text is set in my test color.}
\end{document}
\end{minted}

\begin{macro}{\FarbePdfLiteral}

\end{macro}

\begin{macro}{\FarbeColor}
\begin{macro}{\FarbeColorEnd}
\begin{minted}{latex}
This is not green.
\FarbeColor{green} This is green. It's still green.
\FarbeColorEnd It's not green.
\end{minted}
\end{macro}
\end{macro}

\begin{macro}{\FarbeTextColor}
\begin{minted}{latex}
This is not green. \FarbeTextColor{green}{This is green.} This is not green.
\end{minted}
\end{macro}

\begin{macro}{\FarbeBox}

\end{macro}

\clearpage

\section{Color names}

\subsection{base}

\begin{multicols}{4}
\directlua{farbe.print_color_table('base')}
\end{multicols}

\subsection{svg}

This svg color names are taken from the
\href{https://github.com/latex3/xcolor/blob/c5035d41c6070f4e8936196a994ad04336704872/xcolor.dtx#L7134-L7286}{xcolor}
package.

\def\TmpColor#1{\texttt{#1}}

% https://github.com/latex3/xcolor/blob/c5035d41c6070f4e8936196a994ad04336704872/xcolor.dtx#L2105-L2127
{
\footnotesize\raggedright Duplicate colors:
\TmpColor{Aqua} = \TmpColor{Cyan},
\TmpColor{Fuchsia} = \TmpColor{Magenta};
\TmpColor{Navy} = \TmpColor{NavyBlue};
\TmpColor{Gray} = \TmpColor{Grey},
\TmpColor{DarkGray} = \TmpColor{DarkGrey},
\TmpColor{LightGray} = \TmpColor{LightGrey},
\TmpColor{SlateGray} = \TmpColor{SlateGrey},
\TmpColor{DarkSlateGray} = \TmpColor{DarkSlateGrey},
\TmpColor{LightSlateGray} = \TmpColor{LightSlateGrey},
\TmpColor{DimGray} = \TmpColor{DimGrey}.
\par\smallskip
HTML4 color keyword subset:
\TmpColor{Aqua}, \TmpColor{Black}, \TmpColor{Blue}, \TmpColor{Fuchsia},
\TmpColor{Gray}, \TmpColor{Green}, \TmpColor{Lime}, \TmpColor{Maroon},
\TmpColor{Navy}, \TmpColor{Olive}, \TmpColor{Purple}, \TmpColor{Red},
\TmpColor{Silver}, \TmpColor{Teal}, \TmpColor{White}, \TmpColor{Yellow}.
\par\smallskip
Colors taken from Unix/X11:
\TmpColor{LightGoldenrod},
\TmpColor{LightSlateBlue},
\TmpColor{NavyBlue},
\TmpColor{VioletRed}.
}

\begin{multicols}{4}
\directlua{farbe.print_color_table('svg')}
\end{multicols}

\subsection{x11}

This x11 color names are taken from the
\href{https://github.com/latex3/xcolor/blob/c5035d41c6070f4e8936196a994ad04336704872/xcolor.dtx#L7289-L7607}{xcolor}
package.

% https://github.com/latex3/xcolor/blob/c5035d41c6070f4e8936196a994ad04336704872/xcolor.dtx#L2133-L2135
{
\footnotesize\raggedright Duplicate colors:
\TmpColor{Gray0} = \TmpColor{Grey0,},
\TmpColor{Green0} = \TmpColor{Green1.}.
}

\begin{multicols}{4}
\directlua{farbe.print_color_table('x11')}
\end{multicols}

\clearpage

\section{Implementation}

%%
%
%%

\subsection{farbe.lua}

\inputminted[linenos=true]{lua}{farbe.lua}

%%
%
%%

\clearpage

\subsection{farbe.tex}

\inputminted[linenos=true]{latex}{farbe.tex}

%%
%
%%

\clearpage

\subsection{farbe.sty}

\inputminted[linenos=true]{latex}{farbe.sty}

\pagebreak
\PrintIndex
\end{document}
