summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/lualatex/yamlvars
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-01-18 21:31:33 +0000
committerKarl Berry <karl@freefriends.org>2022-01-18 21:31:33 +0000
commit5d65424a72a5ecee6c3ab7e12c21ac49ee887827 (patch)
treeb3f970ed9781dba9bbf11156a7a2c317bcbee536 /Master/texmf-dist/doc/lualatex/yamlvars
parent65f9c8611e6e13d8d69b1c30a793493c32b92dee (diff)
yamlvars (18jan22)
git-svn-id: svn://tug.org/texlive/trunk@61652 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/yamlvars')
-rw-r--r--Master/texmf-dist/doc/lualatex/yamlvars/README.md6
-rw-r--r--Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdfbin46890 -> 69229 bytes
-rw-r--r--Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex91
3 files changed, 81 insertions, 16 deletions
diff --git a/Master/texmf-dist/doc/lualatex/yamlvars/README.md b/Master/texmf-dist/doc/lualatex/yamlvars/README.md
index 946ee2e374f..031de6c53a7 100644
--- a/Master/texmf-dist/doc/lualatex/yamlvars/README.md
+++ b/Master/texmf-dist/doc/lualatex/yamlvars/README.md
@@ -1,13 +1,13 @@
-# YAMLvars -- parse a YAML document and create LaTeX definitons
+# YAMLvars -- parse a YAML document and create definitions in LaTeX
This LuaLaTeX package provides a YAML parser and some functions to declare and define LaTeX definitions using YAML files.
-It uses the [`tinyyaml`](https://github.com/api7/lua-tinyyaml) parser.
+It uses the [`markdown-tinyyaml`](https://github.com/api7/lua-tinyyaml) parser that is shipped with the [`markdown`](https://ctan.org/pkg/markdown) package.
# License
-Copyright (C) 2021 Kale Ewasiuk
+Copyright (C) 2021-2022 Kale Ewasiuk
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf
index eeeab7ea6c0..974873680d8 100644
--- a/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf
+++ b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex
index 5e32058dabe..057aac5d39d 100644
--- a/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex
+++ b/Master/texmf-dist/doc/lualatex/yamlvars/YAMLvars.tex
@@ -1,6 +1,6 @@
% Kale Ewasiuk (kalekje@gmail.com)
-% 2021-12-15
-% Copyright (C) 2021 Kale Ewasiuk
+% 2022-01-18
+% Copyright (C) 2021-2022 Kale Ewasiuk
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
@@ -29,6 +29,7 @@
\newcommand{\cmd}[1]{\texttt{\detokenize{#1}}}
\newcommand{\qcmd}[1]{``\cmd{#1}''}
\usepackage{url}
+\usepackage{xcolor}
\usepackage{showexpl}
\lstset{explpreset={justification=\raggedright,pos=r,wide=true}}
\setlength\ResultBoxRule{0mm}
@@ -53,13 +54,26 @@
-\usepackage{YAMLvars}
+\usepackage[overwritedefs]{YAMLvars}
\title{YAMLvars}
\subtitle{a YAML variable parser for LuaLaTeX}
\begin{document}
+
+
\maketitle
+
+%%%%%
+
+%{NOTE::: \Huge todo use LTXexample and improve examples/testing\\
+%todo need way better error tracing for this pkg}
+
+
+
+%%%%%%%%%%%
+
+
YAMLvars is a LuaLaTeX-based package to help make definitions or produce LaTeX code using a YAML file.
This package might be useful for you if you want to batch create docummnts
by pushing various sets YAML data to a fixed LaTeX template,
@@ -85,25 +99,31 @@ declare the variables somewhere in the preamble.
This option is offered to help with automation scripts.
An example is showin in Section \ref{example}.
-\leavevmode\llap{\texttt{allowundeclared}\ \ \ }%
+\hspace*{3ex}\llcmd{allowundeclared}%
It might be helpful to define something in your YAML parsing doc without declaring it.
If you want this flexibility, use this setting. Note that eisting definitions will not be overwritten and an error
will br thrown if the name exists.
+\llcmd{overwritedefs}Danger! This will allow you to \cmd{gdef} commands with YAML. Caution should be taken to not set definitions like \cmd{begin}, \cmd{section}, etc.
+
\section{Dependencies}
-This package contains the \texttt{tinyyaml} Lua package.
-If you want to use it for other purposes, you can bring it into Lua by either:
+%This package contains the \texttt{tinyyaml} Lua package.
+\llcmd{Note:}This package requires that the \cmd{markdown} (\url{https://ctan.org/pkg/markdown}) be installed. This package does not use the package in its entirety, but rather depends on the YAML interpreter it comes with: \cmd{markdown-tinyyaml.lua}. This dependency is chosen to avoid redundancy in your TeX installation and align development of the \cmd{tinyyaml} Lua package.
+If you want to use the YAML interpreter for other purposes, you can bring it into Lua by either:
\begin{verbatim}
\directlua{yaml = YAMLvars.yaml} or
-\directlua{yaml = require('tinyyaml')}
+\directlua{yaml = require'markdown-tinyyaml'}
\end{verbatim}
-The distribution: \url{https://github.com/peposso/lua-tinyyaml}\\
+The distribution: \url{https://github.com/api7/lua-tinyyaml}\\
The YAML specification: \url{https://yaml.org/spec/}\\
-Many of the ``transform'' and ``processing'' functions built-in to this package rely on other packages.
-\texttt{penlight},
-\texttt{xspace},
-\texttt{hyperref} for example.
+Many of the ``transform'' and ``processing'' functions built-in to this package rely on other packages,
+like
+\texttt{hyperref}, for example, but it is not loaded, and this package will only load
+\cmd{penlight},
+\cmd{luacode},
+\cmd{xspace}, and
+\cmd{etoolbox}.
\section{Declaring variables}
A declaration file can either be parsed with the command \texttt{declareYAMLvarsFile} command,
@@ -117,6 +137,9 @@ be a table that contains at least one of the following keys:\\
\texttt{prc} (processing, must be a single string), or \\
\texttt{dft} (default value, if being defined. Must be a string).
+If you want to change the way a variable is initialized, you can change the function
+\cmd{YAMLvars.dec.PRC = function (var) ... end } where \cmd{PRC} is how the variable will be processed (\cmd{gdef}, \cmd{yvdef}, \cmd{length}, or something of your choosing).
+
The default value for variables is the Lua \texttt{nil}.
YAMLvars will first check if the definition exists, if so, an error will be thrown
so that we avoid overwriting.
@@ -210,7 +233,49 @@ This package includes \texttt{gdef} to set a definition, \texttt{yvdef} to defin
\texttt{title, author, date} to set \texttt{\textbackslash @title, \textbackslash @author, \textbackslash @date},
respectively
- \section{Example}\label{example}
+\pagebreak
+
+\section{Some Examples}
+
+\begin{LTXexample}
+%! language = yaml
+\begin{declareYAMLvars}
+address:
+ xfm:
+ - list2nl
+ - = x..'!!!'
+name: null
+
+title:
+ xfm:
+ - lb2nl
+# - / YAMLvars.prvcmd(titletext, YAMLvars.varsvals['atitle']:gsub('\n', ' ')..'\\xspace{}')
+\end{declareYAMLvars}
+
+%! language = yaml
+\begin{parseYAMLvars}
+title: |-
+ A Multiline
+ Monumental Title!
+
+name: Joe Smith
+address:
+ - 1234 Fake St.
+ - City
+\end{parseYAMLvars}
+
+\title
+
+%\titletext!
+
+\name
+
+\address
+
+\end{LTXexample}
+
+\pagebreak
+ \section{Automation Example}\label{example}
Suppose you had a number of bills of sales in yaml format and wanted to produce some nice pdfs.
The following code shows how this could be done.