texlive[68961] trunk: texblend (24nov23)
commits+karl at tug.org
commits+karl at tug.org
Fri Nov 24 22:16:55 CET 2023
Revision: 68961
https://tug.org/svn/texlive?view=revision&revision=68961
Author: karl
Date: 2023-11-24 22:16:55 +0100 (Fri, 24 Nov 2023)
Log Message:
-----------
texblend (24nov23)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/Makefile.am
trunk/Build/source/texk/texlive/linked_scripts/Makefile.in
trunk/Build/source/texk/texlive/linked_scripts/scripts.lst
trunk/Master/tlpkg/bin/tlpkg-ctan-check
trunk/Master/tlpkg/libexec/ctan2tds
trunk/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc
Added Paths:
-----------
trunk/Build/source/texk/texlive/linked_scripts/texblend/
trunk/Build/source/texk/texlive/linked_scripts/texblend/texblend
trunk/Master/bin/aarch64-linux/texblend
trunk/Master/bin/amd64-freebsd/texblend
trunk/Master/bin/amd64-netbsd/texblend
trunk/Master/bin/armhf-linux/texblend
trunk/Master/bin/i386-freebsd/texblend
trunk/Master/bin/i386-linux/texblend
trunk/Master/bin/i386-netbsd/texblend
trunk/Master/bin/i386-solaris/texblend
trunk/Master/bin/universal-darwin/texblend
trunk/Master/bin/windows/texblend.exe
trunk/Master/bin/x86_64-cygwin/texblend
trunk/Master/bin/x86_64-darwinlegacy/texblend
trunk/Master/bin/x86_64-linux/texblend
trunk/Master/bin/x86_64-linuxmusl/texblend
trunk/Master/bin/x86_64-solaris/texblend
trunk/Master/texmf-dist/doc/support/texblend/
trunk/Master/texmf-dist/doc/support/texblend/README
trunk/Master/texmf-dist/doc/support/texblend/intro.tex
trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.pdf
trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.tex
trunk/Master/texmf-dist/doc/support/texblend/usage.tex
trunk/Master/texmf-dist/scripts/texblend/
trunk/Master/texmf-dist/scripts/texblend/texblend
trunk/Master/tlpkg/tlpsrc/texblend.tlpsrc
Modified: trunk/Build/source/texk/texlive/linked_scripts/Makefile.am
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/Makefile.am 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Build/source/texk/texlive/linked_scripts/Makefile.am 2023-11-24 21:16:55 UTC (rev 68961)
@@ -225,6 +225,7 @@
sty2dtx/sty2dtx.pl \
svn-multi/svn-multi.pl \
tex4ebook/tex4ebook \
+ texblend/texblend \
texcount/texcount.pl \
texdef/texdef.pl \
texdiff/texdiff \
Modified: trunk/Build/source/texk/texlive/linked_scripts/Makefile.in
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/Makefile.in 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Build/source/texk/texlive/linked_scripts/Makefile.in 2023-11-24 21:16:55 UTC (rev 68961)
@@ -442,6 +442,7 @@
sty2dtx/sty2dtx.pl \
svn-multi/svn-multi.pl \
tex4ebook/tex4ebook \
+ texblend/texblend \
texcount/texcount.pl \
texdef/texdef.pl \
texdiff/texdiff \
Modified: trunk/Build/source/texk/texlive/linked_scripts/scripts.lst
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/scripts.lst 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Build/source/texk/texlive/linked_scripts/scripts.lst 2023-11-24 21:16:55 UTC (rev 68961)
@@ -166,6 +166,7 @@
sty2dtx/sty2dtx.pl
svn-multi/svn-multi.pl
tex4ebook/tex4ebook
+texblend/texblend
texcount/texcount.pl
texdef/texdef.pl
texdiff/texdiff
Added: trunk/Build/source/texk/texlive/linked_scripts/texblend/texblend
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/texblend/texblend (rev 0)
+++ trunk/Build/source/texk/texlive/linked_scripts/texblend/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1,280 @@
+#!/usr/bin/env texlua
+kpse.set_program_name "luatex"
+
+-- TeXBlend -- Compile Segments of LaTeX Documents
+-- Copyright: Michal Hoftich <michal.h21 at 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
+
+
Property changes on: trunk/Build/source/texk/texlive/linked_scripts/texblend/texblend
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/aarch64-linux/texblend
===================================================================
--- trunk/Master/bin/aarch64-linux/texblend (rev 0)
+++ trunk/Master/bin/aarch64-linux/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/aarch64-linux/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/amd64-freebsd/texblend
===================================================================
--- trunk/Master/bin/amd64-freebsd/texblend (rev 0)
+++ trunk/Master/bin/amd64-freebsd/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/amd64-freebsd/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/amd64-netbsd/texblend
===================================================================
--- trunk/Master/bin/amd64-netbsd/texblend (rev 0)
+++ trunk/Master/bin/amd64-netbsd/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/amd64-netbsd/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/armhf-linux/texblend
===================================================================
--- trunk/Master/bin/armhf-linux/texblend (rev 0)
+++ trunk/Master/bin/armhf-linux/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/armhf-linux/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/i386-freebsd/texblend
===================================================================
--- trunk/Master/bin/i386-freebsd/texblend (rev 0)
+++ trunk/Master/bin/i386-freebsd/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/i386-freebsd/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/i386-linux/texblend
===================================================================
--- trunk/Master/bin/i386-linux/texblend (rev 0)
+++ trunk/Master/bin/i386-linux/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/i386-linux/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/i386-netbsd/texblend
===================================================================
--- trunk/Master/bin/i386-netbsd/texblend (rev 0)
+++ trunk/Master/bin/i386-netbsd/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/i386-netbsd/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/i386-solaris/texblend
===================================================================
--- trunk/Master/bin/i386-solaris/texblend (rev 0)
+++ trunk/Master/bin/i386-solaris/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/i386-solaris/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/universal-darwin/texblend
===================================================================
--- trunk/Master/bin/universal-darwin/texblend (rev 0)
+++ trunk/Master/bin/universal-darwin/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/universal-darwin/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/windows/texblend.exe
===================================================================
(Binary files differ)
Index: trunk/Master/bin/windows/texblend.exe
===================================================================
--- trunk/Master/bin/windows/texblend.exe 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Master/bin/windows/texblend.exe 2023-11-24 21:16:55 UTC (rev 68961)
Property changes on: trunk/Master/bin/windows/texblend.exe
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Added: svn:mime-type
## -0,0 +1 ##
+application/octet-stream
\ No newline at end of property
Added: trunk/Master/bin/x86_64-cygwin/texblend
===================================================================
--- trunk/Master/bin/x86_64-cygwin/texblend (rev 0)
+++ trunk/Master/bin/x86_64-cygwin/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/x86_64-cygwin/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/x86_64-darwinlegacy/texblend
===================================================================
--- trunk/Master/bin/x86_64-darwinlegacy/texblend (rev 0)
+++ trunk/Master/bin/x86_64-darwinlegacy/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/x86_64-darwinlegacy/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/x86_64-linux/texblend
===================================================================
--- trunk/Master/bin/x86_64-linux/texblend (rev 0)
+++ trunk/Master/bin/x86_64-linux/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/x86_64-linux/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/x86_64-linuxmusl/texblend
===================================================================
--- trunk/Master/bin/x86_64-linuxmusl/texblend (rev 0)
+++ trunk/Master/bin/x86_64-linuxmusl/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/x86_64-linuxmusl/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/bin/x86_64-solaris/texblend
===================================================================
--- trunk/Master/bin/x86_64-solaris/texblend (rev 0)
+++ trunk/Master/bin/x86_64-solaris/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+link ../../texmf-dist/scripts/texblend/texblend
\ No newline at end of file
Property changes on: trunk/Master/bin/x86_64-solaris/texblend
___________________________________________________________________
Added: svn:special
## -0,0 +1 ##
+*
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/support/texblend/README
===================================================================
--- trunk/Master/texmf-dist/doc/support/texblend/README (rev 0)
+++ trunk/Master/texmf-dist/doc/support/texblend/README 2023-11-24 21:16:55 UTC (rev 68961)
@@ -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.
Property changes on: trunk/Master/texmf-dist/doc/support/texblend/README
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/support/texblend/intro.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/texblend/intro.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/support/texblend/intro.tex 2023-11-24 21:16:55 UTC (rev 68961)
@@ -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.
+
Property changes on: trunk/Master/texmf-dist/doc/support/texblend/intro.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.pdf 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.pdf 2023-11-24 21:16:55 UTC (rev 68961)
Property changes on: trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.tex 2023-11-24 21:16:55 UTC (rev 68961)
@@ -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 at 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}
Property changes on: trunk/Master/texmf-dist/doc/support/texblend/texblend-doc.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/support/texblend/usage.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/texblend/usage.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/support/texblend/usage.tex 2023-11-24 21:16:55 UTC (rev 68961)
@@ -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}
Property changes on: trunk/Master/texmf-dist/doc/support/texblend/usage.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/scripts/texblend/texblend
===================================================================
--- trunk/Master/texmf-dist/scripts/texblend/texblend (rev 0)
+++ trunk/Master/texmf-dist/scripts/texblend/texblend 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1,280 @@
+#!/usr/bin/env texlua
+kpse.set_program_name "luatex"
+
+-- TeXBlend -- Compile Segments of LaTeX Documents
+-- Copyright: Michal Hoftich <michal.h21 at 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
+
+
Property changes on: trunk/Master/texmf-dist/scripts/texblend/texblend
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Modified: trunk/Master/tlpkg/bin/tlpkg-ctan-check
===================================================================
--- trunk/Master/tlpkg/bin/tlpkg-ctan-check 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Master/tlpkg/bin/tlpkg-ctan-check 2023-11-24 21:16:55 UTC (rev 68961)
@@ -813,7 +813,7 @@
tex-ewd tex-font-errors-cheatsheet tex-gyre tex-gyre-math tex-ini-files
tex-label tex-locale tex-nutshell tex-overview tex-ps
tex-refs tex-virtual-academy-pl tex-vpat
- tex4ebook texaccents texapi texbytopic texcount
+ tex4ebook texaccents texapi texblend texbytopic texcount
texdate texdef texdiff texdimens texdirflatten texdoc texdraw
texfindpkg texfot texinfo texilikechaps texilikecover
texliveonfly texloganalyser texlogfilter texlogos texlogsieve
Modified: trunk/Master/tlpkg/libexec/ctan2tds
===================================================================
--- trunk/Master/tlpkg/libexec/ctan2tds 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Master/tlpkg/libexec/ctan2tds 2023-11-24 21:16:55 UTC (rev 68961)
@@ -3800,6 +3800,7 @@
'svn-multi' => 'svn-multi\.pl$',
'tex4ebook' => 'tex4ebook$',
'texaccents' => 'texaccents.sno',
+ 'texblend' => 'texblend$',
'texcount' => '\.pl$',
'texdef' => '\.pl$',
'texdiff' => 'texdiff$',
Modified: trunk/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc
===================================================================
--- trunk/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc 2023-11-24 21:13:10 UTC (rev 68960)
+++ trunk/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc 2023-11-24 21:16:55 UTC (rev 68961)
@@ -89,6 +89,7 @@
depend synctex
depend tex4ebook
depend texaccents
+depend texblend
depend texcount
depend texdef
depend texdiff
Added: trunk/Master/tlpkg/tlpsrc/texblend.tlpsrc
===================================================================
--- trunk/Master/tlpkg/tlpsrc/texblend.tlpsrc (rev 0)
+++ trunk/Master/tlpkg/tlpsrc/texblend.tlpsrc 2023-11-24 21:16:55 UTC (rev 68961)
@@ -0,0 +1 @@
+binpattern f bin/${ARCH}/${PKGNAME}
More information about the tex-live-commits
mailing list.