summaryrefslogtreecommitdiff
path: root/support
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-11-25 03:03:12 +0000
committerNorbert Preining <norbert@preining.info>2023-11-25 03:03:12 +0000
commitad976e54f48605a66054bc56e945dabc425c956a (patch)
treef3905ec1ab486d1cf12b064887e311f2ea10bebf /support
parentac5a5e57a4c9b3c436c3bac327fe885acea28ba4 (diff)
CTAN sync 202311250303
Diffstat (limited to 'support')
-rw-r--r--support/texblend/README27
-rw-r--r--support/texblend/intro.tex153
-rw-r--r--support/texblend/texblend280
-rw-r--r--support/texblend/texblend-doc.pdfbin0 -> 47108 bytes
-rw-r--r--support/texblend/texblend-doc.tex46
-rw-r--r--support/texblend/usage.tex107
6 files changed, 613 insertions, 0 deletions
diff --git a/support/texblend/README b/support/texblend/README
new file mode 100644
index 0000000000..a92e86bf24
--- /dev/null
+++ b/support/texblend/README
@@ -0,0 +1,27 @@
+TeXBlend - Compile Segments of LaTeX Documents
+
+Version v0.1
+
+This tool compiles individual files that are included as parts of larger
+documents. It utilizes the preamble of the main document but disregards all
+other included files.
+
+The main purpose is to allow fast compilation of particular chapters or
+sections, eliminating the need to recompile the entire document. This
+facilitates an efficient way to check for formatting or syntax errors in the
+particular part of the document being worked on.
+
+
+Copyright: 2023 Michal Hoftich
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+ http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is Michal Hoftich.
diff --git a/support/texblend/intro.tex b/support/texblend/intro.tex
new file mode 100644
index 0000000000..5f41e8dc66
--- /dev/null
+++ b/support/texblend/intro.tex
@@ -0,0 +1,153 @@
+% !TEX root = texblend-doc.tex
+% !TEX TS-program = lualatex
+
+\section{Introduction}
+This tool compiles individual files that are included as parts of larger documents.
+It utilizes the preamble of the main document but disregards all other included files.
+
+The main purpose is to allow fast compilation of particular chapters or sections,
+eliminating the need to recompile the entire document.
+This facilitates an efficient way to check for formatting or syntax errors in
+the particular part of the document being worked on.
+
+\section{Structure of \TeX\ Files}
+
+The basic usage is as follows: consider a main document that includes files for
+individual chapters, named for example \texttt{main.tex}:
+
+
+\begin{verbatim}
+\documentclass{article}
+\author{John Doe}
+\title{Sample Document}
+\usepackage{upquote}
+\usepackage{microtype}
+\usepackage{hyperref}
+\begin{document}
+\maketitle
+\tableofcontents
+\input{intro}
+\input{usage}
+\end{document}
+\end{verbatim}
+
+We can compile this document to obtain a PDF file containing the text of all
+chapters. However, by using \TeX Blend, we can generate separate PDFs for each
+chapter. The advantage is that all commands defined in the packages used in the
+main document will be available.
+
+In the included files, we can use special directives that indicate the main
+file and the engine to be used for compilation. Similar directives are employed
+by various \TeX\ editors, such as \TeX Shop or \TeX Works.
+
+For instance, a file like \texttt{intro.tex}, which is included in the main document,
+might look like this:
+
+\begin{verbatim}
+% !TEX root = main.tex
+% !TEX TS-program = lualatex
+
+\section{Introduction}
+This tool compiles individual files that are included
+as parts of larger documents.
+\end{verbatim}
+
+Notice the comments at the beginning of the file. These are
+directives, indicating the main document and the engine to be used for
+compilation. Many \TeX\ editors support these directives, and we utilize them in
+\TeX Blend to effectively control the compilation process too.
+
+These directives follow a specific format, requiring placement at the beginning
+of the file and commencing with a percentage sign. Subsequently, there is a
+space followed by either the marker \texttt{!TEX} or \texttt{!TeX},
+both of which are recognized formats.
+The next element is the property name with an optional \texttt{TS-} prefix
+(in line with the TeX Shop editor), followed by an equals sign and, finally, the
+value.
+
+Two crucial properties are \texttt{root}, indicating the name of the main file, and
+\texttt{program}, through which we can select the program for compiling the document.
+However, it is possible to specify additional properties, which can then be
+utilized in template documents.
+
+\subsection{Placement of the Main Document and Templates}
+\label{sec:placement}
+
+You can specify the full path to the main document in the \verb|root| property.
+\TeX Blend can also be used to compile documents using a universal template.
+The path to this template can be specified in full or can leverage the directory
+structure of TeX by placing it in a directory recognized by the KPSE library.
+This directory is typically designated for user packages, commonly found at
+\verb|~/texmf/tex/latex|, although it may vary on different systems.
+You can identify its location on your system using the command:
+
+\begin{verbatim}
+$ kpsewhich --var-value TEXMFHOME
+\end{verbatim}
+
+This command typically outputs a path similar to this: \texttt{/home/username/texmf}.
+If this directory does not exist, create it. Further, within this directory,
+create the subdirectories \texttt{tex/latex/templates}:
+
+\begin{verbatim}
+$ mkdir -p ~/texmf/tex/latex/templates
+\end{verbatim}
+
+You can then place your templates in this directory.
+To test the availability of the template, run the following command:
+
+\begin{verbatim}
+$ kpsewhich templatename.tex
+\end{verbatim}
+
+It should print path of the template document.
+
+\subsection{Custom Variables in Templates}\label{sec:variables}
+
+As templates are intended to be universal across various projects, it is
+possible to incorporate variables into them. These variables can be populated
+from properties in the directives, such as the document title.
+
+To include variables for expansion in the template, you can use the notation
+\verb|{{variableName}}|. For example, to set the document title, you can use
+\texttt{\textbackslash title\{\{\{title\}\}\}}. The double curly braces around
+the variable will be replaced with its value, while the third pair of curly braces will remain in the
+document.
+
+Say that you have a following template saved in \url{~/texmf/tex/latex/templates/mytemplate.tex}:
+
+\begin{verbatim}
+\documentclass{article}
+\title{{{title}}}
+\author{Michal}
+\usepackage{microtype}
+\begin{document}
+\end{document}
+\end{verbatim}
+
+
+A document that utilizes this template may look like the following:
+
+\begin{verbatim}
+% !TEX root = mytemplate.tex
+% !TEX title = hello world
+\maketitle
+\end{verbatim}
+
+
+This produces a following document with variables expanded:
+
+\begin{verbatim}
+\documentclass{article}
+\title{hello world}
+\author{Michal}
+\usepackage{microtype}
+\begin{document}
+% !TEX root = mytemplate.tex
+% !TEX title = hello world
+\maketitle
+\end{document}
+\end{verbatim}
+
+You can require expansion of variables using the \verb|--expand| command line option.
+
diff --git a/support/texblend/texblend b/support/texblend/texblend
new file mode 100644
index 0000000000..bb5c9d0661
--- /dev/null
+++ b/support/texblend/texblend
@@ -0,0 +1,280 @@
+#!/usr/bin/env texlua
+kpse.set_program_name "luatex"
+
+-- TeXBlend -- Compile Segments of LaTeX Documents
+-- Copyright: Michal Hoftich <michal.h21@gmail.com> (2023)
+--
+-- This work may be distributed and/or modified under the
+-- conditions of the LaTeX Project Public License, either version 1.3
+-- of this license or (at your option) any later version.
+-- The latest version of this license is in
+-- http://www.latex-project.org/lppl.txt
+-- and version 1.3 or later is part of all distributions of LaTeX
+-- version 2005/12/01 or later.
+--
+-- This work has the LPPL maintenance status `maintained'.
+--
+-- The Current Maintainer of this work is Michal Hoftich
+
+local lapp = require "lapp-mk4"
+-- mkutils needs the logging library
+logging = require "make4ht-logging"
+local mkutils = require "mkutils"
+local log = logging.new("TeXBlend")
+
+local version_info = "TeXBlend version v0.1"
+local cmd_options = [[TeXBlend: Compile Segments of LaTeX Documents
+
+This tool compiles individual files that are included as parts of larger documents.
+It utilizes the preamble of the main document but disregards all other included files.
+
+Usage:
+
+$ texblend [options] filename
+
+Available options:
+-e,--expand Expand variables in the template
+-h,--help Print the help message
+-H,--HTML Compile to HTML using TeX4ht
+-l,--lualatex Select lualatex as compiler explicitly
+-o,--output (default "") Set the output file name
+-O,--texoptions (default "") Extra options that should be passed to the LaTeX compiler
+-p,--pdflatex Select pdflatex as compiler explicitly
+-P,--print Don't compile the document, print the expanded template instead
+-s,--shell-escape Enable execution of external commands in LaTeX
+-t,--template (default "") Use explicit template instead of the one provided in the input file
+-v,--version Print version info
+-x,--xelatex Select xelatex as compiler explicitly
+<filename> (string) Use "-" if you want to pass document from the standard input
+
+Documentation: https://www.kodymirus.cz/texblend/
+Bug reports and development: https://github.com/michal-h21/texblend
+]]
+
+
+local default_template = [[\documentclass{article}
+\begin{document}
+\end{document}
+]]
+
+
+
+local function exit_on_error(status, msg)
+ -- function that tests function results
+ -- it prints error messages and exits if there was an error
+ if not status then
+ log:error( msg)
+ os.exit(1)
+ end
+end
+
+local function get_preamble(text)
+ -- try to get the document preamble
+ local preamble = {}
+ local found_begin = false
+ for line in text:gmatch("([^\n]*)") do
+ -- \begin{document} must be on a separate line, preceded only by whitespace
+ if line:match("^%s*\\begin{document}") then
+ found_begin = true
+ break
+ end
+ preamble[#preamble + 1] = line
+ end
+ if found_begin then
+ return table.concat(preamble, "\n")
+ end
+ return nil, "Cannot find \\begin{document} in the template. It must be placed on a separate line."
+end
+
+--
+local function prepare_template(document, template)
+ -- try to read document preamble from the template
+ local preamble, msg = get_preamble(template)
+ if not preamble then return nil, msg end
+ -- fill template with the document
+ return string.format("%s\n\\begin{document}\n%s\n\\end{document}\n", preamble, document)
+end
+
+local function get_metadata(content)
+ -- for now, we support only TeXShop's style of metadata:
+ -- % !TeX program = program
+ -- % !TeX root = root
+ -- also variant with % !TEX TS-var is supported
+ -- program is used for the compilation and root is the template document
+ local metadata = {}
+ for key, value in content:gmatch("%%%s*![Tt][Ee][Xx] T?S?%-?(.-)%s*=%s*([^\n]+)") do
+ metadata[key] = value
+ end
+ metadata.program = metadata.program or "pdflatex"
+ -- remove possible white space at the end of root filename
+ if metadata.root then metadata.root = metadata.root:gsub("%s*$", "") end
+ return metadata
+end
+
+local function use_arguments(metadata, arguments)
+ -- this function modifies metadata using command line arguments
+ -- remove empty strings from arguments
+ for k, v in pairs(arguments) do
+ if v == '""' then arguments[k] = nil end
+ end
+ -- handle output file name
+ if arguments.output then
+ metadata.output = mkutils.remove_extension(arguments.output)
+ else
+ -- base output filename on the input filename if we don't get explicit filename
+ metadata.output = mkutils.remove_extension(arguments.filename)
+ end
+ -- handle program
+ metadata.program = arguments.pdflatex and "pdflatex" or metadata.program
+ metadata.program = arguments.lualatex and "lualatex" or metadata.program
+ metadata.program = arguments.xelatex and "xelatex" or metadata.program
+ -- handle the template
+ metadata.root = arguments.template or metadata.root
+ -- pass other useful flags
+ metadata.shell_escape = arguments["shell-escape"]
+ metadata.html = arguments.HTML
+ metadata.options = arguments.texoptions
+ return metadata
+end
+
+local function expand(metadata, template)
+ -- expand {{variablename}} tags in the template. The variablename key must exitst
+ -- in the metadata table. If the variable doesn't exist, nothing is rendered
+ local expanded = template:gsub("{{([%a%d}]-)}}", function(key)
+ return metadata[key] or ""
+ end)
+ return expanded
+end
+
+local function load_file(filename)
+ -- universal function to read files
+ if not filename then return nil, "No filename passed" end
+ local f = io.open(filename, "r")
+ if not f then return nil, string.format("Cannot open file: %s", filename) end
+ local content = f:read("*all")
+ f:close()
+ return content
+end
+
+local function load_template(filename)
+ -- with kpse, we can use root files in the local TEXMF tree, like ~/tex/latex/tpl/template.tex
+ local filename = kpse.find_file(filename, "tex")
+ return load_file(filename)
+end
+
+local function load_document(filename)
+ -- load the input file and its metadata
+ local content, msg = load_file(filename)
+ if not content then return content, msg end
+ return get_metadata(content), content
+end
+
+
+local function prepare_command(metadata,arguments)
+ -- prepare CLI program to be executed
+ local options = {}
+ local command
+ -- we support HTML creation thanks to make4ht
+ if metadata.html then
+ command = "make4ht"
+ options[#options + 1] = "-j " .. metadata.output
+ options[#options + 1] = metadata.shell_escape and "-s" or nil
+ if metadata.program == "lualatex" then
+ options[#options + 1] = "-l"
+ elseif metadata.program == "xelatex" then
+ options[#options + 1] = "-x"
+ end
+ local texoptions = metadata.options
+ options[#options+1] = texoptions
+ texoptions = texoptions or ""
+ -- if texoptions already contain the - character, don't add it
+ if not texoptions:match("%-%s") and not texoptions:match("%-$") then
+ options[#options+1] = "-"
+ end
+ else
+ command = metadata.program
+ options[#options + 1] = "-jobname=" .. metadata.output
+ options[#options + 1] = metadata.shell_escape and "-shell-escape" or nil
+ options[#options+1] = metadata.options
+ end
+ return string.format("%s %s", command, table.concat(options, " "))
+end
+
+local function compile(command, document)
+ -- execute the command
+ local cmd = io.popen(command, "w")
+ if not cmd then
+ exit_on_error(nil, "Cannot run command")
+ end
+ cmd:write(document)
+ cmd:close()
+end
+
+local arguments
+-- you can set the _G.test=true if you want to load texblend as a library for testing
+if not __test__ then
+ -- process command line options
+ arguments = lapp(cmd_options)
+
+ -- handle non file actions
+ -- arguments.help is handled automatically by lapp
+ if arguments.version then
+ print(version_info)
+ os.exit()
+ end
+
+
+ local metadata, document
+ local filename = arguments.filename
+ if filename == "-" then
+ -- read from the standard input if the filename is -
+ document = io.read("*all")
+ metadata = get_metadata(document)
+ else
+ -- otherwise, load the input file and get metadata
+ metadata, document = load_document(filename)
+ end
+
+ exit_on_error(metadata, document)
+
+ -- enrich metadata with command line arguments
+ metadata = use_arguments(metadata, arguments)
+
+ -- user needs to add explicit output filename when dealing with the standard input
+ if metadata.output == "-" then
+ exit_on_error(nil, "Empty output filename. Use the -o option")
+ end
+
+ metadata.template, msg = metadata.root and load_template(metadata.root) or default_template
+
+ exit_on_error(metadata.template, msg)
+
+ if arguments.expand then
+ metadata.template = expand(metadata,metadata.template)
+ end
+
+ local full_document, msg = prepare_template(document, metadata.template)
+
+ exit_on_error(full_document, msg)
+
+ if arguments.print then
+ print(full_document)
+ os.exit()
+ end
+
+ local command = prepare_command(metadata, arguments)
+
+ log:info(command)
+ compile(command, full_document)
+else
+ return {
+ prepare_command = prepare_command
+ ,prepare_template = prepare_template
+ ,get_metadata = get_metadata
+ ,use_arguments = use_arguments
+ ,get_preamble = get_preamble
+ ,expand = expand
+ }
+end
+
+
diff --git a/support/texblend/texblend-doc.pdf b/support/texblend/texblend-doc.pdf
new file mode 100644
index 0000000000..f2dd4e45e2
--- /dev/null
+++ b/support/texblend/texblend-doc.pdf
Binary files differ
diff --git a/support/texblend/texblend-doc.tex b/support/texblend/texblend-doc.tex
new file mode 100644
index 0000000000..930680b8af
--- /dev/null
+++ b/support/texblend/texblend-doc.tex
@@ -0,0 +1,46 @@
+\documentclass{article}
+\newcommand\authormail[1]{\footnote{\textless\url{#1}\textgreater}}
+\ifdefined\HCode
+ \renewcommand\authormail[1]{\space\textless\Link[#1]{}{}#1\EndLink\textgreater}
+\fi
+
+\usepackage{longtable}
+\usepackage{tabularx}
+\newenvironment{changelog}{\longtable{@{} l p{30em}}}{\endlongtable}
+\newcommand\change[2]{#1 & #2\\}
+
+\author{Michal Hoftich\authormail{michal.h21@gmail.com}}
+\ifdefined\gitdate\else
+ \def\gitdate{\today}
+ \def\version{devel}
+\fi
+\title{\texttt{\TeX Blend} -- Compile Segments of LaTeX Documents}
+\date{Version \version, \gitdate}
+\usepackage{upquote}
+\usepackage{microtype}
+\usepackage{hyperref}
+\usepackage{fontspec}
+\usepackage{linebreaker}
+\setmainfont{Linux Libertine O}
+\usepackage{luacode}
+\begin{document}
+\maketitle
+\begin{tabular}{l l}
+ Homepage: &\url{https://www.kodymirus.cz/texblend/}\\
+ Issue tracker:& \url{https://github.com/michal-h21/texblend}
+\end{tabular}
+\tableofcontents
+\input{intro}
+\input{usage}
+
+\section{License}
+
+Permission is granted to copy, distribute and/or modify this software
+under the terms of the \LaTeX\ Project Public License, version 1.3.
+
+\section{Changelog}
+\begin{changelog}
+ \change{2023-11-24}{Initial release}
+\end{changelog}
+
+\end{document}
diff --git a/support/texblend/usage.tex b/support/texblend/usage.tex
new file mode 100644
index 0000000000..2289ecad98
--- /dev/null
+++ b/support/texblend/usage.tex
@@ -0,0 +1,107 @@
+% !TEX root = texblend-doc.tex
+% !TEX TS-program = lualatex
+\section{Usage}
+
+The basic usage of \TeX Blend is as follows:
+
+\begin{verbatim}
+$ texblend chapter.tex
+\end{verbatim}
+
+This command combines the text from the document \texttt{chapter.tex} with the preamble
+from the main document specified in the root directive and directly compiles
+the resulting document. The output will be saved as \texttt{chapter.pdf}.
+
+\subsection{Command Line Options}
+
+TeXBlend supports a variety of command-line options:
+
+\begin{verbatim}
+ texblend [options] filename
+
+Available options:
+-e,--expand Expand variables in the template
+-h,--help Print the help message
+-H,--HTML Compile to HTML using TeX4ht
+-l,--lualatex Select lualatex as compiler
+-o,--output (default "") Set the output file name
+-O,--texoptions (default "") Extra options that should be passed
+ to the LaTeX compiler
+-p,--pdflatex Select pdflatex as compiler
+-P,--print Don't compile the document,
+ print the expanded template instead
+-s,--shell-escape Enable execution of external
+ commands in LaTeX
+-t,--template (default "") Use explicit template instead of
+ the one provided in the input file
+-v,--version Print version info
+-x,--xelatex Select xelatex as compiler
+<filename> (string) Use "-" if you want to pass
+ document from the standard input
+\end{verbatim}
+
+You can join multiple short options, for example the following call uses separate short options:
+
+\begin{verbatim}
+$ texblend -e -l -o test chapter.tex
+\end{verbatim}
+
+It can be shortened to this form:
+
+\begin{verbatim}
+$ texblend -elo test chapter.tex
+\end{verbatim}
+
+
+
+\subsection{Compilation Options}
+
+You can override the \verb'program' directive, which specifies the \LaTeX\ engine
+used, with one of the options \verb|--lualatex|, \verb|--xelatex|, or \verb|--pdflatex|.
+The default program used when the document lacks a \verb'program' directive and none of these
+options is used is \verb|pdflatex|.
+
+If the document uses external commands, such as with the Minted or Imakeidx
+packages, you can utilize the \verb|--shell-escape| option.
+
+You can specify additional options for the LaTeX compiler using the \verb|--texoptions| option.
+
+Instead of compiling, you can print the assembled document to standard output
+using the option \verb|--print|.
+
+To change name of the generated PDF file, use the \verb|--output| option.
+
+
+\subsection{Usage of Templates}
+
+
+Instead of the main document specified in the \verb'root' directive, you can use
+another document as a template, chosen using the \verb|--template| option. You
+can use the entire file path or simply specify the file name, making use of the
+\verb'kpsewhich' command (see section~\ref{sec:placement}) to locate the file.
+
+If you are using variables in the template (see section~\ref{sec:variables}), use the
+\verb'--expand' option to expand them with the values specified in the document's
+directives.
+
+
+
+
+\subsection{HTML Support}
+
+\TeX Blend supports direct export to HTML using \TeX4ht. A note regarding the
+\verb|--texoptions| command line option: you can utilize this option to pass all
+command-line arguments to \verb|make4ht|. Ensure to include the \verb|-| character in place
+of the filename for proper execution.
+
+For example, if you want to use the \verb|fn-in| option for endnotes, use the following command:
+
+\begin{verbatim}
+$ texblend -HO '- "fn-in"' chapter.tex
+\end{verbatim}
+
+If you want to use a configuration file in addition, you will need this command:
+
+\begin{verbatim}
+$ texblend -HO '-c config.cfg - "fn-in"' chapter.tex
+\end{verbatim}