From ad976e54f48605a66054bc56e945dabc425c956a Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sat, 25 Nov 2023 03:03:12 +0000 Subject: CTAN sync 202311250303 --- support/texblend/README | 27 ++++ support/texblend/intro.tex | 153 +++++++++++++++++++++ support/texblend/texblend | 280 ++++++++++++++++++++++++++++++++++++++ support/texblend/texblend-doc.pdf | Bin 0 -> 47108 bytes support/texblend/texblend-doc.tex | 46 +++++++ support/texblend/usage.tex | 107 +++++++++++++++ 6 files changed, 613 insertions(+) create mode 100644 support/texblend/README create mode 100644 support/texblend/intro.tex create mode 100644 support/texblend/texblend create mode 100644 support/texblend/texblend-doc.pdf create mode 100644 support/texblend/texblend-doc.tex create mode 100644 support/texblend/usage.tex (limited to 'support') 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 (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 + (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 Binary files /dev/null and b/support/texblend/texblend-doc.pdf 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 + (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} -- cgit v1.2.3