diff options
author | Karl Berry <karl@freefriends.org> | 2022-10-30 20:46:45 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-10-30 20:46:45 +0000 |
commit | 00f34d83a0e5a739dda789aebdb2871f3cbeddd8 (patch) | |
tree | 46006acae9ad4313051c0cb504b371e95ba8a40a /Master/texmf-dist/doc/lualatex | |
parent | 418009d3a363c5b15f39b7a52c22aa0ba84b6a66 (diff) |
luaoptions (30oct22)
git-svn-id: svn://tug.org/texlive/trunk@64870 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/lualatex')
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/Contributors.md | 6 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/LICENSE | 21 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/README.md | 15 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/latexmkrc | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.pdf | bin | 0 -> 28593 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.tex | 188 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsbase.cls | 37 | ||||
-rw-r--r-- | Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsmanual.cls | 41 |
8 files changed, 310 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/Contributors.md b/Master/texmf-dist/doc/lualatex/luaoptions/Contributors.md new file mode 100644 index 00000000000..ab09dc720d0 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/Contributors.md @@ -0,0 +1,6 @@ +## Authors + +Luaoptions is developped by: + +- [Fr. Jacques Peron](mailto:cataclop@hotmail.com); [@jperon](https://github.com/jperon) +- [Urs Liska](mailto:git@ursliska.de); [@uliska](https://github.com/uliska), [@openlilylib](https://github.com/openlilylib) diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/LICENSE b/Master/texmf-dist/doc/lualatex/luaoptions/LICENSE new file mode 100644 index 00000000000..479e0ec593b --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2015--2022 the lualatex-tools Project + +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/lualatex/luaoptions/README.md b/Master/texmf-dist/doc/lualatex/luaoptions/README.md new file mode 100644 index 00000000000..19ad0c6770d --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/README.md @@ -0,0 +1,15 @@ +Main author: [Fr. Jacques Peron](mailto:cataclop@hotmail.com)\nThis material is subject to the MIT license.\n +# `luaoptions` +Option handling for LuaLaTeX packages + +This package has been extracted from +[`lyluatex`](https://github.com/jperon/lyluatex) where it was originally +developed as supporting functionality. However, as it turned out it is useful +as a building block for LuaLaTeX packages in general, and the development of +[`luaformatters`](https://github.com/lualatex-tools/luaformatters) made it +clear that the option handling code had to be moved to a standalone package. + +Initially there is no extensive documentation available since the package wasn't +originally intended to be exposed to third-party packages or even end-users; +the best sources of documentation are `lyluatex` and `luaformatters` codes, +and the docstrings of `luaoptions.lua` and `luaoptions-lib.lua`. diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/latexmkrc b/Master/texmf-dist/doc/lualatex/luaoptions/latexmkrc new file mode 100644 index 00000000000..d6544121699 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/latexmkrc @@ -0,0 +1,2 @@ +$pdf_mode="1"; +$pdflatex="lualatex --shell-escape %O %S"; diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.pdf b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.pdf Binary files differnew file mode 100644 index 00000000000..3339fbeb63d --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.pdf diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.tex b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.tex new file mode 100644 index 00000000000..627583f6788 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptions.tex @@ -0,0 +1,188 @@ +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode}{hyperref} +\PassOptionsToPackage{hyphens}{url} +% +\documentclass[ +]{luaoptionsmanual} +\usepackage{amsmath,amssymb} +\usepackage[]{libertine} +\usepackage{iftex} +\ifPDFTeX + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex + \usepackage{unicode-math} + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} +\fi +% Use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +\usepackage{xcolor} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} +\hypersetup{ + pdfauthor={Fr.~Jacques Peron; Urs Liska}, + hidelinks, + pdfcreator={LaTeX via pandoc}} +\urlstyle{same} % disable monospaced font for URLs +\usepackage{color} +\usepackage{fancyvrb} +\newcommand{\VerbBar}{|} +\newcommand{\VERB}{\Verb[commandchars=\\\{\}]} +\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}} +% Add ',fontsize=\small' for more characters per line +\newenvironment{Shaded}{}{} +\newcommand{\AlertTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}} +\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}} +\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} +\newcommand{\BuiltInTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} +\newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}} +\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}} +\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} +\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.56,0.13,0.00}{#1}} +\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} +\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.73,0.13,0.13}{\textit{#1}}} +\newcommand{\ErrorTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}} +\newcommand{\ExtensionTok}[1]{#1} +\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} +\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}} +\newcommand{\ImportTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} +\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} +\newcommand{\NormalTok}[1]{#1} +\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}} +\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.74,0.48,0.00}{#1}} +\newcommand{\RegionMarkerTok}[1]{#1} +\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}} +\newcommand{\StringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}} +\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\setlength{\emergencystretch}{3em} % prevent overfull lines +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures +\fi + +\title{\texttt{luaoptions}} +\usepackage{etoolbox} +\makeatletter +\providecommand{\subtitle}[1]{% add subtitle to \maketitle + \apptocmd{\@title}{\par {\large #1 \par}}{}{} +} +\makeatother +\subtitle{0.8} +\author{Fr.~Jacques Peron \and Urs Liska} +\date{\luaoptionsmanualdate} + +\begin{document} +\maketitle + +\thispagestyle{empty} +\enlargethispage*{3\baselineskip} + +\hypertarget{introduction}{% +\section{Introduction}\label{introduction}} + +\texttt{luaoptions} is a LuaLaTeX package providing extensive support +for handling \emph{options}, on package level and locally. It is hosted +at \url{https://github.com/lualatex-tools/luaoptions} and maintained by +Jacques Peron +(\href{mailto:cataclop@hotmail.com}{\nolinkurl{cataclop@hotmail.com}}) +and Urs Liska +(\href{mailto:git@ursliska.de}{\nolinkurl{git@ursliska.de}}). The +package was originally developed as part of the \texttt{lyluatex} +package\footnote{\url{https://github.com/jperon/lyluatex}} but has now +been extracted as a standalone package because we realized it can be a +useful tool for arbitrary LuaLaTeX packages having to deal with +\emph{options} -- both \emph{package options} and \emph{optional macro +arguments}. A \texttt{lyluatex} installation should not be a dependency +for packages that want to make use of option handling but are not +interested in music engraving \dots + +\texttt{luaoptions} allows the declaration of sets of options, along +with defaults, expected/allowed values and limited type checking. These +options can be enforced as package options, changed at any point during +a document, or overwritten locally by optional macro arguments. It is +also possible to instantiate an \texttt{Options} object as an +independent Lua object, without linking it to a package. +\texttt{luaoptions} can be used to enforce and prepopulate options, or +it can be used to simply handle the parsing of optional +\texttt{key=value} arguments into proper Lua tables. + +The main use of \texttt{luaoptions} is to define package options as +follows: + +\begin{Shaded} +\begin{Highlighting}[] +\FunctionTok{\textbackslash{}RequirePackage}\NormalTok{\{luaoptions\}} +\FunctionTok{\textbackslash{}directlua}\NormalTok{\{} +\NormalTok{ local \_opt = lua\_options} +\NormalTok{ lua\_options.register(\textquotesingle{}myoptions\textquotesingle{}, \{} +\NormalTok{ [\textquotesingle{}option\textquotesingle{}] = \{\textquotesingle{}default value\textquotesingle{}, \textquotesingle{}other value\textquotesingle{}, \textquotesingle{}\textquotesingle{}\},} +\NormalTok{ [\textquotesingle{}otheroption\textquotesingle{}] = \{\textquotesingle{}default\textquotesingle{}, validator\},} +\NormalTok{ [\textquotesingle{}yetanotheroptions\textquotesingle{}] = \{\},} +\NormalTok{ \})} +\NormalTok{\}} +\end{Highlighting} +\end{Shaded} + +\texttt{validator} is a function that returns \texttt{true} when the +defined option is valid, \texttt{false} otherwise. \texttt{luaoptions} +itself contains predefined such functions. + +After that, defined options are available in a lua table, which can be +used by the mean of the \texttt{client} command: + +\begin{Shaded} +\begin{Highlighting}[] +\KeywordTok{local}\NormalTok{ myopts }\OperatorTok{=}\NormalTok{ lua\_options}\OperatorTok{.}\NormalTok{client}\OperatorTok{(}\StringTok{\textquotesingle{}myoptions\textquotesingle{}}\OperatorTok{)} +\NormalTok{tex}\OperatorTok{.}\NormalTok{sprint}\OperatorTok{(}\NormalTok{myopts}\OperatorTok{.}\NormalTok{option}\OperatorTok{)} +\end{Highlighting} +\end{Shaded} + +This initial release does \emph{not} include documentation beyond this +short introduction; please refer to the docstrings in +\texttt{luaoptions.lua} and \texttt{luaoptions-lib.lua} for more +information. + +For the time being it is possible to look into how some of our own +packages make use of \texttt{luaoptions}: + +\begin{itemize} +\tightlist +\item + \url{https://github.com/jperon/lyluatex/blob/master/lyluatextools.sty} +\item + \url{https://github.com/jperon/lyluatex/blob/master/lyluatex.lua} +\item + \url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.sty} +\item + \url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.lua} +\item + \url{https://github.com/lualatex-tools/luaformatters/blob/master/submodules/luaformatters-formatter.lua} +\end{itemize} + +\end{document} diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsbase.cls b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsbase.cls new file mode 100644 index 00000000000..3f2ac5726eb --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsbase.cls @@ -0,0 +1,37 @@ +%Luaoptions LaTeX class. +% +% Copyright (C) 2015-2022 the lualatex-tools Project +% License: MIT +% This file is part of lualatex-tools. + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{luaoptionsbase}[2022/10/30 v0.8] %%LUAOPTIONS_DATE LUAOPTIONS_VERSION + +\LoadClass[DIV=11]{scrartcl} +\RequirePackage{blindtext} +\RequirePackage{libertine} +\RequirePackage{listings} +\RequirePackage{minted} +\RequirePackage{pgffor} +\RequirePackage{fancyvrb} +\RequirePackage[colorlinks=true]{hyperref} + + +% Common formatting elements for manual and examples +\usepackage{xcolor} +\newcommand{\highlight}[1]{\textcolor{blue}{#1}} +\newcommand{\cmd}[1]{\highlight{\texttt{\textbackslash #1}}} +\newcommand{\option}[1]{\highlight{\texttt{#1}}} +\newcommand{\lyMargin}[1]{% + +\medskip +\hspace*{-1em}% +\noindent% +\highlight{#1} +\nopagebreak +} + +\newcommand{\lyOption}[2]{\lyMargin{\texttt{#1} {\small \emph{(#2)}}\index{#1}}} +\newcommand{\lyCmd}[1]{% +\lyMargin{\texttt{\textbackslash #1}\index{\textbackslash #1}}} +\newcommand{\lyIssue}[1]{\lyMargin{\textbf{\textcolor{red}{#1}}}} diff --git a/Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsmanual.cls b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsmanual.cls new file mode 100644 index 00000000000..5de9da32b62 --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/luaoptions/luaoptionsmanual.cls @@ -0,0 +1,41 @@ +%Luaoptions LaTeX class for the manual. +% +% Copyright (C) 2015-2022 the lualatex-tools Project +% License: MIT +% This file is part of luaoptions. + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{luaoptionsmanual}[2022/10/30 v0.8] %%LUAOPTIONS_DATE LUAOPTIONS_VERSION + +\LoadClass{luaoptionsbase} + +\RequirePackage{fontspec} +\RequirePackage{microtype} +\RequirePackage{libertine} +\setmonofont[Scale=MatchLowercase,StylisticSet=1]{InconsolataN} +\defaultfontfeatures{ + Ligatures=TeX, + Scale=MatchLowercase, + Numbers=Proportional, + Numbers=OldStyle +} +\frenchspacing + +\RequirePackage{makeidx} +\makeindex + +\newcommand{\linkexample}[2]{ + \addcontentsline{toc}{subsection}{#2} + \hypertarget{#1}{} +} + + +\newcommand{\luaoptionsmanualdate}{ + \directlua{ + local PC = string.char(37) + local date_fmt = PC..'Y-'..PC..'m-'..PC..'d' + local p = io.popen('git log -n1 --date=short --format='..PC..'"ad"', 'r') + tex.sprint(p and p:read('*a'):sub(1,-2) or os.date(date_fmt)) + if p then p:close() end + } +} |