summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/CHANGES53
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/README.md51
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdfbin720287 -> 714622 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-en.xml12
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-nl.xml13
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/bib2gls.pdfbin5353372 -> 5486421 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdfbin51552 -> 51552 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdfbin54280 -> 54280 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdfbin54064 -> 54064 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdfbin49744 -> 49744 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdfbin97818 -> 97818 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdfbin52553 -> 52553 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdfbin61149 -> 61149 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdfbin121252 -> 121252 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdfbin166586 -> 166586 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdfbin109247 -> 109247 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdfbin255473 -> 255473 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdfbin330879 -> 330879 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdfbin52565 -> 52565 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdfbin50319 -> 50319 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdfbin73095 -> 73095 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdfbin70301 -> 70301 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdfbin57344 -> 57344 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdfbin59080 -> 59080 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdfbin44643 -> 44643 bytes
-rw-r--r--Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdfbin24421 -> 23827 bytes
-rw-r--r--Master/texmf-dist/doc/support/checkcites/README4
-rw-r--r--Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdfbin296081 -> 296211 bytes
-rw-r--r--Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex10
-rw-r--r--Master/texmf-dist/doc/support/crossrefware/Makefile5
-rw-r--r--Master/texmf-dist/doc/support/crossrefware/README9
-rw-r--r--Master/texmf-dist/doc/support/crossrefware/crossrefware.pdfbin234836 -> 236994 bytes
-rw-r--r--Master/texmf-dist/doc/support/crossrefware/head.ltx17
-rw-r--r--Master/texmf-dist/doc/support/digestif/INSTALL.md4
-rw-r--r--Master/texmf-dist/doc/support/digestif/LICENSE.md14
-rw-r--r--Master/texmf-dist/doc/support/digestif/README.md24
-rwxr-xr-xMaster/texmf-dist/doc/support/digestif/bin/digestif3
-rw-r--r--Master/texmf-dist/doc/support/easydtx/CHANGELOG.md15
-rw-r--r--Master/texmf-dist/doc/support/easydtx/FILES2
-rw-r--r--Master/texmf-dist/doc/support/easydtx/README.md17
-rw-r--r--Master/texmf-dist/doc/support/easydtx/easydoctex-mode.el2
-rw-r--r--Master/texmf-dist/doc/support/easydtx/edtx2dtx.1.md91
-rw-r--r--Master/texmf-dist/doc/support/expltools/CHANGES.md133
-rw-r--r--Master/texmf-dist/doc/support/expltools/README.md100
-rw-r--r--Master/texmf-dist/doc/support/expltools/e102.tex12
-rw-r--r--Master/texmf-dist/doc/support/expltools/e104.tex5
-rw-r--r--Master/texmf-dist/doc/support/expltools/latexmkrc9
-rw-r--r--Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools.sty9
-rw-r--r--Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_project-proposal.sty19
-rw-r--r--Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_warnings-and-errors.sty211
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal-01-introduction.md28
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal-02-requirements.md106
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal-03-related-work.md64
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal-04-design.md75
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal-05-benefits-of-grant-funding.md7
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal.cls16
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal.pdfbin0 -> 67243 bytes
-rw-r--r--Master/texmf-dist/doc/support/expltools/project-proposal.tex14
-rw-r--r--Master/texmf-dist/doc/support/expltools/s103.tex2
-rw-r--r--Master/texmf-dist/doc/support/expltools/w100.tex11
-rw-r--r--Master/texmf-dist/doc/support/expltools/w101.tex14
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-00-introduction.md43
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-01-preprocessing.md29
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-02-lexical-analysis.md157
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-03-syntactic-analysis.md26
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-04-semantic-analysis.md510
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-05-flow-analysis.md651
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors-99-caveats.md141
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors.bib55
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors.cls24
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors.ist4
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors.pdfbin0 -> 2780745 bytes
-rw-r--r--Master/texmf-dist/doc/support/expltools/warnings-and-errors.tex24
-rw-r--r--Master/texmf-dist/doc/support/extractbb/README.md81
-rw-r--r--Master/texmf-dist/doc/support/extractbb/extractbb.man1.pdfbin0 -> 20362 bytes
-rw-r--r--Master/texmf-dist/doc/support/fontools/LICENSE (renamed from Master/texmf-dist/doc/support/fontools/GPLv2.txt)0
-rw-r--r--Master/texmf-dist/doc/support/fontools/README84
-rw-r--r--Master/texmf-dist/doc/support/fontools/README.md93
-rwxr-xr-xMaster/texmf-dist/doc/support/fontools/splitttc8
-rw-r--r--Master/texmf-dist/doc/support/latexdiff/README55
-rw-r--r--Master/texmf-dist/doc/support/latexdiff/doc/example-diff.tex4
-rw-r--r--Master/texmf-dist/doc/support/latexdiff/doc/latexdiff-man.pdfbin272513 -> 290596 bytes
-rwxr-xr-xMaster/texmf-dist/doc/support/latexdiff/latexdiff836
-rwxr-xr-xMaster/texmf-dist/doc/support/latexdiff/latexdiff-fast836
-rw-r--r--Master/texmf-dist/doc/support/latexmk/CHANGES24
-rw-r--r--Master/texmf-dist/doc/support/latexmk/INSTALL14
-rw-r--r--Master/texmf-dist/doc/support/latexmk/README4
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/bib2gls_latexmkrc60
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc64
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/splitindex_latexmkrc134
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/xr_latexmkrc6
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.pdfbin241304 -> 242685 bytes
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.txt3064
-rw-r--r--Master/texmf-dist/doc/support/luafindfont/CHANGELOG1
-rw-r--r--Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.pdfbin98571 -> 98752 bytes
-rw-r--r--Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.tex4
-rw-r--r--Master/texmf-dist/doc/support/make4ht/README21
-rw-r--r--Master/texmf-dist/doc/support/make4ht/changelog.tex130
-rw-r--r--Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdfbin161887 -> 165750 bytes
-rw-r--r--Master/texmf-dist/doc/support/make4ht/readme.tex21
-rw-r--r--Master/texmf-dist/doc/support/pdfjam/COPYING44
-rw-r--r--Master/texmf-dist/doc/support/pdfjam/README.md291
-rw-r--r--Master/texmf-dist/doc/support/pdfjam/VERSION1
-rw-r--r--Master/texmf-dist/doc/support/pdfjam/VERSION-4.001
-rw-r--r--Master/texmf-dist/doc/support/pdfjam/pdfjam.conf22
-rw-r--r--Master/texmf-dist/doc/support/pdfjam/tests.zipbin148376 -> 0 bytes
-rw-r--r--Master/texmf-dist/doc/support/pdflatexpicscale/README4
-rw-r--r--Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdfbin117642 -> 127589 bytes
-rw-r--r--Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex100
-rw-r--r--Master/texmf-dist/doc/support/pdflatexpicscale/testprinter.ps2
-rw-r--r--Master/texmf-dist/doc/support/ppmcheckpdf/README.txt2
-rw-r--r--Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.pdfbin25067 -> 72974 bytes
-rw-r--r--Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.tex50
-rw-r--r--Master/texmf-dist/doc/support/sqltex/SQLTeX.pdfbin0 -> 311719 bytes
-rw-r--r--Master/texmf-dist/doc/support/sqltex/SQLTeX.tex1050
-rw-r--r--Master/texmf-dist/doc/support/texfindpkg/README.md49
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/README.md1
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdfbin60722 -> 61082 bytes
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex11
-rw-r--r--Master/texmf-dist/doc/support/tlaunch/Changes8
120 files changed, 7279 insertions, 2746 deletions
diff --git a/Master/texmf-dist/doc/support/bib2gls/CHANGES b/Master/texmf-dist/doc/support/bib2gls/CHANGES
index 88157ab29d6..8c57e38ee37 100644
--- a/Master/texmf-dist/doc/support/bib2gls/CHANGES
+++ b/Master/texmf-dist/doc/support/bib2gls/CHANGES
@@ -1,3 +1,56 @@
+v4.1 (2025-01-03)
+
+ * bib2gls
+
+ - added resource options:
+
+ omit-fields
+ omit-fields-missing-field-action
+ gather-parsed-dependencies
+
+ - added \BibGlsNoCaseChange
+
+v4.0a (2024-12-15)
+
+Corrected distribution (missing files).
+
+v4.0 (2024-12-14)
+
+ * bib2gls
+
+ - added \INTERPRETNOREPL and \REPLACESPCHARS quarks
+
+ - added action=provide
+
+ - added new resource options:
+
+ wordify-math-greek
+ wordify-math-symbol
+ ignored-type
+
+ - added support for \BibGlsOptions and \IfNotBibGls
+ (provided by glossaries-extra v1.54+)
+
+ - added switch --[no-]datatool-sort-markers
+
+ - bug fix: indexplural not setting text field if missing, which
+ results in the text field defaulting to the plural form.
+
+ - bug fix issue #29 "Version 3.8 and 3.9 fail to find aux files in subdirectories of build directory"
+ https://github.com/nlct/bib2gls/issues/29
+
+ - bug fix: complex conditional relations <> <= and >=
+ incorrectly parsing quoted rhs
+
+ - bash script no longer sets java.locale.providers when running the jar file
+ (not necessary for Java 9 onwards)
+
+ * convertgls2bib
+
+ - added support for \loadglsentries
+
+ * Added datatool2bib command-line conversion tool.
+
v3.9 (2024-01-30)
* bib2gls
diff --git a/Master/texmf-dist/doc/support/bib2gls/README.md b/Master/texmf-dist/doc/support/bib2gls/README.md
index 2627a963a16..c1e0ad4ffcf 100644
--- a/Master/texmf-dist/doc/support/bib2gls/README.md
+++ b/Master/texmf-dist/doc/support/bib2gls/README.md
@@ -7,23 +7,32 @@ Author: Nicola Talbot (https://www.dickimaw-books.com/contact)
Application Home Page: https://www.dickimaw-books.com/software/bib2gls
-# Licence
+Version details of the current installation can be obtained with
+`--version` or `-v`:
-Copyright (C) 2017-2024 Nicola L. C. Talbot (dickimaw-books.com)
+```bash
+bib2gls --version
+convertgls2bib --version
+datatool2bib --version
+```
+
+## Licence
+
+Copyright (C) 2017-2025 Nicola L. C. Talbot (dickimaw-books.com)
License GPLv3+: GNU GPL version 3 or later
http://gnu.org/licenses/gpl.html
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
-# Requirements
+## Requirements
- Java Runtime Environment (at least Java 8).
- TeX distribution that includes `glossaries-extra.sty`
and dependent packages (such as `glossaries.sty`).
-# Summary
+## Summary
This application may be used to extract glossary information
stored in a `.bib` file and convert it into glossary entry
@@ -42,6 +51,10 @@ in a system such as JabRef, and only the entries that are
actually required will be defined, reducing the resources
required by TeX.
+##Supplementary applications
+
+### `convertgls2bib`
+
The supplementary application `convertgls2bib` can be used
to convert existing `.tex` files containing definitions
(`\newglossaryentry` etc) to the `.bib` format
@@ -64,7 +77,7 @@ convertgls2tex entries.tex entries.bib
```
to create `entries.bib`.
-# Example
+## Example
File `entries.bib`:
@@ -124,7 +137,12 @@ pdflatex myDoc
(Replace `pdflatex` with `latex`, `xelatex` or `lualatex` as
appropriate.)
-# Related Resources
+### `datatool2bib`.
+
+The supplementary application `datatool2bib` can be used to convert
+`datatool` databases to `.bib` files suitable for use with `bib2gls`.
+
+## Related Resources
- [bib2gls FAQ](https://www.dickimaw-books.com/faq.php?category=bib2gls).
- [bib2gls gallery](https://www.dickimaw-books.com/gallery/#bib2gls).
@@ -140,25 +158,34 @@ TUGboat articles:
poisons), issue [43:1, 2022](https://tug.org/TUGboat/Contents/contents43-1.html).
[(PDF)](https://tug.org/TUGboat/tb43-1/tb133talbot-bib2gls-reorder.pdf)
-# Installation
+## Installation
The files should be installed as follows where *TEXMF* indicates
your local or home TEXMF path (for example, `~/texmf/`):
- *TEXMF*`/scripts/bib2gls/bib2gls.jar` (Java application.)
- *TEXMF*`/scripts/bib2gls/convertgls2bib.jar` (Java application.)
+ - *TEXMF*`/scripts/bib2gls/datatool2bib.jar` (Java application.)
+ - *TEXMF*`/scripts/bib2gls/bibglscommon.jar` (Java library
+ providing code shared by `bib2gls` and the conversion tools.)
- *TEXMF*`/scripts/bib2gls/texparserlib.jar` (Java library.)
- - *TEXMF*`/scripts/bib2gls/resources/bib2gls-en.xml` (English
+ - *TEXMF*`/scripts/bib2gls/resources/bib2gls-en.xml` (main English
resource file.)
+ - *TEXMF*`/scripts/bib2gls/resources/bib2gls-extra-en.xml`
+ (supplementary English resource file.)
+ - *TEXMF*`/scripts/bib2gls/resources/bib2gls-extra-nl.xml`
+ (supplementary Dutch resource file.)
- *TEXMF*`/scripts/bib2gls/bib2gls.sh` (Unix-like systems only.)
- *TEXMF*`/scripts/bib2gls/convertgls2bib.sh` (Unix-like systems
only.)
+ - *TEXMF*`/scripts/bib2gls/datatool2bib.sh` (Unix-like systems
+ only.)
- *TEXMF*`/doc/support/bib2gls/bib2gls.pdf` (User manual.)
- *TEXMF*`/doc/support/bib2gls/bib2gls-begin.pdf` (Introductory Guide.)
- *TEXMF*`/doc/support/bib2gls/examples/` (example files)
Note that `texparserlib.jar` isn't an application. It's
-a library used by `bib2gls.jar` and `convertgls2bib.jar`
+a library used by `bib2gls.jar` and the `*2bib` conversion tools
and so needs to be on the same class path as them.
The bash `.sh` scripts are provided for Unix-like users.
@@ -173,7 +200,7 @@ convertgls2bib --version
```
These should display the version details.
-# Source Code
+## Source Code
Instructions for compiling the manual and jar files are listed
below. The source is also available on GitHub, but that may be for
@@ -183,7 +210,7 @@ a newer experimental version.
- https://github.com/nlct/texparser
-## User Manual (bib2gls.pdf)
+### User Manual (bib2gls.pdf)
The examples directory needs to be ../examples relative to directory
containing bib2gls.tex as the .bib, .tex and .pdf files are included
@@ -201,7 +228,7 @@ xelatex bib2gls
Similarly for the bib2gls-begin.pdf document.
-## JAR Files
+### JAR Files
Create the following directories:
diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
index 3f1c63c4f0a..6b28722213a 100644
--- a/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls-begin.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-en.xml b/Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-en.xml
deleted file mode 100644
index 4606aebe114..00000000000
--- a/Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-en.xml
+++ /dev/null
@@ -1,12 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
-<properties>
-<comment>Additional English language file for bib2gls</comment>
-
-<entry key="tag.en.page">Page</entry>
-<entry key="tag.en.pages">Pages</entry>
-<entry key="tag.en.passim">passim</entry>
-
-<entry key="sentence.en.terminators">.?!</entry>
-
-</properties>
diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-nl.xml b/Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-nl.xml
deleted file mode 100644
index cd5b926c6ce..00000000000
--- a/Master/texmf-dist/doc/support/bib2gls/bib2gls-extra-nl.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
-<properties>
-<comment>Additional Dutch language file for bib2gls</comment>
-
-<entry key="grouptitle.case.nl.ij">IJ</entry>
-
-<entry key="sentencecase.nl.ij">IJ</entry>
-<entry key="nonsentencecase.nl.IJ">ij</entry>
-
-<entry key="sentence.nl.terminators">.?!</entry>
-
-</properties>
diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
index 454b11c159f..25dd4193310 100644
--- a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
index da70242ba98..ab77cca78e1 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-authors.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
index 96501a8a27e..9d2f6b412cc 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-bacteria.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
index 18ab24c96f2..3c50ebfc8f8 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-chemical.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
index 088c11e28ec..da21fbd9cbc 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-citations.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
index 648240c6b0c..634a82fc6fc 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-constants.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf
index 0548bc8ba8d..3bd317511e8 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-hierarchical.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf
index f2a404af38d..b172d129077 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-markuplanguages.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
index d394c64cfb3..8c5271f53a6 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-maths.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
index c708d921655..fb831a78f4f 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-media.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
index f2c35880378..e656893e591 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-msymbols.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
index 6c63366549d..2fdac02fb86 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi1.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
index 4bb1cc66356..321f02fdba6 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-multi2.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf
index 4ee84daa5e8..76bd23cb237 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-nested.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
index ad10280f4a6..69d6b0f5698 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-people.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
index 2b4973e3a90..7dc2cfa528c 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdf
index 32d4e2bbc11..fbe93b50dca 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-textsymbols2.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
index 47316136fa8..8a274954e71 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units1.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
index e93385441e9..1bfec41ad71 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units2.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
index c7e98f02963..ca86f2bc021 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-units3.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf b/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
index a411f9a669f..459ad803d14 100644
--- a/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
+++ b/Master/texmf-dist/doc/support/bib2gls/examples/sample-usergroups.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/checkcites/README b/Master/texmf-dist/doc/support/checkcites/README
index 4e1c29f0c46..30026de3e43 100644
--- a/Master/texmf-dist/doc/support/checkcites/README
+++ b/Master/texmf-dist/doc/support/checkcites/README
@@ -1,5 +1,5 @@
-checkcites.lua -- Version 2.7 from March 3, 2024
-================================================
+checkcites.lua -- Version 2.8 from December 14, 2024
+====================================================
License
-------
diff --git a/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf
index 4f8f8f35ec7..6b14ec24781 100644
--- a/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf
+++ b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex
index 2b1dbfa163f..11fc99aba5b 100644
--- a/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex
+++ b/Master/texmf-dist/doc/support/checkcites/checkcites-doc.tex
@@ -20,7 +20,7 @@
\newcommand{\checkcites}{\texttt{checkcites}}
\newcommand{\email}[1]{\small\texttt{#1}}
-\newcommand{\version}{Version 2.7 from March 3, 2024.}
+\newcommand{\version}{Version 2.8 from December 14, 2024.}
\newenvironment{infoblock}[1]
{\par\addvspace{\medskipamount}
@@ -229,7 +229,7 @@ $ checkcites
| _| | -_| _| '_| _| | _| -_|_ -|
|___|_|_|___|___|_,_|___|_|_| |___|___|
-checkcites.lua -- a reference checker script (v2.7)
+checkcites.lua -- a reference checker script (v2.8)
Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
Copyright (c) 2024, Enrico Gregorio, Island of TeX
@@ -266,7 +266,7 @@ $ checkcites --help
| _| | -_| _| '_| _| | _| -_|_ -|
|___|_|_|___|___|_,_|___|_|_| |___|___|
-checkcites.lua -- a reference checker script (v2.7)
+checkcites.lua -- a reference checker script (v2.8)
Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
Copyright (c) 2024, Enrico Gregorio, Island of TeX
@@ -329,7 +329,7 @@ $ checkcites document.aux
| _| | -_| _| '_| _| | _| -_|_ -|
|___|_|_|___|___|_,_|___|_|_| |___|___|
-checkcites.lua -- a reference checker script (v2.7)
+checkcites.lua -- a reference checker script (v2.8)
Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
Copyright (c) 2024, Enrico Gregorio, Island of TeX
@@ -471,7 +471,7 @@ $ checkcites --backend biber document.bcf
| _| | -_| _| '_| _| | _| -_|_ -|
|___|_|_|___|___|_,_|___|_|_| |___|___|
-checkcites.lua -- a reference checker script (v2.7)
+checkcites.lua -- a reference checker script (v2.8)
Copyright (c) 2012, 2019, Enrico Gregorio, Paulo Cereda
Copyright (c) 2024, Enrico Gregorio, Island of TeX
diff --git a/Master/texmf-dist/doc/support/crossrefware/Makefile b/Master/texmf-dist/doc/support/crossrefware/Makefile
index c8caf35d606..fb54525cbaf 100644
--- a/Master/texmf-dist/doc/support/crossrefware/Makefile
+++ b/Master/texmf-dist/doc/support/crossrefware/Makefile
@@ -25,6 +25,11 @@ check:
pod2man -c "LATEX CROSSREFWARE" -n $* -s 1 -r "" $< > $@
+lastrel = /home/ftp/tex-archive/support/crossrefware
+reldiff:
+ diff -u0r $(lastrel) .
+gitdiff:
+ git diff
clean:
$(RM) *.aux *.toc *.log *.tex *.idx *.ilg *.ind *.out *.zip *.tgz *~
diff --git a/Master/texmf-dist/doc/support/crossrefware/README b/Master/texmf-dist/doc/support/crossrefware/README
index 05d375253e9..d2de384b799 100644
--- a/Master/texmf-dist/doc/support/crossrefware/README
+++ b/Master/texmf-dist/doc/support/crossrefware/README
@@ -1,5 +1,5 @@
Crossrefware Bundle
- version 2024-01-31
+ version 2024-08-27
Scripts useful for working with Crossref, MathSciNet and Zentralblatt MATH.
@@ -30,9 +30,14 @@ Princeton University (Mathematics Department). Thank you!
Changes:
+2024-08-27 - output crossref schema 5.3.1:
+ https://www.crossref.org/documentation/schema-library/schema-versions/
+ (and update various doc urls that crossref broke.)
+ - more documentation on the bib*add scripts.
+
2024-01-31 - exit with bad status if no \end{thebibliography}.
-2022-09-11 - add "***" prefix to bib warnings.
+2022-09-11 - add "*** " prefix to bib warnings.
2022-07-28 - find dev checkout of bibtexperllibs.
diff --git a/Master/texmf-dist/doc/support/crossrefware/crossrefware.pdf b/Master/texmf-dist/doc/support/crossrefware/crossrefware.pdf
index 83b8d3e8a38..18c39074d50 100644
--- a/Master/texmf-dist/doc/support/crossrefware/crossrefware.pdf
+++ b/Master/texmf-dist/doc/support/crossrefware/crossrefware.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/crossrefware/head.ltx b/Master/texmf-dist/doc/support/crossrefware/head.ltx
index 72ae89028e6..21d2b2d9bb1 100644
--- a/Master/texmf-dist/doc/support/crossrefware/head.ltx
+++ b/Master/texmf-dist/doc/support/crossrefware/head.ltx
@@ -30,13 +30,15 @@ upload the submission, just outputs XML.
This \path{.rpi} file is a plain text representation of the metadata for
one article. It is written by the \path{resphilosophica} package
-(\url{https://ctan.org/pkg/resphilosophica}). It can also be created by
-hand.
+(\url{https://ctan.org/pkg/resphilosophica}) and the TUGboat publication
+procedure (\url{https://tug.org/TUGboat/repository.html}). It can also
+be created by hand.
Several scripts, \path{bibdoiadd}, \path{bibmradd} and \path{bibzbladd}
take a \path{bib} file, and add to each entry a DOI, MR or ZBL number
correspondingly, if they can find this entry in the corresponding
-database.
+database. The output of these scripts reformats the BibTeX entries
+where the respective fields were not already present.
The \path{bbl2bib} script tries to reconstruct a \path{bib} file from the
corresponding \path{thebibliography} environment. One can argue that
@@ -44,7 +46,10 @@ this operation is akin to reconstructing the cow from a steak. The
way the script does it is by searching for the entry in the MR database,
and creating the corresponding Bib\TeX\ fields.
-I am grateful to Josko Plazonic from Princeton Math Dept whose
-(unpublished) Python script was an inspiration for this suite.
+I am grateful to Josko Plazonic from the Princeton mathematics
+department whose (unpublished) Python script was an inspiration for this
+suite.
-Following are manual pages for these scripts.
+Following are manual pages for these scripts. See also the
+\texttt{BibTeX::Parser} package
+(\url{https://ctan.org/pkg/bibtexperllibs}).
diff --git a/Master/texmf-dist/doc/support/digestif/INSTALL.md b/Master/texmf-dist/doc/support/digestif/INSTALL.md
index f99f4b286ae..ff4ac037e0a 100644
--- a/Master/texmf-dist/doc/support/digestif/INSTALL.md
+++ b/Master/texmf-dist/doc/support/digestif/INSTALL.md
@@ -59,12 +59,12 @@ Packaging for a TeX distribution
--------------------------------
For an installation depending only on the `texlua` interpreter from
-LuaTeX (which already includes all other dependencies except cjson),
+LuaTeX (which bundles all dependencies except the optional cjson),
create a zip file containing `digestif/*.lua` and `data/*.tags` (no
subdirectories), place it anywhere kpathsearch will find it and use
the `bin/digestif.texlua` executable script. For instance:
- zip -j digestif.zip digestif/*.lua tags/*.tags
+ zip -j digestif.zip digestif/*.lua data/*.tags
install -Dt $TEXMF/scripts digestif.zip
install bin/digestif.texlua $PREFIX/bin/digestif
diff --git a/Master/texmf-dist/doc/support/digestif/LICENSE.md b/Master/texmf-dist/doc/support/digestif/LICENSE.md
index 55165a272d6..2b19eb74af7 100644
--- a/Master/texmf-dist/doc/support/digestif/LICENSE.md
+++ b/Master/texmf-dist/doc/support/digestif/LICENSE.md
@@ -119,6 +119,20 @@ latex.tags:
Adapted from the LaTeX2e Unofficial Reference Manual, which can be found at
https://latexref.xyz/.
+natbib.sty.tags:
+
+ Copyright 1993-2010 Patrick W Daly
+
+ This file 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.
+
+ Adapted from the natbib package documentation, which can be found at
+ https://ctan.org/pkg/natbib
+
pgf.tags:
Copyright 2007-2013 Till Tantau
diff --git a/Master/texmf-dist/doc/support/digestif/README.md b/Master/texmf-dist/doc/support/digestif/README.md
index a7528020ece..25b4fe49209 100644
--- a/Master/texmf-dist/doc/support/digestif/README.md
+++ b/Master/texmf-dist/doc/support/digestif/README.md
@@ -2,7 +2,7 @@ Digestif
========
<p align="center">
-<a href="https://app.travis-ci.com/astoff/digestif"><img src="https://app.travis-ci.com/astoff/digestif.svg?branch=main" alt="Build Status"></a>
+<a href="https://github.com/astoff/digestif/actions/workflows/test.yml"><img src="https://github.com/astoff/digestif/actions/workflows/test.yml/badge.svg"></a>
<a href="https://ctan.org/pkg/digestif"><img alt="CTAN" src="https://img.shields.io/ctan/v/digestif?color=blue"></a>
<a href="https://luarocks.org/modules/astoff/digestif"><img alt="LuaRocks" src="https://img.shields.io/luarocks/v/astoff/digestif?color=blue"></a>
</p>
@@ -12,18 +12,20 @@ ConTeXt et caterva. It provides context-sensitive completion,
documentation, code navigation, and related functionality to any text
editor that speaks the LSP protocol.
-<p align="center"><img src="https://raw.githubusercontent.com/astoff/digestif/images/screenshot.gif" alt="Madatory GIF"></p>
-
Features
--------
- Completion for commands, environments, key-value options (for
instance, TikZ options), cross-references and citations.
+ <p align="center"><img src="https://raw.githubusercontent.com/astoff/digestif/images/completion.png"></p>
+
- Popup help messages, including command signature and documentation.
For the best results, make sure you have the [LaTeX reference
manual][latexref] installed as an [info node][info-issues].
+ <p align="center"><img src="https://raw.githubusercontent.com/astoff/digestif/images/help.png"></p>
+
- Find definition and references to labels and citations.
- Document outline.
@@ -37,12 +39,16 @@ Features
- Digestif is fuzzy! For citations, it tries an exact match against
the BibTeX identifier and a fuzzy match against author and title.
- In the GIF above, the user types `groalhom`, which matches
+ In the picture below, the user typed `groalhom`, which matches
**Gro**thendieck's “Sur quelques points d'**al**gébre
**hom**ologique”; selecting this inserts the BibTeX identifier
- `Tohoku`. Similarly, for cross-references, Digestif tries an exact
- match against the label and a fuzzy match against the text around
- the label.
+ `Tohoku`.
+
+ <p align="center"><img src="https://raw.githubusercontent.com/astoff/digestif/images/cite.png"></p>
+
+ Similarly, for cross-references, Digestif tries an exact match
+ against the label and a fuzzy match against the text around the
+ label.
- Support for LaTeX, ConTeXt, plain TeX, DocTeX (`.dtx` files) and
Texinfo.
@@ -112,6 +118,10 @@ To ensure that Digestif is used, add the following to your init file:
See instructions [here](https://github.com/neoclide/coc.nvim/wiki/Language-servers#latex).
+### Sublime Text with the [LSP](https://packagecontrol.io/packages/LSP) package
+
+See instructions [here](https://lsp.sublimetext.io/language_servers/#digestif).
+
### Other editors
It shouldn't be hard to set up other editors to use Digestif. Please
diff --git a/Master/texmf-dist/doc/support/digestif/bin/digestif b/Master/texmf-dist/doc/support/digestif/bin/digestif
index 818d5b355ac..73b51457b46 100755
--- a/Master/texmf-dist/doc/support/digestif/bin/digestif
+++ b/Master/texmf-dist/doc/support/digestif/bin/digestif
@@ -1,2 +1,5 @@
#!/usr/bin/env lua
+-- Remove relative directories from package path
+package.path = package.path:gsub("%f[^\0;]%.[^;]*", ""):gsub(";+", ";"):gsub("^;", ""):gsub(";$", "")
+package.cpath = package.cpath:gsub("%f[^\0;]%.[^;]*", ""):gsub(";+", ";"):gsub("^;", ""):gsub(";$", "")
require "digestif.langserver".main(arg)
diff --git a/Master/texmf-dist/doc/support/easydtx/CHANGELOG.md b/Master/texmf-dist/doc/support/easydtx/CHANGELOG.md
new file mode 100644
index 00000000000..cf8d2605a3f
--- /dev/null
+++ b/Master/texmf-dist/doc/support/easydtx/CHANGELOG.md
@@ -0,0 +1,15 @@
+# EasyDTX changelog
+
+For the development history, see [EasyDTX's GitHub
+repository](https://github.com/sasozivanovic/easydtx).
+
+## 2024/11/23 v0.2.0
+
+* Generalize to support comments in other programming languages
+ (used to typeset documented code of Memoize's extraction scripts).
+
+* Fix some minor issues with the documentation and the licence.
+
+## 2023/10/10 v0.1.0
+
+The initial release.
diff --git a/Master/texmf-dist/doc/support/easydtx/FILES b/Master/texmf-dist/doc/support/easydtx/FILES
index 92d2e3c04fd..77b5eee2eb4 100644
--- a/Master/texmf-dist/doc/support/easydtx/FILES
+++ b/Master/texmf-dist/doc/support/easydtx/FILES
@@ -1,6 +1,8 @@
doc/man/man1/edtx2dtx.1
doc/support/easydtx/LICENCE
doc/support/easydtx/easydoctex-mode.el
+doc/support/easydtx/edtx2dtx.1.md
+doc/support/easydtx/CHANGELOG.md
doc/support/easydtx/FILES
doc/support/easydtx/README.md
scripts/easydtx/edtx2dtx.pl
diff --git a/Master/texmf-dist/doc/support/easydtx/README.md b/Master/texmf-dist/doc/support/easydtx/README.md
index 8f0030b03b4..ed36bf25d2c 100644
--- a/Master/texmf-dist/doc/support/easydtx/README.md
+++ b/Master/texmf-dist/doc/support/easydtx/README.md
@@ -8,3 +8,20 @@ An `.edtx` file is converted to a `.dtx` by a little Perl script called
forward and inverse search. (The script does what it should, and would really
deserve version 1.0.0. The Emacs mode, however, is just something that works
well enough for me.)
+
+# LICENCE
+
+Copyright (c) 2023- Saso Zivanovic <saso.zivanovic@guest.arnes.si>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
diff --git a/Master/texmf-dist/doc/support/easydtx/easydoctex-mode.el b/Master/texmf-dist/doc/support/easydtx/easydoctex-mode.el
index 3226414e3cb..73b2543f04a 100644
--- a/Master/texmf-dist/doc/support/easydtx/easydoctex-mode.el
+++ b/Master/texmf-dist/doc/support/easydtx/easydoctex-mode.el
@@ -1,4 +1,4 @@
-;; easydoctex-mode.el 0.1.0
+;; easydoctex-mode.el 0.2.0
;;
;; This file is a part of TeX package EasyDTX, available at
;; https://ctan.org/pkg/easydtx and https://github.com/sasozivanovic/easydtx.
diff --git a/Master/texmf-dist/doc/support/easydtx/edtx2dtx.1.md b/Master/texmf-dist/doc/support/easydtx/edtx2dtx.1.md
new file mode 100644
index 00000000000..11b6bb9e64a
--- /dev/null
+++ b/Master/texmf-dist/doc/support/easydtx/edtx2dtx.1.md
@@ -0,0 +1,91 @@
+---
+title: edtx2dtx
+section: 1
+header: User Manual
+footer: edtx2dtx 0.2.0
+date: November 23, 2024
+hyphenate: false
+---
+
+# NAME
+edtx2dtx - Convert .edtx into .dtx
+
+
+# SYNOPSIS
+**edtx2dtx** *filename.edtx* > *filename.dtx*
+
+
+# DESCRIPTION
+
+This utility wraps code chunks by a (commented and properly indented)
+`\begin{macrocode}` and `\end{macrocode}` pair. A code chunk is any sequence of
+lines not introduced by a single (possibly indented) comment character (`%`);
+i.e. both non-commented lines and lines introduced by multiple comment
+characters count as code, and documentation lines may be indented.
+
+The part of the file which should be processed should be marked by a
+`\begin{macrocode}` and `\end{macrocode}` pair. In other words, everything
+preceding `\begin{macrocode}` is considered a header and not changed, and
+everything following `\end{macrocode}` is considered a trailer and not changed.
+In fact, any number of `\begin{macrocode}` — `\end{macrocode}` pairs is
+allowed. (The system allows for the driver to remain as is, and also makes it
+easy to paste a `.dtx` file into an `.edtx`, as using this utility on a `.dtx`
+does not change the file.)
+
+The utility furthermore replaces the first occurrence of `<filename>.edtx` in
+the header, followed by an optional parenthesized note, with `<filename>.dtx`,
+plus the note on how the file was generated.
+
+
+# OPTIONS
+
+**-c, \--comment**
+: The input comment character; the default is `%`. (Any input comment
+ characters in the header and the trailer will be replaced by the output
+ comment character, which is always `%`.)
+
+**-b, \--begin-macrocode** *regex*\
+
+**-e, \--end-macrocode** *regex*
+: Use these options to change the default *input* `\begin{macrocode}` and
+ `\end{macrocode}` markers. (The *output* markers are always
+ `\begin{macrocode}` and `\end{macrocode}`.) The markers should be given as
+ regular expressions matching the entire line. The input markers are not kept
+ in the file, i.e. they are replaced by the output markers.
+
+**-B, \--Begin-macrocode** *regex*\
+
+**-E, \--End-macrocode** *regex*
+: As `-b` and `-e`, but the input markers are kept in the output.
+
+**-s, \--strip-empty**
+: If this option is given, empty lines are not included in the output.
+
+**-h, \--help**
+: Show help and exit.
+
+**-V, \--version**
+: Show the version number and exit.
+
+
+# EXAMPLES
+
+If `input.edtx` is just like a `dtx` file, just without `\begin{macrocode}` and
+`\end{macrocode}` around every chunk of code:
+
+ edtx2dtx input.edtx > output.dtx
+
+Memoize uses the invocation below to produce a `.dtx` from documented Python
+code of `memoize-extract.py`. The value of `-c` adapts the `edtx2dtx` to
+Python comments. `-B` marks everything preceding the version number statement
+as a header, and keeps the version number statement in the output. Similarly,
+`-E` says that the processing should stop when encountering Emacs' local
+variables (which are kept, unchanged, in the output).
+
+ edtx2dtx -s -c '#' -B '^__version__' -E '^# Local Variables:' $< \
+
+
+
+# SEE ALSO
+
+[easydoctex.el](????)
diff --git a/Master/texmf-dist/doc/support/expltools/CHANGES.md b/Master/texmf-dist/doc/support/expltools/CHANGES.md
new file mode 100644
index 00000000000..3192d358ed9
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/CHANGES.md
@@ -0,0 +1,133 @@
+# Changes
+
+## expltools 2024-12-23
+
+### explcheck v0.3.0
+
+#### Development
+
+- Add option `--expect-expl3-everywhere` to ignore \ExplSyntaxOn and Off.
+ (discussed with @muzimuzhi in #17, added in #19)
+
+- Add short-hand command-line option `-p` for `--porcelain`.
+ (suggested by @FrankMittelbach in #8, added in #19)
+
+- Add file `explcheck-config.lua` with the default configuration of explcheck. (#19)
+
+ You may place a file named `explcheck-config.lua` with your own configuration
+ in your repository to control the behavior of explcheck.
+
+ Note that the configuration options are provisional and may be changed or
+ removed before version 1.0.0. Furthermore, support for configuration YAML
+ files that will allow you to specify different configuration for different
+ .tex files is envisioned for a future release and will be the recommended way
+ to configure explcheck.
+
+#### Fixes
+
+- Make the detection of error E102 (expl3 material in non-expl3 parts) more precise.
+ (discussed with @cfr42 in #18, fixed in #19)
+
+- Use a less naïve parser of TeX comments to improve the detection of issues
+ W100 and E102. (reported by @FrankMittelbach in #8, fixed in #16)
+
+#### Documentation
+
+- State in the output of `explcheck --help` that command-line options are
+ provisional and subject to change. (discussed with @FrankMittelbach and
+ @muzimuzhi in #8 and #17, added in #19)
+
+- Display the default maximum line length in the output of `explcheck --help`. (#19)
+
+- Rename E102 to "expl3 material in non-expl3 parts".
+ (discussed with @cfr42 in #18, added in #19)
+
+## expltools 2024-12-13
+
+### explcheck v0.2.0
+
+#### Development
+
+- Add a command-line option `--porcelain` for machine-readable output.
+ (suggested by @FrankMittelbach in #8, added in #15)
+
+ See <https://github.com/Witiko/expltools/pull/15#issuecomment-2542418484>
+ and below for a demonstration of how you might set up your text editor, so
+ that it automatically navigates you to lines with warnings and errors.
+
+#### Fixes
+
+- In the command-line interface, forbid the checking of .ins and .dtx files.
+ Display messages that direct users to check the generated files instead.
+ (reported by @josephwright and @FrankMittelbach in #8, fixed in #14)
+
+- Expect both backslashes and forward slashes when shortening pathnames. (#14)
+
+- Correctly pluralize "1 file" on the first line of command-line output. (#14)
+
+#### Documentation
+
+- Normalize the behavior and documentation of functions `get_*()` across files
+ `explcheck/build.lua`, `explcheck/test.lua`, and `explcheck-cli.lua`. (#14)
+
+## expltools 2024-12-09
+
+### explcheck v0.1.1
+
+#### Fixes
+
+- In LuaTeX, initialize Kpathsea Lua module searchers first.
+ (reported by @josephwright, Lars Madsen, and Philip Taylor on
+ [tex-live@tug.org][tex-live-02] and by @muzimuzhi in #9,
+ fixed on [tex-live@tug.org][tex-live-03] by @gucci-on-fleek)
+
+- Allow spaces between arguments of `\ProvidesExpl*` commands.
+ (reported by @u-fischer and @josephwright in #7, fixed in #13)
+
+ [tex-live-02]: https://tug.org/pipermail/tex-live/2024-December/050958.html
+ [tex-live-03]: https://tug.org/pipermail/tex-live/2024-December/050968.html
+
+#### Documentation
+
+- Include explcheck version in the command-line interface.
+ (reported in #10, fixed in #13)
+
+- Hint in the file `README.md` that .dtx files are not well-supported.
+ (reported by @josephwright in #8, added in #13)
+
+- Show in the file `README.md` how explcheck can be used from Lua code. (#13)
+
+- Include instructions about using l3build in the file `README.md`.
+ (reported in #11, added in #13)
+
+#### Continuous integration
+
+- Add `Dockerfile`, create Docker image, and mention it in the file `README.md`.
+ (discussed in #12, added in #13)
+
+## expltools 2024-12-04
+
+### explcheck v0.1
+
+#### Development
+
+- Implement preprocessing. (#5)
+
+#### Documentation
+
+- Add `README.md`. (suggested by @Skillmon in #1, fixed in #2)
+- Update to Markdown 3. (#3)
+- Use the expl3 prefix `expltools`. (#3)
+- Add project proposal. (#4)
+
+#### Continuous integration
+
+- Use small Docker image. (#3)
+
+#### Distribution
+
+- Make changes to the CTAN archive following a discussion with TeX Live developers
+ on [tex-live@tug.org][tex-live-01] and with CTAN maintainers. Many thanks
+ specifically to Petra Rübe-Pugliese, Reinhard Kotucha, and Zdeněk Wagner.
+
+ [tex-live-01]: https://tug.org/pipermail/tex-live/2024-December/050952.html
diff --git a/Master/texmf-dist/doc/support/expltools/README.md b/Master/texmf-dist/doc/support/expltools/README.md
new file mode 100644
index 00000000000..4b2f33cdcdf
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/README.md
@@ -0,0 +1,100 @@
+# Expltools: Development tools for expl3 programmers
+
+This repository contains the code and documentation of an expl3 static analysis tool `explcheck` outlined in the following devlog posts:
+
+1. [Introduction][1]
+2. [Requirements][2]
+3. [Related work][3]
+4. [Design][4]
+
+On September 6, 2024, the tool has been [accepted for funding][5] by [the TeX Development Fund][6].
+The full text of the project proposal, which summarizes devlog posts 1–4 is available [here][7].
+
+These devlog posts chronicle the latest updates and progress in the ongoing development of the tool:
+
+5. [Frank Mittelbach in Brno, the first public release of explcheck, and expl3 usage statistics][8] from December 5, 2024
+6. [A flurry of releases, CSTUG talk, and what's next][9] from December 19, 2024
+
+In the future, this repository may also contain the code of other useful development tools for expl3 programmers, such as a command-line utility similar to `grep` that will ignore whitespaces and newlines as well as other tools.
+
+ [1]: https://witiko.github.io/Expl3-Linter-1/
+ [2]: https://witiko.github.io/Expl3-Linter-2/
+ [3]: https://witiko.github.io/Expl3-Linter-3/
+ [4]: https://witiko.github.io/Expl3-Linter-4/
+ [5]: https://tug.org/tc/devfund/grants.html
+ [6]: https://tug.org/tc/devfund/application.html
+ [7]: https://tug.org/tc/devfund/documents/2024-09-expltools.pdf
+ [8]: https://witiko.github.io/Expl3-Linter-5/
+ [9]: https://witiko.github.io/Expl3-Linter-6/
+
+## Usage
+
+You can use the tool from the command line as follows:
+
+```
+$ explcheck [options] [.tex, .cls, and .sty files]
+```
+
+You can also use the tool from your own Lua code by importing the corresponding files `explcheck-*.lua`.
+For example, here is Lua code that applies the preprocessing step to the code from a file named `code.tex`:
+
+``` lua
+local new_issues = require("explcheck-issues")
+local preprocessing = require("explcheck-preprocessing")
+
+-- LuaTeX users must initialize Kpathsea Lua module searchers first.
+local using_luatex, kpse = pcall(require, "kpse")
+if using_luatex then
+ kpse.set_program_name("texlua", "explcheck")
+end
+
+-- Apply the preprocessing step to a file "code.tex".
+local filename = "code.tex"
+local issues = new_issues()
+
+local file = assert(io.open(filename, "r"))
+local content = assert(file:read("*a"))
+assert(file:close())
+
+local line_starting_byte_numbers = preprocessing(issues, content)
+
+print(
+ "There were " .. #issues.warnings .. " warnings "
+ .. "and " .. #issues.errors .. " errors "
+ .. "in the file " .. filename .. "."
+)
+```
+
+You can also use the tool from continuous integration workflows using the Docker image `ghcr.io/witiko/expltools/explcheck`.
+For example, here is a GitHub Actions workflow file that applies the tool to all .tex file in a Git repository:
+
+``` yaml
+name: Check expl3 code
+on:
+ push:
+jobs:
+ typeset:
+ runs-on: ubuntu-latest
+ container:
+ image: ghcr.io/witiko/expltools/explcheck
+ steps:
+ - uses: actions/checkout@v4
+ - run: explcheck *.tex
+```
+
+## Notes to distributors
+
+You can prepare the expltools bundle for distribution with the following two commands:
+
+1. `l3build tag`: Add the current version numbers to the file `explcheck-lua.cli`.
+2. `l3build ctan`: Run tests, build the documentation, and create a CTAN archive `expltools-ctan.zip`.
+
+The file `explcheck.lua` should be installed in the TDS directory `scripts/expltools/explcheck`. Furthermore, it should be made executable and either symlinked to system directories as `explcheck` on Unix or have a wrapper `explcheck.exe` installed on Windows.
+
+## Authors
+
+- Vít Starý Novotný (<witiko@mail.muni.cz>)
+
+## License
+
+This material is dual-licensed under GNU GPL 2.0 or later and LPPL 1.3c or later.
diff --git a/Master/texmf-dist/doc/support/expltools/e102.tex b/Master/texmf-dist/doc/support/expltools/e102.tex
new file mode 100644
index 00000000000..0085df8b174
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/e102.tex
@@ -0,0 +1,12 @@
+\ProvidesExplFile{example.tex}{2024-04-09}{1.0.0}{An example file}
+\tl_new:N
+ \g_example_tl
+\tl_gset:Nn
+ \g_example_tl
+ { Hello,~ }
+\tl_gput_right:Nn
+ \g_example_tl
+ { world! }
+\ExplSyntaxOff
+\tl_use:N % error on this line
+ \g_example_tl % error on this line
diff --git a/Master/texmf-dist/doc/support/expltools/e104.tex b/Master/texmf-dist/doc/support/expltools/e104.tex
new file mode 100644
index 00000000000..24f441d729b
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/e104.tex
@@ -0,0 +1,5 @@
+\ProvidesExplPackage
+ {example.sty}{2024-04-09}{1.0.0}{An example package}
+\ExplSyntaxOff
+\ProvidesExplClass % error on this line
+ {example.cls}{2024-04-09}{1.0.0}{An example class}
diff --git a/Master/texmf-dist/doc/support/expltools/latexmkrc b/Master/texmf-dist/doc/support/expltools/latexmkrc
new file mode 100644
index 00000000000..28c69b9594e
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/latexmkrc
@@ -0,0 +1,9 @@
+# Custom latexmk configuration
+## Enable shell escape
+set_tex_cmds('--shell-escape %O %S');
+
+## Output PDF by default and use LuaLaTeX
+$pdf_mode = 4;
+
+## Treat warnings as errors
+$warnings_as_errors = 1;
diff --git a/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools.sty b/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools.sty
new file mode 100644
index 00000000000..b7503826bfe
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools.sty
@@ -0,0 +1,9 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesExplPackage
+ {markdownthemewitiko_expltools}%
+ {2024-12-04}%
+ {0.0.2}%
+ {Snippets for typesetting the documentation of expltools}
+\markdownSetupSnippet
+ { metadata }
+ { raw_attribute }
diff --git a/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_project-proposal.sty b/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_project-proposal.sty
new file mode 100644
index 00000000000..ab78ceba196
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_project-proposal.sty
@@ -0,0 +1,19 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesExplPackage
+ {markdownthemewitiko_expltools_explcheck_project-proposal}%
+ {2024-09-06}%
+ {0.0.1}%
+ {Snippets for typesetting the documentation of the project proposal for the %
+ expl3 analysis tool}
+\markdownSetupSnippet
+ { body }
+ {
+ raw_attribute,
+ code = {
+ \tableofcontents
+ \clearpage
+ },
+ renderers = {
+ link = { \href { #3 } { #1 } }
+ }
+ }
diff --git a/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_warnings-and-errors.sty b/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_warnings-and-errors.sty
new file mode 100644
index 00000000000..aa07a0f3d76
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/markdownthemewitiko_expltools_explcheck_warnings-and-errors.sty
@@ -0,0 +1,211 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesExplPackage
+ {markdownthemewitiko_expltools_explcheck_warnings-and-errors}%
+ {2024-11-29}%
+ {0.0.3}%
+ {Snippets for typesetting the documentation of the warnings and errors for %
+ the expl3 analysis tool}
+\int_new:N
+ \g__expltools_explcheck_subsection_int
+\tl_new:N
+ \g__expltools_explcheck_subsection_tl
+\tl_new:N
+ \l__expltools_explcheck_current_label_tl
+\tl_new:N
+ \l__expltools_explcheck_current_identifier_tl
+\prop_new:N
+ \g__expltools_explcheck_labels_prop
+\cs_new:Nn
+ \__expltools_explcheck_increment_counters:
+ {
+ \int_gincr:N
+ \g__expltools_explcheck_subsection_int
+ \int_compare:nTF
+ { \g__expltools_explcheck_subsection_int < 10 }
+ {
+ \tl_gset:Nn
+ \g__expltools_explcheck_subsection_tl
+ { 0 }
+ \tl_gput_right:NV
+ \g__expltools_explcheck_subsection_tl
+ \g__expltools_explcheck_subsection_int
+ }
+ {
+ \tl_gset:NV
+ \g__expltools_explcheck_subsection_tl
+ \g__expltools_explcheck_subsection_int
+ }
+ \tl_if_empty:NF
+ \l__expltools_explcheck_current_identifier_tl
+ {
+ \prop_gput:NVV
+ \g__expltools_explcheck_labels_prop
+ \l__expltools_explcheck_current_identifier_tl
+ \l__expltools_explcheck_current_label_tl
+ \exp_args:NV
+ \label
+ \l__expltools_explcheck_current_identifier_tl
+ }
+ \exp_args:NV
+ \index
+ \l__expltools_explcheck_current_label_tl
+ }
+\markdownSetupSnippet
+ { body }
+ {
+ citations,
+ content_blocks,
+ definition_lists,
+ fenced_code,
+ notes,
+ header_attributes,
+ html,
+ raw_attribute,
+ relative_references,
+ renderers = {
+ underscore = {
+ \discretionary
+ { _ \textnormal { - } }
+ { }
+ { _ }
+ },
+ link = {
+ \tl_set:Nn
+ \l_tmpa_tl
+ { #3 }
+ \tl_set:Nx
+ \l_tmpb_tl
+ {
+ \tl_range:Nnn
+ \l_tmpa_tl
+ { 1 }
+ { 1 }
+ }
+ \str_if_eq:NNT
+ \l_tmpb_tl
+ \c_hash_str
+ {
+ \tl_set:Nx
+ \l_tmpb_tl
+ {
+ \tl_range:Nnn
+ \l_tmpa_tl
+ { 2 }
+ { -1 }
+ }
+ \tl_set:Nn
+ \l_tmpa_tl
+ { \hyperref [ }
+ \tl_put_right:NV
+ \l_tmpa_tl
+ \l_tmpb_tl
+ \tl_put_right:Nn
+ \l_tmpa_tl
+ { ] }
+ \prop_get:NVN
+ \g__expltools_explcheck_labels_prop
+ \l_tmpb_tl
+ \l_tmpb_tl
+ \tl_put_right:Nx
+ \l_tmpa_tl
+ { { \l_tmpb_tl } }
+ \tl_use:N
+ \l_tmpa_tl
+ }
+ },
+ headingOne = {
+ \section { #1 }
+ \int_gset:Nn
+ \g__expltools_explcheck_subsection_int
+ { 0 }
+ \tl_gset:Nn
+ \g__expltools_explcheck_subsection_tl
+ { 00 }
+ },
+ headerAttributeContextBegin = {
+ \group_begin:
+ \markdownSetup
+ {
+ renderers = {
+ attributeIdentifier = {
+ \tl_set:Nn
+ \l__expltools_explcheck_current_identifier_tl
+ { ##1 }
+ },
+ attributeKeyValue = {
+ \str_if_eq:nnT
+ { ##1 }
+ { label }
+ {
+ \tl_set:Nx
+ \l_tmpa_tl
+ { \str_uppercase:n { ##2 } }
+ \str_if_eq:VVF
+ \l_tmpa_tl
+ \l__expltools_explcheck_current_label_tl
+ {
+ \msg_error:nnVV
+ { expltools / explcheck }
+ { unexpected-label }
+ \l_tmpa_tl
+ \l__expltools_explcheck_current_label_tl
+ }
+ }
+ },
+ attributeClassName = {
+ \tl_set:Nx
+ \l__expltools_explcheck_current_label_tl
+ {
+ \str_uppercase:n { ##1 }
+ \thesection
+ \g__expltools_explcheck_subsection_tl
+ }
+ \markdownSetup
+ {
+ renderers = {
+ headingTwo = {
+ \subsection
+ {
+ ####1~[ \l__expltools_explcheck_current_label_tl ]
+ }
+ \__expltools_explcheck_increment_counters:
+ },
+ headingThree = {
+ \subsubsection
+ {
+ ####1~[ \l__expltools_explcheck_current_label_tl ]
+ }
+ \__expltools_explcheck_increment_counters:
+ },
+ },
+ }
+ }
+ },
+ }
+ },
+ headerAttributeContextEnd = {
+ \group_end:
+ },
+ contentBlock = {
+ \str_case:nnF
+ { #1 }
+ {
+ { tex }
+ {
+ \markdownRendererInputFencedCode
+ { #3 }
+ { tex }
+ { tex }
+ }
+ }
+ {
+ \markdownInput
+ { #3 }
+ }
+ },
+ },
+ }
+\msg_new:nnn
+ { expltools / explcheck }
+ { unexpected-label }
+ { Expected~section~label~"#1",~but~"#2"~was~generated }
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal-01-introduction.md b/Master/texmf-dist/doc/support/expltools/project-proposal-01-introduction.md
new file mode 100644
index 00000000000..c59fae55315
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal-01-introduction.md
@@ -0,0 +1,28 @@
+# Introduction
+
+In 2021, I used [the expl3 programming language][7] for the first time in my life. I had already been eyeing expl3 for some time and, when it came to defining a `\LaTeX`{=tex}-specific interface for processing YAML metadata in [version 2.11.0][1] of [the Markdown package for `\TeX`{=tex}][2], I took the plunge.
+
+After two and a half years, approximately 3.5k out of the 5k lines of `\TeX`{=tex} code in [version 3.5.0][3] of the Markdown package are written in expl3. I also developed several consumer products with it, and I have written [three][4] [journal][5] [articles][6] for my local `\TeX`{=tex} users group about it. Needless to say, expl3 has been a blast for me!
+
+In the Markdown package, each change is reviewed by a number of automated static analysis tools (so-called *linters*), which look for programming errors in the code. While these tools don't catch all programming errors, they have proven extremely useful in catching the typos that inevitably start trickling in after 2AM.
+
+Since the Markdown package contains code in different programming languages, we use many different linters such as [`shellcheck`][8] for shell scripts, [`luacheck`][9] for Lua, and [`flake8`][10] and [`pytype`][11] for Python. However, since no linters for expl3 exist, typos are often only caught by regression tests, human reviewers, and sometimes even by our users after a release. Nobody is happy about this.
+
+Earlier this year, I realized that, unlike `\TeX`{=tex}, expl3 has the following two properties that seem to make it well-suited to static analysis:
+
+1. Simple uniform syntax: (Almost) all operations are expressed as function calls. This Lisp-like quality makes is easy to convert well-behaved expl3 programs that only use high-level interfaces into abstract syntax trees. This is a prerequisite for accurate static analysis.
+2. Explicit type and scope: Variables and constants are separate from functions. Each variable is either local or global. Variables and constants are explicitly typed. This information makes it easy to detect common programming errors related to the incorrect use of variables.
+
+For the longest time, I wanted to try my hand at building a linter from the ground up. Therefore, I decided to kill two birds with one stone and improve the tooling for expl3 while learning something new along the way by building a linter for expl3.
+
+ [1]: https://github.com/Witiko/markdown/releases/tag/2.11.0
+ [2]: https://ctan.org/pkg/markdown
+ [3]: https://github.com/Witiko/markdown/releases/tag/3.5.0
+ [4]: http://dx.doi.org/10.5300/2022-1-4/35
+ [5]: http://dx.doi.org/10.5300/2023-1-2/3
+ [6]: http://dx.doi.org/10.5300/2023-3-4/153
+ [7]: http://mirrors.ctan.org/macros/latex/required/l3kernel/expl3.pdf
+ [8]: https://www.shellcheck.net/
+ [9]: https://github.com/mpeterv/luacheck
+ [10]: https://pypi.org/project/flake8/
+ [11]: https://pypi.org/project/pytype/ \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal-02-requirements.md b/Master/texmf-dist/doc/support/expltools/project-proposal-02-requirements.md
new file mode 100644
index 00000000000..95626c0a874
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal-02-requirements.md
@@ -0,0 +1,106 @@
+# Requirements
+
+In this section, I outline the requirements for the linter. These will form the basis of the design and the implementation.
+
+## Functional requirements
+
+The linter should accept a list of input expl3 files. Then, the linter should process each input file and print out issues it has identified with the file.
+
+Initially, the linter should recognize at least the following types of issues:
+
+- Style:
+ - Overly long lines
+ - Missing stylistic white-spaces
+ - Malformed names of functions, variables, constants, quarks, and scan marks
+- Functions:
+ - Multiply defined functions and function variants
+ - Calling undefined functions and function variants
+ - Calling [deprecated and removed][2] functions
+ - Unknown argument specifiers
+ - Unexpected function call arguments
+ - Unused private functions and function variants
+- Variables:
+ - Multiply declared variables and constants
+ - Using undefined variables and constants
+ - Using variables of incompatible types
+ - Using deprecated and removed variables and constants
+ - Setting constants and undeclared variables
+ - Unused variables and constants
+ - Locally setting global variables and vice versa
+
+## Non-functional requirements
+
+### Issues
+
+The linter should make distinction between two types of issues: warnings and errors. As a rule of thumb, whereas warnings are suggestions about best practices, errors will likely result in runtime errors.
+
+Here are three examples of warnings:
+
+- Missing stylistic white-spaces around curly braces
+- Using deprecated functions and variables
+- Unused variable or constant
+
+Here are three examples of errors:
+
+- Using an undefined message
+- Calling a function with a `V`-type argument with a variable or constant that does not support `V`-type expansion
+- Multiply declared variable or constant
+
+The overriding design goal for the initial releases of the linter should be the simplicity of implementation and robustness to unexpected input. For all issues, the linter should prefer [precision over recall][1] and only print them out when it is reasonably certain that it has understood the code, even at the expense of potentially missing some issues.
+
+Each issue should be assigned a unique identifier. Using these identifiers, issues can be disabled globally using a config file, for individual input files from the command-line, and for sections of code or individual lines of code using `\TeX`{=tex} comments.
+
+### Architecture
+
+To make the linter easy to use in continuous integration pipelines, it should be written in Lua 5.3 using just the standard Lua library. One possible exception is checking whether functions, variables, and other symbols from the input files are expl3 build-ins. This may require using the `texlua` interpreter and a minimal `\TeX`{=tex} distribution that includes the `\LaTeX`{=tex}3 kernel, at least initially.
+
+The linter should process input files in a series of discrete steps, which should be represented as Lua modules. Users should be able to import the modules into their Lua code and use them independently on the rest of the linter.
+
+Each step should process the input received from the previous step, identify any issues with the input, and transform the input to an output format appropriate for the next step. The default command-line script for the linter should execute all steps and print out issues from all steps. Users should be able to easily adapt the default script in the following ways:
+
+1. Change how the linter discovers input files.
+2. Change or replace processing steps or insert additional steps.
+3. Change how the linter reacts to issues with the input files.
+
+The linter should integrate easily with text editors. Therefore, the linter should either directly support the [language server protocol (LSP)][6] or be designed in a way that makes it easy to write an LSP wrapper for it.
+
+### Validation
+
+As a part of the test-driven development paradigm, all issues identified by a processing step should have at least one associated test in the code repository of the linter. All tests should be executed periodically during the development of the linter.
+
+As a part of the dogfooding paradigm, the linter should be used in the continuous integration pipeline of [the Markdown Package for `\TeX`{=tex}][3] since the initial releases of the linter in order to collect early user feedback. Other early adopters are also welcome to try the initial releases of the linter and report issues to its code repository.
+
+At some point, a larger-scale validation should be conducted as an experimental part of a TUGboat article that will introduce the linter to the wider `\TeX`{=tex} community. In this validation, all expl3 packages from current and historical `\TeX`{=tex} Live distributions should be processed with the linter. The results should be evaluated both quantitatively and qualitatively. While the quantitative evaluation should focus mainly on trends in how expl3 is used in packages, the qualitative evaluation should explore the shortcomings of the linter and ideas for future improvements.
+
+### License terms
+
+The linter should be [free software][8] and dual-licensed under [the GNU General Public License (GNU GPL) 2.0][12] or later and [the `\LaTeX`{=tex} Project Public License (LPPL) 1.3c][13] or later.
+
+The option to use GNU GPL 2.0 or later is motivated by the fact that GNU GPL 2.0 and 3.0 are [mutually incompatible][14]. Supporting both GNU GPL 2.0 and 3.0 extends the number of free open-source projects that will be able to alter and redistribute the linter.
+
+The option to use LPPL 1.3c is motivated by the fact that it imposes very few licensing restrictions on `\TeX`{=tex} users. Furthermore, it also preserves the integrity of `\TeX`{=tex} distributions by enforcing its naming and maintenance clauses, which ensure ongoing project stewardship and prevent confusion between modified and official versions.
+
+Admittedly, GNU GPL and LPPL may seem like an unusual combination, since GNU GPL is a copyleft license whereas LPPL is a permissive license. However, there are strategic benefits to offering both.
+
+We would offer LPPL as the primary license for derivative works within the `\TeX`{=tex} ecosystem. One downside of using LPPL is that it could potentially allow bad actors to create proprietary derivative works without contributing back to the original project. However, this trade-off helps maintain the `\TeX`{=tex} ecosystem's consistency and reliability. Incidentally, there is an element of trust in the `\TeX`{=tex} user community to voluntarily contribute improvements back, even though the license itself does not mandate it.
+
+We would offer GNU GPL as an alternative license for derivative works outside the `\TeX`{=tex} ecosystem. The key benefit of including GNU GPL is that it enables the code to be integrated into free open-source projects, especially those with licenses that are incompatible with LPPL's naming requirements. This opens the door for broader collaboration with the free software community.
+
+Notably, GNU GPL creates a one-way licensing situation: Once a derivative work is licensed under GNU GPL, it cannot be legally re-licensed under a less restrictive license like LPPL. As a result, we wouldn't be able to incorporate changes made to GNU GPL-licensed works back into the original project under LPPL without also creating two forks of the project licensed under GNU GPL 2.0 and GNU GPL 3.0, respectively. While this might seem like a downside, I view it as an important counterbalance to the potential for proprietary derivative works under LPPL.
+
+In summary, this dual-licensing approach allows us to maintain the integrity of the `\TeX`{=tex} ecosystem while making the project more accessible to the broader free open-source community. It provides flexibility for different use cases, though we will need to carefully manage contributions to ensure compliance with all licenses.
+
+ [1]: https://developers.google.com/machine-learning/crash-course/classification/precision-and-recall
+ [2]: https://github.com/latex3/latex3/blob/main/l3kernel/doc/l3obsolete.txt
+ [3]: https://github.com/witiko/markdown
+ [4]: /Expl3-Linter-1
+ [5]: /Expl3-Linter-2.5
+ [6]: https://microsoft.github.io/language-server-protocol/
+ [7]: https://www.gnu.org/licenses/lgpl-3.0.en.html
+ [8]: https://www.gnu.org/philosophy/free-sw.html
+ [9]: https://www.gnu.org/licenses/gpl-3.0.html
+ [10]: https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses
+ [11]: /Expl3-Linter-3
+ [12]: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ [13]: https://www.latex-project.org/lppl/lppl-1-3c/
+ [14]: https://www.gnu.org/licenses/rms-why-gplv3.en.html \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal-03-related-work.md b/Master/texmf-dist/doc/support/expltools/project-proposal-03-related-work.md
new file mode 100644
index 00000000000..198275d71eb
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal-03-related-work.md
@@ -0,0 +1,64 @@
+# Related work
+
+In this section, I review the related work in the analysis of `\TeX`{=tex} programs and documents. This related work should be considered in the design of the linter and reused whenever it is appropriate and compatible with the license of the linter.
+
+## Unravel
+
+[The unravel package][11] by Bruno Le Floch analyses of expl3 programs as well as `\TeX`{=tex} programs and documents in general. The package was suggested to me as related work by Joseph Wright in personal correspondence.
+
+Unlike a linter, which performs _static_ analysis by leafing through the code and makes suggestions, unravel is a _debugger_ that is used for _dynamic_ analysis. It allows the user to step through the execution of code while providing extra information about the state of `\TeX`{=tex}. Unravel is written in expl3 and emulates `\TeX`{=tex} primitives using expl3 functions. It has been released under the `\LaTeX`{=tex} Project Public License (LPPL) 1.3c.
+
+While both linters and debuggers are valuable in producing bug-free software, linters prevent bugs by proactively pointing out potential bugs without any user interaction, whereas debuggers are typically used interactively to determine the cause of a bug after it has already manifested.
+
+## Chktex, chklref, cmdtrack, lacheck, match_parens, nag, and tex2tok
+
+The Comprehensive `\TeX`{=tex} Archive Network (CTAN) lists related software projects on the topics of [debuging support][12] and [`\LaTeX`{=tex} quality][13], some of which I list in this section.
+
+[The chktex package][14] by Jens T. Berger Thielemann is a linter for the static analysis of `\LaTeX`{=tex} documents. It has been written in ANSI C and released under the GNU GPL 2.0 license. The types of issues with the input files and how they are reported to the user can be configured to some extent from the command-line and using configuration files to a larger extent. Chktex is extensible and, in addition to the configuration of existing issues, it allows the definition of new types of issues using regular expressions.
+
+[The lacheck package][17] by Kresten Krab Thorup is a linter for the static analysis of `\LaTeX`{=tex} documents. Similarly to chktex, lacheck has been written in ANSI C and released under the GNU GPL 1.0 license. Unlike chktex, lacheck cannot be configured either from the command-line or using configuration files.
+
+[The chklref package][15] by Jérôme Lelong is a linter for the static analysis of `\LaTeX`{=tex} documents. It has been written in Perl and released under the GNU GPL 3.0 license. Unlike chktex, chklref focuses just on the detection of unused labels, which often accumulate over the lifetime of a `\LaTeX`{=tex} document.
+
+[The match_parens package][18] by Wybo Dekker is a linter for the static analysis of expl3 programs as well as `\TeX`{=tex} programs and documents in general. It has been written in Ruby and released under the GNU GPL 1.0 license. Unlike chktex, match_parens focuses just on the detection of mismatched paired punctuation, such as parentheses, braces, brackets, and quotation marks. As such, it can also be used for the static analysis of natural text as well as programs and documents in programming and markup languages that use paired punctuation in its syntax.
+
+[The cmdtrack package][16] by Michael John Downes is a debugger for the dynamic analysis of `\LaTeX`{=tex} documents. It has been written in `\LaTeX`{=tex} and released under the LPPL 1.0 license. It detects unused user-defined commands, which also often accumulate over the lifetime of a `\LaTeX`{=tex} document, and mentions them in the `.log` file produced during the compilation of a `\LaTeX`{=tex} document.
+
+[The nag package][19] by Ulrich Michael Schwarz is a debugger for the dynamic analysis of `\LaTeX`{=tex} documents. Similarly to cmdtrack, nag has also been written in `\LaTeX`{=tex} and released under the LPPL 1.0 license. It detects the use of obsolete `\LaTeX`{=tex} commands, document classes, and packages and mentions them in the `.log` file produced during the compilation of a `\LaTeX`{=tex} document.
+
+[The tex2tok package][20] by Jonathan Fine is a debugger for the dynamic analysis of expl3 programs as well as `\TeX`{=tex} programs and documents in general. It has been written in `\TeX`{=tex} and released under the GNU GPL 2.0 license. It executes a `\TeX`{=tex} file and produces a new `.tok` file with a list of `\TeX`{=tex} tokens in the file. Compared to static analysis, the dynamic analysis ensures correct category codes. However, it requires the execution of the `\TeX`{=tex} file, which may take long or never complete in the presence of bugs in the code.
+
+## Luacheck and flake8
+
+[Luacheck][21] by Peter Melnichenko and [flake8][22] by Tarek Ziade are linters for the static analysis of Lua and Python programs, respectively. They have been written in Lua and Python, respectively, and released under the MIT license. Both tools are widely used and should inform the design of my linter in terms of architecture, configuration, and extensibility.
+
+Similar to chktex, the types of issues with the input files and how they are reported to the user can be configured from the command-line and using configuration files. Additionally, the reporting can also be enabled or disabled in the code of the analyzed program using inline comments.
+
+Unlike luacheck, which is not extensible at the time of writing and only allows the configuration of existing issues, flake8 supports Python extensions that can add support for new types of issues.
+
+## TeXLab and digestif
+
+[TeXLab][23] by Eric and Patrick Förscher and [digestif][24] by Augusto Stoffel are [language servers][6] for the static analysis of `\TeX`{=tex} programs and documents. They have been written in Rust and Lua, respectively, and released under the GNU GPL 3.0 license. The language servers were suggested to me as related work by Michal Hoftich at TUG 2024.
+
+Whereas `\TeX`{=tex}Lab focuses on `\LaTeX`{=tex} documents, digestif also supports other formats such as `\Hologo{ConTeXt}`{=tex} and GNU Texinfo. Neither `\TeX`{=tex}Lab nor digestif support expl3 code at the time of writing.
+
+In terms of the programming language, license, and scope, digestif seems like the most related work to my linter. However, its GNU GPL 3.0 license is incompatible with the dual license of the linter, which prohibits code reuse.
+
+ [1]: /Expl3-Linter-2
+ [2]: /Expl3-Linter-2#license-terms
+ [5]: /Expl3-Linter-2.5
+ [6]: https://microsoft.github.io/language-server-protocol/
+ [11]: https://ctan.org/pkg/unravel
+ [12]: https://ctan.org/topic/debug-supp
+ [13]: https://ctan.org/topic/latex-qual
+ [14]: https://ctan.org/pkg/chktex
+ [15]: https://ctan.org/pkg/chklref
+ [16]: https://ctan.org/pkg/cmdtrack
+ [17]: https://ctan.org/pkg/lacheck
+ [18]: https://ctan.org/pkg/match_parens
+ [19]: https://ctan.org/pkg/nag
+ [20]: https://ctan.org/pkg/tex2tok
+ [21]: https://github.com/mpeterv/luacheck
+ [22]: https://github.com/pycqa/flake8
+ [23]: https://ctan.org/pkg/texlab
+ [24]: https://ctan.org/pkg/digestif \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal-04-design.md b/Master/texmf-dist/doc/support/expltools/project-proposal-04-design.md
new file mode 100644
index 00000000000..b80b0eade70
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal-04-design.md
@@ -0,0 +1,75 @@
+# Design
+
+In this section, I outline the design of the linter and I create a code
+repository for the linter.
+
+## Processing steps
+
+As outlined in the requirements, the linter will process input files in a
+series of discrete steps, each represented by a single Lua module.
+
+Here are the individual processing steps that should be supported by the linter:
+
+1. Preprocessing: Determine which parts of the input files contain expl3 code.
+2. Lexical analysis: Convert expl3 parts of the input files into `\TeX`{=tex} tokens.
+3. Syntactic analysis: Convert `\TeX`{=tex} tokens into a tree of function calls.
+4. Semantic analysis: Determine the meaning of the different function calls.
+5. Flow analysis: Determine additional emergent properties of the code.
+
+## Warnings and errors
+
+As also outlined in the requirements, each processing step should identify
+issues with the output and produce either a warning or an error. Furthermore,
+the requirements list 16 types of issues that should be recognized by the linter
+at a minimum. Lastly, the requirements require that, as a part of the
+test-driven development paradigm, all issues identified by a processing step
+should have at least one associated test in the code repository of the linter.
+
+In [a document titled "Warnings and errors for the expl3 analysis tool"][6],
+I compiled a list of 66 warnings and errors that should be recognized by the
+initial version of the linter. For each issue, there is also an example of
+expl3 code with and without the issue. These examples can be directly converted
+to tests and used during the development of the corresponding processing steps.
+
+## Limitations
+
+Due to the dynamic nature of `\TeX`{=tex}, initial versions of the linter will make some
+naïve assumption and simplification during the analysis, such as:
+
+- Assume default expl3 [catcodes][8] everywhere.
+- Ignore non-expl3 and third-party code.
+- Do not analyze expansion and key–value calls.
+
+As a result, the initial version of the linter may not have a sufficient
+understanding of expl3 code to support proper flow analysis. Instead, the
+initial version of the linter may need to use pseudo-flow-analysis that would
+check for simple cases of the warnings and errors from flow analysis. Future
+versions of the linter should improve their code understanding to the point
+where proper flow analysis can be performed.
+
+The warnings and errors in this document do not cover the complete expl3
+language. The limitations currently include the areas outlined in a section
+of [the document with warnings and errors][6] titled "Caveats". Future versions
+of the linter should improve the coverage.
+
+## Code repository
+
+I created a repository [`witiko/expltools`][3] titled "Development tools for
+expl3 programmers" at GitHub. As outlined in the requirements, I dual-license the code under [GNU GPL 2.0][10] or later and [LPPL 1.3c][11] or later.
+
+Furthermore, I also [registered][7] the expl3 prefix `expltools`, so that it
+can be used in the documentation for the linter, in other supporting expl3 code
+used in the linter, and also possibly in development tools for expl3
+programmers other than the linter.
+
+ [1]: /Expl3-Linter-2
+ [2]: /Expl3-Linter-3
+ [3]: https://github.com/Witiko/expltools
+ [4]: https://github.com/astoff/digestif/blob/7962d25/digestif/Parser.lua
+ [5]: https://ctan.org/pkg/digestif
+ [6]: https://github.com/Witiko/expltools/releases/download/2024-09-06/warnings-and-errors.pdf
+ [7]: https://github.com/latex3/latex3/pull/1556
+ [8]: https://en.wikibooks.org/wiki/TeX/catcode
+ [9]: /Expl3-Linter-2#license-terms
+ [10]: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ [11]: https://www.latex-project.org/lppl/lppl-1-3c/ \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal-05-benefits-of-grant-funding.md b/Master/texmf-dist/doc/support/expltools/project-proposal-05-benefits-of-grant-funding.md
new file mode 100644
index 00000000000..4ae89f495cf
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal-05-benefits-of-grant-funding.md
@@ -0,0 +1,7 @@
+# Benefits of grant funding
+
+Securing this grant will significantly enhance my ability to dedicate focused and uninterrupted time to this project, enabling me to allocate at least two full weeks of work over the next 12 months. This concentrated effort will be far more productive than the fragmented hours I currently manage to find after a long day's work, ensuring that I can make substantial progress.
+
+Additionally, the grant will serve as a meaningful endorsement of the project's value, reflecting the community's interest and support. This recognition will not only reinforce the importance of the work but also help attract other contributors who share a commitment to advancing the project.
+
+Finally, the visibility that comes with receiving this grant will elevate the project's profile, making it more prominent within the TeX community and beyond. This increased visibility is crucial for attracting further interest, feedback, and potential collaborations, all of which are vital for the project's long-term success. \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal.cls b/Master/texmf-dist/doc/support/expltools/project-proposal.cls
new file mode 100644
index 00000000000..9e4156d4391
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal.cls
@@ -0,0 +1,16 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass%
+ {project-proposal}%
+ [2024-09-06 0.0.1 Document class for typesetting the project proposal for %
+ the expl3 analysis tool]
+\LoadClass{article}
+\RequirePackage{lua-widow-control}
+\RequirePackage{markdown}
+\markdownSetup {
+ import = {
+ witiko/expltools = metadata,
+ witiko/expltools/explcheck/project-proposal = body,
+ }
+}
+\RequirePackage{hologo}
+\RequirePackage{hyperref}
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal.pdf b/Master/texmf-dist/doc/support/expltools/project-proposal.pdf
new file mode 100644
index 00000000000..a4bc78b18b5
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/expltools/project-proposal.tex b/Master/texmf-dist/doc/support/expltools/project-proposal.tex
new file mode 100644
index 00000000000..6161fe1105c
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/project-proposal.tex
@@ -0,0 +1,14 @@
+\documentclass{project-proposal}
+\begin{yaml}[snippet=metadata]
+title: 'Project proposal: expl3 static analyzer'
+author: Vít Starý Novotný
+date: 2024-09-06
+\end{yaml}
+\begin{document}
+\markdownSetup{snippet=body}
+\markdownInput{project-proposal-01-introduction.md}
+\markdownInput{project-proposal-02-requirements.md}
+\markdownInput{project-proposal-03-related-work.md}
+\markdownInput{project-proposal-04-design.md}
+\markdownInput{project-proposal-05-benefits-of-grant-funding.md}
+\end{document}
diff --git a/Master/texmf-dist/doc/support/expltools/s103.tex b/Master/texmf-dist/doc/support/expltools/s103.tex
new file mode 100644
index 00000000000..898d1160da7
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/s103.tex
@@ -0,0 +1,2 @@
+This line is not very long, because it is 80 characters long, not 81 characters.
+This line is very long, because it is 81 characters long. % warning on this line
diff --git a/Master/texmf-dist/doc/support/expltools/w100.tex b/Master/texmf-dist/doc/support/expltools/w100.tex
new file mode 100644
index 00000000000..227c228efef
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/w100.tex
@@ -0,0 +1,11 @@
+% file-wide warning
+\tl_new:N
+ \g_example_tl
+\tl_gset:Nn
+ \g_example_tl
+ { Hello,~ }
+\tl_gput_right:Nn
+ \g_example_tl
+ { world! }
+\tl_use:N
+ \g_example_tl
diff --git a/Master/texmf-dist/doc/support/expltools/w101.tex b/Master/texmf-dist/doc/support/expltools/w101.tex
new file mode 100644
index 00000000000..0af25ae1aab
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/w101.tex
@@ -0,0 +1,14 @@
+\input expl3-generic
+\ExplSyntaxOff % warning on this line
+\ExplSyntaxOn
+\tl_new:N
+ \g_example_tl
+\tl_gset:Nn
+ \g_example_tl
+ { Hello,~ }
+\ExplSyntaxOn % warning on this line
+\tl_gput_right:Nn
+ \g_example_tl
+ { world! }
+\tl_use:N
+ \g_example_tl
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-00-introduction.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-00-introduction.md
new file mode 100644
index 00000000000..d28b738b806
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-00-introduction.md
@@ -0,0 +1,43 @@
+# Introduction
+
+In this document, I list the warnings and errors for the different processing steps of the expl3 linter [@starynovotny2024static3]:
+
+Preprocessing
+
+: Determine which parts of the input files contain expl3 code.
+
+Lexical analysis
+
+: Convert expl3 parts of the input files into `\TeX`{=tex} tokens.
+
+Syntactic analysis
+
+: Convert `\TeX`{=tex} tokens into a tree of function calls.
+
+Semantic analysis
+
+: Determine the meaning of the different function calls.
+
+Flow analysis
+
+: Determine additional emergent properties of the code.
+
+For each warning and error, I specify a unique identifier that can be used to disable the warning or error, a description of the condition for the warning or error, and a code example that demonstrates the condition and serves as a test case for the linter.
+
+Warnings and errors have different types that decides the prefix of their idenfitiers:
+
+- Warnings:
+
+ `S`
+ : Style warnings
+
+ `W`
+ : Other warnings
+
+- Errors:
+
+ `T`
+ : Type errors
+
+ `E`
+ : Other errors \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-01-preprocessing.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-01-preprocessing.md
new file mode 100644
index 00000000000..965156dbc8b
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-01-preprocessing.md
@@ -0,0 +1,29 @@
+# Preprocessing
+In the preprocessing step, the expl3 analysis tool determines which parts of the input files contain expl3 code. Inline `\TeX`{=tex} comments that disable warnings and errors are also analyzed in this step.
+
+## No standard delimiters {.w label=w100}
+An input file contains no delimiters such as `\ExplSyntaxOn`, `\ExplSyntaxOff`, `\ProvidesExplPackage`, `\ProvidesExplClass`, and `\ProvidesExplFile` [@latexteam2024interfaces, Section 2.1]. The analysis tool should assume that the whole input file is in expl3.
+
+ /w100.tex
+
+## Unexpected delimiters {.w label=w101}
+An input file contains extraneous `\ExplSyntaxOn` delimiters [@latexteam2024interfaces, Section 2.1] in expl3 parts or extraneous `\ExplSyntaxOff` delimiters in non-expl3 parts.
+
+ /w101.tex
+
+## Expl3 material in non-expl3 parts {.e label=e102}
+An input file contains what looks like expl3 material [@latexteam2024interfaces, Section 1.1] in non-expl3 parts.
+
+ /e102.tex
+
+## Line too long {.s label=s103}
+Some lines in expl3 parts are longer than 80 characters [@latexteam2024style, Section 2].
+
+ /s103.tex
+
+The maximum line length can be configured using the command-line option `--max-line-length` or with the parameter `max_line_length` of the function returned by the Lua module `explcheck-preprocessing`.
+
+## Multiple delimiters `\ProvidesExpl*` in a single file {.e label=e104}
+An input file contains multiple delimiters `\ProvidesExplPackage`, `\ProvidesExplClass`, and `\ProvidesExplFile`.
+
+ /e104.tex
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-02-lexical-analysis.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-02-lexical-analysis.md
new file mode 100644
index 00000000000..9dc0b564cd7
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-02-lexical-analysis.md
@@ -0,0 +1,157 @@
+# Lexical analysis
+In the lexical analysis step, the expl3 analysis tool converts the expl3 parts of the input files into a list of `\TeX`{=tex} tokens.
+
+## “Weird” and “Do not use” argument specifiers {.w}
+Some control sequence tokens correspond to functions with `w` (weird) or `D` (do not use) argument specifiers.
+
+``` tex
+\cs_new:Npn
+ \show_until_if:w % warning on this line
+ #1 \if:w % warning on this line
+ { \tl_show:n {#1} }
+\show_until_if:w % warning on this line
+ \tex_if:D % warning on this line
+ \if_charcode:w % warning on this line
+ \if:w % warning on this line
+```
+
+The above example has been taken from @latexteam2024interfaces [Chapter 24].
+
+## Unknown argument specifiers {.e}
+Some control sequence tokens correspond to functions with unknown argument specifiers. [@latexteam2024interfaces, Section 1.1]
+
+``` tex
+\cs_new:Nn
+ \example:bar % error on this line
+ { foo }
+ { bar }
+ { baz }
+```
+
+## Deprecated control sequences {.w}
+Some control sequence tokens correspond to deprecated expl3 control sequences from `l3obsolete.txt` [@josephwright2024obsolete].
+<!-- vi "$(texdoc -Il l3obsolete.txt | sed -r 's/\s*[0-9]+\s*//')" -->
+
+``` tex
+\str_lower_case:n % warning on this line
+ { FOO BAR }
+```
+
+## Removed control sequences {.e}
+Some control sequence tokens correspond to removed expl3 control sequences from `l3obsolete.txt` [@josephwright2024obsolete].
+<!-- vi "$(texdoc -Il l3obsolete.txt | sed -r 's/\s*[0-9]+\s*//')" -->
+
+``` tex
+\msg_log:n % error on this line
+ {
+ Foo~bar~
+ \c_one_thousand % error on this line
+ }
+```
+
+## Missing stylistic whitespaces {.s}
+Some control sequences and curly braces are not surrounded by whitespaces [@latexteam2024programming, Section 6] [@latexteam2024style, Section 3].
+
+``` tex
+\cs_new:Npn \foo_bar:Nn #1#2
+{
+ \cs_if_exist:NTF#1 % warning on this line
+ { \__foo_bar:n {#2} }
+ { \__foo_bar:nn{#2}{literal} } % warning on this line
+}
+```
+
+## Malformed function name {.s}
+Some function have names that are not in the format `\texttt{\textbackslash\meta{module}\_\meta{description}:\meta{arg-spec}}`{=tex} [@latexteam2024programming, Section 3.2].
+
+``` tex
+\cs_new:Nn
+ \description: % warning on this line
+ { foo }
+```
+
+``` tex
+\cs_new:Nn
+ \module__description: % warning on this line
+ { foo }
+```
+
+``` tex
+\cs_new:Nn
+ \_module_description: % warning on this line
+ { foo }
+```
+
+``` tex
+\cs_new:Nn
+ \__module_description:
+ { foo }
+```
+
+## Malformed variable or constant name {.s}
+Some expl3 variables and constants have names that are not in the format `\texttt{\textbackslash\meta{scope}\_\meta{module}\_\meta{description}\_\meta{type}}`{=tex} [@latexteam2024programming, Section 3.2], where the `\meta{module}`{=tex} part is optional.
+
+``` tex
+\tl_new:Nn
+ \g_description_box % warning on this line
+\tl_new:Nn
+ \l__description_box % warning on this line
+\tl_const:Nn
+ \c_description % warning on this line
+ { foo }
+```
+
+``` tex
+\tl_new:Nn
+ \g_module_description_box
+\tl_new:Nn
+ \l_module_description_box
+\tl_const:Nn
+ \c__module_description_box
+ { foo }
+```
+
+An exception is made for scratch variables [@latexteam2024interfaces, Section 1.1.1]:
+
+``` tex
+\tl_use:N
+ \l_tmpa_tl
+\int_use:N
+ \l_tmpb_int
+\str_use:N
+ \l_tmpa_str
+```
+
+## Malformed quark or scan mark name {.s}
+Some expl3 quarks and scan marks have names that do not start with `\q_` and `\s_`, respectively [@latexteam2024programming, Chapter 19].
+
+``` tex
+\quark_new:N
+ \foo_bar % error on this line
+```
+
+``` tex
+\quark_new:N
+ \q_foo_bar
+```
+
+``` tex
+\scan_new:N
+ \foo_bar % error on this line
+```
+
+``` tex
+\scan_new:N
+ \s_foo_bar
+```
+
+## Too many closing braces {.e}
+An expl3 part of the input file contains too many closing braces.
+
+``` tex
+\tl_new:N
+ \g_example_tl
+\tl_gset:Nn
+ \g_example_tl
+ { Hello,~ } } % error on this line
+```
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-03-syntactic-analysis.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-03-syntactic-analysis.md
new file mode 100644
index 00000000000..18a956167cf
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-03-syntactic-analysis.md
@@ -0,0 +1,26 @@
+# Syntactic analysis
+In the syntactic analysis step, the expl3 analysis tool converts the list of `\TeX`{=tex} tokens into a tree of function calls.
+
+## Unexpected function call argument {.e}
+A function is called with an unexpected argument. Partial applications are detected by analysing closing braces (`}`) and do not produce an error.
+
+``` tex
+\cs_new:Nn
+ \example_foo:n
+ { foo~#1 }
+\cs_new:Nn
+ \example_bar:
+ { \example_foo:n }
+\cs_new:Nn
+ \example_baz:
+ {
+ \example_bar:
+ { bar }
+ }
+```
+
+``` tex
+\cs_new:Nn
+ { unexpected } % error on this line
+ \l_tmpa_tl % error on this line
+```
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-04-semantic-analysis.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-04-semantic-analysis.md
new file mode 100644
index 00000000000..781386b8ba8
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-04-semantic-analysis.md
@@ -0,0 +1,510 @@
+# Semantic analysis
+In the semantic analysis step, the expl3 analysis tool determines the meaning of the different function calls.
+
+## Functions and conditional functions
+
+### Expanding an unexpandable variable or constant {.t}
+A function with a `V`-type argument is called with a variable or constant that does not support `V`-type expansion [@latexteam2024interfaces, Section 1.1].
+
+``` tex
+\cs_new:Nn
+ \module_foo:n
+ { #1 }
+\cs_generate_variant:Nn
+ \module_foo:n
+ { V }
+\module_foo:V % error on this line
+ \c_false_bool
+```
+
+### Unused function {.w #unused-function}
+A private function or conditional function is defined but unused.
+
+``` tex
+\cs_new:Nn % warning on this line
+ \__module_foo:
+ { bar }
+```
+
+``` tex
+\prg_new_conditional:Nnn % warning on this line
+ \__module_foo:
+ { p, T, F, TF }
+ { \prg_return_true: }
+```
+
+### Unused function variant {.w #unused-function-variant}
+A private function or conditional function variant is defined but unused.
+
+``` tex
+\cs_new:Nn
+ \__module_foo:n
+ { bar~#1 }
+\cs_generate_variant:Nn % warning on this line
+ \__module_foo:n
+ { V }
+\__module_foo:n
+ { baz }
+```
+
+``` tex
+\prg_new_conditional:Nnn
+ \__module_foo:n
+ { p, T, F, TF }
+ { \prg_return_true: }
+\prg_generate_conditional_variant:Nnn % warning on this line
+ \__module_foo:n
+ { TF }
+ { V }
+\__module_foo:nTF
+ { foo }
+ { bar }
+ { baz }
+```
+
+### Function variant of incompatible type {.t}
+A function variant is generated from an incompatible argument type [@latexteam2024interfaces, Section 5.2, documentation of function `\cs_generate_variant:Nn`].
+
+``` tex
+\cs_new:Nn
+ \module_foo:Nn
+ { bar }
+\cs_generate_variant:Nn % error on this line
+ \module_foo:Nn
+ { nn }
+\cs_generate_variant:Nn % error on this line
+ \module_foo:Nn
+ { NN }
+```
+
+### Protected predicate function {.e}
+A protected predicate function is defined.
+
+``` tex
+\prg_new_protected_conditional:Nnn
+ \module_foo:
+ { p }
+ { \prg_return_true: }
+```
+
+### Function variant for an undefined conditional function {.e}
+A variant is defined for an undefined conditional function.
+
+``` tex
+\prg_new_conditional:Nnn
+ \module_foo:n
+ { p, T, F }
+ { \prg_return_true: }
+\prg_generate_conditional_variant:Nnn % warning on this line
+ \module_foo:n
+ { TF }
+ { V }
+\module_foo:nT
+ { bar }
+ { baz }
+```
+
+### Multiply defined function variant {.w}
+A function or conditional function is defined multiple times.
+
+``` tex
+\cs_new:Nn
+ \module_foo:n
+ { bar~#1 }
+\cs_generate_variant:Nn
+ \module_foo:n
+ { V }
+\cs_generate_variant:Nn % warning on this line
+ \module_foo:n
+ { o, V }
+```
+
+``` tex
+\prg_new_conditional:Nnn
+ \module_foo:n
+ { p, T, F, TF }
+ { \prg_return_true: }
+\prg_generate_conditional_variant:Nnn
+ \module_foo:n
+ { TF }
+ { V }
+\prg_generate_conditional_variant:Nnn % warning on this line
+ \module_foo:n
+ { TF }
+ { o, V }
+```
+
+### Calling an undefined function {.e #calling-undefined-function}
+A function is used but undefined.
+
+``` tex
+\module_foo: % error on this line
+```
+
+### Calling an undefined function variant {.e #calling-undefined-function-variant}
+A function or conditional function variant is used but undefined.
+
+``` tex
+\cs_new:Nn
+ \module_foo:n
+ { bar~#1 }
+\tl_set:Nn
+ \l_tmpa_tl
+ { baz }
+\module_foo:V % error on this line
+ \l_tmpa_tl
+```
+
+``` tex
+\prg_new_conditional:Nnn
+ \module_foo:n
+ { p, T, F, TF }
+ { \prg_return_true: }
+\prg_generate_conditional_variant:Nnn
+ \module_foo:n
+ { TF }
+ { V }
+\module_foo:VTF % error on this line
+ \l_tmpa_tl
+ { foo }
+ { bar }
+```
+
+## Variables and constants
+
+### Unused variable or constant {.w #unused-variable-or-constant}
+A variable or a constant is declared and perhaps defined but unused.
+
+``` tex
+\tl_new:N % warning on this line
+ \g_declared_but_undefined_tl
+```
+
+``` tex
+\tl_new:N % warning on this line
+ \g_defined_but_unused_tl
+\tl_gset:Nn
+ \g_defined_but_unused_tl
+ { foo }
+```
+
+``` tex
+\tl_new:N
+ \g_defined_but_unused_tl
+\tl_gset:Nn
+ \g_defined_but_unused_tl
+ { foo }
+\tl_use:N
+ \g_defined_but_unused_tl
+```
+
+``` tex
+\tl_const:Nn % warning on this line
+ \c_defined_but_unused_tl
+ { foo }
+```
+
+``` tex
+\tl_const:Nn
+ \c_defined_but_unused_tl
+ { foo }
+\tl_use:N
+ \c_defined_but_unused_tl
+```
+
+### Setting an undeclared variable {.w #setting-undeclared-variable}
+An undeclared variable is set.
+
+``` tex
+\tl_gset:Nn % warning on this line
+ \g_example_tl
+ { bar }
+```
+
+### Setting a constant {.e}
+A constant is set.
+
+``` tex
+\tl_gset:Nn % error on this line
+ \c_example_tl
+ { bar }
+```
+
+### Using a token list variable or constant without an accessor {.w}
+A token list variable or constant is used without an accessor function.
+
+``` tex
+\tl_set:Nn
+ \l_tmpa_tl
+ { world }
+Hello,~\l_tmpa_tl! % warning on this line
+Hello,~\tl_use:N \l_tmpa_tl !
+```
+
+This also applies to subtypes of token lists such as strings
+and comma-lists:
+
+``` tex
+\str_set:Nn
+ \l_tmpa_str
+ { world }
+Hello,~\l_tmpa_str! % warning on this line
+Hello,~\str_use:N \l_tmpa_str !
+```
+
+``` tex
+\clist_set:Nn
+ \l_tmpa_clist
+ { world }
+Hello,~\l_tmpa_clist! % warning on this line
+Hello,~\clist_use:Nn \l_tmpa_clist { and } !
+```
+
+### Using non-token-list variable or constant without an accessor {.e #using-variables-without-accessors}
+A non-token-list variable or constant is used without an accessor function.
+
+``` tex
+Hello,~\l_tmpa_seq! % error on this line
+Hello,~\seq_use:Nn \l_tmpa_seq { and } !
+```
+
+Note that boolean and integer variables may be used without accessor functions in boolean and integer expressions, respectively. Therefore, we may want to initially exclude them from this check to prevent false positives.
+
+### Multiply declared variable or constant {.e}
+A variable or constant is declared multiple times.
+
+``` tex
+\tl_new:N
+ \g_example_tl
+\tl_new:N % error on this line
+ \g_example_tl
+```
+
+``` tex
+\tl_const:Nn
+ \c_example_tl
+ { foo }
+\tl_const:Nn % error on this line
+ \c_example_tl
+ { bar }
+```
+
+### Using an undefined variable or constant {.e #using-undefined-variable-or-constant}
+A variable or constant is used but undeclared or undefined.
+
+``` tex
+\tl_use:N % error on this line
+ \g_undeclared_tl
+```
+
+``` tex
+\tl_new:N
+ \g_declared_but_undefined_tl
+\tl_use:N % error on this line
+ \g_declared_but_undefined_tl
+```
+
+``` tex
+\tl_new:N
+ \g_defined_tl
+\tl_gset:Nn
+ \g_defined_tl
+ { foo }
+\tl_use:N
+ \g_defined_tl
+```
+
+``` tex
+\tl_use:N % error on this line
+ \c_undefined_tl
+```
+
+``` tex
+\tl_const:Nn
+ \c_defined_tl
+ { foo }
+\tl_use:N
+ \c_defined_tl
+```
+
+### Locally setting a global variable {.e}
+A global variable is locally set.
+
+``` tex
+\tl_new:N
+ \g_example_tl
+\tl_set:Nn % error on this line
+ \g_example_tl
+ { foo }
+```
+
+### Globally setting a local variable {.e}
+A local variable is globally set.
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_gset:Nn % error on this line
+ \l_example_tl
+ { foo }
+```
+
+### Using a variable of an incompatible type {.t}
+A variable of one type is used where a variable of a different type should be used.
+
+``` tex
+\tl_new:N
+ \l_example_str % error on this line
+```
+
+``` tex
+\ior_new:N
+ \l_example_ior
+\iow_open:Nn
+ \l_example_ior % error on this line
+ { example }
+```
+
+``` tex
+\clist_new:N
+ \l_example_clist
+\tl_set:Nn
+ \l_tmpa_tl
+ { foo }
+\clist_set_eq:NN
+ \l_example_clist
+ \l_tmpa_tl % error on this line
+```
+
+``` tex
+\tl_set:Nn
+ \l_tmpa_tl
+ { foo }
+\seq_set_from_clist:NN
+ \l_tmpa_seq
+ \l_tmpa_tl % error on this line
+```
+
+``` tex
+\tl_set:Nn
+ \l_tmpa_tl
+ { foo }
+\regex_set:Nn
+ \l_tmpa_regex
+ { foo }
+\int_set:Nn
+ \l_tmpa_int
+ { 1 + 2 }
+\regex_show:N
+ \l_tmpa_tl
+\regex_show:N
+ \l_tmpa_regex
+\regex_show:N
+ \l_tmpa_int % error on this line
+```
+
+``` tex
+\tl_set:Nn
+ \l_tmpa_tl
+ { foo }
+\int_set_eq:NN
+ \l_tmpa_int
+ \l_tmpa_tl % error on this line
+```
+
+## Messages
+
+### Unused message {.w #unused-message}
+A message is defined but unused.
+
+``` tex
+\msg_new:nnn % warning on this line
+ { foo }
+ { bar }
+ { baz }
+```
+
+``` tex
+\msg_new:nnn
+ { bar }
+ { bar }
+ { baz }
+\msg_info:nn
+ { bar }
+ { bar }
+```
+
+### Setting an undefined message {.w #setting-undefined-message}
+A message is set but undefined.
+
+``` tex
+\msg_set:nnn % error on this line
+ { foo }
+ { bar }
+ { baz }
+```
+
+``` tex
+\msg_new:nnn
+ { foo }
+ { bar }
+ { baz }
+\msg_set:nnn
+ { foo }
+ { bar }
+ { baz }
+```
+
+### Multiply defined message {.e}
+A message is defined multiple times.
+
+``` tex
+\msg_new:nnn
+ { foo }
+ { bar }
+ { baz }
+\msg_new:nnn % error on this line
+ { foo }
+ { bar }
+ { baz }
+```
+
+### Using an undefined message {.e #using-undefined-message}
+A message is used but undefined.
+
+``` tex
+\msg_info:nn
+ { foo }
+ { bar }
+```
+
+### Incorrect parameters in message text {.e #invalid-parameters-in-message-text}
+Parameter tokens other than `#1`, `#2`, `#3`, and `#4` are specified in a message text.
+
+``` tex
+\msg_new:nnn
+ { foo }
+ { bar }
+ { #5 } % error on this line
+```
+
+``` tex
+\msg_new:nnnn
+ { foo }
+ { bar }
+ { #4 }
+ { #5 } % error on this line
+```
+
+## Sorting
+### Comparison conditional without signature `:nnTF` {.e}
+A sorting function is called with a conditional that has a signature different than `:nnTF` [@latexteam2024interfaces, Section 15.5.4].
+
+``` tex
+\cs_new:Nn
+ \example_foo:
+ { \prg_return_true: }
+\tl_sort:nN
+ { { foo } { bar } }
+ \example_foo:TF
+```
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-05-flow-analysis.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-05-flow-analysis.md
new file mode 100644
index 00000000000..257b7407838
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-05-flow-analysis.md
@@ -0,0 +1,651 @@
+# Flow analysis
+In the flow analysis step, the expl3 analysis tool determines compiler-theoretic properties of functions, such as expandability, and variables, such as reaching definitions.
+
+## Functions and conditional functions
+
+### Multiply defined function {.e}
+A function or conditional function is defined multiple times.
+
+``` tex
+\cs_new:Nn
+ \module_foo:
+ { bar }
+\cs_new:Nn % error on this line
+ \module_foo:
+ { bar }
+```
+
+``` tex
+\cs_new:Nn
+ \module_foo:
+ { bar }
+\cs_undefine:N
+ \module_foo:
+\cs_new:Nn
+ \module_foo:
+ { bar }
+```
+
+``` tex
+\prg_new_conditional:Nnn
+ \module_foo:
+ { p, T, F, TF }
+ { \prg_return_true: }
+\prg_new_conditional:Nnn % error on this line
+ \module_foo:
+ { p, T, F, TF }
+ { \prg_return_true: }
+```
+
+``` tex
+\prg_new_conditional:Nnn
+ \module_foo:
+ { p, T, F, TF }
+ { \prg_return_true: }
+\cs_undefine:N
+ \module_foo_p:
+\cs_undefine:N
+ \module_foo:T
+\cs_undefine:N
+ \module_foo:F
+\cs_undefine:N
+ \module_foo:TF
+\prg_new_conditional:Nnn
+ \module_foo:
+ { p, T, F, TF }
+ { \prg_return_true: }
+```
+
+### Unreachable function {.w}
+A private function or conditional function is defined but all its calls are unreachable.[^1]
+
+ [^1]: Code is unreachable if it is only reachable through private functions which that are either unused or also unreachable.
+
+``` tex
+\cs_new:Nn % warning on this line
+ \__module_foo:
+ { bar }
+\cs_new:Nn
+ \__module_baz:
+ { \__module_foo: }
+```
+
+This check is a stronger version of <#unused-function> and should only be emitted if <#unused-function> has not previously been emitted for this function.
+
+### Unreachable function variant {.w}
+A private function or conditional function variant is defined but all its calls are unreachable.
+
+``` tex
+\cs_new:Nn
+ \__module_foo:n
+ { bar~#1 }
+\cs_new:Nn
+ \__module_baz:
+ {
+ \tl_set:Nn
+ \l_tmpa_tl
+ { baz }
+ \__module_foo:V
+ \l_tmpa_tl
+ }
+\cs_generate_variant:Nn % warning on this line
+ \__module_foo:n
+ { V }
+\__module_foo:n
+ { baz }
+```
+
+This check is a stronger version of <#unused-function-variant> and should only be emitted if <#unused-function-variant> has not previously been emitted for this function variant.
+
+### Calling a function before definition {.e}
+A function is used before it has been defined or after it has been undefined.
+
+``` tex
+\module_foo: % error on this line
+\cs_new:Nn
+ \module_foo:
+ { bar }
+```
+
+``` tex
+\cs_new:Nn
+ \module_foo:
+ { bar }
+\cs_undefine:N
+ \module_foo:
+\module_foo: % error on this line
+```
+
+This check is a stronger version of <#calling-undefined-function> and should only be emitted if <#calling-undefined-function> has not previously been emitted for this function.
+
+### Calling a function variant before definition {.e}
+A function or conditional function variant is used before it has been defined.
+
+``` tex
+\cs_new:Nn
+ \module_foo:n
+ { bar~#1 }
+\tl_set:Nn
+ \l_tmpa_tl
+ { baz }
+\module_foo:V % error on this line
+ \l_tmpa_tl
+\cs_generate_variant:Nn
+ \module_foo:n
+ { V }
+```
+
+This check is a stronger version of <#calling-undefined-function-variant> and should only be emitted if <#calling-undefined-function-variant> has not previously been emitted for this function variant.
+
+### Setting a function before definition {.w}
+A function is set before it has been defined or after it has been undefined.
+
+``` tex
+\cs_gset:N % warning on this line
+ \module_foo:
+ { foo }
+\cs_new:Nn
+ \module_foo:
+ { bar }
+```
+
+``` tex
+\cs_new:Nn
+ \module_foo:
+ { bar }
+\cs_undefine:N
+ \module_foo:
+\cs_gset:N % warning on this line
+ \module_foo:
+ { foo }
+```
+
+### Unexpandable or restricted-expandable boolean expression {.e}
+A boolean expression [@latexteam2024interfaces, Section 9.2] is not fully-expandable.
+
+``` tex
+\cs_new_protected:N
+ \example_unexpandable:
+ {
+ \tl_set:Nn
+ \l_tmpa_tl
+ { bar }
+ \c_true_bool
+ }
+\cs_new:N
+ \example_restricted_expandable:
+ {
+ \bool_do_while:Nn
+ \c_false_bool
+ { }
+ \c_true_bool
+ }
+\cs_new_protected:N
+ \example_expandable:
+ { \c_true_bool }
+\bool_set:Nn
+ \l_tmpa_bool
+ { \example_unexpandable: } % error on this line
+\bool_set:Nn
+ \l_tmpa_bool
+ { \example_restricted_expandable: } % error on this line
+\bool_set:Nn
+ \l_tmpa_bool
+ { \example_expandable: }
+```
+
+### Expanding an unexpandable function {.e}
+An unexpandable function or conditional function is called within an `x`-type, `e`-type, or `f`-type argument.
+
+``` tex
+\cs_new_protected:N
+ \example_unexpandable:
+ {
+ \tl_set:Nn
+ \l_tmpa_tl
+ { bar }
+ }
+\cs_new:N
+ \module_foo:n
+ { #1 }
+\cs_generate_variant:Nn
+ \module_foo:n
+ { x, e, f }
+\module_foo:n
+ { \example_unexpandable: }
+\module_foo:x
+ { \example_unexpandable: } % error on this line
+\module_foo:e
+ { \example_unexpandable: } % error on this line
+\module_foo:f
+ { \example_unexpandable: } % error on this line
+```
+
+### Fully-expanding a restricted-expandable function {.e}
+An restricted-expadable function or conditional function is called within an `f`-type argument.
+
+``` tex
+\cs_new:N
+ \example_restricted_expandable:
+ {
+ \int_to_roman:n
+ { 1 + 2 }
+ }
+\cs_new:N
+ \module_foo:n
+ { #1 }
+\cs_generate_variant:Nn
+ \module_foo:n
+ { x, e, f }
+\module_foo:n
+ { \example_restricted_expandable: }
+\module_foo:x
+ { \example_restricted_expandable: }
+\module_foo:e
+ { \example_restricted_expandable: }
+\module_foo:f
+ { \example_restricted_expandable: } % error on this line
+```
+
+### Defined an expandable function as protected {.w}
+A fully expandable function or conditional function is defined using a creator function `\cs_new_protected:*` or `\prg_new_protected_conditional:*`. [@latexteam2024style, Section 4]
+
+``` tex
+\cs_new_protected:Nn % warning on this line
+ \example_expandable:
+ { foo }
+```
+
+``` tex
+\prg_new_protected_conditional:Nnn % warning on this line
+ \example_expandable:
+ { T, F, TF }
+ { \prg_return_true: }
+```
+
+### Defined an unexpandable function as unprotected {.w}
+An unexpandable or restricted-expandable function or conditional function is defined using a creator function `\cs_new:*` or `\prg_new_conditional:*`. [@latexteam2024style, Section 4]
+
+``` tex
+\cs_new:Nn % warning on this line
+ \example_unexpandable:
+ {
+ \tl_set:Nn
+ \l_tmpa_tl
+ { bar }
+ }
+```
+
+``` tex
+\prg_new_conditional:Nnn % warning on this line
+ \example_unexpandable:
+ { p, T, F, TF }
+ {
+ \tl_set:Nn
+ \l_tmpa_tl
+ { bar }
+ \prg_return_true:
+ }
+```
+
+### Conditional function with no return value {.e}
+A conditional functions has no return value.
+
+``` tex
+\prg_new_conditional:Nnn % error on this line
+ \example_no_return_value:
+ { p, T, F, TF }
+ { foo }
+```
+
+``` tex
+\prg_new_conditional:Nnn
+ \example_has_return_value:
+ { p, T, F, TF }
+ { \example_foo: }
+\cs_new:Nn
+ \example_foo:
+ { \prg_return_true: }
+```
+
+### Comparison code with no return value {.e}
+A comparison code [@latexteam2024interfaces, Section 6.1] has no return value.
+
+``` tex
+\clist_set:Nn
+ \l_foo_clist
+ { 3 , 01 , -2 , 5 , +1 }
+\clist_sort:Nn % error on this line
+ \l_foo_clist
+ { foo }
+```
+
+``` tex
+\clist_set:Nn
+ \l_foo_clist
+ { 3 , 01 , -2 , 5 , +1 }
+\clist_sort:Nn
+ \l_foo_clist
+ { \example_foo: }
+\cs_new:Nn
+ \example_foo:
+ {
+ \int_compare:nNnTF { #1 } > { #2 }
+ { \sort_return_swapped: }
+ { \sort_return_same: }
+ }
+```
+
+The above example has been taken from @latexteam2024interfaces [Chapter 6].
+
+## Variables and constants
+
+### Unreachable variable or constant {.w}
+A variable or a constant is declared and perhaps defined but all its uses are unreachable.
+
+``` tex
+\tl_new:N % warning on this line
+ \g_defined_but_unreachable_tl
+\tl_gset:Nn
+ \g_defined_but_unreachable_tl
+ { foo }
+\cs_new:Nn
+ \__module_baz:
+ {
+ \tl_use:N
+ \g_defined_but_unreachable_tl
+ }
+```
+
+This check is a stronger version of <#unused-variable-or-constant> and should only be emitted if <#unused-variable-or-constant> has not previously been emitted for this variable or constant.
+
+### Setting a variable before declaration {.e}
+A variable is set before it has been declared.
+
+``` tex
+\tl_gset:Nn % error on this line
+ \g_example_tl
+ { bar }
+\tl_new:N
+ \g_example_tl
+```
+
+This check is a stronger version of <#setting-undeclared-variable> and should prevent <#setting-undeclared-variable> from being emitted for this variable.
+
+### Using a variable or constant before definition {.e}
+A variable or constant is used before it has been defined.
+
+``` tex
+\tl_new:N
+ \g_example_tl
+\tl_use:N % error on this line
+ \g_example_tl
+\tl_gset:Nn
+ \g_example_tl
+ { foo }
+```
+
+This check is a stronger version of <#using-undefined-variable-or-constant> and should only be emitted if <#using-undefined-variable-or-constant> has not previously been emitted for this variable or constant.
+
+## Messages
+
+### Unreachable message {.w}
+A message is defined but all its uses are unreachable.
+
+``` tex
+\msg_new:nnn % warning on this line
+ { foo }
+ { bar }
+ { baz }
+\cs_new:Nn
+ \__module_baz:
+ {
+ \msg_info:nn
+ { foo }
+ { bar }
+ }
+```
+
+This check is a stronger version of <#unused-message> and should only be emitted if <#unused-message> has not previously been emitted for this message.
+
+### Setting a message before definition {.e}
+A message is set before it has been defined.
+
+``` tex
+\msg_set:nnn % error on this line
+ { foo }
+ { bar }
+ { baz }
+\msg_new:nnn
+ { foo }
+ { bar }
+ { baz }
+```
+
+This check is a stronger version of <#setting-undefined-message> and should prevent <#setting-undefined-message> from being emitted for this message.
+
+### Using a message before definition {.e}
+A message is used before it has been defined.
+
+``` tex
+\msg_info:nn % error on this line
+ { foo }
+ { bar }
+\msg_new:nnn
+ { foo }
+ { bar }
+ { baz }
+```
+
+This check is a stronger version of <#using-undefined-message> and should only be emitted if <#using-undefined-message> has not previously been emitted for this message.
+
+### Too few arguments supplied to message {.e #too-few-arguments-supplied-to-message}
+A message was supplied fewer arguments than there are parameters in the message text.
+
+``` tex
+\msg_new:nnn
+ { foo }
+ { bar }
+ { #1~#2 }
+\msg_info:nn % error on this line
+ { foo }
+ { bar }
+\msg_info:nnn % error on this line
+ { foo }
+ { bar }
+ { baz }
+\msg_info:nnnn
+ { foo }
+ { bar }
+ { baz }
+ { baz }
+```
+
+Since a message can be redefined, we need to track the (possibly many) definitions that can be active when we display a message.
+
+``` tex
+\msg_new:nnn
+ { foo }
+ { bar }
+ { #1 }
+\msg_set:nnn
+ { foo }
+ { bar }
+ { baz }
+\msg_info:nnn % error on this line
+ { foo }
+ { bar }
+ { baz }
+```
+
+``` tex
+\msg_new:nnn
+ { foo }
+ { bar }
+ { #1 }
+\msg_info:nnn
+ { foo }
+ { bar }
+ { baz }
+\msg_set:nnn
+ { foo }
+ { bar }
+ { baz }
+```
+
+## Input–output streams
+### Using an unopened or closed stream {.e}
+A stream is used before it has been opened or after it has been closed.
+
+``` tex
+\ior_new:N
+ \l_example_ior
+\ior_str_get:NN % error on this line
+ \l_example_ior
+ \l_tmpa_tl
+\ior_open:Nn
+ \l_example_ior
+ { example }
+```
+
+``` tex
+\ior_new:N
+ \l_example_ior
+\ior_open:Nn
+ \l_example_ior
+ { example }
+\ior_close:N
+ \l_example_ior
+\ior_str_get:NN % error on this line
+ \l_example_ior
+ \l_tmpa_tl
+```
+
+### Multiply opened stream {.e}
+A stream is opened a second time without closing the stream first.
+
+``` tex
+\iow_new:N
+ \l_example_iow
+\iow_open:Nn
+ \l_example_iow
+ { foo }
+\iow_open:Nn % error on this line
+ \l_example_iow
+ { bar }
+\iow_close:N
+ \l_example_iow
+```
+
+### Unclosed stream {.w}
+A stream is opened but not closed.
+
+``` tex
+% file-wide warning
+\ior_new:N
+ \l_example_ior
+\ior_open:Nn
+ \l_example_ior
+ { example }
+```
+
+## Piecewise token list construction
+### Building on a regular token list {.t}
+A token list variable is used with `\tl_build_*` functions before a function `\tl_build_*begin:N` has been called or after a function `\tl_build_*end:N` has been called.
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_build_put_right:Nn % error on this line
+ \l_example_tl
+ { foo }
+\tl_build_begin:N
+ \l_example_tl
+\tl_build_end:N
+ \l_example_tl
+```
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+\tl_build_put_right:Nn
+ \l_example_tl
+ { foo }
+\tl_build_end:N
+ \l_example_tl
+```
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+\tl_build_end:N
+ \l_example_tl
+\tl_build_put_right:Nn % error on this line
+ \l_example_tl
+ { foo }
+```
+
+### Using a semi-built token list {.t}
+A token list variable is used where a regular token list is expected after a function `\tl_build_*begin:N` has been called and before a function `\tl_build_*end:N` has been called.
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_use:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+\tl_build_end:N
+ \l_example_tl
+```
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+\tl_use:N
+ \l_example_tl % error on this line
+\tl_build_end:N
+ \l_example_tl
+```
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+\tl_build_end:N
+ \l_example_tl
+\tl_use:N
+ \l_example_tl
+```
+
+### Multiply started building a token list {.e}
+A function `\tl_build_*begin:N` is called on a token list variable a second time without calling a function `\tl_build_*end:N` first.
+
+``` tex
+\tl_new:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+\tl_build_begin:N % error on this line
+ \l_example_tl
+\tl_build_end:N
+ \l_example_tl
+```
+
+### Unfinished semi-built token list {.w}
+A function `\tl_build_*begin:N` is called on a token list variable without calling a function `\tl_build_*end:N` later.
+
+``` tex
+% file-wide warning
+\tl_new:N
+ \l_example_tl
+\tl_build_begin:N
+ \l_example_tl
+```
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors-99-caveats.md b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-99-caveats.md
new file mode 100644
index 00000000000..47bd424a0e3
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors-99-caveats.md
@@ -0,0 +1,141 @@
+# Caveats
+The warnings and errors in this documents do not cover the complete expl3 language. The caveats currently include the following areas, among others:
+
+- Functions with “weird” (`w`) argument specifiers
+- Verifying the `nopar` restriction on functions
+ [@latexteam2024interfaces, Section 4.3.1]
+- Symbolic evaluation of expansion functions
+ [@latexteam2024interfaces, sections 5.4–5.10]
+- Validation of parameters in (inline) functions
+ (c.f. <#invalid-parameters-in-message-text>
+ and <#too-few-arguments-supplied-to-message>)
+- Shorthands such as `\~` and `\\` in message texts
+ [@latexteam2024interfaces, sections 11.4 and 12.1.3]
+- Quotes in shell commands and file names
+ [@latexteam2024interfaces, Section 10.7 and Chapter 12]
+- Functions used outside their intended context:
+ - `\sort_return_*:` outside comparison code
+ [@latexteam2024interfaces, Section 6.1]
+ - `\prg_return_*:` outside conditional functions
+ [@latexteam2024interfaces, Section 9.1]
+ - Predicates (`\*_p:*`) outside boolean expressions
+ [@latexteam2024interfaces, Section 9.3]
+ - `\*_map_break:*` outside a corresponding mapping
+ [@latexteam2024interfaces, sections 9.8]
+ - `\msg_line_*:`, `\iow_char:N`, and `\iow_newline:`
+ outside message text
+ [@latexteam2024interfaces, sections 11.3 and 12.1.3]
+ - `\iow_wrap_allow_break:` and `\iow_indent:n`
+ outside wrapped message text
+ [@latexteam2024interfaces, Section 12.1.4]
+ - Boolean variable without an accessor function
+ `\bool_to_str:N` outside boolean expressions
+ [@latexteam2024interfaces, Section 21.4]
+ (see <#using-variables-without-accessors>)
+ - Integer variable without an accessor function
+ `\int_use:N` outside integer or floating point
+ expressions [@latexteam2024interfaces, Section 21.4]
+ (see <#using-variables-without-accessors>)
+ - Dimension variable without an accessor function
+ `\dim_use:N` outside dimension or floating point
+ expressions [@latexteam2024interfaces, Section 26.7]
+ (see <#using-variables-without-accessors>)
+ - Skip variable without an accessor function
+ `\skip_use:N` outside skip or floating point expressions
+ [@latexteam2024interfaces, Section 26.14]
+ (see <#using-variables-without-accessors>)
+ - Muskip variable without an accessor function
+ `\muskip_use:N` outside muskip or floating point
+ expressions [@latexteam2024interfaces, Section 26.21]
+ (see <#using-variables-without-accessors>)
+ - Floating point variable without an accessor function
+ `\fp_use:N` outside floating point
+ expressions [@latexteam2024interfaces, Section 29.3]
+ (see <#using-variables-without-accessors>)
+ - Box variable without accessor functions
+ `\box_use(_drop)?:N` or `\[hv]box_unpack(_drop)?:N`,
+ or without a measuring function
+ `\box_(dp|ht|wd|ht_plus_dp):*` outside dimension or
+ floating point expressions
+ [@latexteam2024interfaces, sections 35.2 and 35.3]
+ - Coffin variable without accessor function
+ `\coffin_typeset:Nnnnn` outside dimension or
+ floating point expressions
+ [@latexteam2024interfaces, Section 36.4]
+- Validation of literal expressions:
+ - Comparison expressions in functions
+ `\*_compare(_p:n|:nT?F?)`
+ - Regular expressions and replacement text
+ [@latexteam2024interfaces, sections 8.1 and 8.2]
+ - Boolean expressions
+ [@latexteam2024interfaces, Section 9.3]
+ - Integer expressions and bases
+ [@latexteam2024interfaces, sections 21.1 and 21.8]
+ - Dimension, skip, and muskip expressions
+ [@latexteam2024interfaces, Chapter 26]
+ - Floating point expressions
+ [@latexteam2024interfaces, Section 29.12]
+ - Color expressions
+ [@latexteam2024interfaces, Chapter 37.3]
+- Validation of naming schemes and member access:
+ - String encoding and escaping
+ [@latexteam2024interfaces, Section 18.1]
+ - Key–value interfaces
+ [@latexteam2024interfaces, Chapter 27]:
+ - Are keys defined at the point of use or is the module
+ or its subdivision set up to accept unknown keys?
+ [@latexteam2024interfaces, sections 27.2, 27.5,
+ and 27.6]
+ - Are inheritance parents, choices, multi-choices, and
+ groups used in a key definition defined at points of
+ use? [@latexteam2024interfaces, sections 27.1, 27.3,
+ and 27.7]
+ - Floating-point symbolic expressions and user-defined
+ functions [@latexteam2024interfaces, sections 29.6
+ and 29.7]
+ - Names of bitset indexes
+ [@latexteam2024interfaces, Section 31.1]
+ - BCP-47 language tags
+ [@latexteam2024interfaces, Section 34.2]
+ - Color support
+ [@latexteam2024interfaces, Chapter 37]:
+ - Named colors [@latexteam2024interfaces, Section 37.4]
+ - Color export targets [@latexteam2024interfaces,
+ Section 37.8]
+ - Color models and their families and params
+ [@latexteam2024interfaces, sections 37.2 and 37.9]
+- Function `\file_input_stop:` not used on its own line
+ [@latexteam2024interfaces, Section 12.2.3]
+- Exhaustively or fully expanding quarks and scan marks
+ [@latexteam2024interfaces, Chapter 19]
+- Bounds checking for accessing constant sequences and other
+ sequences where the number of items can be easily bounded
+ such as integer and floating point arrays
+ [@latexteam2024interfaces, chapters 28 and 30]:
+ - Index checking functions `\*_range*:*` and `\*_item*:*`
+ - Endless loop checking in functions `\*_step_*:*`
+ [@latexteam2024interfaces, Section 21.7]
+ - Number of symbols in a value-to-symbol mapping
+ [@latexteam2024interfaces, Section 21.8]
+- Applying functions `\clist_remove_duplicates:N` and
+ `\clist_if_in:*` to comma lists that contain `{`, `}`, or `*`
+ [@latexteam2024interfaces, sections 23.3 and 23.4]
+- Incorrect parameters to function `\char_generate:nn`
+ [@latexteam2024interfaces, Section 24.1]
+- Incorrect parameters to functions `\char_set_*code:nn`
+ [@latexteam2024interfaces, Section 24.2]
+- Using implicit tokens `\c_catcode_(letter|other)_token` or
+ the token list `\c_catcode_active_tl`
+ [@latexteam2024interfaces, Section 24.3]
+- Validation of key–value interfaces
+ [@latexteam2024interfaces, Chapter 27]:
+ - Setting a key with some properties `.*_g?(set|put)*:*`
+ should be validated similarly to calling the corresponding
+ functions directly: Have the variables been declared, do
+ they have the correct type, does the value have the
+ correct type?
+ - Do points of use always set keys with property
+ `.value_required:n` and never set keys with
+ property `.value_forbidden:n`?
+- Horizontal box operation on a vertical box or vice
+ versa [@latexteam2024interfaces, Chapter 35]
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors.bib b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.bib
new file mode 100644
index 00000000000..189014b1174
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.bib
@@ -0,0 +1,55 @@
+@online{latexteam2024interfaces,
+ title = {The {\LaTeX}3 interfaces},
+ author = {{The {\LaTeX} Project}},
+ date = {2024-05-08},
+ url = {http://mirrors.ctan.org/macros/latex/required/l3kernel/interface3.pdf},
+ urldate = {2024-05-15},
+ note = {The referenced version of the document is attached to this document.\embedfile{interface3.pdf}},
+}
+
+@online{latexteam2024style,
+ title = {The {\LaTeX}3 kernel},
+ subtitle = {Style guide for code authors},
+ author = {{The {\LaTeX} Project}},
+ date = {2024-04-11},
+ url = {http://mirrors.ctan.org/macros/latex/required/l3kernel/l3styleguide.pdf},
+ urldate = {2024-05-08},
+ note = {The referenced version of the document is attached to this document.\embedfile{l3styleguide.pdf}},
+}
+
+@online{latexteam2024programming,
+ title = {The expl3 package and {\LaTeX}3 programming},
+ author = {{The {\LaTeX} Project}},
+ date = {2024-04-11},
+ url = {http://mirrors.ctan.org/macros/latex/required/l3kernel/expl3.pdf},
+ urldate = {2024-05-08},
+ note = {The referenced version of the document is attached to this document.\embedfile{expl3.pdf}},
+}
+
+@online{starynovotny2024static3,
+ title = {Static analysis of expl3 programs (3)},
+ subtitle = {Design Specification},
+ author = {Starý Novotný, Vít},
+ url = {https://witiko.github.io/Expl3-Linter-3/},
+% urldate = {XXX},
+ note = {To be released},
+}
+
+@online{josephwright2024obsolete,
+ author = {Joseph Wright},
+ date = {2024-04-29},
+ url = {https://github.com/latex3/latex3/pull/1542#issuecomment-2082352499},
+ urldate = {2024-05-15},
+}
+
+@book{flemming1999principles,
+ author = {Flemming Nielson and Nielson, Hanne Riis and Chris Hankin},
+ title = {Principles of Program Analysis},
+ doi = {10.1007/978-3-662-03811-6},
+ isbn = {978-3-540-65410-0},
+ date = {1999-10-22},
+ publisher = {Springer},
+ location = {Berlin, Heidelberg},
+ edition = {1},
+ pagetotal = {452},
+}
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors.cls b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.cls
new file mode 100644
index 00000000000..168488db23e
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.cls
@@ -0,0 +1,24 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass%
+ {warnings-and-errors}%
+ [2024-12-04 0.0.4 Document class for typesetting the documentation of the %
+ warnings and errors for the expl3 analysis tool]
+\LoadClass{article}
+\RequirePackage{lua-widow-control}
+\RequirePackage{minted}
+\setminted{breaklines, linenos}
+\RequirePackage{markdown}
+\markdownSetup {
+ import = {
+ witiko/expltools = metadata,
+ witiko/expltools/explcheck/warnings-and-errors = body,
+ }
+}
+\RequirePackage{biblatex}
+\addbibresource{warnings-and-errors.bib}
+\RequirePackage{embedfile}
+\RequirePackage{imakeidx}
+\makeindex[columns=3, intoc, options=-s warnings-and-errors.ist]
+\RequirePackage{hyperref}
+\def\meta#1{$\langle$\textrm{\textit{#1}}$\rangle$}
+\RequirePackage{datetime2}
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors.ist b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.ist
new file mode 100644
index 00000000000..cffb2b4873e
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.ist
@@ -0,0 +1,4 @@
+headings_flag 1
+
+heading_prefix "\n\\noindent\\textbf{"
+heading_suffix "}\\par\\nopagebreak\n" \ No newline at end of file
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors.pdf b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.pdf
new file mode 100644
index 00000000000..53c8011a94e
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/expltools/warnings-and-errors.tex b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.tex
new file mode 100644
index 00000000000..37b70748729
--- /dev/null
+++ b/Master/texmf-dist/doc/support/expltools/warnings-and-errors.tex
@@ -0,0 +1,24 @@
+\documentclass{warnings-and-errors}
+\begin{yaml}[snippet=metadata]
+title: Warnings and errors for the expl3 analysis tool
+author: Vít Starý Novotný
+date: `\today`{=tex}
+\end{yaml}
+\begin{document}
+\tableofcontents
+\clearpage
+\setcounter{secnumdepth}{0}
+\markdownSetup{snippet=body}
+\markdownInput{warnings-and-errors-00-introduction.md}
+\setcounter{secnumdepth}{1}
+\markdownInput{warnings-and-errors-01-preprocessing.md}
+\markdownInput{warnings-and-errors-02-lexical-analysis.md}
+\markdownInput{warnings-and-errors-03-syntactic-analysis.md}
+\setcounter{secnumdepth}{2}
+\markdownInput{warnings-and-errors-04-semantic-analysis.md}
+\markdownInput{warnings-and-errors-05-flow-analysis.md}
+\setcounter{secnumdepth}{0}
+\markdownInput{warnings-and-errors-99-caveats.md}
+\printbibliography[heading=bibintoc]
+\printindex
+\end{document}
diff --git a/Master/texmf-dist/doc/support/extractbb/README.md b/Master/texmf-dist/doc/support/extractbb/README.md
new file mode 100644
index 00000000000..164d282e487
--- /dev/null
+++ b/Master/texmf-dist/doc/support/extractbb/README.md
@@ -0,0 +1,81 @@
+<!-- extractbb-lua
+ https://github.com/gucci-on-fleek/extractbb
+ SPDX-License-Identifier: MPL-2.0+ OR CC-BY-SA-4.0+
+ SPDX-FileCopyrightText: 2024 Max Chernoff
+-->
+
+`extractbb-lua`
+===============
+
+A reimplementation of
+[`extractbb`](https://texdoc.org/serve/extractbb/0), written in Lua.
+
+
+Variants
+--------
+
+There are two variants of `extractbb-lua`:
+
+- **`wrapper`**: A wrapper script around the original `xdvipdmfx`-based
+ `extractbb` that is used to fix a security vulernability in
+ `xdvipdfmx`.
+
+- **`scratch`**: A standalone implementation of `extractbb`, written in
+ Lua from scratch, with no dependencies on `xdvipdfmx`.
+
+Currently, the script `extractbb` defaults to the `wrapper` variant, but
+you can manually select any specific variant by setting the
+`TEXLIVE_EXTRACTBB` environment variable to either `wrapper` or
+`scratch`.
+
+> [!WARNING]
+> The `scratch` variant is still in development and may be buggy or
+> insecure.
+
+
+### Secret Developer Options
+
+If you set `TEXLIVE_EXTRACTBB` to the full path of an executable, it
+will run that directly. And if you set
+`TEXLIVE_EXTRACTBB_UNSAFE=unsafe`, then it will ignore some of the
+security checks.
+
+
+Support
+-------
+
+If you have any problems with this tool, please report it (in order of
+preference):
+
+1. By [opening a new issue on
+ GitHub](https://github.com/gucci-on-fleek/extractbb/issues/new).
+
+2. Via email to the public [`tex-live@tug.org` mailing list](https://tug.org/mailman/listinfo/tex-live).
+
+3. By contacting the author directly at `tex@maxchernoff.ca`.
+
+
+Building
+--------
+
+Please see the file
+[`documentation/BUILDING.md`](https://github.com/gucci-on-fleek/extractbb/blob/master/documentation/BUILDING.md)
+on GitHub.
+
+
+Licence
+-------
+
+`extractbb-lua` is licensed under the [_Mozilla Public License_, version
+2.0](https://www.mozilla.org/en-US/MPL/2.0/) or greater. The
+documentation is additionally licensed under [CC-BY-SA, version
+4.0](https://creativecommons.org/licenses/by-sa/4.0/legalcode) or
+greater.
+
+The test files have various licences, please see the file
+[`tests/LICENCE.md`](tests/LICENCE.md) for more information. (Since
+these files are not distributed with the package, neither is this
+licence file.)
+
+---
+_v1.0.6 (2024-11-21)_ <!--%%version %%dashdate-->
diff --git a/Master/texmf-dist/doc/support/extractbb/extractbb.man1.pdf b/Master/texmf-dist/doc/support/extractbb/extractbb.man1.pdf
new file mode 100644
index 00000000000..e038e6d0384
--- /dev/null
+++ b/Master/texmf-dist/doc/support/extractbb/extractbb.man1.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/fontools/GPLv2.txt b/Master/texmf-dist/doc/support/fontools/LICENSE
index 1972a882127..1972a882127 100644
--- a/Master/texmf-dist/doc/support/fontools/GPLv2.txt
+++ b/Master/texmf-dist/doc/support/fontools/LICENSE
diff --git a/Master/texmf-dist/doc/support/fontools/README b/Master/texmf-dist/doc/support/fontools/README
deleted file mode 100644
index a7edc5d48e6..00000000000
--- a/Master/texmf-dist/doc/support/fontools/README
+++ /dev/null
@@ -1,84 +0,0 @@
-
- -=- FONTOOLS -=-
-
-
-This package provides tools to simplify using OpenType fonts with LaTeX.
-
-By far the most important program in this bundle is autoinst:
-
- AUTOINST - a wrapper script around Eddie Kohler's LCDF TypeTools.
- Autoinst aims to automate the installation of OpenType fonts in LaTeX
- by calling the LCDF TypeTools (with the correct options) for all fonts
- you wish to install, and generating the necessary .fd and .sty files.
-
-In addition, this bundle contains a few other, less important utilities:
-
- AFM2AFM - re-encode .afm files
-
- OT2KPX - extract kerning pairs from OpenType fonts
-
- SPLITTTC - split an OpenType Collection file (ttc or otc) into
- individual fonts
-
-
-
-PREREQUISITES
-=============
-
-Perl
-
- The Fontools are written in Perl; any remotely recent version should work.
- Perl is usually installed on Linux and Unix systems;
- for Windows, try ActivePerl (http://www.activestate.com)
- or Strawberry Perl (http://strawberryperl.com).
-
-LCDF TypeTools and T1Utils
- Of course, Autoinst needs the LCDF TypeTools and T1Utils
- (available from www.lcdf.org/type, and also on CTAN and in TeXLive);
- these should be installed in a directory on your PATH.
-
-Kpathsea
- Automatically installing the fonts into a suitable TEXMF tree
- (as Autoinst does by default) requires a TeX-installation that uses
- the kpathsea library; with TeX distributions that implement their
- own directory searching (such as MiKTeX), Autoinst will complain that
- it cannot find the kpsewhich program and install all generated files
- into subdirectories of the current directory.
-
- If you use such a TeX distribution, either move these files to their
- destinations by hand, or use the -target command line option
- (please see the manual for more information).
-
-
-Installation
-------------
-When installing manually, the encoding files in the "share/" directory
-should be moved to a "standard" location where otftotfm can find them.
-What this location is depends on your TeX installation;
-in TeXLive, it should be $TEXMFLOCAL/fonts/enc/dvips/fontools/ or,
-if you don't have write permissions in $TEXMFLOCAL,
-$TEXMFHOME/fonts/enc/dvips/fontools/.
-
-The scripts in the "bin/" directory should be placed in a directory
-on your PATH (or else you have to call them with their full path name).
-
-Of course, when using a package manager (such as tlmgr) to do
-the installation, all files will automatically be put in the right
-location.
-
-
-DISCLAIMER
-==========
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-See the GNU General Public License for more details.
-
-
-LICENSE & COPYRIGHT
-===================
-
-This software is copyright (C) 2005-2023 Marc Penninga.
-It is released under the terms of the GNU General Public Licence;
-see the file GPLv2.txt for the license conditions.
diff --git a/Master/texmf-dist/doc/support/fontools/README.md b/Master/texmf-dist/doc/support/fontools/README.md
new file mode 100644
index 00000000000..2595a14d191
--- /dev/null
+++ b/Master/texmf-dist/doc/support/fontools/README.md
@@ -0,0 +1,93 @@
+FONTOOLS
+========
+
+This package provides tools to simplify the use of OpenType fonts with pdftex.
+
+By far the most important program in this bundle is autoinst:
+
+ * **autoinst**
+
+ a wrapper script around Eddie Kohler's LCDF TypeTools.
+ Autoinst aims to automate the installation of OpenType fonts in LaTeX
+ by calling the LCDF TypeTools (with the correct options) for all fonts
+ you wish to install, and generating the necessary .fd and .sty files.
+
+In addition, this bundle contains a few other, less important utilities:
+
+* **afm2afm**
+
+ re-encode .afm files
+
+* **ot2kpx**
+
+ extract kerning pairs from OpenType fonts
+
+* **splitttc**
+
+ split an OpenType Collection file (ttc or otc) into individual fonts
+
+
+Prerequisites
+-------------
+
+### Perl
+
+The Fontools are written in Perl; any remotely recent version should work.
+Perl is usually installed on Linux and Unix systems;
+for Windows, try [ActivePerl](http://www.activestate.com)
+or [Strawberry Perl](http://strawberryperl.com).
+
+### LCDF TypeTools and T1Utils
+
+Of course, Autoinst needs the LCDF TypeTools and T1Utils
+(available from <www.lcdf.org/type>, and also on [CTAN](https://ctan.org/pkg/lcdf-typetools)
+and as part of TeXLive);
+these should be installed in a directory on your PATH.
+
+### Kpathsea
+
+Automatically installing the fonts into a suitable TEXMF tree
+(as Autoinst does by default) requires a TeX-installation that uses
+the kpathsea library; with TeX distributions that implement their
+own directory searching (such as MiKTeX), Autoinst will complain that
+it cannot find the kpsewhich program and install all generated files
+into subdirectories of the current directory.
+
+If you use such a TeX distribution, either move these files to their
+destinations by hand, or use the -target command line option
+(please see the manual for more information).
+
+
+Installation
+------------
+
+When installing manually, the encoding files in the `share` directory
+should be moved to a "standard" location where otftotfm can find them.
+What this location is depends on your TeX installation;
+in TeXLive, it should be `$TEXMFLOCAL/fonts/enc/dvips/fontools` or,
+if you don't have write permissions in `$TEXMFLOCAL`,
+`$TEXMFHOME/fonts/enc/dvips/fontools`.
+
+The scripts in the `bin` directory should be placed in a directory
+on your PATH (or else you have to call them with their full path name).
+
+Of course, when using a package manager (such as tlmgr) to do
+the installation, all files will automatically be put in the right
+location.
+
+
+LICENSE & COPYRIGHT
+-------------------
+
+This software is copyright (C) 2005-2025 Marc Penninga.
+It is released under the terms of the GNU General Public Licence;
+see the file LICENSE for the license conditions.
+
+
+DISCLAIMER
+----------
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
diff --git a/Master/texmf-dist/doc/support/fontools/splitttc b/Master/texmf-dist/doc/support/fontools/splitttc
index 8ea34fe468c..417a1a4cb3c 100755
--- a/Master/texmf-dist/doc/support/fontools/splitttc
+++ b/Master/texmf-dist/doc/support/fontools/splitttc
@@ -4,7 +4,7 @@
----------------------------------------------------------------------------
- Copyright (C) 2023 Marc Penninga.
+ Copyright (C) 2025 Marc Penninga.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
@@ -38,7 +38,7 @@ use File::Basename;
use Getopt::Long;
use Pod::Usage;
-my $VERSION = "20231230";
+my $VERSION = "20250107";
parse_commandline();
@@ -280,7 +280,7 @@ Marc Penninga <marcpenninga@gmail.com>
=head1 COPYRIGHT
-Copyright (C) 2019-2023 Marc Penninga.
+Copyright (C) 2019-2025 Marc Penninga.
=head1 LICENSE
@@ -303,7 +303,7 @@ See the GNU General Public License for more details.
=head1 VERSION
-This document describes B<splitttc> version 20231230.
+This document describes B<splitttc> version 20250107.
=head1 RECENT CHANGES
diff --git a/Master/texmf-dist/doc/support/latexdiff/README b/Master/texmf-dist/doc/support/latexdiff/README
index 6f4d1a280a8..f0310ce32db 100644
--- a/Master/texmf-dist/doc/support/latexdiff/README
+++ b/Master/texmf-dist/doc/support/latexdiff/README
@@ -1,4 +1,13 @@
+latexdiff
+=========
+
+Compares two latex files and marks up significant differences between them. Releases on https://ctan.org/pkg/latexdiff and mirrors.
+
+Link to full manual: http://mirrors.ctan.org/support/latexdiff/doc/latexdiff-man.pdf
+
+
INTRODUCTION
+------------
latexdiff is a Perl script, which compares two latex files and marks
up significant differences between them (i.e. a diff for latex files).
@@ -16,11 +25,9 @@ behaviour and accept or reject selected changes only.
The author is F Tilmann.
-Project webpage: https://github.com/ftilmann/latexdiff/
-CTAN page: http://www.ctan.org/pkg/latexdiff
-
REQUIREMENTS
+------------
Perl 5.8 or higher must be installed.
The latexdiff script makes use of the Perl package Algorithm::Diff (available
@@ -38,6 +45,7 @@ UNIX-diff mean that the resulting set of differences will generally not be the s
for the standard latexdiff. In most practical cases, these differences are minor, though.
INSTALLATION UNIX/LINUX
+-----------------------
The basic installation procedure is almost trivial:
@@ -53,34 +61,40 @@ The basic installation procedure is almost trivial:
The attached trivial Makefile contains example commands to carry out above
steps as root for a typical UNIX installation. Type
- make install (for the stand alone version)
+ `make install` (for the stand alone version)
+
or
- make install-ext (for the version using the external Algorithm::Diff)
+
+ `make install-ext` (for the version using the external Algorithm::Diff)
+
or
- make install-fast (for the version using the UNIX 'diff' function for fast differencing)
+
+ `make install-fast` (for the version using the UNIX 'diff' function for fast differencing)
to get it rolling. You can type
- make test
-or
- make test-ext
-or
- make test-fast
+ `make test` or
+
+ `make test-ext` or
+
+ `make test-fast`
to test the respective versions on a brief example before installation. It will often be
as easy to carry out these steps manually instead of using the Makefile.
-DOCUMENTATION:
+DOCUMENTATION
+-------------
Usage instructions are in the manual latexdiff-man.pdf as well as the
man pages.
-CHANGELOGS:
-
+CHANGELOGS
+----------
Check out the comment lines at the beginning of the perl scripts (latexdiff, latexdiff-vc, latexrevise)
CONTRIBUTIONS
+-------------
The directory contrib contains code written by others relating to latexdiff.
Currently this directory contains:
@@ -97,15 +111,19 @@ Contributions by the following authors were incorporated into the latexdiff code
extend latexdiff in a similar way: J. Paisley, N. Becker, K. Huebner
EXTERNAL LATEXDIFF SUPPORT PROGRAMS
+-----------------------------------
+
+LATEXDIDFFR (Author: David Hugh-Jones) is a small library that uses the latexdiff command to create a diff of two Rmarkdown, .Rnw or TeX files.
+https://github.com/hughjonesd/latexdiffr
LATEXDIFFCITE (Author: Christer van der Meeren) is a wrapper around latexdiff to make citations diff properly. It works by expanding \cite type commands using the bbl or bib file, such that citations are treated just like normal text rather than as atomic in the plain latexdiff.
-https://latexdiffcite.readthedocs.org
+https://github.com/twilsonco/latexdiffcite
GIT-LATEXDIFF (lead author: Matthieu Moy) is a wrapper (bash script) around latexdiff that allows using it to diff two revisions of a LaTeX file under git revision control (similar functionality is provided by latexdiff-vc --git with --flatten option included with this distribution but git-latexdiff allows more fine-grained control on (not to be confused with latexdiff-git, which is normally installed as a soft link to latexdiff-vc)
https://gitorious.org/git-latexdiff/
-LICENSE (also see file COPYING)
-
+LICENSE
+-------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License Version 3 as published by
the Free Software Foundation.
@@ -116,3 +134,6 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details (file LICENSE in the
distribution).
+
+
+
diff --git a/Master/texmf-dist/doc/support/latexdiff/doc/example-diff.tex b/Master/texmf-dist/doc/support/latexdiff/doc/example-diff.tex
index 8eda2a43aa8..b68c11aff9f 100644
--- a/Master/texmf-dist/doc/support/latexdiff/doc/example-diff.tex
+++ b/Master/texmf-dist/doc/support/latexdiff/doc/example-diff.tex
@@ -22,7 +22,7 @@
\RequirePackage[normalem]{ulem} %DIF PREAMBLE
\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1} %DIF PREAMBLE
\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}} %DIF PREAMBLE
-\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}} %DIF PREAMBLE
+\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}} %DIF PREAMBLE
%DIF SAFE PREAMBLE %DIF PREAMBLE
\providecommand{\DIFaddbegin}{} %DIF PREAMBLE
\providecommand{\DIFaddend}{} %DIF PREAMBLE
@@ -53,6 +53,8 @@
} %DIF PREAMBLE
\lstnewenvironment{DIFverbatim}{\lstset{style=DIFverbatimstyle}}{} %DIF PREAMBLE
\lstnewenvironment{DIFverbatim*}{\lstset{style=DIFverbatimstyle,showspaces=true}}{} %DIF PREAMBLE
+\lstset{extendedchars=\true,inputencoding=utf8}
+
%DIF END PREAMBLE EXTENSION ADDED BY LATEXDIFF
\begin{document}
diff --git a/Master/texmf-dist/doc/support/latexdiff/doc/latexdiff-man.pdf b/Master/texmf-dist/doc/support/latexdiff/doc/latexdiff-man.pdf
index 2ea00571b30..d0e57ad5c96 100644
--- a/Master/texmf-dist/doc/support/latexdiff/doc/latexdiff-man.pdf
+++ b/Master/texmf-dist/doc/support/latexdiff/doc/latexdiff-man.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/latexdiff/latexdiff b/Master/texmf-dist/doc/support/latexdiff/latexdiff
index a032ae23b53..5df02b753f6 100755
--- a/Master/texmf-dist/doc/support/latexdiff/latexdiff
+++ b/Master/texmf-dist/doc/support/latexdiff/latexdiff
@@ -25,6 +25,21 @@
#
# Note references to issue numbers are for the github repository of latexdiff: https://github.com/ftilmann/latexdiff
#
+# Version 1.3.4:
+# New features:
+# - Option to use lua-ul instead of ulem (for use with LuaLaTeX) (fix #17, #60, #188, #255, #270)
+# Enhancement
+# - If amsmath is detected as one of the included (based on idea in PR #263 contributed by github user xlucn
+# Bug fix
+# - sometimes the introduction of aux commands to show deleted lists or descriptions leaves in place empty auxiliary
+# list environments, which would cause error messages (though skipping messages would result in a correct output pdf).
+# These are now removed.
+# - add more mboxsafecmd and safecmd commands for SIunitx to stay compatible with newer versionsof SIunitx (PR #283, fixing issue #282, contributed by github user joe6302413)
+# - File added via --preamble option is no longer assumed to be ASCII, but read either with encoding as defined by --encoding option or using the encoding of the LOCALE (fixes issue #285 )
+# - multicolumn argument is now treated as text
+# - when tikz-dependency package is used, \& is no longer a safe command as it has special meaning inside dependency environment. The fix is a little of a hack as really it should only be considered unsafe within dependency environment (fixes (mostly) issue #303 )
+# - listings package had trouble with non-ASCII chars. The encoding is now set (thanks to github user anka-213 for finding this). Fixes #304
+#
# Version 1.3.3:
# New features:
# - Option --no-del to remove all deleted text (merge contributed by github user tdegeus PR #252, fixing issue #66
@@ -33,22 +48,22 @@
# - Abbreviations involving punctuations within them. They need special treatment because otherwise in some
# circumstances the gnoring of white space differences in conjunction with merging according to MINWORDSBLOCK rule
# could turn 'i.e.' into 'i.\PAR e.' (see https://github.com/ftilmann/latexdiff/issues/269). A few abbreviations
-# are now hard-coded and treated as atomic:
+# are now hard-coded and treated as atomic:
# English: i.e., e.g. Deutsch: z.B.
# (fixes issue #269)
# - In WHOLE and COARSE math modes, now properly treat math environments with arguments such as \alignat. Fixes #251
-# - For FINE math mode, multiple improvments to the processing work flow yield more robust outcomes. In particular, changes
-# to the equation type, e.g. \begin{displaymath} -> \begin{equation} without modifications now usually no longer result
-# in errors. (Partially) fixes issues #235 and #244.
-# - When encountering deleted math array environments such as align or eqnarray, rather than replacing them with a
-# fixed replacement environment (e.g. align* or eqnarray*), an asterisk is now added to the original command, which
+# - For FINE math mode, multiple improvments to the processing work flow yield more robust outcomes. In particular, changes
+# to the equation type, e.g. \begin{displaymath} -> \begin{equation} without modifications now usually no longer result
+# in errors. (Partially) fixes issues #235 and #244.
+# - When encountering deleted math array environments such as align or eqnarray, rather than replacing them with a
+# fixed replacement environment (e.g. align* or eqnarray*), an asterisk is now added to the original command, which
# in amsmath (and with eqnarray) will result in the same environment but without line numbers. Config variable MATHARRREPL
# is therefore (nearly) redundant, and a depracation warning is given when it is set. Reference to MATHARRREPL are have
# been removed from the manual (there is one exception, when it's still being used: sometimes latexdiff can figure out
# that there is a deleted array environment, but does not know which one. In this case, MATHARRREPL is still being used
-# to encapsulate these parts of the source, and therefore it is still set internally. But this is a quite rare situation).
+# to encapsulate these parts of the source, and therefore it is still set internally. But this is a quite rare situation).
# Fixes issue #216
-# - Unlike 'array' environment, 'split' (amsmath) does not work in argument of \DIFadd or \DIFdl in UNDERLINE modes; therefore remove it from ARRENV configuration variable.
+# - Unlike 'array' environment, 'split' (amsmath) does not work in argument of \DIFadd or \DIFdl in UNDERLINE modes; therefore remove it from ARRENV configuration variable.
# Exclude \begin and \end in math environments in COARSE and WHOLE modes. Fixes #258. Fixes #109
# - --flatten now works for empty files. Fixes issue #242
# - improved processing of Chinese and Japanese texts in that splitting is done based on characters. Thanks to LuXu (Oliver Lew) in git for working this out. Fixes #229, fixes #145
@@ -65,7 +80,7 @@
# Bug fixes:
# - fix issue #206 affecting proper markup of text commands which are not also safe cmd's and have multiple arguments
# - fix issue #210 by adding \eqref (amsmath package) to the list of safe commands
-# - fix bug reported in issue #168 mangled verbatim line environment
+# - fix bug reported in issue #168 mangled verbatim line environment
# - fix bug reported in issue #218 by replacing \hspace{0pt} after \mbox{..} auxiliary commands with \hskip0pt.
# - more ways to process \frac correctly with atomic arguments (committed by julianuu PR #246
# - fix a bug in biblatex mode, which prevented proper processing of modified \textcite (see: https://tex.stackexchange.com/questions/555157/latexdiff-and-biblatex-citation-commands)
@@ -74,10 +89,10 @@
# Version 1.3.1.1
# - remove spurious \n to fix error: Unknown regexp modifier "/n" at .../latexdiff line 1974, near "=~ " (see github issue #201)
#
-# Version 1.3.1
+# Version 1.3.1
# Bug fixes:
# - remove some uninitialised variable $2 warnings in string substitution in flatten function in case included file is not found
-# - add minimal postprocessing to diff processing of preamble commands (replace \RIGHTBRACE by \} )
+# - add minimal postprocessing to diff processing of preamble commands (replace \RIGHTBRACE by \} )
# - pre-processing: replace (contributed) routine take_comments_and_enter_from_frac() with take_comments_and_newline_from_frac(), which does the same thing
# (remove whitespace characters and comments between the argument of \frac commands) in an easier and more robust way. In addition, it
# will replace commands like \frac12 with \frac{1}{2} as pre-processing step. Fixes issue #184
@@ -95,15 +110,15 @@
# Version 1.3.0 (7 October 2018):
# - treat options to \documentclass as potential package names (some packages allow implicit loading of or imply selected packages
# - improved pattern matching: now allows nested angular brackets, and is no longer confused by escaped curly braces
-# - improved pattern matching in COARSE mode: occasionally, the closing bracket or some other elements would be matched in an 'unnatural' way due to another sequence being more minimal in the computational sense, sometimes even causing errors due to tokens moving in or out of the scope of math environments. This is now discouraged by adding internal \DIFANCHOR commands (which are removed again in post-processing) (fixes issues reported via email by li_ruomeng .
+# - improved pattern matching in COARSE mode: occasionally, the closing bracket or some other elements would be matched in an 'unnatural' way due to another sequence being more minimal in the computational sense, sometimes even causing errors due to tokens moving in or out of the scope of math environments. This is now discouraged by adding internal \DIFANCHOR commands (which are removed again in post-processing) (fixes issues reported via email by li_ruomeng .
# - verbatim and lstlisting environments are marked-up with line-by-line in a similar style to non-verbatim text (requires the listing package to be installed)
# (see new configuration variable VERBATIMLINEENV) (several issues and pull requests by jprotze)
-# - --flatten: now supports \verbatiminput and \lstlistinput
+# - --flatten: now supports \verbatiminput and \lstlistinput
# - --flatten: if file is not found, do not fail, simply warn and leave command unexpanded (inspired by issue #112). Don't warn if file name contains #[0-9] as it is then most likely an argument within a command definition rather than an actual file (applies to \input, \subfile, \include commands)
# - added to textcmds: \intertext
# - new config variable CUSTOMDIFCMD to allow defining special versions of commands in added or deleted blocks (Pull request by github user jprotze)
# - added option -no-links (mostly for use by latexdiff-vc in only-changes modes) (Pull request by github user jprotze)
-# - new option --filter-script to run both input through a pre-processing script (PR jasonmccsmith #167)
+# - new option --filter-script to run both input through a pre-processing script (PR jasonmccsmith #167)
# new option --no-filter-stderr to hide stderr output from filter-script (potentially dangerous, as this might hide malfunctioning of filter scripts)
# - --flatten now can deal with imports made using the import package {PR jasonmccsmith #173)
# Bug fixes:
@@ -122,12 +137,12 @@
# make environments that are treated like verbatim environments configurable (config variable VERBATIMENV)
# treat lstinlne as equivalent to verb command
# partially addresses issue #38
-# - refactoring: set default configuration variables in a hash, and those that correspond to lists
+# - refactoring: set default configuration variables in a hash, and those that correspond to lists
# - feature: option --add-to-config used to amend configuration variables, which are regex pattern lists
# - bug fix: deleted figures when endfloat package is activated
# - bug fix: alignat environment now always processed correctly (fix issues #65)
# - bug fix: avoid processing of commands as potential files in routine init_regex_arr (fix issue #70 )
-# - minimal feature enhancement: treat '@' as allowed character in commands (strictly speaking requires prior \makeatletter statement, but always assuming it to be
+# - minimal feature enhancement: treat '@' as allowed character in commands (strictly speaking requires prior \makeatletter statement, but always assuming it to be
# @ a letter if it is part of a command name will usually lead to the correct behaviour (see http://tex.stackexchange.com/questions/346651/latexdiff-and-let)
# - new feature/bug fix: --flatten option \endinput in included files now respected but only if \endinput stands right at the beginning of the line (issue #77)
# - bug fix: flatten would incorrectly attempt to process commented out \include commands (from discussion in issue #77 )
@@ -165,7 +180,7 @@
# - introduce list UNSAFEMATHCMD, which holds list of commands which cannot be marked up with \DIFadd or \DIFdel commands (only relevant for WHOLE and COARSE math markup modes)
# - new subtype LABEL which gives each change a label. This can later be used to only display pages where changes
# have been made (instructions for that are put as comments into the diff'ed file) inspired by answer on http://tex.stackexchange.com/questions/166049/invisible-markers-in-pdfs-using-pdflatex
-# - Configuration variables take into accout some commands from additional packages:
+# - Configuration variables take into accout some commands from additional packages:
# tikzpicture environment now treated as PICTUREENV, and \smallmatrix in ARRENV (amsmath)
# - --flatten: support for \subfile command (subfiles package) (in response to http://tex.stackexchange.com/questions/167620/latexdiff-with-subfiles )
# - --flatten: \bibliography commands expand if corresponding bbl file present
@@ -179,11 +194,11 @@
# - \% in one-letter sub/Superscripts was not converted correctly
#
# Version 1.0.3
-# - fix bug in add_safe_commands that made latexdiff hang on DeclareMathOperator
+# - fix bug in add_safe_commands that made latexdiff hang on DeclareMathOperator
# command in preamble
# - \(..\) inline math expressions were not parsed correctly, if they contained a linebreak
# - applied patch contributed by tomflannaghan via Berlios: [ Patch #3431 ] Adds correct handling of \left< and \right>
-# - \$ is treated correctly as a literal dollar sign (thanks to Reed Cartwright and Joshua Miller for reporting this bug
+# - \$ is treated correctly as a literal dollar sign (thanks to Reed Cartwright and Joshua Miller for reporting this bug
# and sketching out the solution)
# - \^ and \_ are correctly interpreted as accent and underlined space, respectively, not as superscript of subscript
# (thanks to Wail Yahyaoui for pointing out this bug)
@@ -191,19 +206,19 @@
# Version 1.0.1 - treat \big,\bigg etc. equivalently to \left and
# \right - include starred version in MATHENV - apply
# - flatten recursively and --flatten expansion is now
-# aware of comments (thanks to Tim Connors for patch)
+# aware of comments (thanks to Tim Connors for patch)
# - Change to post-processing for more reliability for
# deleted math environments
-# - On linux systems, recognise and remove DOS style newlines
+# - On linux systems, recognise and remove DOS style newlines
# - Provide markup for some special preamble commands (\title,
-# \author,\date,
-# - configurable by setting context2cmd
+# \author,\date,
+# - configurable by setting context2cmd
# - for styles using ulem package, remove \emph and \text.. from list of
# safe commands in order to allow linebreaks within the
-# highlighted sections.
-# - for ulem style, now show citations by enclosing them in \mbox commands.
-# This unfortunately implies linebreaks within citations no longer function,
-# so this functionality can be turned off (Option --disable-citation-markup).
+# highlighted sections.
+# - for ulem style, now show citations by enclosing them in \mbox commands.
+# This unfortunately implies linebreaks within citations no longer function,
+# so this functionality can be turned off (Option --disable-citation-markup).
# With --enable-citation-markup, the mbox markup is forced for other styles)
# - new substyle COLOR. This is particularly useful for marking up citations
# and some special post-processing is implemented to retain cite
@@ -211,11 +226,11 @@
# - four different levels of math-markup
# - Option --driver for choosing driver for modes employing changebar package
# - accept \\* as valid command (and other commands of form \.*). Also accept
-# \<nl> (backslashed newline)
+# \<nl> (backslashed newline)
# - some typo fixes, include commands defined in preamble as safe commands
-# (Sebastian Gouezel)
+# (Sebastian Gouezel)
# - include compared filenames as comments as line 2 and 3 of
-# the preamble (can be modified with option --label, and suppressed with
+# the preamble (can be modified with option --label, and suppressed with
# --no-label), option --visible-label to show files in generated pdf or dvi
# at the beginning of main document
#
@@ -231,7 +246,7 @@
#
# Version 0.4 March 06 option for fast differencing using UNIX diff command, several minor bug fixes (\par bug, improved highlighting of textcmds)
#
-# Version 0.3 August 05 improved parsing of displayed math, --allow-spaces
+# Version 0.3 August 05 improved parsing of displayed math, --allow-spaces
# option, several minor bug fixes
#
# Version 0.25 October 04 Fix bug with deleted equations, add math mode commands to safecmd, add | to allowed interpunctuation signs
@@ -247,12 +262,13 @@ use utf8 ;
use File::Spec ;
+
my ($algodiffversion)=split(/ /,$Algorithm::Diff::VERSION);
my ($versionstring)=<<EOF ;
-This is LATEXDIFF 1.3.3 (Algorithm::Diff $Algorithm::Diff::VERSION, Perl $^V)
- (c) 2004-2022 F J Tilmann
+This is LATEXDIFF 1.3.4 (Algorithm::Diff $Algorithm::Diff::VERSION, Perl $^V)
+ (c) 2004-2024 F J Tilmann
EOF
# Hash with defaults for configuration variables. These marked undef have default values constructed from list defined in the DATA block
@@ -343,9 +359,9 @@ my $DELCMDOPEN='%DIFDELCMD < '; # To mark begin of deleted commands (must begin
my $DELCMDCLOSE="%%%\n"; # To mark end of deleted commands (must end with a new line)
my $AUXCMD='%DIFAUXCMD' ; # follows auxiliary commands put in by latexdiff to make difference file legal
# auxiliary commands must be on a line of their own
- # Note that for verbatim environment openings the %DIFAUXCMD cannot be placed in
+ # Note that for verbatim environment openings the %DIFAUXCMD cannot be placed in
# the same line as this would mean they are shown
- # so the special form "%DIFAUXCMD NEXT" is used to indicate that the next line
+ # so the special form "%DIFAUXCMD NEXT" is used to indicate that the next line
# is an auxiliary command
# Similarly "%DIFAUXCMD LAST" would indicate the auxiliary command is in previous line (not currently used)
my $DELCOMMENT='DIF < '; # To mark deleted comment line
@@ -356,21 +372,21 @@ my @TEXTCMDLIST=(); # array containing patterns of commands with text arguments
my @TEXTCMDEXCL=(); # array containing patterns of commands without text arguments (if a pattern
# matches both TEXTCMDLIST and TEXTCMDEXCL it is excluded)
my @CONTEXT1CMDLIST=(); # array containing patterns of commands with text arguments (subset of text commands),
- # but which cause confusion if used out of context (e.g. \caption).
+ # but which cause confusion if used out of context (e.g. \caption).
# In deleted passages, the command will be disabled but its argument is marked up
- # Otherwise they behave exactly like TEXTCMD's
+ # Otherwise they behave exactly like TEXTCMD's
my @CONTEXT1CMDEXCL=(); # exclude list for above, but always empty
my @CONTEXT2CMDLIST=(); # array containing patterns of commands with text arguments, but which fail or cause confusion
# if used out of context (e.g. \title). They and their arguments will be disabled in deleted
# passages
my @CONTEXT2CMDEXCL=(); # exclude list for above, but always empty
my @MATHTEXTCMDLIST=(); # treat like textcmd. If a textcmd is in deleted or added block, just wrap the
- # whole content with \DIFadd or \DIFdel irrespective of content. This functionality
+ # whole content with \DIFadd or \DIFdel irrespective of content. This functionality
# is useful for pseudo commands \MATHBLOCK.. into which math environments are being
- # transformed
-my @MATHTEXTCMDEXCL=(); #
+ # transformed
+my @MATHTEXTCMDEXCL=(); #
-# Note I need to declare this with "our" instead of "my" because later in the code I have to "local"ise these
+# Note I need to declare this with "our" instead of "my" because later in the code I have to "local"ise these
our @SAFECMDLIST=(); # array containing patterns of safe commands (which do not break when in the argument of DIFadd or DIFDEL)
our @SAFECMDEXCL=();
my @MBOXCMDLIST=(); # patterns for commands which are in principle safe but which need to be surrounded by an \mbox
@@ -435,7 +451,7 @@ $mathmarkup=COARSE;
$verbose=0;
$onlyadditions=0;
# output debug and intermediate files, set to 0 in final distribution
-$debug=0;
+$debug=0;
# insert preamble directly after documentclass - experimental feature, set to 0 in final distribution
# Note that this failed with mini example (or other files, where packages used in latexdiff preamble
# are called again with incompatible options in preamble of resulting file)
@@ -458,9 +474,9 @@ END
my %verbhash;
Getopt::Long::Configure('bundling');
-GetOptions('type|t=s' => \$type,
- 'subtype|s=s' => \$subtype,
- 'floattype|f=s' => \$floattype,
+GetOptions('type|t=s' => \$type,
+ 'subtype|s=s' => \$subtype,
+ 'floattype|f=s' => \$floattype,
'config|c=s' => \@configlist,
'add-to-config=s' => \@addtoconfiglist,
'preamble|p=s' => \$preamblefile,
@@ -509,11 +525,11 @@ if ( $help ) {
if ( $version ) {
- print STDERR $versionstring ;
+ print STDERR $versionstring ;
exit 0;
}
-print STDERR $versionstring if $verbose;
+print STDERR $versionstring if $verbose;
if (defined($showall)){
$showpreamble=$showsafe=$showtext=$showconfig=1;
@@ -531,7 +547,7 @@ if (defined($mathmarkup)) {
$mathmarkup=~tr/a-z/A-Z/;
if ( $mathmarkup eq 'OFF' ){
$mathmarkup=OFF;
- } elsif ( $mathmarkup eq 'WHOLE' ){
+ } elsif ( $mathmarkup eq 'WHOLE' ){
$mathmarkup=WHOLE;
} elsif ( $mathmarkup eq 'COARSE' ){
$mathmarkup=COARSE;
@@ -634,7 +650,7 @@ foreach $config ( @configlist ) {
}
}
foreach $assign ( @config ) {
- $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
+ $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
exists $CONFIG{$1} or die "Unknown configuration variable $1.";
$CONFIG{$1}=$2;
}
@@ -671,7 +687,7 @@ foreach $key ( keys(%CONFIG) ) {
foreach $assign ( @addtoconfig ) {
###print STDERR "assign:|$assign|\n";
- $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
+ $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
exists $CONFIG{$1} or die "Unknown configuration variable $1.";
$CONFIG{$1}.=";$2";
}
@@ -686,8 +702,8 @@ foreach ( keys(%CONFIG) ) {
elsif ( $_ eq "MATHENV" ) { $MATHENV = liststringtoregex($CONFIG{$_}) ; }
elsif ( $_ eq "MATHREPL" ) { $MATHREPL = $CONFIG{$_} ; }
elsif ( $_ eq "MATHARRENV" ) { $MATHARRENV = liststringtoregex($CONFIG{$_}) ; }
- elsif ( $_ eq "MATHARRREPL" ) { $MATHARRREPL = $CONFIG{$_} ;
- print STDERR "WARNING: Setting MATHARRREPL is depracated. Generally deleted math array environments will be set to their starred varieties and the setting of MATHARREPL is ignored.\n\n" unless $MATHARRREPL =~ /eqnarray\*/ ;
+ elsif ( $_ eq "MATHARRREPL" ) { $MATHARRREPL = $CONFIG{$_} ;
+ print STDERR "WARNING: Setting MATHARRREPL is depracated. Generally deleted math array environments will be set to their starred varieties and the setting of MATHARREPL is ignored.\n\n" unless $MATHARRREPL =~ /eqnarray\*/ ;
}
elsif ( $_ eq "ARRENV" ) { $ARRENV = liststringtoregex($CONFIG{$_}) ; }
elsif ( $_ eq "VERBATIMENV" ) { $VERBATIMENV = liststringtoregex($CONFIG{$_}) ; }
@@ -714,11 +730,11 @@ foreach $pkg ( @packagelist ) {
if ($showconfig || $showtext || $showsafe || $showpreamble) {
show_configuration();
- exit 0;
+ exit 0;
}
-if ( @ARGV != 2 ) {
+if ( @ARGV != 2 ) {
print STDERR "2 and only 2 non-option arguments required. Write latexdiff -h to get help\n";
exit(2);
}
@@ -726,7 +742,7 @@ if ( @ARGV != 2 ) {
# Are extra spaces between command arguments permissible?
my $extraspace;
if ($allowspaces) {
- $extraspace='\s*';
+ $extraspace='\s*';
} else {
$extraspace='';
}
@@ -749,14 +765,14 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
# if you get "undefined control sequence MATHBLOCKmath" error, increase the maximum value in this loop
for (my $i_pat = 0; $i_pat < 20; ++$i_pat){
$pat_n = '(?:[^{}]|\{'.$pat_n.'\}|\\\\\{|\\\\\})*';
- # Actually within the text body, quoted braces are replaced in pre-processing. The only place where
+ # Actually within the text body, quoted braces are replaced in pre-processing. The only place where
# the last part of the pattern matters is when processing the arguments of context2cmds in the preamble
# and these contain a \{ or \} combination, probably rare.
# It should thus be fine to use the simpler version below.
### $pat_n = '(?:[^{}]|\{'.$pat_n.'\})*';
}
- my $brat0 = '(?:[^\[\]]|\\\[|\\\])*';
+ my $brat0 = '(?:[^\[\]]|\\\[|\\\])*';
my $brat_n = $brat0;
for (my $i_pat = 0; $i_pat < 4; ++$i_pat){
$brat_n = '(?:[^\[\]]|\['.$brat_n.'\]|\\\[|\\\])*';
@@ -773,7 +789,7 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
# could turn 'i.e.' into 'i.\PAR e.' (see https://github.com/ftilmann/latexdiff/issues/269)
# English: i.e., e.g. Deutsch: z.B.
my $abbreviation='(?:i\. ?e\.|e\. ?g\.|z\. ?B\.)' ;
- my $number='-?\d*\.\d*';
+ my $number='-?\d*\.\d*';
# word: sequence of letters or accents followed by letter
my $word_cj='\p{Han}|\p{InHiragana}|\p{InKatakana}';
@@ -801,7 +817,7 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
# inline math $....$ or \(..\)
### the commented out version is simpler but for some reason cannot cope with newline (in spite of s option) - need to include \newline explicitly
### my $math='\$(?:[^$]|\\\$)*?\$|\\\\[(].*?\\\\[)]';
- my $math='\$(?:[^$]|\\\$)*?\$|\\\\[(](?:.|\n)*?\\\\[)]';
+ my $math='\$(?:[^$]|\\\$)*?\$|\\\\[(](?:.|\n)*?\\\\[)]';
### test version (this seems to give the same results as version above)
## the current maths command cannot cope with newline within the math expression
### my $math='\$(?:[^$]|\\\$)*?\$|\\[(].*?\\[)]';
@@ -819,7 +835,7 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
-# now we are done setting up and can start working
+# now we are done setting up and can start working
my ($oldfile, $newfile) = @ARGV;
# check for existence of input files
if ( ! -e $oldfile ) {
@@ -847,7 +863,7 @@ my ($oldtime,$newtime,$oldlabel,$newlabel);
if (defined($labels[0])) {
$oldlabel=$labels[0] ;
} else {
- $oldtime=localtime((stat($oldfile))[9]);
+ $oldtime=localtime((stat($oldfile))[9]);
$oldlabel="$oldfile " . " "x($oldlabel_n_spaces) . $oldtime;
}
if (defined($labels[1])) {
@@ -860,6 +876,7 @@ if (defined($labels[1])) {
$encoding=guess_encoding($newfile) unless defined($encoding);
$encoding = "utf8" if $encoding =~ m/^utf8/i ;
+print STDERR "Encoding $encoding\n" if $verbose;
if (lc($encoding) eq "utf8" ) {
binmode(STDOUT, ":utf8");
binmode(STDERR, ":utf8");
@@ -943,7 +960,7 @@ my @auxlines;
my ($ulem)=0;
if ( length $oldpreamble && length $newpreamble ) {
- # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
+ # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
# and marking up content with latexdiff markup
@auxlines=preprocess_preamble($oldpreamble,$newpreamble);
@@ -975,7 +992,7 @@ if (defined($graphicsmarkup)) {
} else {
# Default: no explicit setting in menu
if ( defined $packages{"graphicx"} or defined $packages{"graphics"} ) {
- $graphicsmarkup=NEWONLY;
+ $graphicsmarkup=NEWONLY;
} else {
$graphicsmarkup=NONE;
}
@@ -1008,7 +1025,7 @@ if ($graphicsmarkup != NONE ) {
@matches=( $latexdiffpreamble =~ m/command\{\\DIFaddbeginFL}\{($pat_n)}/sg ) ;
# we look at the last one of the list to take into account possible redefinition but almost always matches should have exactly one element
if ( $matches[$#matches] =~ m/\\DIFaddbegin/ ) {
- die "Cannot combine graphics markup with float styles defining \\DIFaddbeginFL in terms of \\DIFaddbegin. Use --graphics-markup=none option or choose a different float style.";
+ die "Cannot combine graphics markup with float styles defining \\DIFaddbeginFL in terms of \\DIFaddbegin. Use --graphics-markup=none option or choose a different float style.";
exit 10;
}
###}
@@ -1022,6 +1039,11 @@ if ($graphicsmarkup != NONE ) {
$ulem = ($latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{ulem\}/ || defined $packages{"ulem"});
+# If amsmath is defined and $ulem is used for markup, redefine the \sout command to also work (mostly) in math mode
+# See stack exchange https://tex.stackexchange.com/questions/20609/strikeout-in-math-mode/308647#308647 based on comment by Taylor Raine
+if ( defined($packages{'amsmath'}) and $ulem ) {
+ $latexdiffpreamble .= join "\n",(extrapream('AMSMATHULEM'),"");
+}
# If listings is being used or can be found in the latexdiff search path, add to the preamble auxiliary code to enable line-by-line markup
if ( defined($packages{"listings"}) or `kpsewhich listings.sty` ne "" ) {
@@ -1031,7 +1053,7 @@ if ( defined($packages{"listings"}) or `kpsewhich listings.sty` ne "" ) {
}
my @listingDIFcode=();
my $replaced;
- # note that in case user supplies preamblefile the type might not reflect well the
+ # note that in case user supplies preamblefile the type might not reflect well the actual markup style
@listingDIFcode=extrapream("-nofail","DIFCODE_" . $type) unless defined($preamblefile);
if (!(@listingDIFcode)) {
# if listingDIFcode is empty try to guess a suitable one from the preamble
@@ -1045,13 +1067,17 @@ if ( defined($packages{"listings"}) or `kpsewhich listings.sty` ne "" ) {
@listingDIFcode=extrapream("DIFCODE_BOLD");
}
}
- # now splice it in
+ # add configuration so that listings work with utf-8
+ push @listingpreamble, '\lstset{extendedchars=\true,inputencoding='.$encoding."}\n";
+
+
+ # now splice it in
$replaced=0;
###print STDERR "DEBUG: listingDIFcode: ",join("\n",@listingDIFcode),"|||\n" if $debug;
- @listingpreamble=grep {
+ @listingpreamble=grep {
# only replace if this has not been done already (use short-circuit property of and)
- if (!$replaced and $_ =~ s/^.*%DIFCODE TEMPLATE.*$/join("\n",@listingDIFcode)/e ) {
+ if (!$replaced and $_ =~ s/^.*%DIFCODE TEMPLATE.*$/join("\n",@listingDIFcode)/e ) {
###print STDERR "DEBUG: Replaced text $_\n" if $debug;
$replaced=1;
1;
@@ -1081,7 +1107,7 @@ if ( length $oldpreamble && length $newpreamble ) {
unshift @oldpreamble,'';
@diffpreamble = linediff(\@oldpreamble, \@newpreamble);
# remove dummy line again
- shift @diffpreamble;
+ shift @diffpreamble;
# add filenames, modification time and latexdiff mark
defined($nolabel) or splice @diffpreamble,1,0,
"%DIF LATEXDIFF DIFFERENCE FILE",
@@ -1130,8 +1156,8 @@ if (defined $packages{"siunitx"} ) {
# protect SI command by surrounding them with an \mbox
# this is done to get around an incompatibility between the ulem and siunitx package
print STDERR "siunitx package detected.\n" if $verbose ;
- my $mboxcmds='SI,ang,numlist,numrange,SIlist,SIrange';
- init_regex_arr_list(\@SAFECMDLIST,'num,si');
+ my $mboxcmds='SI,ang,numlist,numrange,SIlist,SIrange,qty,qtylist,qtyproduct,qtyrange,complexqty';
+ init_regex_arr_list(\@SAFECMDLIST,'num,si,numproduct,unit,complexnum');
if ( $enablecitmark || ( $ulem && ! $disablecitmark )) {
init_regex_arr_list(\@MBOXCMDLIST,$mboxcmds);
} else {
@@ -1153,7 +1179,7 @@ if (defined $packages{"cleveref"} ) {
if (defined $packages{"glossaries"} ) {
# protect selected command by surrounding them with an \mbox
- # this is done to get around an incompatibility between ulem and glossaries package
+ # this is done to get around an incompatibility between ulem and glossaries package
print STDERR "glossaries package detected.\n" if $verbose ;
my $mboxcmds='[gG][lL][sS](?:|pl|disp|link|first|firstplural|desc|user[iv][iv]?[iv]?),[aA][cC][rR](?:long|longpl|full|fullpl),[aA][cC][lfp]?[lfp]?';
init_regex_arr_list(\@SAFECMDLIST,'[gG][lL][sS](?:(?:entry)?(?:text|plural|name|symbol)|displaynumberlist|entryfirst|entryfirstplural|entrydesc|entrydescplural|entrysymbolplural|entryuser[iv][iv]?[iv]?|entrynumberlist|entrydisplaynumberlist|entrylong|entrylongpl|entryshort|entryshortpl|entryfull|entryfullpl),[gG]lossentry(?:name|desc|symbol),[aA][cC][rR](?:short|shortpl),[aA]csp?');
@@ -1182,6 +1208,10 @@ if (defined $packages{"mhchem"} ) {
# push(@MATHTEXTCMDLIST,'cee');
}
+if ( defined $packages{"tikz-dependency"} ) {
+ init_regex_arr_ext(\@SAFECMDEXCL, 'AMPERSAND');
+}
+
my ( $citpat);
@@ -1269,7 +1299,7 @@ print STDERR "(",exetime()," s)\n","Done.\n" if $verbose;
# liststringtoregex(liststring)
-# expands string with semi-colon separated list into a regular expression corresponding
+# expands string with semi-colon separated list into a regular expression corresponding
# matching any of the elements
sub liststringtoregex {
my ($liststring)=@_;
@@ -1282,7 +1312,7 @@ sub liststringtoregex {
}
# show_configuration
-# note that this is not encapsulated but uses variables from the main program
+# note that this is not encapsulated but uses variables from the main program
# It is provided for convenience because in the future it is planned to allow output
# to be modified based on what packages are read etc - this works only if the input files are actually read
# whether or not additional files are provided
@@ -1309,7 +1339,7 @@ sub show_configuration {
print "\nContext1 commands (last argument textual, command will be disabled in deleted passages, last argument will be shown as plain text):\n";
print_regex_arr(@CONTEXT1CMDLIST);
print "\nContext2 commands (last argument textual, command and its argument will be disabled in deleted passages):\n";
- print_regex_arr(@CONTEXT2CMDLIST);
+ print_regex_arr(@CONTEXT2CMDLIST);
print "\nExclude list of Commands with last argument not textual (overrides patterns above):\n";
print_regex_arr(@TEXTCMDEXCL);
}
@@ -1417,7 +1447,7 @@ sub list_packages {
my %packages=();
my $pkg;
- # remove comments
+ # remove comments
$preamble=~s/(?<!\\)%.*$//mg ;
while ( $preamble =~ m/\\(?:documentclass|usepackage|RequirePackage)(?:\[($brat_n)\])?\{(.*?)\}/gs ) {
@@ -1522,7 +1552,7 @@ sub flatten {
my ($includeonly,$dirname,$fname,$newpage,$fullfile,$filecontent,$replacement,$begline,$inputcmd,$bblfile,$subfile,$command,$verbenv,$verboptions,$ignore,$fileonly);
my ($subpreamble,$subbody,$subpost);
my ($subdir,$subdirfull,$importfilepath);
- require File::Basename ;
+ require File::Basename ;
### require File::Spec ; # now this is needed even if flatten option not given
$filename = File::Spec->rel2abs( $filename ) ;
($ignore, $dirname, $fileonly) = File::Spec->splitpath($filename) ;
@@ -1562,15 +1592,15 @@ sub flatten {
$subdirfull = (defined($3) ? File::Spec->catdir($dirname,$subdir) : $subdir);
$importfilepath = File::Spec->catfile($subdirfull, $fname);
-
+
print STDERR "importing importfilepath:", $importfilepath,"\n" if $verbose;
if ( -f $importfilepath ) {
# If file exists, replace input or include command with expanded input
#TODO: need remove_endinput & newpage similar to other replacements inside flatten
- $replacement=flatten(read_file_with_encoding($importfilepath, $encoding), $preamble,$importfilepath,$encoding);
+ $replacement=flatten(read_file_with_encoding($importfilepath, $encoding), $preamble,$importfilepath,$encoding);
} else {
# if file does not exist, do not expand include or input command (do not warn if fname contains #[0-9] as it is then likely part of a command definition
- # and is not meant to be expanded directly
+ # and is not meant to be expanded directly
print STDERR "WARNING: Could not find included file ",$importfilepath,". I will continue but not expand |$2|\n";
$replacement = $2;
$replacement .= "{$subdir}{$fname} % Processed";
@@ -1579,13 +1609,13 @@ sub flatten {
}/exgm;
# recursively replace \\input and \\include files
- $text =~ s/(^(?:[^%\n]|\\%)*)(\\input\{(.*?)\}|\\include\{(${includeonly}(?:\.tex)?)\})/{
+ $text =~ s/(^(?:[^%\n]|\\%)*)(\\input\{(.*?)\}|\\include\{(${includeonly}(?:\.tex)?)\})/{
$begline=(defined($1)? $1 : "") ;
$inputcmd=$2;
$fname = $3 if defined($3) ;
$fname = $4 if defined($4) ;
$newpage=(defined($4)? " \\newpage " : "") ;
- # # add tex extension unless there is a three or four letter extension already
+ # # add tex extension unless there is a three or four letter extension already
$fname .= ".tex" unless $fname =~ m|\.\w{3,4}$|;
$fullfile = File::Spec->catfile($dirname,$fname);
print STDERR "DEBUG Beg of line match |$1|\n" if defined($1) && $debug ;
@@ -1594,12 +1624,12 @@ sub flatten {
# content of file becomes replacement value (use recursion), add \newpage if the command was include
if ( -f $fullfile ) {
# If file exists, replace input or include command with expanded input
- $replacement=flatten(read_file_with_encoding($fullfile, $encoding), $preamble,$filename,$encoding);
- $replacement = remove_endinput($replacement);
+ $replacement=flatten(read_file_with_encoding($fullfile, $encoding), $preamble,$filename,$encoding);
+ $replacement = remove_endinput($replacement);
# \include always starts a new page; use explicit \newpage command to simulate this
} else {
# if file does not exist, do not expand include or input command (do not warn if fname contains #[0-9] as it is then likely part of a command definition
- # and is not meant to be expanded directly
+ # and is not meant to be expanded directly
print STDERR "WARNING: Could not find included file ",$fullfile,". I will continue but not expand |$inputcmd|\n" unless $fname =~ m(#[0-9]) ;
$replacement = $inputcmd ; # i.e. just the original command again -> make no change file does not exist
$newpage="";
@@ -1608,7 +1638,7 @@ sub flatten {
}/exgm;
# replace bibliography with bbl file if it exists
- $text=~s/(^(?:[^%\n]|\\%)*)\\bibliography\{(.*?)\}/{
+ $text=~s/(^(?:[^%\n]|\\%)*)\\bibliography\{(.*?)\}/{
if ( -f $bblfile ){
$replacement=read_file_with_encoding(File::Spec->catfile($bblfile), $encoding);
} else {
@@ -1620,10 +1650,10 @@ sub flatten {
}/exgm;
# replace subfile with contents (subfile package)
- $text=~s/(^(?:[^%\n]|\\%)*)\\subfile\{(.*?)\}/{
+ $text=~s/(^(?:[^%\n]|\\%)*)\\subfile\{(.*?)\}/{
$begline=(defined($1)? $1 : "") ;
- $fname = $2;
- # # add tex extension unless there is a three or four letter extension already
+ $fname = $2;
+ # # add tex extension unless there is a three or four letter extension already
$fname .= ".tex" unless $fname =~ m|\.\w{3,4}|;
print STDERR "Include file as subfile $fname\n" if $verbose;
# content of file becomes replacement value (use recursion)
@@ -1634,10 +1664,10 @@ sub flatten {
# if file exists, expand \subfile command by contents of file
$subfile=read_file_with_encoding($fullfile,$encoding) or die "Could not open included subfile ",$fullfile,": $!";
($subpreamble,$subbody,$subpost)=splitdoc($subfile,'\\\\begin\{document\}','\\\\end\{document\}');
- ### $subfile=~s|^.*\\begin{document}||s;
+ ### $subfile=~s|^.*\\begin{document}||s;
### $subfile=~s|\\end{document}.*$||s;
$replacement=flatten($subbody, $preamble,$fullfile,$encoding);
- ### $replacement = remove_endinput($replacement);
+ ### $replacement = remove_endinput($replacement);
} else {
# if file does not exist, do not expand subfile
print STDERR "WARNING: Could not find subfile ",$fullfile,". I will continue but not expand |$2|\n" unless $fname =~ m(#[0-9]) ;
@@ -1648,11 +1678,11 @@ sub flatten {
}/exgm;
# replace \verbatiminput and \lstlistinginput
- $text=~s/(^(?:[^%\n]|\\%)*)\\(verbatiminput\*?|lstinputlisting)$extraspace(\[$brat_n\])?$extraspace\{(.*?)\}/{
+ $text=~s/(^(?:[^%\n]|\\%)*)\\(verbatiminput\*?|lstinputlisting)$extraspace(\[$brat_n\])?$extraspace\{(.*?)\}/{
$begline=(defined($1)? $1 : "") ;
$command = $2 ;
$fname = $4 ;
- $verboptions = defined($3)? $3 : "" ;
+ $verboptions = defined($3)? $3 : "" ;
if ($command eq 'verbatiminput' ) {
$verbenv = "verbatim" ;
} elsif ($command eq 'verbatiminput*' ) {
@@ -1661,7 +1691,7 @@ sub flatten {
$verbenv = "lstlisting" ;
} else {
die "Internal errorL Unexpected verbatim input type $command.\n";
- }
+ }
print STDERR "DEBUG Beg of line match |$begline|\n" if $debug ;
print STDERR "Include file $fname verbatim\n" if $verbose;
print STDERR "DEBUG looking for file ",File::Spec->catfile($dirname,$fname), "\n" if $debug;
@@ -1693,8 +1723,8 @@ sub print_regex_arr {
# if $type is a filename, it will read the file instead of reading from the appendix
# otherwise it will screen appendix for line "%DIF $TYPE" and copy everything up to line
# '%DIF END $TYPE' (where $TYPE is upcased version of $type)
-# extrapream('-nofail',$type) will---instead of failing---simply return nothing if
-# it does not find the matching line in a appendix (do not use -nofail option with multiple types!)
+# extrapream('-nofail',$type) will---instead of failing---simply return nothing if
+# it does not find the matching line in appendix (do not use -nofail option with multiple types!)
sub extrapream {
my @types=@_;
my ($type,$arg);
@@ -1711,14 +1741,20 @@ sub extrapream {
$type=$arg;
$copy=0;
if ( -f $type || lc $type eq '/dev/null' ) {
- open (FILE,$type) or die "Cannot open preamble file $type: $!";
print STDERR "Reading preamble file $type\n" if $verbose ;
+ open (FILE,$type) or die "Cannot open preamble file $type: $!";
+ if (defined($encoding)) {
+ binmode(FILE,":encoding($encoding)");
+ } else {
+ require Encode::Locale;
+ binmode(FILE,":encoding(locale)");
+ }
while (<FILE>) {
chomp ;
if ( $_ =~ m/%DIF PREAMBLE/ ) {
- push (@retval,"$_");
+ push (@retval,"$_");
} else {
- push (@retval,"$_ %DIF PREAMBLE");
+ push (@retval,"$_ %DIF PREAMBLE");
}
}
} else { # not (-f $type)
@@ -1730,9 +1766,9 @@ sub extrapream {
my $data_start = tell DATA;
while (<DATA>) {
if ( m/^%DIF $type/ ) {
- $copy=1;
+ $copy=1;
} elsif ( m/^%DIF END $type/ ) {
- last;
+ last;
}
chomp;
push (@retval,"$_ %DIF PREAMBLE") if $copy;
@@ -1772,7 +1808,7 @@ sub splitdoc {
$pos=pos $rest;
$part2=substr($rest,0,$pos-length($2));
$part3=substr($rest,$pos);
- }
+ }
else {
die "$word1 and $word2 not in the correct order or not present as a pair." ;
}
@@ -1844,7 +1880,7 @@ sub splitlatex {
my $leadin=$1;
length($string)>0 or return ($leadin);
- my @retval=($string =~ m/$pat/osg);
+ my @retval=($string =~ m/$pat/osg);
if (length($string) != length(join("",@retval))) {
print STDERR "\nWARNING: Inconsistency in length of input string and parsed string:\n This often indicates faulty or non-standard latex code.\n In many cases you can ignore this and the following warning messages.\n Note that character numbers in the following are counted beginning after \\begin{document} and are only approximate." unless $ignorewarnings;
@@ -1888,17 +1924,17 @@ sub splitlatex {
# pass1( \@seq1,\@seq2)
# Look for differences between seq1 and seq2.
-# Where an common-subsequence block is flanked by deleted or appended blocks,
+# Where an common-subsequence block is flanked by deleted or appended blocks,
# and is shorter than $MINWORDSBLOCK words it is appended
-# to the last deleted or appended word. If the block contains tokens other than words
+# to the last deleted or appended word. If the block contains tokens other than words
# or punctuation it is not merged.
# Deleted or appended block consisting of words and safe commands only are
# also merged, to prevent break-up in pass2 (after previous isolated words have been removed)
-# If there are commands with textual arguments (e.g. \caption) both in corresponding
-# appended and deleted blocks split them such that the command and opening bracket
-# are one token, then the rest is split up following standard rules, and the closing
+# If there are commands with textual arguments (e.g. \caption) both in corresponding
+# appended and deleted blocks split them such that the command and opening bracket
+# are one token, then the rest is split up following standard rules, and the closing
# bracket is a separate token, ie. turn
-# "\caption{This is a textual argument}" into
+# "\caption{This is a textual argument}" into
# ("\caption{","This ","is ","a ","textual ","argument","}")
# No return value. Destructively changes sequences
sub pass1 {
@@ -1927,15 +1963,15 @@ sub pass1 {
my $adddiscard = sub {
if ($cnt > 0 ) {
$matblkcnt++;
- # just after an unchanged block
+ # just after an unchanged block
# print STDERR "Unchanged block $cnt, $last1,$last2 \n";
- if ($cnt < $MINWORDSBLOCK
+ if ($cnt < $MINWORDSBLOCK
&& $cnt==scalar (
- grep { /^$wpat/ || ( /^\\((?:[`'^"~=.]|[\w\d@*]+))((?:\[$brat_n\]|\{$pat_n\})*)/o
- && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
+ grep { /^$wpat/ || ( /^\\((?:[`'^"~=.]|[\w\d@*]+))((?:\[$brat_n\]|\{$pat_n\})*)/o
+ && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
&& scalar(@dummy=split(" ",$2))<3 ) }
@$block) ) {
- # merge identical blocks shorter than $MINWORDSBLOCK
+ # merge identical blocks shorter than $MINWORDSBLOCK
# and only containing ordinary words
# with preceding different word
# We cannot carry out this merging immediately as this
@@ -1943,23 +1979,23 @@ sub pass1 {
# the algorithm, instead we store in @$todo where we have to merge
push(@$todo, [ $last1,$last2,$cnt,@$block ]);
}
- $block = [];
+ $block = [];
$cnt=0; $last1=-1; $last2=-1;
}
};
my $discard=sub { $deltokcnt++;
&$adddiscard; #($_[0],$_[1]);
push(@$delblock,[ $seq1->[$_[0]],$_[0] ]);
- $last1=$_[0] };
+ $last1=$_[0] };
my $add = sub { $addtokcnt++;
&$adddiscard; #($_[0],$_[1]);
push(@$addblock,[ $seq2->[$_[1]],$_[1] ]);
- $last2=$_[1] };
+ $last2=$_[1] };
my $match = sub { $mattokcnt++;
if ($cnt==0) { # first word of matching sequence after changed sequence or at beginning of word sequence
- $deltextblocks = extracttextblocks($delblock);
+ $deltextblocks = extracttextblocks($delblock);
$delblkcnt++ if scalar @$delblock;
$addtextblocks = extracttextblocks($addblock);
$addblkcnt++ if scalar @$addblock;
@@ -1975,7 +2011,7 @@ sub pass1 {
### Algorithm::Diff 1.19
$matchindex=Algorithm::Diff::_longestCommonSubsequence($delcmds,$addcmds, 0, sub { $_[0]->[0] } );
} else {
- ### Algorithm::Diff 1.15
+ ### Algorithm::Diff 1.15
$matchindex=Algorithm::Diff::_longestCommonSubsequence($delcmds,$addcmds, sub { $_[0]->[0] } );
}
@@ -2006,11 +2042,11 @@ sub pass1 {
my ($index,$block,$cnt)=@{ shift(@$addtextblocks) };
push(@$todo, [-1,$index,$cnt,@$block]);
}
-
+
$addblock=[];
$delblock=[];
}
- push(@$block,$seq2->[$_[1]]);
+ push(@$block,$seq2->[$_[1]]);
$cnt++ };
my $keyfunc = sub { join(" ",split(" ",shift())) };
@@ -2018,7 +2054,7 @@ sub pass1 {
traverse_sequences($seq1,$seq2, { MATCH=>$match, DISCARD_A=>$discard, DISCARD_B=>$add }, $keyfunc );
- # now carry out the merging/splitting. Refer to elements relative from
+ # now carry out the merging/splitting. Refer to elements relative from
# the end (with negative indices) as these offsets don't change before the instruction is executed
# cnt>0: merged small unchanged groups with previous changed blocks
# cnt==-1: split textual commands into components
@@ -2033,7 +2069,7 @@ sub pass1 {
}
}
- if ($verbose) {
+ if ($verbose) {
print STDERR "\n";
print STDERR " $mattokcnt matching tokens in $matblkcnt blocks.\n";
print STDERR " $deltokcnt discarded tokens in $delblkcnt blocks.\n";
@@ -2043,10 +2079,10 @@ sub pass1 {
# extracttextblocks(\@blockindex)
-# $blockindex has the following format
-# [ [ token1, index1 ], [token2, index2],.. ]
-# where index refers to the index in the original old or new word sequence
-# Returns: reference to an array of the form
+# $blockindex has the following format
+# [ [ token1, index1 ], [token2, index2],.. ]
+# where index refers to the index in the original old or new word sequence
+# Returns: reference to an array of the form
# [[ $index, $textblock, $cnt ], ..
# where $index index of block to be merged
# $textblock contains all the words to be merged with the word at $index (but does not contain this word)
@@ -2054,7 +2090,7 @@ sub pass1 {
#
# requires: iscmd
#
-sub extracttextblocks {
+sub extracttextblocks {
my $block=shift;
my ($i,$token,$index);
my $textblock=[];
@@ -2064,13 +2100,13 @@ sub extracttextblocks {
# we redefine locally $extraspace (shadowing the global definition) to capture command sequences with intervening spaces no matter what the global setting
# this is done so we can capture those commands with a predefined number of arguments without having to introduce them again explicitly here
- my $extraspace='\s*';
+ my $extraspace='\s*';
for ($i=0;$i< scalar @$block;$i++) {
($token,$index)=@{ $block->[$i] };
# store pure text blocks
- if ($token =~ /$wpat/ || ( $token =~/^\\((?:[`'^"~=.]|[\w\d@\*]+))((?:${extraspace}\[$brat_n\]${extraspace}|${extraspace}\{$pat_n\})*)/
- && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
+ if ($token =~ /$wpat/ || ( $token =~/^\\((?:[`'^"~=.]|[\w\d@\*]+))((?:${extraspace}\[$brat_n\]${extraspace}|${extraspace}\{$pat_n\})*)/
+ && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
&& !iscmd($1,\@TEXTCMDLIST,\@TEXTCMDEXCL))) {
# we have text or a command which can be treated as text
if ($last<0) {
@@ -2078,7 +2114,7 @@ sub extracttextblocks {
$last=$index;
} else {
# add to pure-text block
- push(@$textblock, $token);
+ push(@$textblock, $token);
}
} else {
# it is not text
@@ -2099,29 +2135,29 @@ sub extracttextblocks {
# extractcommands( \@blockindex )
-# $blockindex has the following format
-# [ [ token1, index1 ], [token2, index2],.. ]
-# where index refers to the index in the original old or new word sequence
-# Returns: reference to an array of the form
-# [ [ "\cmd1", index, "\cmd1[optarg]{arg1}{", "arg2" ,"} " ],..
-# where index is just taken from input array
-# command must have a textual argument as last argument
-#
-# requires: iscmd
-#
-sub extractcommands {
+# $blockindex has the following format
+# [ [ token1, index1 ], [token2, index2],.. ]
+# where index refers to the index in the original old or new word sequence
+# Returns: reference to an array of the form
+# [ [ "\cmd1", index, "\cmd1[optarg]{arg1}{", "arg2" ,"} " ],..
+# where index is just taken from input array
+# command must have a textual argument as last argument
+#
+# requires: iscmd
+#
+sub extractcommands {
my $block=shift;
my ($i,$token,$index,$cmd,$open,$mid,$closing);
my $retval=[];
# we redefine locally $extraspace (shadowing the global definition) to capture command sequences with intervening spaces no matter what the global setting
# this is done so we can capture those commands with a predefined number of arguments without having to introduce them again explicitly here
- my $extraspace='\s*';
+ my $extraspace='\s*';
for ($i=0;$i< scalar @$block;$i++) {
($token,$index)=@{ $block->[$i] };
# check if token is an alphanumeric command sequence with at least one non-optional argument
- # \cmd[...]{...}{last argument}
+ # \cmd[...]{...}{last argument}
# Capturing in the following results in these associations
# $1: \cmd[...]{...}{
# $2: \cmd
@@ -2129,7 +2165,7 @@ sub extractcommands {
# $4: } + trailing spaces
if ( ( $token =~ m/^(\\([\w\d\*]+)(?:${extraspace}\[$brat_n\]|${extraspace}\{$pat_n\})*${extraspace}\{)($pat_n)(\}\s*)$/so )
&& iscmd($2,\@TEXTCMDLIST,\@TEXTCMDEXCL) ) {
- print STDERR "DEBUG EXTRACTCOMMANDS Match |$1|$2|$3|$4|$index \n" if $debug;
+ print STDERR "DEBUG EXTRACTCOMMANDS Match |$1|$2|$3|$4|$index \n" if $debug;
# push(@$retval,[ $2,$index,$1,$3,$4 ]);
($cmd,$open,$mid,$closing) = ($2,$1,$3,$4) ;
$closing =~ s/\}/\\RIGHTBRACE/ ;
@@ -2140,7 +2176,7 @@ sub extractcommands {
}
# iscmd($cmd,\@regexarray,\@regexexcl) checks
-# return 1 if $cmd matches any of the patterns in the
+# return 1 if $cmd matches any of the patterns in the
# array $@regexarray, and none of the patterns in \@regexexcl, otherwise return 0
sub iscmd {
my ($cmd,$regexar,$regexexcl)=@_;
@@ -2148,7 +2184,7 @@ sub iscmd {
### print STDERR "DEBUG: iscmd($cmd)=" if $debug;
foreach $pat ( @$regexar ) {
if ( $cmd =~ m/^${pat}$/ ) {
- $ret=1 ;
+ $ret=1 ;
last;
}
}
@@ -2164,13 +2200,13 @@ sub iscmd {
# pass2( \@seq1,\@seq2)
-# Look for differences between seq1 and seq2.
+# Look for differences between seq1 and seq2.
# Mark begin and end of deleted and appended sequences with tags $DELOPEN and $DELCLOSE
# and $ADDOPEN and $ADDCLOSE, respectively, however exclude { } & and all comands, unless
# they match an element of the whitelist (SAFECMD)
# For words in TEXTCMD but not in SAFECMD, enclose interior with $ADDOPEN and $ADDCLOSE brackets
-# Deleted comment lines are marked with %DIF <
-# Added comment lines are marked with %DIF >
+# Deleted comment lines are marked with %DIF <
+# Added comment lines are marked with %DIF >
sub pass2 {
my $seq1 = shift ;
my $seq2 = shift ;
@@ -2202,7 +2238,7 @@ sub pass2 {
$addhunk = [];
}
push(@$retval,$seq2->[$_[1]]) };
-
+
my $keyfunc = sub { join(" ",split(" ",shift())) };
traverse_sequences($seq1,$seq2, { MATCH=>$match, DISCARD_A=>$discard, DISCARD_B=>$add }, $keyfunc );
@@ -2211,7 +2247,7 @@ sub pass2 {
push @$retval,marktags($ADDMARKOPEN,$ADDMARKCLOSE,$ADDOPEN,$ADDCLOSE,"","",$ADDCOMMENT,$addhunk) if scalar @$addhunk;
- if ($verbose) {
+ if ($verbose) {
print STDERR "\n";
print STDERR " $mattokcnt matching tokens. \n";
print STDERR " $deltokcnt discarded tokens in $delblkcnt blocks.\n";
@@ -2233,7 +2269,7 @@ sub marktags {
my (@argtext);
my $retval=[];
my $noncomment=0;
- my $cmd=-1; # -1 at beginning 0: last token written is a ordinary word
+ my $cmd=-1; # -1 at beginning 0: last token written is a ordinary word
# 1: last token written is a command
# for keeping track whether we are just in a command sequence or in a word sequence
my $cmdcomment= ($opencmd =~ m/^%/); # Flag to indicate whether opencmd is a comment (i.e. if we intend to simply comment out changed commands)
@@ -2249,31 +2285,31 @@ sub marktags {
# we redefine locally $extraspace (shadowing the global definition) to capture command sequences with intervening spaces no matter what the global setting
# this is done so we can capture those commands with a predefined number of arguments without having to introduce them again explicitly here
- my $extraspace_mt='\s*';
+ my $extraspace_mt='\s*';
foreach (@$block) {
- $word=$_;
+ $word=$_;
if ( $word =~ s/^%/%$comment/ ) {
# a comment
if ($cmd==1) {
push (@$retval,$closecmd) ;
$cmd=-1;
}
- push (@$retval,$word);
+ push (@$retval,$word);
next;
}
if ( $word =~ m/^\s*$/ ) {
### print STDERR "DEBUG MARKTAGS: whitespace detected |$word| cmdcom |$cmdcomment| |$opencmd|\n" if $debug;
# a sequence of white-space characters - this should only ever happen for the first element of block.
- # in deleted block, omit, otherwise just copy it in
+ # in deleted block, omit, otherwise just copy it in
if ( ! $cmdcomment) { # ignore in deleted blocks
push(@$retval,$word);
}
next;
}
if (! $noncomment) {
- push (@$retval,$openmark);
+ push (@$retval,$openmark);
$noncomment=1;
}
# negative lookahead pattern (?!) in second clause is put in to avoid matching \( .. \) patterns
@@ -2283,7 +2319,7 @@ sub marktags {
# word is a command or other significant token (not in SAFECMDLIST)
## same conditions as in subroutine extractcommand:
# check if token is an alphanumeric command sequence with at least one non-optional argument
- # \cmd[...]{...}{last argument}
+ # \cmd[...]{...}{last argument}
# Capturing in the following results in these associations
# $1: \cmd[...]{...}{
# $2: cmd
@@ -2300,11 +2336,11 @@ sub marktags {
# Condition 3: But if we are in a deleted block ($cmdcomment=1) and
# $2 (the command) is in context2, just treat it as an ordinary command (i.e. comment it open with $opencmd)
# Because we do not want to disable this command
- # here we do not use $opencmd and $closecmd($opencmd is empty)
+ # here we do not use $opencmd and $closecmd($opencmd is empty)
print STDERR "DEBUG: Detected text |$word| but not safe command \$2: $2 \$3: $3\n." if $debug;
if ($cmd==1) {
push (@$retval,$closecmd) ;
- } elsif ($cmd==0) {
+ } elsif ($cmd==0) {
push (@$retval,$close) ;
}
$command=$1; $commandword=$2; $closingbracket=$4;
@@ -2320,16 +2356,16 @@ sub marktags {
# for latexrevise
push (@$retval,$command,"%\n{$AUXCMD\n",marktags("","",$open,$close,$opencmd,$closecmd,$comment,\@argtext),$closingbracket);
} elsif ( iscmd($commandword,,\@MATHTEXTCMDLIST, \@MATHTEXTCMDEXCL) ) {
- # MATHBLOCK pseudo command: consider all commands safe, except & and \\, \begin and \end and a few package sprcific one (look at UNSAFEMATHCMD definition)
- # Keep these commands even in deleted blocks, hence set $opencmd and $closecmd (5th and 6th argument of marktags) to
+ # MATHBLOCK pseudo command: consider all commands safe, except & and \\, \begin and \end and a few package sprcific one (look at UNSAFEMATHCMD definition)
+ # Keep these commands even in deleted blocks, hence set $opencmd and $closecmd (5th and 6th argument of marktags) to
# ""
- local @SAFECMDLIST=(".*");
+ local @SAFECMDLIST=(".*");
local @SAFECMDEXCL=('\\','\\\\',@UNSAFEMATHCMD);
push(@$retval,$command,marktags("","",$open,$close,"","",$comment,\@argtext)#@argtext
,$closingbracket);
} else {
# normal textcmd or context1cmd in an added block
- push (@$retval,$command,marktags("","",$open,$close,$opencmd,$closecmd,$comment,\@argtext),$closingbracket);
+ push (@$retval,$command,marktags("","",$open,$close,$opencmd,$closecmd,$comment,\@argtext),$closingbracket);
}
push (@$retval,$AUXCMD,"\n") if $cmdcomment ;
$cmd=-1 ;
@@ -2415,10 +2451,10 @@ sub take_comments_and_newline_from_frac() {
# names or labels but it does not matter because they are converted back in the postprocessing step
# Returns: leading white space removed in step 1
sub preprocess {
- for (@_) {
+ for (@_) {
- # change in \verb and similar commands - note that I introduce an extra space here so that the
+ # change in \verb and similar commands - note that I introduce an extra space here so that the
# already hashed variants do not trigger again
# transform \lstinline{...}
# s/\\lstinline(\[$brat0\])?(\{(?:.*?)\})/"\\DIFlstinline". $1 ."{". tohash(\%verbhash,"$2") ."}"/esg;
@@ -2448,7 +2484,7 @@ sub preprocess {
1 while s/(?<!\\)_(\s*{($pat_n)})/\\SUBSCRIPT$1/g ;
# Convert ^n into \SUPERSCRIPTNB{n} and ^{nnn} into \SUPERSCRIPT{nn}
1 while s/(?<!\\)\^(\s*([^{\\\s]|\\\w+))/\\SUPERSCRIPTNB{$1}/g ;
- 1 while s/(?<!\\)\^(\s*{($pat_n)})/\\SUPERSCRIPT$1/g ;
+ 1 while s/(?<!\\)\^(\s*{($pat_n)})/\\SUPERSCRIPT$1/g ;
# Convert \sqrt{n} into \SQRT{n} and \sqrt nn into SQRTNB{nn}
1 while s/(?<!\\)\\sqrt(\s*([^{\\\s]|\\\w+))/\\SQRTNB{$1}/g ;
1 while s/(?<!\\)\\sqrt(\s*{($pat_n)})/\\SQRT$1/g ;
@@ -2468,16 +2504,16 @@ sub preprocess {
if ( $mathmarkup != FINE ) {
# DIFANCHORARRB and DIFANCHORARRE, DIFANCHORMATHB and DIFANCHORMATHE markers are inserted here to encourage the matching algorithm
# to always match up the closing brace. Otherwise sometimes one ends up with a situation where
- # the closing brace is deleted and added at another point. The deleted closing brace is then
+ # the closing brace is deleted and added at another point. The deleted closing brace is then
# prevented by a %DIFDELCMD, leading to material leaking in or out of the math environment.
# The anchors are removed in post-processing again. (note that they are simple text to cause least amount of complications
- # Admittedly, this is something of a hack and will not always work. If it does not, then one needs to
+ # Admittedly, this is something of a hack and will not always work. If it does not, then one needs to
# resort to WHOLE or FINE, or NONE math mode processing.
s/\\begin\{($ARRENV)}(.*?)\\end\{\1}/\\ARRAYBLOCK$1\{$2\\DIFANCHORARRB \}\\DIFANCHORARRE /sg;
take_comments_and_newline_from_frac();
- # Convert Math environments with arguments
+ # Convert Math environments with arguments
s/\\begin\{($MATHENV|$MATHARRENV|SQUAREBRACKET)\}((?:\[$brat_n\])|(?:\{$pat_n\}))+(.*?)\\end\{\1\}/\\MATHBLOCK$1\[$2\]\{$3\\DIFANCHORMATHB \}\\DIFANCHORMATHE /sg;
# Convert Math environments without arguments
s/\\begin\{($MATHENV|$MATHARRENV|SQUAREBRACKET)\}(.*?)\\end\{\1\}/\\MATHBLOCK$1\{$2\\DIFANCHORMATHB \}\\DIFANCHORMATHE /sg;
@@ -2491,7 +2527,7 @@ sub preprocess {
# $expanded=linecomment($string)
#preface all lines with verbatim marker (usually DIFVRB)
-sub linecomment {
+sub linecomment {
my @verbatimlines=split("\n",$_[0]);
# the first line needs special treatment - we do want to retain optional arguments as is but wrap the remainder also with VERBCOMMENT
### print STDERR "DEBUG: before verbatimlines[0] = ",$verbatimlines[0],"\n";
@@ -2501,7 +2537,7 @@ sub linecomment {
}
# $simple=reverselinecomment($env $string)
-# remove DIFVRB comments but leave changed lines marked
+# remove DIFVRB comments but leave changed lines marked
sub reverselinecomment {
my ($environment, $verbatimtext)=@_;
### print STDERR "DEBUG REVERSELINECOMMENT input: $environment,|$verbatimtext|\n" if $debug;
@@ -2516,7 +2552,7 @@ sub reverselinecomment {
$verbatimtext =~ s/\\DIFdelend //g;
$verbatimtext =~ s/$DELCMDOPEN.*//g;
- # remove DIFVRB mark
+ # remove DIFVRB mark
$verbatimtext=~ s/%$VERBCOMMENT//g;
# remove part of the markup in changed lines
@@ -2607,7 +2643,7 @@ sub writedebugfile {
# * Remove STOP token from the end
# * Replace \RIGHTBRACE by }
# * If option --no-del is set delete all deleted blocks
-# 1. Check all deleted blocks:
+# 1. Check all deleted blocks:
# a.where a deleted block contains a matching \begin and
# \end environment (these will be disabled by a %DIFDELCMD statements), for selected environments enable
# these commands again (such that for example displayed math in a deleted equation
@@ -2628,14 +2664,14 @@ sub writedebugfile {
# For added blocks:
# c. If in-line math mode contains array environment, enclose the whole environment in \mbox'es
# d. place \cite commands in mbox'es (for UNDERLINE style)
-#
+#
# 2. If math-mode COARSE,WHOLE or NONE option set: Convert \MATHBLOCKmath{..} commands back to environments
#
# Convert all PICTUREblock{..} commands back to the appropriate environments
# 3. Convert DIFadd, DIFdel, DIFaddbegin , ... into FL varieties
# within floats (currently recognised float environments: plate,table,figure
# plus starred varieties).
-# 4. Remove empty %DIFDELCMD < lines
+# 4. Remove empty %DIFDELCMD < lines
# 4. Convert \begin{SQUAREBRACKET} \end{SQUAREBRACKET} into \[ \]
# Convert \begin{DOLLARDOLLAR} \end{DOLLARDOLLAR} into $$ $$
# 5. Convert \SUPERSCRIPTNB{n} into ^n and \SUPERSCRIPT{nn} into ^{nnn}
@@ -2648,7 +2684,7 @@ sub writedebugfile {
# 4, undo renaming of the \begin, \end,{,} in comments
# Change \QLEFTBRACE, \QRIGHTBRACE,\AMPERSAND to \{,\},\&
#
-# Note have to manually synchronize substitution commands below and
+# Note have to manually synchronize substitution commands below and
# DIF.. command names in the header
sub postprocess {
my ($begin,$len,$float,$delblock,$addblock); ### $cnt
@@ -2660,7 +2696,7 @@ sub postprocess {
my (@itemargs, $itemarg);
- for (@_) {
+ for (@_) {
# change $'s in comments to something harmless
1 while s/(%.*)\$/$1DOLLARDIF/mg ;
@@ -2670,7 +2706,7 @@ sub postprocess {
# the only way to get these is as %DIFDELCMD < \RIGHTBRACE construction
# This essentially marks closing right braces of MATHBLOCK environments, which did not get matched
# up. This case should be rare, so I just leave this in the diff file output. Not really elegant
- # but can still be dealt with later if it results in problems.
+ # but can still be dealt with later if it results in problems.
s/%DIFDELCMD < \\RIGHTBRACE/%DIFDELCMD < \\MBLOCKRIGHTBRACE/g ;
# Replace \RIGHTBRACE by }
s/\\RIGHTBRACE/}/g;
@@ -2698,7 +2734,7 @@ sub postprocess {
$len=length($&);
$begin=pos($_) - $len;
$delblock=$&;
- ### A much simpler method for math replacement might follow this strategy (can recycle part of the commands below for following
+ ### A much simpler method for math replacement might follow this strategy (can recycle part of the commands below for following
### this strategy:
### 1. a Insert aux commands \begin{MATHMODE} or \end{MATHMODE} for all deleted commands opening or closing displayed math mode
### b Insert aux commands \begin{MATHARRMODE} or \end{MATHARRMODE} for all deleted commands opening or closing math array mode
@@ -2724,14 +2760,14 @@ sub postprocess {
###0.5: $delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \s*\\end\{((?:$MATHENV)|SQUAREBRACKET)\}\s*?(?:$DELCMDCLOSE|\n))(.*?[^\n]?)\n?(?<!${AUXCMD}\n)(\%DIFDELCMD < \s*\\begin\{\2\})/\\end{MATHMODE}$AUXCMD\n$1$3\n\\begin{MATHMODE}$AUXCMD\n$4/sg;
$delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{((?:$MATHENV)|SQUAREBRACKET)\}.*?(?:$DELCMDCLOSE|\n))(.*?[^\n]?)\n?(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{\2\})/\\end\{MATHMODE\}$AUXCMD\n$1$3\n\\begin\{MATHMODE\}$AUXCMD\n$4/sg;
- # now look for unpaired %DIFDELCMD < \begin{MATHENV}; if found add \begin{$MATHREPL} and insert \end{$MATHREPL}
+ # now look for unpaired %DIFDELCMD < \begin{MATHENV}; if found add \begin{$MATHREPL} and insert \end{$MATHREPL}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{((?:$MATHENV)|SQUAREBRACKET)\}\s*?(?:$DELCMDCLOSE|\n))/$1\\begin{$MATHREPL}$AUXCMD\n/sg ) {
### print STDERR "BINGO: begin block: \nBefore: |" . substr($_,$begin,$len) . "|\n" if $debug ;
$delblock =~ s/(\\DIFdelend$)/\\end{$MATHREPL}$AUXCMD\n$1/s ;
### print STDERR "After: |" . $delblock . "|\n\n" if $debug ;
}
- # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
+ # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{((?:$MATHENV)|SQUAREBRACKET)\}\s*?(?:$DELCMDCLOSE|\n))/$1\\end\{MATHMODE\}$AUXCMD\n/sg ) {
### print STDERR "BINGO: end block:\nBefore: |" . substr($_,$begin,$len) . "|\n" if $debug;
@@ -2754,15 +2790,15 @@ sub postprocess {
$delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{($MATHARRENV)\}\s*?(?:$DELCMDCLOSE|\n))(.*?[^\n]?)\n?(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{\2\})/\\end{MATHMODE}$AUXCMD\n$1$3\n\\begin{MATHMODE}$AUXCMD\n$4/sg;
### print STDERR "STEP1: |" . $delblock . "|\n\n" if $debug ;
- # now look for unpaired %DIFDELCMD < \begin{MATHARRENV}; if found add \begin{$MATHARRREPL} and insert \end{$MATHARRREPL}
+ # now look for unpaired %DIFDELCMD < \begin{MATHARRENV}; if found add \begin{$MATHARRREPL} and insert \end{$MATHARRREPL}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{($MATHARRENV)\}(.*?)(?:$DELCMDCLOSE|\n))/$1\\begin{$2*}$3$AUXCMD\n/sg ) {
$arrenv=$2;
- $delblock =~ s/(\\DIFdelend$)/\\end{$arrenv*}}$AUXCMD\n$1/s ;
+ $delblock =~ s/(\\DIFdelend$)/\\end{$arrenv*}$AUXCMD\n$1/s ;
}
### print STDERR "STEP2: |" . $delblock . "|\n\n" if $debug ;
- # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
+ # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{($MATHARRENV)\}\s*?(?:$DELCMDCLOSE|\n))/$1\\end{MATHMODE}$AUXCMD\n/sg ) {
$delblock =~ s/(\\DIFdelend$)/\\begin{MATHMODE}$AUXCMD\n$1/s ;
@@ -2780,7 +2816,7 @@ sub postprocess {
### $eqarrayblock=~ s/(\%DIFDELCMD < \s*(\&|\\\\)\s*?(?:$DELCMDCLOSE|\n))/$1$2$AUXCMD\n/sg ;
$eqarrayblock =~ s/(\%DIFDELCMD < (.*?(?:\&|\\\\).*)(?:$DELCMDCLOSE|\n))/
# The pattern captures comments with at least one of & or \\
- @symbols= split(m@((?:&|\\\\)\s*)@,$2); # extract & and \\ and other material from sequence
+ @symbols= split(m@((?:&|\\\\)\s*)@,$2); # extract & and \\ and other material from sequence
@symbols= grep ( m@&|\\\\\s*@, @symbols); # select & and \\ (and subsequent spaces)
"$1@symbols$AUXCMD\n"
/eg ;
@@ -2793,7 +2829,7 @@ sub postprocess {
} elsif ( $mathmarkup == COARSE || $mathmarkup == WHOLE ) {
# Convert MATHBLOCKmath commands to their uncounted numbers (e.g. convert equation -> displaymath
# (environments defined in $MATHENV will be replaced by $MATHREPL, and environments in $MATHARRENV
- # will be replaced by their starred variety
+ # will be replaced by their starred variety
$delblock=~ s/\\MATHBLOCK($MATHENV)((?:\[$brat_n\])?)\{($pat_n)\}/\\MATHBLOCK$MATHREPL$2\{$3\}/sg;
$delblock=~ s/\\MATHBLOCK($MATHARRENV)((?:\[$brat_n\])?)\{($pat_n)\}/\\MATHBLOCK$1\*$2\{$3\}/sg;
}
@@ -2807,10 +2843,10 @@ sub postprocess {
print STDERR "DELBLOCK after maths processing: |" . $delblock . "|\n\n" if $debug ;
- # Reinstate completely deleted list environments. note that items within the
+ # Reinstate completely deleted list environments. note that items within the
# environment will still be commented out. They will be restored later
$delblock=~ s/(\%DIFDELCMD < \s*\\begin\{($LISTENV)\}\s*?(?:\n|$DELCMDCLOSE))(.*?)(\%DIFDELCMD < \s*\\end\{\2\})/{
- ### # block within the search; replacement environment
+ ### # block within the search; replacement environment
### "$1\\begin{$2}$AUXCMD\n". restore_item_commands($3). "\n\\end{$2}$AUXCMD\n$4";
"$1\\begin{$2}$AUXCMD\n$3\n\\end{$2}$AUXCMD\n$4";
}/esg;
@@ -2844,7 +2880,7 @@ sub postprocess {
### if ($CITE2CMD) {
###### ${extraspace}(?:\[$brat0\]${extraspace}){0,2}\{$pat_n\})) .*?%%%\n
### $delblock=~s/($DELCMDOPEN\s*\\($CITE2CMD)(.*)$DELCMDCLOSE)/
- ### # Replacement code
+ ### # Replacement code
### {my ($aux,$all);
### $aux=$all=$1;
### $aux=~s#\n?($DELCMDOPEN|$DELCMDCLOSE)##g;
@@ -2854,7 +2890,7 @@ sub postprocess {
### if ($CITECMD) {
###### $delblock=~s/(\\($CITECMD)${extraspace}(?:\[$brat0\]${extraspace}){0,2}\{$pat_n\})(\s*)/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/msg ;
### $delblock=~s/(\\($CITECMD)${extraspace}(?:<$abrat0>${extraspace})?(?:\[$brat0\]${extraspace}){0,2}\{$pat_n\})(\s*)/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/msg ;
- ### }
+ ### }
# if MBOXINLINEMATH is set, protect inlined math environments with an extra mbox
@@ -2862,7 +2898,7 @@ sub postprocess {
# note additional \newline after command is omitted from output if right at the end of deleted block (otherwise a spurious empty line is generated)
$delblock=~s/($math)(?:[\s\n]*)?/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/sg;
}
- ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/)) {
+ ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/)) {
### # change included verbatim environments
### $delblock =~ s/\\DIFverb\{/\\DIFDIFdelverb\{/g;
### $delblock =~ s/\\DIFlstinline/\\DIFDIFdellstinline/g;
@@ -2904,7 +2940,7 @@ sub postprocess {
##$addblock=~s/($math)/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/sg;
$addblock=~s/($math)(?:[\s\n]*)?/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/sg;
}
- ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat0\])?\{color\}/)) {
+ ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat0\])?\{color\}/)) {
# mark added verbatim commands
$addblock =~ s/\\DIFverb/\\DIFDIFaddverb/g;
$addblock =~ s/\\DIFlstinline/\\DIFDIFaddlstinline/g;
@@ -2922,11 +2958,11 @@ sub postprocess {
pos = $begin + length($addblock);
}
- # Go through whole text, and by counting list environment commands, find out when we are within a list environment.
+ # Go through whole text, and by counting list environment commands, find out when we are within a list environment.
# Within those restore deleted \item commands
- @textparts=split /(?<!$DELCMDOPEN)(\\(?:begin|end)\{$LISTENV\})/ ;
+ @textparts=split /(?<!$DELCMDOPEN)(\\(?:begin|end)\{$LISTENV\})/ ;
@liststack=();
- @newtextparts=map {
+ @newtextparts=map {
### print STDERR ":::::::: $_\n";
if ( ($listtype) = m/^\\begin\{($LISTENV)\}$/ ) {
print STDERR "DEBUG: postprocess \\begin{$listtype}\n" if $debug;
@@ -2942,7 +2978,7 @@ sub postprocess {
} else {
print STDERR "DEBUG: postprocess \@liststack=(",join(",",@liststack),")\n" if $debug;
if (scalar @liststack > 0 ) {
- # we are within a list environment and should replace all item commands
+ # we are within a list environment and should replace all item commands
$_=restore_item_commands($_);
}
# else: we are outside a list environment and do not need to do anything
@@ -2955,17 +2991,17 @@ sub postprocess {
# Replace MATHMODE environments from step 1a above by the correct Math environment and remove unncessary pairings
-
+
if ( $mathmarkup == FINE ) {
# look for AUXCMD math-mode pairs which have only comments (or empty lines between them), and remove the added commands
# \begin{..} ... \end{..} pairs
- s/\\begin\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\end\{\1\}$AUXCMD\n/$2/sg;
+ s/\\begin\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\end\{\1\}$AUXCMD\n/$2/sg;
# \end{..} .... \begin{..} pairs
- s/\\end\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\begin\{\1\}$AUXCMD\n/$2/sg;
+ s/\\end\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\begin\{\1\}$AUXCMD\n/$2/sg;
writedebugfile($_,'postprocess15');
# The next line is complicated. The negative look-ahead insertion makes sure that no \end{$MATHENV} (or other mathematical
- # environments) are between the \begin{$MATHENV} and \end{MATHMODE} commands. This is necessary as the minimal matching
+ # environments) are between the \begin{$MATHENV} and \end{MATHMODE} commands. This is necessary as the minimal matching
# is not globally minimal but only 'locally' (matching is beginning from the left side of the string)
# [NB: Do not be tempted to prettify the expression with /x modified. It seems this is applied after strings are expanded so will ignore spaces in strings
1 while s/(?<!$DELCMDOPEN)\\begin\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET)}((?:${DELCMDOPEN}[^\n]*|.(?!(?:\\end\{(?:(?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET)}|\\begin\{MATHMODE})))*?)\\end\{MATHMODE}/\\begin{$1}$2\\end{$1}/s;
@@ -3040,7 +3076,7 @@ sub postprocess {
# remove empty DIFCMD < lines
s/^\Q${DELCMDOPEN}\E\n//msg;
- # Expand hashes of verb and verbatim environments
+ # Expand hashes of verb and verbatim environments
s/${DELCMDOPEN}\\($VERBATIMENV)\{([-\d]*?)\}/"${DELCMDOPEN}\\begin{${1}}".fromhash(\%verbhash,$2,$DELCMDOPEN)."${DELCMDOPEN}\\end{${1}}"/esg;
# revert changes to verbatim environments for line diffs (and add code to mark up changes) (note negative look behind assertions to not leak out of DIFDELCMD comments)
# Example:
@@ -3066,8 +3102,8 @@ sub postprocess {
((?:\%\Q$DELCOMMENT$VERBCOMMENT\E[^\n]*?\n)*)
# Deleted \end command of verbatim environment. Note that the type is forced to match the opening. Captures: $5: Whole deleted environment (previous way this line was written: (\Q$DELCMDOPEN\E\\end\{\2\}(?:\n|\s|\Q$DELCMDOPEN\E)*\Q$DELCMDCLOSE\E)
(\Q$DELCMDOPEN\E\\end\{\2\})
- / # Substitution part
- $1 # Leave expression as is
+ / # Substitution part
+ $1 # Leave expression as is
. "$AUXCMD NEXT\n" # Mark the following line as an auxiliary command
. "" # reinstate the original environment without options
. reverselinecomment($2, "$3$4") # modify the body to change the markup; reverselinecomment parses for options
@@ -3076,7 +3112,7 @@ sub postprocess {
/esgx; # Modifiers of substitution command
writedebugfile($_,'postprocess2');
# where changes have occurred in verbatim environment, change verbatim to DIFverbatim to allow mark-up
- # (I use the presence of optional paramater to verbatim environment as the marker - normal verbatim
+ # (I use the presence of optional paramater to verbatim environment as the marker - normal verbatim
# environment does not take optional arguments)
s/(?<!$DELCMDOPEN)\\begin\{(verbatim[*]?)\}(\[$brat_n\].*?)\\end\{\1\}/\\begin{DIF$1}$2\\end{DIF$1}/sg;
@@ -3090,7 +3126,7 @@ sub postprocess {
# convert remaining PAR commands (which are preceded by non-white space characters, usually "}" ($ADDCLOSE)
s/\\PAR\n/\n\n/sg;
- # package specific processing:
+ # package specific processing:
if ( defined($packages{"endfloat"})) {
#endfloat: make sure \begin{figure} and \end{figure} are always
# on a line by themselves, similarly for table environment
@@ -3103,12 +3139,16 @@ sub postprocess {
s/^((?:[^%]+)\\(?:begin|end)\{(?:figure|table)\}(?:\[[a-zA-Z]+\])?)(.+)((?:%.*)?)$/$1\n$2$3/mg;
}
- # Convert '\PERCENTAGE ' back into '\%' (the final question mark catches a special situation where due to a latter pre-processing step the ' ' becomes separated
+ # Remove empty auxiliary LISTENV (sometmes these are generated if list environment occurs within the argument of a deleted comment)
+ # (slightly hacky but I could not see an easy way to see if in argument of another command when this extra markup is added)
+ s/\\begin\{($LISTENV)\}$AUXCMD\n((?:\s*\%[^\n]*\n)*\n?)\\end\{\1\}$AUXCMD\n/$2\n/msg ;
+
+ # Convert '\PERCENTAGE ' back into '\%' (the final question mark catches a special situation where due to a latter pre-processing step the ' ' becomes separated
s/\\PERCENTAGE ?/\\%/g;
- # Convert '\DOLLAR ' back into '\$'
+ # Convert '\DOLLAR ' back into '\$'
s/\\DOLLAR /\\\$/g;
- # undo renaming of the \begin and \end,{,} and dollars in comments
+ # undo renaming of the \begin and \end,{,} and dollars in comments
# although we only renamed $ in comments to DOLLARDIFF, we might have lost the % in unchanged verbatim blocks, so rename all
s/DOLLARDIF/\$/g;
@@ -3126,7 +3166,7 @@ sub postprocess {
# Convert \SQRT{n} into \sqrt{n} and \SQRTNB{nn} into \sqrt nn
1 while s/\\SQRT(\s*\{($pat_n)\})/\\sqrt$1/g ;
1 while s/\\SQRTNB\{(\s*$pat0)\}/\\sqrt$1/g ;
-
+
1 while s/(%.*)\\CFRAC (.*)$/$1\\frac$2/mg ;
1 while s/(%.*)\\CRIGHTBRACE (.*)$/$1\}$2/mg ;
1 while s/(%.*)\\CLEFTBRACE (.*)$/$1\{$2/mg ;
@@ -3137,7 +3177,7 @@ sub postprocess {
s/\\QRIGHTBRACE /\\\}/sg;
s/\\AMPERSAND /\\&/sg;
# Highlight added inline verbatim commands if possible
- if ( $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/ ) {
+ if ( $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/ ) {
# wrap added verb commands with color commands
s/\\DIFDIFadd((?:verb\*?|lstinline(?:\[$brat_n\])?)\{[-\d]*?\}[\s\n]*)/\{\\color{blue}$AUXCMD\n\\DIF$1%\n\}$AUXCMD\n/sg;
s/\\DIFDIFdel((?:verb\*?|lstinline(?:\[$brat_n\])?)\{[-\d]*?\}[\s\n]*$AUXCMD)/\{\\color{red}${AUXCMD}\n\\DIF$1\n\}${AUXCMD}/sg;
@@ -3152,8 +3192,8 @@ sub postprocess {
# finally add the comment to the ones not having an optional argument before
###s/\\DIFaddlstinline(?!\[)/\\lstinline\n[basicstyle=\\color{blue}]$AUXCMD\n/g;
- return;
}
+ return;
}
# $out = restore_item_commands($listenviron)
@@ -3177,13 +3217,13 @@ sub restore_item_commands {
# @auxlines=preprocess_preamble($oldpreamble,$newpreamble);
- # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
- # the list of commands is defined in CONTEXT2CMD
- # if found then use a bodydiff to mark up content, and replace the corresponding commands
+ # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
+ # the list of commands is defined in CONTEXT2CMD
+ # if found then use a bodydiff to mark up content, and replace the corresponding commands
# in both preambles by marked up version to 'fool' the linediff (such that only body is marked up).
# A special case are e.g. author commands being added (or removed)
# 1. If commands are added, then the entire content is marked up as new, but also the lines are marked as new in the linediff
- # 2. If commands are removed, then the linediff will mark the line as deleted. The program returns
+ # 2. If commands are removed, then the linediff will mark the line as deleted. The program returns
# with $auxlines a text to be appended at the end of the preamble, which shows the respective fields as deleted
sub preprocess_preamble {
my ($oldpreambleref,$newpreambleref)=(\$_[0],\$_[1]) ;
@@ -3205,7 +3245,7 @@ EOF
$titlecmd = "(?:".join("|",@CONTEXT2CMDLIST).")";
# as context2cmdlist is stored as regex, e.g. ((?-xism:^title$), we need to remove ^- fo
# resue in a more complex regex
- $titlecmd =~ s/[\$\^]//g;
+ $titlecmd =~ s/[\$\^]//g;
# make sure to not match on comment lines:
$titlecmdpat=qr/^(?:[^%\n]|\\%)*(\\($titlecmd)$extraspace(?:\[($brat_n)\])?(?:\{($pat_n)\}))/ms;
###print STDERR "DEBUG:",$titlecmdpat,"\n";
@@ -3231,7 +3271,7 @@ EOF
$cmd=shift @newtitlecommands;
$optarg=shift @newtitlecommands;
$arg=shift @newtitlecommands;
-
+
if ( defined($newhash{$cmd})) {
warn "$cmd is used twice in preamble of new file. Reverting to pure line diff mode for preamble.\n";
print STDERR $warnmsgdetail;
@@ -3258,7 +3298,7 @@ EOF
}
$argnew=$newhash{$cmd}->[2];
$argdiff="{" . join("",bodydiff($argold,$argnew)) ."}";
- # Replace \RIGHTBRACE by }
+ # Replace \RIGHTBRACE by }
$argdiff =~ s/\\RIGHTBRACE/}/g;
if ( length $optargnew ) {
@@ -3273,7 +3313,7 @@ EOF
$optargdiff="";
}
### print STDERR "DEBUG s/\\Q$newhash{$cmd}->[0]\\E/\\$cmd$optargdiff$argdiff/s\n";
- # Note: \Q and \E force literal interpretation of what it between them but allow
+ # Note: \Q and \E force literal interpretation of what it between them but allow
# variable interpolation, such that e.g. \title matches just that and not TAB-itle
$$newpreambleref=~s/\Q$newhash{$cmd}->[0]\E/\\$cmd$optargdiff$argdiff/s;
# replace this in old preamble if necessary
@@ -3313,7 +3353,7 @@ EOF
#%< old deleted line(s)
#%DIF -------
#%DIF mmann-nn
-#new appended line %<
+#new appended line %<
#%DIF -------
# Future extension: mark change explicitly
# Assumes: traverse_sequence traverses deletions before insertions in changed sequences
@@ -3325,9 +3365,9 @@ sub linediff {
my $block = [];
my $retseq = [];
my @begin=('','',''); # dummy initialisation
- my $instring ;
+ my $instring ;
- my $discard = sub { @begin=('d',$_[0],$_[1]) unless scalar @$block ;
+ my $discard = sub { @begin=('d',$_[0],$_[1]) unless scalar @$block ;
push(@$block, "%DIF < " . $seq1->[$_[0]]) };
my $add = sub { if (! scalar @$block) {
@begin=('a',$_[0],$_[1]) ;}
@@ -3342,12 +3382,12 @@ sub linediff {
$instring = sprintf "%%DIF %da%d-%d",$begin[1],$begin[2],$_[1]-1; }
elsif ( $begin[0] eq 'c' ) {
$instring = sprintf "%%DIF %sc%s",
- ($begin[1]==$_[0]-1) ? "$begin[1]" : $begin[1]."-".($_[0]-1) ,
+ ($begin[1]==$_[0]-1) ? "$begin[1]" : $begin[1]."-".($_[0]-1) ,
($begin[2]==$_[1]-1) ? "$begin[2]" : $begin[2]."-".($_[1]-1) ; }
else {
$instring = sprintf "%%DIF %d%s%d",$begin[1],$begin[0],$begin[2]; }
- push @$retseq, $instring,@$block, "%DIF -------" ;
- $block = [];
+ push @$retseq, $instring,@$block, "%DIF -------" ;
+ $block = [];
}
push @$retseq, $seq2->[$_[1]]
};
@@ -3355,7 +3395,7 @@ sub linediff {
my $keyfunc = sub { join(" ",split(" ",shift())) };
traverse_sequences($seq1,$seq2, { MATCH=>$match, DISCARD_A=>$discard, DISCARD_B=>$add }, $keyfunc );
- push @$retseq, @$block if scalar @$block;
+ push @$retseq, @$block if scalar @$block;
return wantarray ? @$retseq : $retseq ;
}
@@ -3365,23 +3405,23 @@ sub linediff {
# init_regex_arr_data(\@array,"TOKEN INIT")
# scans DATA file handel for line "%% TOKEN INIT" line
# then appends each line not beginning with % into array (as a quoted regex)
-# This is used for command lists and configuration variables, but the processing is slightly
-# different:
+# This is used for command lists and configuration variables, but the processing is slightly
+# different:
# For lists, the regular expression is extended to include beginning (^) and end ($) markers, to require full-string matching
# For configuration variables (and all others), simply an unadorned list is copied
sub init_regex_arr_data {
my ($arr,$token)=@_;
my $copy=0;
my ($mode);
- if ($token =~ m/COMMANDS/ ) {
- $mode=0; # Reading command list
+ if ($token =~ m/COMMANDS/ ) {
+ $mode=0; # Reading command list
} else {
$mode=1; # Reading configuration variables
}
while (<DATA>) {
if ( m/^%%BEGIN $token\s*$/ ) {
- $copy=1;
+ $copy=1;
next;
} elsif ( m/^%%END $token\s*$/ ) {
last; }
@@ -3462,17 +3502,18 @@ sub exetime {
sub usage {
- print STDERR <<"EOF";
+ print STDERR <<"EOF";
Usage: $0 [options] old.tex new.tex > diff.tex
-Compares two latex files and writes tex code to stdout, which has the same format as new.tex but
+Compares two latex files and writes tex code to stdout, which has the same format as new.tex but
has all changes relative to old.tex marked up or commented. Note that old.tex and new.tex need to
-be real files (not pipes or similar) as they are opened twice.
+be real files (not pipes or similar) as they are opened twice.
--type=markupstyle
-t markupstyle Add code to preamble for selected markup style
- Available styles: UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
+ Available styles: UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT
+ LUAUNDERLINE
[ Default: UNDERLINE ]
--subtype=markstyle
@@ -3483,7 +3524,7 @@ be real files (not pipes or similar) as they are opened twice.
* LABEL subtype is deprecated
--floattype=markstyle
--f markstyle Add code to preamble for selected style which
+-f markstyle Add code to preamble for selected style which
replace standard marking and markup commands within floats
(e.g., marginal remarks cause an error within floats
so marginal marking can be disabled thus)
@@ -3492,11 +3533,11 @@ be real files (not pipes or similar) as they are opened twice.
--encoding=enc
-e enc Specify encoding of old.tex and new.tex. Typical encodings are
- ascii, utf8, latin1, latin9. A list of available encodings can be
- obtained by executing
+ ascii, utf8, latin1, latin9. A list of available encodings can be
+ obtained by executing
perl -MEncode -e 'print join ("\\n",Encode->encodings( ":all" )) ;'
[Default encoding is utf8 unless the first few lines of the preamble contain
- an invocation "\\usepackage[..]{inputenc} in which case the
+ an invocation "\\usepackage[..]{inputenc} in which case the
encoding chosen by this command is asssumed. Note that ASCII (standard
latex) is a subset of utf8]
@@ -3513,22 +3554,22 @@ be real files (not pipes or similar) as they are opened twice.
--exclude-safecmd=exclude-file
--exclude-safecmd="cmd1,cmd2,..."
--A exclude-file
+-A exclude-file
--replace-safecmd=replace-file
--append-safecmd=append-file
--append-safecmd="cmd1,cmd2,..."
-a append-file Exclude from, replace or append to the list of regex
- matching commands which are safe to use within the
+ matching commands which are safe to use within the
scope of a \\DIFadd or \\DIFdel command. The file must contain
one Perl-RegEx per line (Comment lines beginning with # or % are
ignored). A literal comma within the comma-separated list must be
- escaped thus "\\,", Note that the RegEx needs to match the whole of
+ escaped thus "\\,", Note that the RegEx needs to match the whole of
the token, i.e., /^regex\$/ is implied and that the initial
"\\" of the command is not included. The --exclude-safecmd
- and --append-safecmd options can be combined with the --replace-safecmd
+ and --append-safecmd options can be combined with the --replace-safecmd
option and can be used repeatedly to add cumulatively to the lists.
---exclude-textcmd=exclude-file
+--exclude-textcmd=exclude-file
--exclude-textcmd="cmd1,cmd2,..."
-X exclude-file
--replace-textcmd=replace-file
@@ -3544,7 +3585,7 @@ be real files (not pipes or similar) as they are opened twice.
Replace or append to the list of regex matching commands
whose last argument is text but which require a particular
context to work, e.g. \\caption will only work within a figure
- or table. These commands behave like text commands, except when
+ or table. These commands behave like text commands, except when
they occur in a deleted section, when they are disabled, but their
argument is shown as deleted text.
@@ -3554,7 +3595,7 @@ be real files (not pipes or similar) as they are opened twice.
As corresponding commands for context1. The only difference is that
context2 commands are completely disabled in deleted sections, including
their arguments.
- context2 commands are also the only commands in the preamble, whose argument will
+ context2 commands are also the only commands in the preamble, whose argument will
be processed in word-by-word mode (which only works, if they occur no more than
once in the preamble).
@@ -3563,15 +3604,15 @@ be real files (not pipes or similar) as they are opened twice.
--append-mboxsafecmd=append-file
--append-mboxsafecmd="cmd1,cmd2,..."
Define safe commands, which additionally need to be protected by encapsulating
- in an \\mbox{..}. This is sometimes needed to get around incompatibilities
+ in an \\mbox{..}. This is sometimes needed to get around incompatibilities
between external packages and the ulem package, which is used for highlighting
in the default style UNDERLINE as well as CULINECHBAR CFONTSTRIKE
-
+
--config var1=val1,var2=val2,...
-c var1=val1,.. Set configuration variables.
--c configfile Available variables:
+-c configfile Available variables:
ARRENV (RegEx)
COUNTERCMD (RegEx)
FLOATENV (RegEx)
@@ -3590,15 +3631,15 @@ be real files (not pipes or similar) as they are opened twice.
--add-to-config varenv1=pattern1,varenv2=pattern2
For configuration variables containing a regular expression (essentially those ending
- in ENV, and COUNTERCMD) this provides an alternative way to modify the configuration
+ in ENV, and COUNTERCMD) this provides an alternative way to modify the configuration
variables. Instead of setting the complete pattern, with this option it is possible to add an
alternative pattern. varenv must be one of the variables listed above that take a regular
- expression as argument, and pattern is any regular expression (which might need to be
+ expression as argument, and pattern is any regular expression (which might need to be
protected from the shell by quotation). Several patterns can be added at once by using semi-colons
to separate them, e.g. --add-to-config "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote"
--packages=pkg1,pkg2,..
- Tell latexdiff that .tex file is processed with the packages in list
+ Tell latexdiff that .tex file is processed with the packages in list
loaded. This is normally not necessary if the .tex file includes the
preamble, as the preamble is automatically scanned for \\usepackage commands.
Use of the --packages option disables automatic scanning, so if for any
@@ -3619,57 +3660,57 @@ be real files (not pipes or similar) as they are opened twice.
--show-all Show all of the above
- NB For all --show commands, no old.tex or new.tex file needs to be given, and no
+ NB For all --show commands, no old.tex or new.tex file needs to be given, and no
differencing takes place.
Other configuration options:
--allow-spaces Allow spaces between bracketed or braced arguments to commands
- [Default requires arguments to directly follow each other without
+ [Default requires arguments to directly follow each other without
intervening spaces]
--math-markup=level Determine granularity of markup in displayed math environments:
Possible values for level are (both numerical and text labels are acceptable):
- off or 0: suppress markup for math environments. Deleted equations will not
- appear in diff file. This mode can be used if all the other modes
+ off or 0: suppress markup for math environments. Deleted equations will not
+ appear in diff file. This mode can be used if all the other modes
cause invalid latex code.
whole or 1: Differencing on the level of whole equations. Even trivial changes
- to equations cause the whole equation to be marked changed. This
- mode can be used if processing in coarse or fine mode results in
+ to equations cause the whole equation to be marked changed. This
+ mode can be used if processing in coarse or fine mode results in
invalid latex code.
coarse or 2: Detect changes within equations marked up with a coarse
- granularity; changes in equation type (e.g.displaymath to equation)
+ granularity; changes in equation type (e.g.displaymath to equation)
appear as a change to the complete equation. This mode is recommended
for situations where the content and order of some equations are still
being changed. [Default]
fine or 3: Detect small change in equations and mark up and fine granularity.
This mode is most suitable, if only minor changes to equations are
- expected, e.g. correction of typos.
+ expected, e.g. correction of typos.
--graphics-markup=level Change highlight style for graphics embedded with \\includegraphics commands
Possible values for level:
none,off or 0: no highlighting for figures
new-only or 1: surround newly added or changed figures with a blue frame [Default]
- both or 2: highlight new figures with a blue frame and show deleted figures
+ both or 2: highlight new figures with a blue frame and show deleted figures
at reduced scale, and crossed out with a red diagonal cross. Use configuration
variable SCALEDELGRAPHICS to set size of deleted figures.
- Note that changes to the optional parameters will make the figure appear as changed
+ Note that changes to the optional parameters will make the figure appear as changed
to latexdiff, and this figure will thus be highlighted.
In some circumstances "Misplaced \\noalign" errors can occur if there are certain types
- of changes in tables. In this case please use option --graphics-markup=none as a
- work-around.
+ of changes in tables. In this case please use option --graphics-markup=none as a
+ work-around.
---no-del Suppress deleted text from the diff. It is similar in effect to the BOLD style,
+--no-del Suppress deleted text from the diff. It is similar in effect to the BOLD style,
but the deleted text ist not just invisible in the output, it is also not included in the
- diff text file. This can be more robust than just making it invisible.
+ diff text file. This can be more robust than just making it invisible.
---disable-citation-markup
---disable-auto-mbox Suppress citation markup and markup of other vulnerable commands in styles
+--disable-citation-markup
+--disable-auto-mbox Suppress citation markup and markup of other vulnerable commands in styles
using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR)
(the two options are identical and are simply aliases)
--enable-citation-markup
---enforce-auto-mbox Protect citation commands and other vulnerable commands in changed sections
+--enforce-auto-mbox Protect citation commands and other vulnerable commands in changed sections
with \\mbox command, i.e. use default behaviour for ulem package for other packages
(the two options are identical and are simply aliases)
@@ -3685,14 +3726,14 @@ Miscellaneous options
--no-label Suppress inclusion of old and new file names as comment in output file
---visible-label Include old and new filenames (or labels set with --label option) as
+--visible-label Include old and new filenames (or labels set with --label option) as
visible output
--flatten Replace \\input and \\include commands within body by the content
of the files in their argument. If \\includeonly is present in the
- preamble, only those files are expanded into the document. However,
- no recursion is done, i.e. \\input and \\include commands within
- included sections are not expanded. The included files are assumed to
+ preamble, only those files are expanded into the document. However,
+ no recursion is done, i.e. \\input and \\include commands within
+ included sections are not expanded. The included files are assumed to
be located in the same directories as the old and new master files,
respectively, making it possible to organise files into old and new directories.
--flatten is applied recursively, so inputted files can contain further
@@ -3715,7 +3756,7 @@ Miscellaneous options
-h Show this help text.
--ignore-warnings Suppress warnings about inconsistencies in length between input
- and parsed strings and missing characters.
+ and parsed strings and missing characters.
--verbose
-V Output various status information to stderr during processing.
@@ -3727,10 +3768,10 @@ Internal options:
These options are mostly for automated use by latexdiff-vc. They can be used directly, but
the API should be considered less stable than for the other options.
---no-links Suppress generation of hyperreferences, used for minimal diffs
+--no-links Suppress generation of hyperreferences, used for minimal diffs
(option --only-changes of latexdiff-vc).
EOF
- exit 0;
+ exit 0;
}
=head1 NAME
@@ -3756,8 +3797,8 @@ be real files (not pipes or similar) as they are opened twice (unless C<--encodi
The program treats the preamble differently from the main document.
Differences between the preambles are found using line-based
differencing (similarly to the Unix diff command, but ignoring white
-spaces). A comment, "S<C<%DIF E<gt>>>" is appended to each added line, i.e. a
-line present in C<new.tex> but not in C<old.tex>. Discarded lines
+spaces). A comment, "S<C<%DIF E<gt>>>" is appended to each added line, i.e. a
+line present in C<new.tex> but not in C<old.tex>. Discarded lines
are deactivated by prepending "S<C<%DIF E<lt>>>". Changed blocks are preceded by
comment lines giving information about line numbers in the original files. Where there are insignificant
differences, the resulting file C<diff.tex> will be similar to
@@ -3810,7 +3851,7 @@ curly braces immediately following a command (i.e. a sequence of
letters beginning with a backslash) are arguments for that command.
As a restriction to condition 1 above it is thus necessary to surround
all arguments with curly braces, and to not insert
-extraneous spaces. For example, write
+extraneous spaces. For example, write
\section{\textem{This is an emphasized section title}}
@@ -3842,7 +3883,7 @@ but the choice is yours. Any markup within the environment will be
removed, and generally everything within the environment will just be
taken from the new file.
-It is also possible to difference files which do not have a preamble.
+It is also possible to difference files which do not have a preamble.
In this case, the file is processed in the main document
mode, but the definitions of the markup commands are not inserted.
@@ -3860,7 +3901,7 @@ the scope of C<\DIFadd>. Added comments are marked by prepending
Within deleted blocks text is highlighted with C<\DIFdel>. Deleted
comments are marked by prepending "S<C<%DIF E<lt> >>". Non-safe command
-and curly braces within deleted blocks are commented out with
+and curly braces within deleted blocks are commented out with
"S<C<%DIFDELCMD E<lt> >>".
@@ -3870,7 +3911,7 @@ and curly braces within deleted blocks are commented out with
=head2 Preamble
The following options determine the visual markup style by adding the appropriate
-command definitions to the preamble. See the end of this section for a description of
+command definitions to the preamble. See the end of this section for a description of
available styles.
=over 4
@@ -3880,15 +3921,16 @@ B<-t markupstyle>
Add code to preamble for selected markup style. This option defines
C<\DIFadd> and C<\DIFdel> commands.
-Available styles:
+Available styles:
-C<UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
-CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT>
+C<UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
+CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT
+LUAUNDERLINE>
[ Default: C<UNDERLINE> ]
=item B<--subtype=markstyle> or
-B<-s markstyle>
+B<-s markstyle>
Add code to preamble for selected style for bracketing
commands (e.g. to mark changes in margin). This option defines
@@ -3901,27 +3943,27 @@ Available styles: C<SAFE MARGIN COLOR DVIPSCOL ZLABEL ONLYCHANGEDPAGE (LABEL)*>
=item B<--floattype=markstyle> or
B<-f markstyle>
-Add code to preamble for selected style which
+Add code to preamble for selected style which
replace standard marking and markup commands within floats
(e.g., marginal remarks cause an error within floats
-so marginal marking can be disabled thus). This option defines all
+so marginal marking can be disabled thus). This option defines all
C<\DIF...FL> commands.
Available styles: C<FLOATSAFE TRADITIONALSAFE IDENTICAL>
[ Default: C<FLOATSAFE> ]
-=item B<--encoding=enc> or
+=item B<--encoding=enc> or
B<-e enc>
Specify encoding of old.tex and new.tex. Typical encodings are
-C<ascii>, C<utf8>, C<latin1>, C<latin9>. A list of available encodings can be
-obtained by executing
+C<ascii>, C<utf8>, C<latin1>, C<latin9>. A list of available encodings can be
+obtained by executing
C<perl -MEncode -e 'print join ("\n",Encode->encodings( ":all" )) ;' >
If this option is used, then old.tex, new.tex are only opened once.
[Default encoding is utf8 unless the first few lines of the preamble contain
-an invocation C<\usepackage[..]{inputenc}> in which case the
+an invocation C<\usepackage[..]{inputenc}> in which case the
encoding chosen by this command is asssumed. Note that ASCII (standard
latex) is a subset of utf8]
@@ -3938,7 +3980,7 @@ C<\DIFaddbeginFL, \DIFaddendFL, \DIFaddFL{..},
(If this option is set B<-t>, B<-s>, and B<-f> options
are ignored.)
-=item B<--packages=pkg1,pkg2,..>
+=item B<--packages=pkg1,pkg2,..>
Tell latexdiff that .tex file is processed with the packages in list
loaded. This is normally not necessary if the .tex file includes the
@@ -3949,13 +3991,13 @@ The following packages trigger special behaviour:
=over 8
-=item C<endfloat>
+=item C<endfloat>
Ensure that C<\begin{figure}> and C<\end{figure}> always appear by themselves on a line.
=item C<hyperref>
-Change name of C<\DIFadd> and C<\DIFdel> commands to C<\DIFaddtex> and C<\DIFdeltex> and
+Change name of C<\DIFadd> and C<\DIFdel> commands to C<\DIFaddtex> and C<\DIFdeltex> and
define new C<\DIFadd> and C<\DIFdel> commands, which provide a wrapper for these commands,
using them for the text but not for the link defining command (where any markup would cause
errors).
@@ -4007,17 +4049,17 @@ B<-A exclude-file> or B<--exclude-safecmd="cmd1,cmd2,...">
=item B<--replace-safecmd=replace-file>
-=item B<--append-safecmd=append-file> or
+=item B<--append-safecmd=append-file> or
B<-a append-file> or B<--append-safecmd="cmd1,cmd2,...">
Exclude from, replace or append to the list of regular expressions (RegEx)
-matching commands which are safe to use within the
+matching commands which are safe to use within the
scope of a C<\DIFadd> or C<\DIFdel> command. The file must contain
one Perl-RegEx per line (Comment lines beginning with # or % are
-ignored). Note that the RegEx needs to match the whole of
+ignored). Note that the RegEx needs to match the whole of
the token, i.e., /^regex$/ is implied and that the initial
-"\" of the command is not included.
-The B<--exclude-safecmd> and B<--append-safecmd> options can be combined with the -B<--replace-safecmd>
+"\" of the command is not included.
+The B<--exclude-safecmd> and B<--append-safecmd> options can be combined with the -B<--replace-safecmd>
option and can be used repeatedly to add cumulatively to the lists.
B<--exclude-safecmd>
and B<--append-safecmd> can also take a comma separated list as input. If a
@@ -4030,7 +4072,7 @@ B<-X exclude-file> or B<--exclude-textcmd="cmd1,cmd2,...">
=item B<--replace-textcmd=replace-file>
-=item B<--append-textcmd=append-file> or
+=item B<--append-textcmd=append-file> or
B<-x append-file> or B<--append-textcmd="cmd1,cmd2,...">
Exclude from, replace or append to the list of regular expressions
@@ -4038,7 +4080,7 @@ matching commands whose last argument is text. See
entry for B<--exclude-safecmd> directly above for further details.
-=item B<--replace-context1cmd=replace-file>
+=item B<--replace-context1cmd=replace-file>
=item B<--append-context1cmd=append-file> or
@@ -4047,11 +4089,11 @@ entry for B<--exclude-safecmd> directly above for further details.
Replace or append to the list of regex matching commands
whose last argument is text but which require a particular
context to work, e.g. C<\caption> will only work within a figure
-or table. These commands behave like text commands, except when
+or table. These commands behave like text commands, except when
they occur in a deleted section, when they are disabled, but their
argument is shown as deleted text.
-=item B<--replace-context2cmd=replace-file>
+=item B<--replace-context2cmd=replace-file>
=item B<--append-context2cmd=append-file> or
@@ -4061,9 +4103,9 @@ As corresponding commands for context1. The only difference is that
context2 commands are completely disabled in deleted sections, including
their arguments.
-context2 commands are also the only commands in the preamble, whose argument will be processed in
+context2 commands are also the only commands in the preamble, whose argument will be processed in
word-by-word mode (which only works, if they occur no more than once in the preamble). The algorithm currently cannot cope with repeated context2 commands in the preamble, as they occur e.g. for the C<\author> argument in some journal styles (not in the standard styles, though
-If such a repetition is detected, the whole preamble will be processed in line-by-line mode. In such a case, use C<--replace-context2cmd> option to just select the commands, which should be processed and are not used repeatedly in the preamble.
+If such a repetition is detected, the whole preamble will be processed in line-by-line mode. In such a case, use C<--replace-context2cmd> option to just select the commands, which should be processed and are not used repeatedly in the preamble.
@@ -4072,7 +4114,7 @@ If such a repetition is detected, the whole preamble will be processed in line-b
=item B<--append-mboxsafecmd=append-file> or B<--append-mboxsafecmd="cmd1,cmd2,...">
Define safe commands, which additionally need to be protected by encapsulating
-in an C<\mbox{..}>. This is sometimes needed to get around incompatibilities
+in an C<\mbox{..}>. This is sometimes needed to get around incompatibilities
between external packages and the ulem package, which is used for highlighting
in the default style UNDERLINE as well as CULINECHBAR CFONTSTRIKE
@@ -4086,7 +4128,7 @@ in the default style UNDERLINE as well as CULINECHBAR CFONTSTRIKE
Set configuration variables. The option can be repeated to set different
variables (as an alternative to the comma-separated list).
-Available variables (see below for further explanations):
+Available variables (see below for further explanations):
C<ARRENV> (RegEx)
@@ -4116,10 +4158,10 @@ C<SCALEDELGRAPHICS> (Float)
=item B<--add-to-config varenv1=pattern1,varenv2=pattern2,...>
For configuration variables, which are a regular expression (essentially those ending
-in ENV, COUNTERCMD and CUSTOMDIFCMD, see list above) this option provides an alternative way to modify the configuration
+in ENV, COUNTERCMD and CUSTOMDIFCMD, see list above) this option provides an alternative way to modify the configuration
variables. Instead of setting the complete pattern, with this option it is possible to add an
alternative pattern. C<varenv> must be one of the variables listed above that take a regular
-expression as argument, and pattern is any regular expression (which might need to be
+expression as argument, and pattern is any regular expression (which might need to be
protected from the shell by quotation). Several patterns can be added at once by using semi-colons
to separate them, e.g. C<--add-to-config "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote">
@@ -4139,7 +4181,7 @@ Show values of configuration variables.
Combine all --show commands.
-NB For all --show commands, no C<old.tex> or C<new.tex> file needs to be specified, and no
+NB For all --show commands, no C<old.tex> or C<new.tex> file needs to be specified, and no
differencing takes place.
=back
@@ -4156,29 +4198,29 @@ might get lumpeded with preceding commands) so should only be used if the
default produces erroneous results. (Default requires arguments to
directly follow each other without intervening spaces).
-=item B<--math-markup=level>
+=item B<--math-markup=level>
-Determine granularity of markup in displayed math environments:
+Determine granularity of markup in displayed math environments:
Possible values for level are (both numerical and text labels are acceptable):
-C<off> or C<0>: suppress markup for math environments. Deleted equations will not
-appear in diff file. This mode can be used if all the other modes
+C<off> or C<0>: suppress markup for math environments. Deleted equations will not
+appear in diff file. This mode can be used if all the other modes
cause invalid latex code.
C<whole> or C<1>: Differencing on the level of whole equations. Even trivial changes
-to equations cause the whole equation to be marked changed. This
-mode can be used if processing in coarse or fine mode results in
+to equations cause the whole equation to be marked changed. This
+mode can be used if processing in coarse or fine mode results in
invalid latex code.
C<coarse> or C<2>: Detect changes within equations marked up with a coarse
-granularity; changes in equation type (e.g.displaymath to equation)
+granularity; changes in equation type (e.g.displaymath to equation)
appear as a change to the complete equation. This mode is recommended
for situations where the content and order of some equations are still
being changed. [Default]
C<fine> or C<3>: Detect small change in equations and mark up at fine granularity.
This mode is most suitable, if only minor changes to equations are
-expected, e.g. correction of typos.
+expected, e.g. correction of typos.
=item B<--graphics-markup=level>
@@ -4190,33 +4232,33 @@ C<none>, C<off> or C<0>: no highlighting for figures
C<new-only> or C<1>: surround newly added or changed figures with a blue frame [Default if graphicx package loaded]
-C<both> or C<2>: highlight new figures with a blue frame and show deleted figures at reduced
+C<both> or C<2>: highlight new figures with a blue frame and show deleted figures at reduced
scale, and crossed out with a red diagonal cross. Use configuration
variable SCALEDELGRAPHICS to set size of deleted figures.
-Note that changes to the optional parameters will make the figure appear as changed
+Note that changes to the optional parameters will make the figure appear as changed
to latexdiff, and this figure will thus be highlighted.
In some circumstances "Misplaced \noalign" error can occur if there are certain types
-of changes in tables. In this case please use C<--graphics-markup=none> as a
-work-around.
+of changes in tables. In this case please use C<--graphics-markup=none> as a
+work-around.
-=item B<--no-del>
+=item B<--no-del>
-Suppress deleted text from the diff. It is similar in effect to the BOLD style,
-but the deleted text ist not just invisible in the output, it is also not included in the diff text file.
-This can be more robust than just making it invisible.
+Suppress deleted text from the diff. It is similar in effect to the BOLD style,
+but the deleted text ist not just invisible in the output, it is also not included in the diff text file.
+This can be more robust than just making it invisible.
=item B<--disable-citation-markup> or B<--disable-auto-mbox>
-Suppress citation markup and markup of other vulnerable commands in styles
+Suppress citation markup and markup of other vulnerable commands in styles
using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR)
(the two options are identical and are simply aliases)
=item B<--enable-citation-markup> or B<--enforce-auto-mbox>
-Protect citation commands and other vulnerable commands in changed sections
+Protect citation commands and other vulnerable commands in changed sections
with C<\mbox> command, i.e. use default behaviour for ulem package for other packages
(the two options are identical and are simply aliases)
@@ -4262,18 +4304,18 @@ Suppress inclusion of old and new file names as comment in output file
=item B<--visible-label>
-Include old and new filenames (or labels set with C<--label> option) as
+Include old and new filenames (or labels set with C<--label> option) as
visible output.
=item B<--flatten>
Replace C<\input> and C<\include> commands within body by the content
of the files in their argument. If C<\includeonly> is present in the
-preamble, only those files are expanded into the document. However,
-no recursion is done, i.e. C<\input> and C<\include> commands within
-included sections are not expanded. The included files are assumed to
+preamble, only those files are expanded into the document. However,
+no recursion is done, i.e. C<\input> and C<\include> commands within
+included sections are not expanded. The included files are assumed to
be located in the same directories as the old and new master files,
-respectively, making it possible to organise files into old and new directories.
+respectively, making it possible to organise files into old and new directories.
--flatten is applied recursively, so inputted files can contain further
C<\input> statements. Also handles files included by the import package
(C<\import> and C<\subimport>), and C<\subfile> command.
@@ -4320,7 +4362,7 @@ Suppress generation of hyperreferences, used for minimal diffs (option --only-ch
=back
-=head2 Predefined styles
+=head2 Predefined styles
=head2 Major types
@@ -4333,9 +4375,14 @@ The major type determine the markup of plain text and some selected latex comman
Added text is wavy-underlined and blue, discarded text is struck out and red
(Requires color and ulem packages). Overstriking does not work in displayed math equations such that deleted parts of equation are underlined, not struck out (this is a shortcoming inherent to the ulem package).
+=item C<LUAUNDERLINE>
+
+Added text is underlined and blue, discarded text is struck out and red
+(Requires lua-ul package + LuaLaTeX).
+
=item C<CTRADITIONAL>
-Added text is blue and set in sans-serif, and a red footnote is created for each discarded
+Added text is blue and set in sans-serif, and a red footnote is created for each discarded
piece of text. (Requires color package)
=item C<TRADITIONAL>
@@ -4376,13 +4423,13 @@ Added text is set in bold face, discarded is not shown. (also see --no-del optio
=item C<PDFCOMMENT>
-The pdfcomment package is used to underline new text, and mark deletions with a PDF comment. Note that this markup might appear differently or not at all based on the pdf viewer used. The viewer with best support for pdf markup is probably acroread. This style is only recommended if the number of differences is small.
+The pdfcomment package is used to underline new text, and mark deletions with a PDF comment. Note that this markup might appear differently or not at all based on the pdf viewer used. The viewer with best support for pdf markup is probably acroread. This style is only recommended if the number of differences is small.
=back
=head2 Subtypes
-The subtype defines the commands that are inserted at the begin and end of added or discarded blocks, irrespectively of whether these blocks contain text or commands (Defined commands: C<\DIFaddbegin, \DIFaddend, \DIFdelbegin, \DIFdelend>)
+The subtype defines the commands that are inserted at the begin and end of added or discarded blocks, irrespectively of whether these blocks contain text or commands (Defined commands: C<\DIFaddbegin, \DIFaddend, \DIFdelbegin, \DIFdelend>)
=over 10
@@ -4400,7 +4447,7 @@ from the intended position.
An alternative way of marking added passages in blue, and deleted ones in red.
(It is recommeneded to use instead the main types to effect colored markup,
-although in some cases coloring with dvipscol can be more complete, for example
+although in some cases coloring with dvipscol can be more complete, for example
with citation commands).
=item C<DVIPSCOL>
@@ -4415,12 +4462,12 @@ although in some cases coloring with dvipscol can be more complete).
can be used to highlight only changed pages, but requires post-processing. It is recommend to not call this option manually but use C<latexdiff-vc> with C<--only-changes> option. Alternatively, use the script given within preamble of diff files made using this style.
-=item C<ONLYCHANGEDPAGE>
+=item C<ONLYCHANGEDPAGE>
also highlights changed pages, without the need for post-processing, but might not work reliably if
there is floating material (figures, tables).
-=item C<LABEL>
+=item C<LABEL>
is similar to C<ZLABEL>, but does not need the zref package and works less reliably (deprecated).
@@ -4428,7 +4475,7 @@ is similar to C<ZLABEL>, but does not need the zref package and works less relia
=head2 Float Types
-Some of the markup used in the main text might cause problems when used within
+Some of the markup used in the main text might cause problems when used within
floats (e.g. figures or tables). For this reason alternative versions of all
markup commands are used within floats. The float type defines these alternative commands.
@@ -4455,7 +4502,7 @@ Make no difference between the main text and floats.
=item C<ARRENV>
-If a match to C<ARRENV> is found within an inline math environment within a deleted or added block, then the inlined math
+If a match to C<ARRENV> is found within an inline math environment within a deleted or added block, then the inlined math
is surrounded by C<\mbox{>...C<}>. This is necessary as underlining does not work within inlined array environments.
[ Default: C<ARRENV>=S<C<(?:array|[pbvBV]matrix)> >
@@ -4475,9 +4522,9 @@ C<|subsubsection|paragraph|subparagraph)> ]
This option is for advanced users and allows definition of special versions of commands, which do not work as safe commands.
Commands in C<CUSTOMDIFCMD> that occur in added or deleted blocks will be given an ADD or DEL prefix.
-The prefixed versions of the command must be defined in the preamble, either by putting them
+The prefixed versions of the command must be defined in the preamble, either by putting them
in the preamble of at least the new file, or by creating a custom preamble file (Option --preamble).
-For example the command C<\blindtext> (from package blindtext) does not interact well with underlining, so that
+For example the command C<\blindtext> (from package blindtext) does not interact well with underlining, so that
for the standard markup type, it is not satisfactory to define it as a safe command. Instead, a customised versions
without underlining can be defined in the preamble:
@@ -4491,7 +4538,7 @@ and then latexdiff should be invoked with the option C<-c CUSTOMDIFCMD=blindtext
=item C<FLOATENV>
-Environments whose name matches the regular expression in C<FLOATENV> are
+Environments whose name matches the regular expression in C<FLOATENV> are
considered floats. Within these environments, the I<latexdiff> markup commands
are replaced by their FL variaties.
@@ -4540,17 +4587,17 @@ If C<--graphics-markup=both> is chosen, C<SCALEDELGRAPHICS> is the factor, by wh
=item C<VERBATIMENV>
-RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of these environments will not be processed in any way:
+RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of these environments will not be processed in any way:
deleted content is commented out, new content is not marked up
[ Default: S<C<comment> > ]
=item C<VERBATIMLINEENV>
-RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of environments described by VERBATIMLINEENV are compared in
+RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of environments described by VERBATIMLINEENV are compared in
line mode, and changes are marked up using the listings package. The markup style is set based on the chosen mains markup type (Option -t), or on an analysis
of the preamble.
-Note that "listings.sty" must be installed. If this file is not found the fallback solution is to
+Note that "listings.sty" must be installed. If this file is not found the fallback solution is to
treat VERBATIMLINEENV environments treated exactly the same way as VERBATIMENV environments.
[ Default: S<C<(?:verbatim[*]?|lstlisting> > ]
@@ -4561,30 +4608,40 @@ treat VERBATIMLINEENV environments treated exactly the same way as VERBATIMENV e
=over 10
-=item Citations result in overfull boxes
+=item Changed citations result in overfull boxes
There is an incompatibility between the C<ulem> package, which C<latexdiff> uses for underlining and striking out in the UNDERLINE style,
-the default style, and the way citations are generated. In order to be able to mark up citations properly, they are enclosed with an C<\mbox>
-command. As mboxes cannot be broken across lines, this procedure frequently results in overfull boxes, possibly obscuring the content as it extends beyond the right margin. The same occurs for some other packages (e.g., siunitx). If this is a problem, you have two possibilities.
+the default style, and the way citations are generated. In order to be able to mark up citations properly, they are enclosed with an C<\mbox>
+command. As mboxes cannot be broken across lines, this procedure frequently results in overfull boxes, possibly obscuring the content as it extends beyond the right margin. The same occurs for some other packages (e.g., siunitx). If this is a problem, you have several possibilities.
1. Use C<CFONT> type markup (option C<-t CFONT>): If this markup is chosen, then changed citations are no longer marked up
-with the wavy line (additions) or struck out (deletions), but are still highlighted in the appropriate color, and deleted text is shown with a different font. Other styles not using the C<ulem> package will also work.
+with the wavy line (additions) or struck out (deletions), but are still highlighted in the appropriate color, and deleted text is shown with a different font. Other styles not using the C<ulem> package will also work.
2. Choose option C<--disable-citation-markup> which turns off the marking up of citations: deleted citations are no longer shown, and
-added citations are shown without markup. (This was the default behaviour of latexdiff at versions 0.6 and older)
-
+added citations are shown without markup. (This was the default behaviour of latexdiff at versions 0.6 and older).
For custom packages you can define the commands which need to be protected by C<\mbox> with C<--append-mboxsafecmd> and C<--excludemboxsafecmd> options
(submit your lists of command as feature request at github page to set the default behaviour of future versions, see section 6)
-=item Changes in complicated mathematical equations result in latex processing errors
+3. If you are using luatex >= 1.12.0 you can use option LUAUNDERLINE that uses lua-ul instead of ulem for underlining, which does not have this problem (experimental feature).
+
+=item Changes in complicated mathematical equations result in latex processing errors.
+
+Try option C<--math-markup=whole>. If even that fails, you can turn off mark up for equations with C<--math-markup=off>.
-Try options C<--math-markup=whole>. If even that fails, you can turn off mark up for equations with C<--math-markup=off>.
+=item Deleted parts in equations are not struck out but underlined.
-=item How can I just show the pages where changes had been made
+This is a limitation of the ulem package that implements the strike-out. If you use the amsmath package, then the strike-out command is redefined in such a way that deleted passages are wrapped with C<\text> command; adding C<\usepackage{amsmath}> to your preamble will trigger this behaviour. (If amsmath is not included directly, but imported by another package, latexdiff will not be able to detect its availability; in this case you can give latexdiff a hint with option C<--packages=amsmath>.
-Use options -C<-s ZLABEL> (some postprocessing required) or C<-s ONLYCHANGEDPAGE>. C<latexdiff-vc --ps|--pdf> with C<--only-changes> option takes care of
+
+=item How can I just show the pages where changes had been made?
+
+Use options C<--s ZLABEL> (some postprocessing required) or C<-s ONLYCHANGEDPAGE>. C<latexdiff-vc --ps|--pdf> with C<--only-changes> option takes care of
the post-processing for you (requires zref package to be installed).
+=item The character encoding breaks when running latexdiff from powershell.
+
+This problem is not limited to C<latexdiff> and has to do with the default settings of C<powershell> in Windows. It is recommended to use C<cmd> instead.
+
=back
=head1 BUGS
@@ -4597,13 +4654,13 @@ different numbers of inter-argument spaces are treated as significant.
=back
-Please submit bug reports using the issue tracker of the github repository page I<https://github.com/ftilmann/latexdiff.git>,
+Please submit bug reports using the issue tracker of the github repository page I<https://github.com/ftilmann/latexdiff.git>,
or send them to I<tilmann -- AT -- gfz-potsdam.de>. Include the version number of I<latexdiff>
(from comments at the top of the source or use B<--version>). If you come across latex
files that are error-free and conform to the specifications set out
above, and whose differencing still does not result in error-free
latex, please send me those files, ideally edited to only contain the
-offending passage as long as that still reproduces the problem. If your
+offending passage as long as that still reproduces the problem. If your
file relies on non-standard class files, you must include those. I will not
look at examples where I have trouble to latex the original files.
@@ -4614,24 +4671,24 @@ L<latexrevise>, L<latexdiff-vc>
=head1 PORTABILITY
I<latexdiff> does not make use of external commands and thus should run
-on any platform supporting Perl 5.6 or higher. If files with encodings
+on any platform supporting Perl 5.6 or higher. If files with encodings
other than ASCII or UTF-8 are processed, Perl 5.8 or higher is required.
The standard version of I<latexdiff> requires installation of the Perl package
-C<Algorithm::Diff> (available from I<www.cpan.org> -
+C<Algorithm::Diff> (available from I<www.cpan.org> -
I<http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15>) but a stand-alone
version, I<latexdiff-so>, which has this package inlined, is available, too.
I<latexdiff-fast> requires the I<diff> command to be present.
=head1 AUTHOR
-Version 1.3.3
-Copyright (C) 2004-2022 Frederik Tilmann
+Version 1.3.4
+Copyright (C) 2004-2024 Frederik Tilmann
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License Version 3
-Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N. Becker, T. Doerges, K. Huebner,
+Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N. Becker, T. Doerges, K. Huebner,
T. Connors, Sebastian Gouezel and many others.
Thanks to the many people who sent in bug reports, feature suggestions, and other feedback.
@@ -4902,13 +4959,14 @@ value
underline
sqrt
(SUPER|SUB)SCRIPT
-%%END TEXT COMMANDS
+%%END TEXT COMMANDS
%%BEGIN CONTEXT1 COMMANDS
% Regex matching commands with a text argument (leave out the \), which will fail out of context. These commands behave like text commands, except when they occur in a deleted section, where they are disabled, but their argument is shown as deleted text.
caption
subcaption
-%%END CONTEXT1 COMMANDS
+multicolumn
+%%END CONTEXT1 COMMANDS
%%BEGIN CONTEXT2 COMMANDS
% Regex matching commands with a text argument (leave out the \), which will fail out of context. As corresponding commands for context1. The only difference is that context2 commands are completely disabled in deleted sections, including their arguments.
@@ -4916,7 +4974,7 @@ title
author
date
institute
-%%END CONTEXT2 COMMANDS
+%%END CONTEXT2 COMMANDS
%% CONFIGURATION variabe defaults
%%BEGIN LISTENV CONFIG
@@ -4994,9 +5052,16 @@ verbatim[*]?
\RequirePackage[normalem]{ulem}
\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1}
\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}}
-\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}
+\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}
%DIF END UNDERLINE PREAMBLE
+%DIF LUAUNDERLINE PREAMBLE
+\RequirePackage{lua-ul}
+\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1}
+\providecommand{\DIFadd}[1]{{\protect\color{blue}\underLine{#1}}}
+\providecommand{\DIFdel}[1]{{\protect\color{red}\strikeThrough{#1}}}
+%DIF END LUAUNDERLINE PREAMBLE
+
%DIF CTRADITIONAL PREAMBLE
\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1}
\RequirePackage[stable]{footmisc}
@@ -5168,7 +5233,7 @@ verbatim[*]?
% To show only pages with changes (dvips/dvipdf)
% latex diff.tex
% latex diff.tex
-% dvips -pp `perl -lne 'if (m/\\newlabel{DIFchg[be]\d*}{{.*}{(.*)}}/) { print $1 }' diff.aux | uniq | tr -s \\n ','` diff.dvi
+% dvips -pp `perl -lne 'if (m/\\newlabel{DIFchg[be]\d*}{{.*}{(.*)}}/) { print $1 }' diff.aux | uniq | tr -s \\n ','` diff.dvi
\typeout{Check comments in preamble of output for instructions how to show only pages where changes have been made}
\usepackage[user,abspage]{zref}
\newcount\DIFcounterb
@@ -5188,10 +5253,10 @@ verbatim[*]?
\RequirePackage{etoolbox}
\RequirePackage{zref}
% redefine label command to write immediately to aux file - page references will be lost
-\makeatletter \let\oldlabel\label% Store \label
-\renewcommand{\label}[1]{% Update \label to write to the .aux immediately
-\zref@wrapper@immediate{\oldlabel{#1}}}
-\makeatother
+\makeatletter \let\oldlabel\label% Store \label
+\renewcommand{\label}[1]{% Update \label to write to the .aux immediately
+\zref@wrapper@immediate{\oldlabel{#1}}}
+\makeatother
\newbool{DIFkeeppage}
\newbool{DIFchange}
\boolfalse{DIFkeeppage}
@@ -5209,7 +5274,7 @@ verbatim[*]?
\providecommand{\DIFmodend}{\global\booltrue{DIFkeeppage}\global\boolfalse{DIFchange}}
%DIF END ONLYCHANGEDPAGE PREAMBLE
-%% FLOAT TYPES
+%% FLOAT TYPES
%DIF FLOATSAFE PREAMBLE
\providecommand{\DIFaddFL}[1]{\DIFadd{#1}}
@@ -5241,7 +5306,7 @@ verbatim[*]?
%DIF END TRADITIONALSAFE PREAMBLE
% see:
-% http://tex.stackexchange.com/questions/47351/can-i-redefine-a-command-to-contain-itself
+% http://tex.stackexchange.com/questions/47351/can-i-redefine-a-command-to-contain-itself
%DIF HIGHLIGHTGRAPHICS PREAMBLE
\RequirePackage{settobox}
@@ -5287,6 +5352,15 @@ verbatim[*]?
%% SPECIAL PACKAGE PREAMBLE COMMANDS
+%% Redefine strike out command to wrap in text box if amsmath is used and markup style with ulem is used
+%DIF AMSMATHULEM PREAMBLE
+\makeatletter
+\let\sout@orig\sout
+\renewcommand{\sout}[1]{\ifmmode\text{\sout@orig{\ensuremath{#1}}}\else\sout@orig{#1}\fi}
+\makeatother
+%DIF END AMSMATHULEM PREAMBLE
+
+
% Standard \DIFadd and \DIFdel are redefined as \DIFaddtex and \DIFdeltex
% when hyperref package is included.
%DIF HYPERREF PREAMBLE
@@ -5389,7 +5463,7 @@ verbatim[*]?
%DIF END DIFCODE_BOLD
%DIF DIFCODE_PDFCOMMENT
-
+
moredelim=[il][\color{white}\tiny]{\%DIF\ <\ },
moredelim=[il][\sffamily\bfseries]{\%DIF\ >\ }
%DIF END DIFCODE_PDFCOMMENT
diff --git a/Master/texmf-dist/doc/support/latexdiff/latexdiff-fast b/Master/texmf-dist/doc/support/latexdiff/latexdiff-fast
index ff9a732bacc..44d6005845f 100755
--- a/Master/texmf-dist/doc/support/latexdiff/latexdiff-fast
+++ b/Master/texmf-dist/doc/support/latexdiff/latexdiff-fast
@@ -25,6 +25,21 @@
#
# Note references to issue numbers are for the github repository of latexdiff: https://github.com/ftilmann/latexdiff
#
+# Version 1.3.4:
+# New features:
+# - Option to use lua-ul instead of ulem (for use with LuaLaTeX) (fix #17, #60, #188, #255, #270)
+# Enhancement
+# - If amsmath is detected as one of the included (based on idea in PR #263 contributed by github user xlucn
+# Bug fix
+# - sometimes the introduction of aux commands to show deleted lists or descriptions leaves in place empty auxiliary
+# list environments, which would cause error messages (though skipping messages would result in a correct output pdf).
+# These are now removed.
+# - add more mboxsafecmd and safecmd commands for SIunitx to stay compatible with newer versionsof SIunitx (PR #283, fixing issue #282, contributed by github user joe6302413)
+# - File added via --preamble option is no longer assumed to be ASCII, but read either with encoding as defined by --encoding option or using the encoding of the LOCALE (fixes issue #285 )
+# - multicolumn argument is now treated as text
+# - when tikz-dependency package is used, \& is no longer a safe command as it has special meaning inside dependency environment. The fix is a little of a hack as really it should only be considered unsafe within dependency environment (fixes (mostly) issue #303 )
+# - listings package had trouble with non-ASCII chars. The encoding is now set (thanks to github user anka-213 for finding this). Fixes #304
+#
# Version 1.3.3:
# New features:
# - Option --no-del to remove all deleted text (merge contributed by github user tdegeus PR #252, fixing issue #66
@@ -33,22 +48,22 @@
# - Abbreviations involving punctuations within them. They need special treatment because otherwise in some
# circumstances the gnoring of white space differences in conjunction with merging according to MINWORDSBLOCK rule
# could turn 'i.e.' into 'i.\PAR e.' (see https://github.com/ftilmann/latexdiff/issues/269). A few abbreviations
-# are now hard-coded and treated as atomic:
+# are now hard-coded and treated as atomic:
# English: i.e., e.g. Deutsch: z.B.
# (fixes issue #269)
# - In WHOLE and COARSE math modes, now properly treat math environments with arguments such as \alignat. Fixes #251
-# - For FINE math mode, multiple improvments to the processing work flow yield more robust outcomes. In particular, changes
-# to the equation type, e.g. \begin{displaymath} -> \begin{equation} without modifications now usually no longer result
-# in errors. (Partially) fixes issues #235 and #244.
-# - When encountering deleted math array environments such as align or eqnarray, rather than replacing them with a
-# fixed replacement environment (e.g. align* or eqnarray*), an asterisk is now added to the original command, which
+# - For FINE math mode, multiple improvments to the processing work flow yield more robust outcomes. In particular, changes
+# to the equation type, e.g. \begin{displaymath} -> \begin{equation} without modifications now usually no longer result
+# in errors. (Partially) fixes issues #235 and #244.
+# - When encountering deleted math array environments such as align or eqnarray, rather than replacing them with a
+# fixed replacement environment (e.g. align* or eqnarray*), an asterisk is now added to the original command, which
# in amsmath (and with eqnarray) will result in the same environment but without line numbers. Config variable MATHARRREPL
# is therefore (nearly) redundant, and a depracation warning is given when it is set. Reference to MATHARRREPL are have
# been removed from the manual (there is one exception, when it's still being used: sometimes latexdiff can figure out
# that there is a deleted array environment, but does not know which one. In this case, MATHARRREPL is still being used
-# to encapsulate these parts of the source, and therefore it is still set internally. But this is a quite rare situation).
+# to encapsulate these parts of the source, and therefore it is still set internally. But this is a quite rare situation).
# Fixes issue #216
-# - Unlike 'array' environment, 'split' (amsmath) does not work in argument of \DIFadd or \DIFdl in UNDERLINE modes; therefore remove it from ARRENV configuration variable.
+# - Unlike 'array' environment, 'split' (amsmath) does not work in argument of \DIFadd or \DIFdl in UNDERLINE modes; therefore remove it from ARRENV configuration variable.
# Exclude \begin and \end in math environments in COARSE and WHOLE modes. Fixes #258. Fixes #109
# - --flatten now works for empty files. Fixes issue #242
# - improved processing of Chinese and Japanese texts in that splitting is done based on characters. Thanks to LuXu (Oliver Lew) in git for working this out. Fixes #229, fixes #145
@@ -65,7 +80,7 @@
# Bug fixes:
# - fix issue #206 affecting proper markup of text commands which are not also safe cmd's and have multiple arguments
# - fix issue #210 by adding \eqref (amsmath package) to the list of safe commands
-# - fix bug reported in issue #168 mangled verbatim line environment
+# - fix bug reported in issue #168 mangled verbatim line environment
# - fix bug reported in issue #218 by replacing \hspace{0pt} after \mbox{..} auxiliary commands with \hskip0pt.
# - more ways to process \frac correctly with atomic arguments (committed by julianuu PR #246
# - fix a bug in biblatex mode, which prevented proper processing of modified \textcite (see: https://tex.stackexchange.com/questions/555157/latexdiff-and-biblatex-citation-commands)
@@ -74,10 +89,10 @@
# Version 1.3.1.1
# - remove spurious \n to fix error: Unknown regexp modifier "/n" at .../latexdiff line 1974, near "=~ " (see github issue #201)
#
-# Version 1.3.1
+# Version 1.3.1
# Bug fixes:
# - remove some uninitialised variable $2 warnings in string substitution in flatten function in case included file is not found
-# - add minimal postprocessing to diff processing of preamble commands (replace \RIGHTBRACE by \} )
+# - add minimal postprocessing to diff processing of preamble commands (replace \RIGHTBRACE by \} )
# - pre-processing: replace (contributed) routine take_comments_and_enter_from_frac() with take_comments_and_newline_from_frac(), which does the same thing
# (remove whitespace characters and comments between the argument of \frac commands) in an easier and more robust way. In addition, it
# will replace commands like \frac12 with \frac{1}{2} as pre-processing step. Fixes issue #184
@@ -95,15 +110,15 @@
# Version 1.3.0 (7 October 2018):
# - treat options to \documentclass as potential package names (some packages allow implicit loading of or imply selected packages
# - improved pattern matching: now allows nested angular brackets, and is no longer confused by escaped curly braces
-# - improved pattern matching in COARSE mode: occasionally, the closing bracket or some other elements would be matched in an 'unnatural' way due to another sequence being more minimal in the computational sense, sometimes even causing errors due to tokens moving in or out of the scope of math environments. This is now discouraged by adding internal \DIFANCHOR commands (which are removed again in post-processing) (fixes issues reported via email by li_ruomeng .
+# - improved pattern matching in COARSE mode: occasionally, the closing bracket or some other elements would be matched in an 'unnatural' way due to another sequence being more minimal in the computational sense, sometimes even causing errors due to tokens moving in or out of the scope of math environments. This is now discouraged by adding internal \DIFANCHOR commands (which are removed again in post-processing) (fixes issues reported via email by li_ruomeng .
# - verbatim and lstlisting environments are marked-up with line-by-line in a similar style to non-verbatim text (requires the listing package to be installed)
# (see new configuration variable VERBATIMLINEENV) (several issues and pull requests by jprotze)
-# - --flatten: now supports \verbatiminput and \lstlistinput
+# - --flatten: now supports \verbatiminput and \lstlistinput
# - --flatten: if file is not found, do not fail, simply warn and leave command unexpanded (inspired by issue #112). Don't warn if file name contains #[0-9] as it is then most likely an argument within a command definition rather than an actual file (applies to \input, \subfile, \include commands)
# - added to textcmds: \intertext
# - new config variable CUSTOMDIFCMD to allow defining special versions of commands in added or deleted blocks (Pull request by github user jprotze)
# - added option -no-links (mostly for use by latexdiff-vc in only-changes modes) (Pull request by github user jprotze)
-# - new option --filter-script to run both input through a pre-processing script (PR jasonmccsmith #167)
+# - new option --filter-script to run both input through a pre-processing script (PR jasonmccsmith #167)
# new option --no-filter-stderr to hide stderr output from filter-script (potentially dangerous, as this might hide malfunctioning of filter scripts)
# - --flatten now can deal with imports made using the import package {PR jasonmccsmith #173)
# Bug fixes:
@@ -122,12 +137,12 @@
# make environments that are treated like verbatim environments configurable (config variable VERBATIMENV)
# treat lstinlne as equivalent to verb command
# partially addresses issue #38
-# - refactoring: set default configuration variables in a hash, and those that correspond to lists
+# - refactoring: set default configuration variables in a hash, and those that correspond to lists
# - feature: option --add-to-config used to amend configuration variables, which are regex pattern lists
# - bug fix: deleted figures when endfloat package is activated
# - bug fix: alignat environment now always processed correctly (fix issues #65)
# - bug fix: avoid processing of commands as potential files in routine init_regex_arr (fix issue #70 )
-# - minimal feature enhancement: treat '@' as allowed character in commands (strictly speaking requires prior \makeatletter statement, but always assuming it to be
+# - minimal feature enhancement: treat '@' as allowed character in commands (strictly speaking requires prior \makeatletter statement, but always assuming it to be
# @ a letter if it is part of a command name will usually lead to the correct behaviour (see http://tex.stackexchange.com/questions/346651/latexdiff-and-let)
# - new feature/bug fix: --flatten option \endinput in included files now respected but only if \endinput stands right at the beginning of the line (issue #77)
# - bug fix: flatten would incorrectly attempt to process commented out \include commands (from discussion in issue #77 )
@@ -165,7 +180,7 @@
# - introduce list UNSAFEMATHCMD, which holds list of commands which cannot be marked up with \DIFadd or \DIFdel commands (only relevant for WHOLE and COARSE math markup modes)
# - new subtype LABEL which gives each change a label. This can later be used to only display pages where changes
# have been made (instructions for that are put as comments into the diff'ed file) inspired by answer on http://tex.stackexchange.com/questions/166049/invisible-markers-in-pdfs-using-pdflatex
-# - Configuration variables take into accout some commands from additional packages:
+# - Configuration variables take into accout some commands from additional packages:
# tikzpicture environment now treated as PICTUREENV, and \smallmatrix in ARRENV (amsmath)
# - --flatten: support for \subfile command (subfiles package) (in response to http://tex.stackexchange.com/questions/167620/latexdiff-with-subfiles )
# - --flatten: \bibliography commands expand if corresponding bbl file present
@@ -179,11 +194,11 @@
# - \% in one-letter sub/Superscripts was not converted correctly
#
# Version 1.0.3
-# - fix bug in add_safe_commands that made latexdiff hang on DeclareMathOperator
+# - fix bug in add_safe_commands that made latexdiff hang on DeclareMathOperator
# command in preamble
# - \(..\) inline math expressions were not parsed correctly, if they contained a linebreak
# - applied patch contributed by tomflannaghan via Berlios: [ Patch #3431 ] Adds correct handling of \left< and \right>
-# - \$ is treated correctly as a literal dollar sign (thanks to Reed Cartwright and Joshua Miller for reporting this bug
+# - \$ is treated correctly as a literal dollar sign (thanks to Reed Cartwright and Joshua Miller for reporting this bug
# and sketching out the solution)
# - \^ and \_ are correctly interpreted as accent and underlined space, respectively, not as superscript of subscript
# (thanks to Wail Yahyaoui for pointing out this bug)
@@ -191,19 +206,19 @@
# Version 1.0.1 - treat \big,\bigg etc. equivalently to \left and
# \right - include starred version in MATHENV - apply
# - flatten recursively and --flatten expansion is now
-# aware of comments (thanks to Tim Connors for patch)
+# aware of comments (thanks to Tim Connors for patch)
# - Change to post-processing for more reliability for
# deleted math environments
-# - On linux systems, recognise and remove DOS style newlines
+# - On linux systems, recognise and remove DOS style newlines
# - Provide markup for some special preamble commands (\title,
-# \author,\date,
-# - configurable by setting context2cmd
+# \author,\date,
+# - configurable by setting context2cmd
# - for styles using ulem package, remove \emph and \text.. from list of
# safe commands in order to allow linebreaks within the
-# highlighted sections.
-# - for ulem style, now show citations by enclosing them in \mbox commands.
-# This unfortunately implies linebreaks within citations no longer function,
-# so this functionality can be turned off (Option --disable-citation-markup).
+# highlighted sections.
+# - for ulem style, now show citations by enclosing them in \mbox commands.
+# This unfortunately implies linebreaks within citations no longer function,
+# so this functionality can be turned off (Option --disable-citation-markup).
# With --enable-citation-markup, the mbox markup is forced for other styles)
# - new substyle COLOR. This is particularly useful for marking up citations
# and some special post-processing is implemented to retain cite
@@ -211,11 +226,11 @@
# - four different levels of math-markup
# - Option --driver for choosing driver for modes employing changebar package
# - accept \\* as valid command (and other commands of form \.*). Also accept
-# \<nl> (backslashed newline)
+# \<nl> (backslashed newline)
# - some typo fixes, include commands defined in preamble as safe commands
-# (Sebastian Gouezel)
+# (Sebastian Gouezel)
# - include compared filenames as comments as line 2 and 3 of
-# the preamble (can be modified with option --label, and suppressed with
+# the preamble (can be modified with option --label, and suppressed with
# --no-label), option --visible-label to show files in generated pdf or dvi
# at the beginning of main document
#
@@ -231,7 +246,7 @@
#
# Version 0.4 March 06 option for fast differencing using UNIX diff command, several minor bug fixes (\par bug, improved highlighting of textcmds)
#
-# Version 0.3 August 05 improved parsing of displayed math, --allow-spaces
+# Version 0.3 August 05 improved parsing of displayed math, --allow-spaces
# option, several minor bug fixes
#
# Version 0.25 October 04 Fix bug with deleted equations, add math mode commands to safecmd, add | to allowed interpunctuation signs
@@ -808,12 +823,13 @@ use utf8 ;
use File::Spec ;
+
my ($algodiffversion)=split(/ /,$Algorithm::Diff::VERSION);
my ($versionstring)=<<EOF ;
-This is LATEXDIFF 1.3.3 (Algorithm::Diff $Algorithm::Diff::VERSION, Perl $^V)
- (c) 2004-2022 F J Tilmann
+This is LATEXDIFF 1.3.4 (Algorithm::Diff $Algorithm::Diff::VERSION, Perl $^V)
+ (c) 2004-2024 F J Tilmann
EOF
# Hash with defaults for configuration variables. These marked undef have default values constructed from list defined in the DATA block
@@ -904,9 +920,9 @@ my $DELCMDOPEN='%DIFDELCMD < '; # To mark begin of deleted commands (must begin
my $DELCMDCLOSE="%%%\n"; # To mark end of deleted commands (must end with a new line)
my $AUXCMD='%DIFAUXCMD' ; # follows auxiliary commands put in by latexdiff to make difference file legal
# auxiliary commands must be on a line of their own
- # Note that for verbatim environment openings the %DIFAUXCMD cannot be placed in
+ # Note that for verbatim environment openings the %DIFAUXCMD cannot be placed in
# the same line as this would mean they are shown
- # so the special form "%DIFAUXCMD NEXT" is used to indicate that the next line
+ # so the special form "%DIFAUXCMD NEXT" is used to indicate that the next line
# is an auxiliary command
# Similarly "%DIFAUXCMD LAST" would indicate the auxiliary command is in previous line (not currently used)
my $DELCOMMENT='DIF < '; # To mark deleted comment line
@@ -917,21 +933,21 @@ my @TEXTCMDLIST=(); # array containing patterns of commands with text arguments
my @TEXTCMDEXCL=(); # array containing patterns of commands without text arguments (if a pattern
# matches both TEXTCMDLIST and TEXTCMDEXCL it is excluded)
my @CONTEXT1CMDLIST=(); # array containing patterns of commands with text arguments (subset of text commands),
- # but which cause confusion if used out of context (e.g. \caption).
+ # but which cause confusion if used out of context (e.g. \caption).
# In deleted passages, the command will be disabled but its argument is marked up
- # Otherwise they behave exactly like TEXTCMD's
+ # Otherwise they behave exactly like TEXTCMD's
my @CONTEXT1CMDEXCL=(); # exclude list for above, but always empty
my @CONTEXT2CMDLIST=(); # array containing patterns of commands with text arguments, but which fail or cause confusion
# if used out of context (e.g. \title). They and their arguments will be disabled in deleted
# passages
my @CONTEXT2CMDEXCL=(); # exclude list for above, but always empty
my @MATHTEXTCMDLIST=(); # treat like textcmd. If a textcmd is in deleted or added block, just wrap the
- # whole content with \DIFadd or \DIFdel irrespective of content. This functionality
+ # whole content with \DIFadd or \DIFdel irrespective of content. This functionality
# is useful for pseudo commands \MATHBLOCK.. into which math environments are being
- # transformed
-my @MATHTEXTCMDEXCL=(); #
+ # transformed
+my @MATHTEXTCMDEXCL=(); #
-# Note I need to declare this with "our" instead of "my" because later in the code I have to "local"ise these
+# Note I need to declare this with "our" instead of "my" because later in the code I have to "local"ise these
our @SAFECMDLIST=(); # array containing patterns of safe commands (which do not break when in the argument of DIFadd or DIFDEL)
our @SAFECMDEXCL=();
my @MBOXCMDLIST=(); # patterns for commands which are in principle safe but which need to be surrounded by an \mbox
@@ -996,7 +1012,7 @@ $mathmarkup=COARSE;
$verbose=0;
$onlyadditions=0;
# output debug and intermediate files, set to 0 in final distribution
-$debug=0;
+$debug=0;
# insert preamble directly after documentclass - experimental feature, set to 0 in final distribution
# Note that this failed with mini example (or other files, where packages used in latexdiff preamble
# are called again with incompatible options in preamble of resulting file)
@@ -1019,9 +1035,9 @@ END
my %verbhash;
Getopt::Long::Configure('bundling');
-GetOptions('type|t=s' => \$type,
- 'subtype|s=s' => \$subtype,
- 'floattype|f=s' => \$floattype,
+GetOptions('type|t=s' => \$type,
+ 'subtype|s=s' => \$subtype,
+ 'floattype|f=s' => \$floattype,
'config|c=s' => \@configlist,
'add-to-config=s' => \@addtoconfiglist,
'preamble|p=s' => \$preamblefile,
@@ -1070,11 +1086,11 @@ if ( $help ) {
if ( $version ) {
- print STDERR $versionstring ;
+ print STDERR $versionstring ;
exit 0;
}
-print STDERR $versionstring if $verbose;
+print STDERR $versionstring if $verbose;
if (defined($showall)){
$showpreamble=$showsafe=$showtext=$showconfig=1;
@@ -1092,7 +1108,7 @@ if (defined($mathmarkup)) {
$mathmarkup=~tr/a-z/A-Z/;
if ( $mathmarkup eq 'OFF' ){
$mathmarkup=OFF;
- } elsif ( $mathmarkup eq 'WHOLE' ){
+ } elsif ( $mathmarkup eq 'WHOLE' ){
$mathmarkup=WHOLE;
} elsif ( $mathmarkup eq 'COARSE' ){
$mathmarkup=COARSE;
@@ -1195,7 +1211,7 @@ foreach $config ( @configlist ) {
}
}
foreach $assign ( @config ) {
- $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
+ $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
exists $CONFIG{$1} or die "Unknown configuration variable $1.";
$CONFIG{$1}=$2;
}
@@ -1232,7 +1248,7 @@ foreach $key ( keys(%CONFIG) ) {
foreach $assign ( @addtoconfig ) {
###print STDERR "assign:|$assign|\n";
- $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
+ $assign=~ m/\s*(\w*)\s*=\s*(\S*)\s*$/ or die "Illegal assignment $assign in configuration list (must be variable=value)";
exists $CONFIG{$1} or die "Unknown configuration variable $1.";
$CONFIG{$1}.=";$2";
}
@@ -1247,8 +1263,8 @@ foreach ( keys(%CONFIG) ) {
elsif ( $_ eq "MATHENV" ) { $MATHENV = liststringtoregex($CONFIG{$_}) ; }
elsif ( $_ eq "MATHREPL" ) { $MATHREPL = $CONFIG{$_} ; }
elsif ( $_ eq "MATHARRENV" ) { $MATHARRENV = liststringtoregex($CONFIG{$_}) ; }
- elsif ( $_ eq "MATHARRREPL" ) { $MATHARRREPL = $CONFIG{$_} ;
- print STDERR "WARNING: Setting MATHARRREPL is depracated. Generally deleted math array environments will be set to their starred varieties and the setting of MATHARREPL is ignored.\n\n" unless $MATHARRREPL =~ /eqnarray\*/ ;
+ elsif ( $_ eq "MATHARRREPL" ) { $MATHARRREPL = $CONFIG{$_} ;
+ print STDERR "WARNING: Setting MATHARRREPL is depracated. Generally deleted math array environments will be set to their starred varieties and the setting of MATHARREPL is ignored.\n\n" unless $MATHARRREPL =~ /eqnarray\*/ ;
}
elsif ( $_ eq "ARRENV" ) { $ARRENV = liststringtoregex($CONFIG{$_}) ; }
elsif ( $_ eq "VERBATIMENV" ) { $VERBATIMENV = liststringtoregex($CONFIG{$_}) ; }
@@ -1275,11 +1291,11 @@ foreach $pkg ( @packagelist ) {
if ($showconfig || $showtext || $showsafe || $showpreamble) {
show_configuration();
- exit 0;
+ exit 0;
}
-if ( @ARGV != 2 ) {
+if ( @ARGV != 2 ) {
print STDERR "2 and only 2 non-option arguments required. Write latexdiff -h to get help\n";
exit(2);
}
@@ -1287,7 +1303,7 @@ if ( @ARGV != 2 ) {
# Are extra spaces between command arguments permissible?
my $extraspace;
if ($allowspaces) {
- $extraspace='\s*';
+ $extraspace='\s*';
} else {
$extraspace='';
}
@@ -1310,14 +1326,14 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
# if you get "undefined control sequence MATHBLOCKmath" error, increase the maximum value in this loop
for (my $i_pat = 0; $i_pat < 20; ++$i_pat){
$pat_n = '(?:[^{}]|\{'.$pat_n.'\}|\\\\\{|\\\\\})*';
- # Actually within the text body, quoted braces are replaced in pre-processing. The only place where
+ # Actually within the text body, quoted braces are replaced in pre-processing. The only place where
# the last part of the pattern matters is when processing the arguments of context2cmds in the preamble
# and these contain a \{ or \} combination, probably rare.
# It should thus be fine to use the simpler version below.
### $pat_n = '(?:[^{}]|\{'.$pat_n.'\})*';
}
- my $brat0 = '(?:[^\[\]]|\\\[|\\\])*';
+ my $brat0 = '(?:[^\[\]]|\\\[|\\\])*';
my $brat_n = $brat0;
for (my $i_pat = 0; $i_pat < 4; ++$i_pat){
$brat_n = '(?:[^\[\]]|\['.$brat_n.'\]|\\\[|\\\])*';
@@ -1334,7 +1350,7 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
# could turn 'i.e.' into 'i.\PAR e.' (see https://github.com/ftilmann/latexdiff/issues/269)
# English: i.e., e.g. Deutsch: z.B.
my $abbreviation='(?:i\. ?e\.|e\. ?g\.|z\. ?B\.)' ;
- my $number='-?\d*\.\d*';
+ my $number='-?\d*\.\d*';
# word: sequence of letters or accents followed by letter
my $word_cj='\p{Han}|\p{InHiragana}|\p{InKatakana}';
@@ -1362,7 +1378,7 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
# inline math $....$ or \(..\)
### the commented out version is simpler but for some reason cannot cope with newline (in spite of s option) - need to include \newline explicitly
### my $math='\$(?:[^$]|\\\$)*?\$|\\\\[(].*?\\\\[)]';
- my $math='\$(?:[^$]|\\\$)*?\$|\\\\[(](?:.|\n)*?\\\\[)]';
+ my $math='\$(?:[^$]|\\\$)*?\$|\\\\[(](?:.|\n)*?\\\\[)]';
### test version (this seems to give the same results as version above)
## the current maths command cannot cope with newline within the math expression
### my $math='\$(?:[^$]|\\\$)*?\$|\\[(].*?\\[)]';
@@ -1380,7 +1396,7 @@ push(@SAFECMDLIST, qr/^QLEFTBRACE$/, qr/^QRIGHTBRACE$/);
-# now we are done setting up and can start working
+# now we are done setting up and can start working
my ($oldfile, $newfile) = @ARGV;
# check for existence of input files
if ( ! -e $oldfile ) {
@@ -1408,7 +1424,7 @@ my ($oldtime,$newtime,$oldlabel,$newlabel);
if (defined($labels[0])) {
$oldlabel=$labels[0] ;
} else {
- $oldtime=localtime((stat($oldfile))[9]);
+ $oldtime=localtime((stat($oldfile))[9]);
$oldlabel="$oldfile " . " "x($oldlabel_n_spaces) . $oldtime;
}
if (defined($labels[1])) {
@@ -1421,6 +1437,7 @@ if (defined($labels[1])) {
$encoding=guess_encoding($newfile) unless defined($encoding);
$encoding = "utf8" if $encoding =~ m/^utf8/i ;
+print STDERR "Encoding $encoding\n" if $verbose;
if (lc($encoding) eq "utf8" ) {
binmode(STDOUT, ":utf8");
binmode(STDERR, ":utf8");
@@ -1504,7 +1521,7 @@ my @auxlines;
my ($ulem)=0;
if ( length $oldpreamble && length $newpreamble ) {
- # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
+ # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
# and marking up content with latexdiff markup
@auxlines=preprocess_preamble($oldpreamble,$newpreamble);
@@ -1536,7 +1553,7 @@ if (defined($graphicsmarkup)) {
} else {
# Default: no explicit setting in menu
if ( defined $packages{"graphicx"} or defined $packages{"graphics"} ) {
- $graphicsmarkup=NEWONLY;
+ $graphicsmarkup=NEWONLY;
} else {
$graphicsmarkup=NONE;
}
@@ -1569,7 +1586,7 @@ if ($graphicsmarkup != NONE ) {
@matches=( $latexdiffpreamble =~ m/command\{\\DIFaddbeginFL}\{($pat_n)}/sg ) ;
# we look at the last one of the list to take into account possible redefinition but almost always matches should have exactly one element
if ( $matches[$#matches] =~ m/\\DIFaddbegin/ ) {
- die "Cannot combine graphics markup with float styles defining \\DIFaddbeginFL in terms of \\DIFaddbegin. Use --graphics-markup=none option or choose a different float style.";
+ die "Cannot combine graphics markup with float styles defining \\DIFaddbeginFL in terms of \\DIFaddbegin. Use --graphics-markup=none option or choose a different float style.";
exit 10;
}
###}
@@ -1583,6 +1600,11 @@ if ($graphicsmarkup != NONE ) {
$ulem = ($latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{ulem\}/ || defined $packages{"ulem"});
+# If amsmath is defined and $ulem is used for markup, redefine the \sout command to also work (mostly) in math mode
+# See stack exchange https://tex.stackexchange.com/questions/20609/strikeout-in-math-mode/308647#308647 based on comment by Taylor Raine
+if ( defined($packages{'amsmath'}) and $ulem ) {
+ $latexdiffpreamble .= join "\n",(extrapream('AMSMATHULEM'),"");
+}
# If listings is being used or can be found in the latexdiff search path, add to the preamble auxiliary code to enable line-by-line markup
if ( defined($packages{"listings"}) or `kpsewhich listings.sty` ne "" ) {
@@ -1592,7 +1614,7 @@ if ( defined($packages{"listings"}) or `kpsewhich listings.sty` ne "" ) {
}
my @listingDIFcode=();
my $replaced;
- # note that in case user supplies preamblefile the type might not reflect well the
+ # note that in case user supplies preamblefile the type might not reflect well the actual markup style
@listingDIFcode=extrapream("-nofail","DIFCODE_" . $type) unless defined($preamblefile);
if (!(@listingDIFcode)) {
# if listingDIFcode is empty try to guess a suitable one from the preamble
@@ -1606,13 +1628,17 @@ if ( defined($packages{"listings"}) or `kpsewhich listings.sty` ne "" ) {
@listingDIFcode=extrapream("DIFCODE_BOLD");
}
}
- # now splice it in
+ # add configuration so that listings work with utf-8
+ push @listingpreamble, '\lstset{extendedchars=\true,inputencoding='.$encoding."}\n";
+
+
+ # now splice it in
$replaced=0;
###print STDERR "DEBUG: listingDIFcode: ",join("\n",@listingDIFcode),"|||\n" if $debug;
- @listingpreamble=grep {
+ @listingpreamble=grep {
# only replace if this has not been done already (use short-circuit property of and)
- if (!$replaced and $_ =~ s/^.*%DIFCODE TEMPLATE.*$/join("\n",@listingDIFcode)/e ) {
+ if (!$replaced and $_ =~ s/^.*%DIFCODE TEMPLATE.*$/join("\n",@listingDIFcode)/e ) {
###print STDERR "DEBUG: Replaced text $_\n" if $debug;
$replaced=1;
1;
@@ -1642,7 +1668,7 @@ if ( length $oldpreamble && length $newpreamble ) {
unshift @oldpreamble,'';
@diffpreamble = linediff(\@oldpreamble, \@newpreamble);
# remove dummy line again
- shift @diffpreamble;
+ shift @diffpreamble;
# add filenames, modification time and latexdiff mark
defined($nolabel) or splice @diffpreamble,1,0,
"%DIF LATEXDIFF DIFFERENCE FILE",
@@ -1691,8 +1717,8 @@ if (defined $packages{"siunitx"} ) {
# protect SI command by surrounding them with an \mbox
# this is done to get around an incompatibility between the ulem and siunitx package
print STDERR "siunitx package detected.\n" if $verbose ;
- my $mboxcmds='SI,ang,numlist,numrange,SIlist,SIrange';
- init_regex_arr_list(\@SAFECMDLIST,'num,si');
+ my $mboxcmds='SI,ang,numlist,numrange,SIlist,SIrange,qty,qtylist,qtyproduct,qtyrange,complexqty';
+ init_regex_arr_list(\@SAFECMDLIST,'num,si,numproduct,unit,complexnum');
if ( $enablecitmark || ( $ulem && ! $disablecitmark )) {
init_regex_arr_list(\@MBOXCMDLIST,$mboxcmds);
} else {
@@ -1714,7 +1740,7 @@ if (defined $packages{"cleveref"} ) {
if (defined $packages{"glossaries"} ) {
# protect selected command by surrounding them with an \mbox
- # this is done to get around an incompatibility between ulem and glossaries package
+ # this is done to get around an incompatibility between ulem and glossaries package
print STDERR "glossaries package detected.\n" if $verbose ;
my $mboxcmds='[gG][lL][sS](?:|pl|disp|link|first|firstplural|desc|user[iv][iv]?[iv]?),[aA][cC][rR](?:long|longpl|full|fullpl),[aA][cC][lfp]?[lfp]?';
init_regex_arr_list(\@SAFECMDLIST,'[gG][lL][sS](?:(?:entry)?(?:text|plural|name|symbol)|displaynumberlist|entryfirst|entryfirstplural|entrydesc|entrydescplural|entrysymbolplural|entryuser[iv][iv]?[iv]?|entrynumberlist|entrydisplaynumberlist|entrylong|entrylongpl|entryshort|entryshortpl|entryfull|entryfullpl),[gG]lossentry(?:name|desc|symbol),[aA][cC][rR](?:short|shortpl),[aA]csp?');
@@ -1743,6 +1769,10 @@ if (defined $packages{"mhchem"} ) {
# push(@MATHTEXTCMDLIST,'cee');
}
+if ( defined $packages{"tikz-dependency"} ) {
+ init_regex_arr_ext(\@SAFECMDEXCL, 'AMPERSAND');
+}
+
my ( $citpat);
@@ -1830,7 +1860,7 @@ print STDERR "(",exetime()," s)\n","Done.\n" if $verbose;
# liststringtoregex(liststring)
-# expands string with semi-colon separated list into a regular expression corresponding
+# expands string with semi-colon separated list into a regular expression corresponding
# matching any of the elements
sub liststringtoregex {
my ($liststring)=@_;
@@ -1843,7 +1873,7 @@ sub liststringtoregex {
}
# show_configuration
-# note that this is not encapsulated but uses variables from the main program
+# note that this is not encapsulated but uses variables from the main program
# It is provided for convenience because in the future it is planned to allow output
# to be modified based on what packages are read etc - this works only if the input files are actually read
# whether or not additional files are provided
@@ -1870,7 +1900,7 @@ sub show_configuration {
print "\nContext1 commands (last argument textual, command will be disabled in deleted passages, last argument will be shown as plain text):\n";
print_regex_arr(@CONTEXT1CMDLIST);
print "\nContext2 commands (last argument textual, command and its argument will be disabled in deleted passages):\n";
- print_regex_arr(@CONTEXT2CMDLIST);
+ print_regex_arr(@CONTEXT2CMDLIST);
print "\nExclude list of Commands with last argument not textual (overrides patterns above):\n";
print_regex_arr(@TEXTCMDEXCL);
}
@@ -1978,7 +2008,7 @@ sub list_packages {
my %packages=();
my $pkg;
- # remove comments
+ # remove comments
$preamble=~s/(?<!\\)%.*$//mg ;
while ( $preamble =~ m/\\(?:documentclass|usepackage|RequirePackage)(?:\[($brat_n)\])?\{(.*?)\}/gs ) {
@@ -2083,7 +2113,7 @@ sub flatten {
my ($includeonly,$dirname,$fname,$newpage,$fullfile,$filecontent,$replacement,$begline,$inputcmd,$bblfile,$subfile,$command,$verbenv,$verboptions,$ignore,$fileonly);
my ($subpreamble,$subbody,$subpost);
my ($subdir,$subdirfull,$importfilepath);
- require File::Basename ;
+ require File::Basename ;
### require File::Spec ; # now this is needed even if flatten option not given
$filename = File::Spec->rel2abs( $filename ) ;
($ignore, $dirname, $fileonly) = File::Spec->splitpath($filename) ;
@@ -2123,15 +2153,15 @@ sub flatten {
$subdirfull = (defined($3) ? File::Spec->catdir($dirname,$subdir) : $subdir);
$importfilepath = File::Spec->catfile($subdirfull, $fname);
-
+
print STDERR "importing importfilepath:", $importfilepath,"\n" if $verbose;
if ( -f $importfilepath ) {
# If file exists, replace input or include command with expanded input
#TODO: need remove_endinput & newpage similar to other replacements inside flatten
- $replacement=flatten(read_file_with_encoding($importfilepath, $encoding), $preamble,$importfilepath,$encoding);
+ $replacement=flatten(read_file_with_encoding($importfilepath, $encoding), $preamble,$importfilepath,$encoding);
} else {
# if file does not exist, do not expand include or input command (do not warn if fname contains #[0-9] as it is then likely part of a command definition
- # and is not meant to be expanded directly
+ # and is not meant to be expanded directly
print STDERR "WARNING: Could not find included file ",$importfilepath,". I will continue but not expand |$2|\n";
$replacement = $2;
$replacement .= "{$subdir}{$fname} % Processed";
@@ -2140,13 +2170,13 @@ sub flatten {
}/exgm;
# recursively replace \\input and \\include files
- $text =~ s/(^(?:[^%\n]|\\%)*)(\\input\{(.*?)\}|\\include\{(${includeonly}(?:\.tex)?)\})/{
+ $text =~ s/(^(?:[^%\n]|\\%)*)(\\input\{(.*?)\}|\\include\{(${includeonly}(?:\.tex)?)\})/{
$begline=(defined($1)? $1 : "") ;
$inputcmd=$2;
$fname = $3 if defined($3) ;
$fname = $4 if defined($4) ;
$newpage=(defined($4)? " \\newpage " : "") ;
- # # add tex extension unless there is a three or four letter extension already
+ # # add tex extension unless there is a three or four letter extension already
$fname .= ".tex" unless $fname =~ m|\.\w{3,4}$|;
$fullfile = File::Spec->catfile($dirname,$fname);
print STDERR "DEBUG Beg of line match |$1|\n" if defined($1) && $debug ;
@@ -2155,12 +2185,12 @@ sub flatten {
# content of file becomes replacement value (use recursion), add \newpage if the command was include
if ( -f $fullfile ) {
# If file exists, replace input or include command with expanded input
- $replacement=flatten(read_file_with_encoding($fullfile, $encoding), $preamble,$filename,$encoding);
- $replacement = remove_endinput($replacement);
+ $replacement=flatten(read_file_with_encoding($fullfile, $encoding), $preamble,$filename,$encoding);
+ $replacement = remove_endinput($replacement);
# \include always starts a new page; use explicit \newpage command to simulate this
} else {
# if file does not exist, do not expand include or input command (do not warn if fname contains #[0-9] as it is then likely part of a command definition
- # and is not meant to be expanded directly
+ # and is not meant to be expanded directly
print STDERR "WARNING: Could not find included file ",$fullfile,". I will continue but not expand |$inputcmd|\n" unless $fname =~ m(#[0-9]) ;
$replacement = $inputcmd ; # i.e. just the original command again -> make no change file does not exist
$newpage="";
@@ -2169,7 +2199,7 @@ sub flatten {
}/exgm;
# replace bibliography with bbl file if it exists
- $text=~s/(^(?:[^%\n]|\\%)*)\\bibliography\{(.*?)\}/{
+ $text=~s/(^(?:[^%\n]|\\%)*)\\bibliography\{(.*?)\}/{
if ( -f $bblfile ){
$replacement=read_file_with_encoding(File::Spec->catfile($bblfile), $encoding);
} else {
@@ -2181,10 +2211,10 @@ sub flatten {
}/exgm;
# replace subfile with contents (subfile package)
- $text=~s/(^(?:[^%\n]|\\%)*)\\subfile\{(.*?)\}/{
+ $text=~s/(^(?:[^%\n]|\\%)*)\\subfile\{(.*?)\}/{
$begline=(defined($1)? $1 : "") ;
- $fname = $2;
- # # add tex extension unless there is a three or four letter extension already
+ $fname = $2;
+ # # add tex extension unless there is a three or four letter extension already
$fname .= ".tex" unless $fname =~ m|\.\w{3,4}|;
print STDERR "Include file as subfile $fname\n" if $verbose;
# content of file becomes replacement value (use recursion)
@@ -2195,10 +2225,10 @@ sub flatten {
# if file exists, expand \subfile command by contents of file
$subfile=read_file_with_encoding($fullfile,$encoding) or die "Could not open included subfile ",$fullfile,": $!";
($subpreamble,$subbody,$subpost)=splitdoc($subfile,'\\\\begin\{document\}','\\\\end\{document\}');
- ### $subfile=~s|^.*\\begin{document}||s;
+ ### $subfile=~s|^.*\\begin{document}||s;
### $subfile=~s|\\end{document}.*$||s;
$replacement=flatten($subbody, $preamble,$fullfile,$encoding);
- ### $replacement = remove_endinput($replacement);
+ ### $replacement = remove_endinput($replacement);
} else {
# if file does not exist, do not expand subfile
print STDERR "WARNING: Could not find subfile ",$fullfile,". I will continue but not expand |$2|\n" unless $fname =~ m(#[0-9]) ;
@@ -2209,11 +2239,11 @@ sub flatten {
}/exgm;
# replace \verbatiminput and \lstlistinginput
- $text=~s/(^(?:[^%\n]|\\%)*)\\(verbatiminput\*?|lstinputlisting)$extraspace(\[$brat_n\])?$extraspace\{(.*?)\}/{
+ $text=~s/(^(?:[^%\n]|\\%)*)\\(verbatiminput\*?|lstinputlisting)$extraspace(\[$brat_n\])?$extraspace\{(.*?)\}/{
$begline=(defined($1)? $1 : "") ;
$command = $2 ;
$fname = $4 ;
- $verboptions = defined($3)? $3 : "" ;
+ $verboptions = defined($3)? $3 : "" ;
if ($command eq 'verbatiminput' ) {
$verbenv = "verbatim" ;
} elsif ($command eq 'verbatiminput*' ) {
@@ -2222,7 +2252,7 @@ sub flatten {
$verbenv = "lstlisting" ;
} else {
die "Internal errorL Unexpected verbatim input type $command.\n";
- }
+ }
print STDERR "DEBUG Beg of line match |$begline|\n" if $debug ;
print STDERR "Include file $fname verbatim\n" if $verbose;
print STDERR "DEBUG looking for file ",File::Spec->catfile($dirname,$fname), "\n" if $debug;
@@ -2254,8 +2284,8 @@ sub print_regex_arr {
# if $type is a filename, it will read the file instead of reading from the appendix
# otherwise it will screen appendix for line "%DIF $TYPE" and copy everything up to line
# '%DIF END $TYPE' (where $TYPE is upcased version of $type)
-# extrapream('-nofail',$type) will---instead of failing---simply return nothing if
-# it does not find the matching line in a appendix (do not use -nofail option with multiple types!)
+# extrapream('-nofail',$type) will---instead of failing---simply return nothing if
+# it does not find the matching line in appendix (do not use -nofail option with multiple types!)
sub extrapream {
my @types=@_;
my ($type,$arg);
@@ -2272,14 +2302,20 @@ sub extrapream {
$type=$arg;
$copy=0;
if ( -f $type || lc $type eq '/dev/null' ) {
- open (FILE,$type) or die "Cannot open preamble file $type: $!";
print STDERR "Reading preamble file $type\n" if $verbose ;
+ open (FILE,$type) or die "Cannot open preamble file $type: $!";
+ if (defined($encoding)) {
+ binmode(FILE,":encoding($encoding)");
+ } else {
+ require Encode::Locale;
+ binmode(FILE,":encoding(locale)");
+ }
while (<FILE>) {
chomp ;
if ( $_ =~ m/%DIF PREAMBLE/ ) {
- push (@retval,"$_");
+ push (@retval,"$_");
} else {
- push (@retval,"$_ %DIF PREAMBLE");
+ push (@retval,"$_ %DIF PREAMBLE");
}
}
} else { # not (-f $type)
@@ -2291,9 +2327,9 @@ sub extrapream {
my $data_start = tell DATA;
while (<DATA>) {
if ( m/^%DIF $type/ ) {
- $copy=1;
+ $copy=1;
} elsif ( m/^%DIF END $type/ ) {
- last;
+ last;
}
chomp;
push (@retval,"$_ %DIF PREAMBLE") if $copy;
@@ -2333,7 +2369,7 @@ sub splitdoc {
$pos=pos $rest;
$part2=substr($rest,0,$pos-length($2));
$part3=substr($rest,$pos);
- }
+ }
else {
die "$word1 and $word2 not in the correct order or not present as a pair." ;
}
@@ -2405,7 +2441,7 @@ sub splitlatex {
my $leadin=$1;
length($string)>0 or return ($leadin);
- my @retval=($string =~ m/$pat/osg);
+ my @retval=($string =~ m/$pat/osg);
if (length($string) != length(join("",@retval))) {
print STDERR "\nWARNING: Inconsistency in length of input string and parsed string:\n This often indicates faulty or non-standard latex code.\n In many cases you can ignore this and the following warning messages.\n Note that character numbers in the following are counted beginning after \\begin{document} and are only approximate." unless $ignorewarnings;
@@ -2449,17 +2485,17 @@ sub splitlatex {
# pass1( \@seq1,\@seq2)
# Look for differences between seq1 and seq2.
-# Where an common-subsequence block is flanked by deleted or appended blocks,
+# Where an common-subsequence block is flanked by deleted or appended blocks,
# and is shorter than $MINWORDSBLOCK words it is appended
-# to the last deleted or appended word. If the block contains tokens other than words
+# to the last deleted or appended word. If the block contains tokens other than words
# or punctuation it is not merged.
# Deleted or appended block consisting of words and safe commands only are
# also merged, to prevent break-up in pass2 (after previous isolated words have been removed)
-# If there are commands with textual arguments (e.g. \caption) both in corresponding
-# appended and deleted blocks split them such that the command and opening bracket
-# are one token, then the rest is split up following standard rules, and the closing
+# If there are commands with textual arguments (e.g. \caption) both in corresponding
+# appended and deleted blocks split them such that the command and opening bracket
+# are one token, then the rest is split up following standard rules, and the closing
# bracket is a separate token, ie. turn
-# "\caption{This is a textual argument}" into
+# "\caption{This is a textual argument}" into
# ("\caption{","This ","is ","a ","textual ","argument","}")
# No return value. Destructively changes sequences
sub pass1 {
@@ -2488,15 +2524,15 @@ sub pass1 {
my $adddiscard = sub {
if ($cnt > 0 ) {
$matblkcnt++;
- # just after an unchanged block
+ # just after an unchanged block
# print STDERR "Unchanged block $cnt, $last1,$last2 \n";
- if ($cnt < $MINWORDSBLOCK
+ if ($cnt < $MINWORDSBLOCK
&& $cnt==scalar (
- grep { /^$wpat/ || ( /^\\((?:[`'^"~=.]|[\w\d@*]+))((?:\[$brat_n\]|\{$pat_n\})*)/o
- && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
+ grep { /^$wpat/ || ( /^\\((?:[`'^"~=.]|[\w\d@*]+))((?:\[$brat_n\]|\{$pat_n\})*)/o
+ && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
&& scalar(@dummy=split(" ",$2))<3 ) }
@$block) ) {
- # merge identical blocks shorter than $MINWORDSBLOCK
+ # merge identical blocks shorter than $MINWORDSBLOCK
# and only containing ordinary words
# with preceding different word
# We cannot carry out this merging immediately as this
@@ -2504,23 +2540,23 @@ sub pass1 {
# the algorithm, instead we store in @$todo where we have to merge
push(@$todo, [ $last1,$last2,$cnt,@$block ]);
}
- $block = [];
+ $block = [];
$cnt=0; $last1=-1; $last2=-1;
}
};
my $discard=sub { $deltokcnt++;
&$adddiscard; #($_[0],$_[1]);
push(@$delblock,[ $seq1->[$_[0]],$_[0] ]);
- $last1=$_[0] };
+ $last1=$_[0] };
my $add = sub { $addtokcnt++;
&$adddiscard; #($_[0],$_[1]);
push(@$addblock,[ $seq2->[$_[1]],$_[1] ]);
- $last2=$_[1] };
+ $last2=$_[1] };
my $match = sub { $mattokcnt++;
if ($cnt==0) { # first word of matching sequence after changed sequence or at beginning of word sequence
- $deltextblocks = extracttextblocks($delblock);
+ $deltextblocks = extracttextblocks($delblock);
$delblkcnt++ if scalar @$delblock;
$addtextblocks = extracttextblocks($addblock);
$addblkcnt++ if scalar @$addblock;
@@ -2536,7 +2572,7 @@ sub pass1 {
### Algorithm::Diff 1.19
$matchindex=Algorithm::Diff::_longestCommonSubsequence($delcmds,$addcmds, 0, sub { $_[0]->[0] } );
} else {
- ### Algorithm::Diff 1.15
+ ### Algorithm::Diff 1.15
$matchindex=Algorithm::Diff::_longestCommonSubsequence($delcmds,$addcmds, sub { $_[0]->[0] } );
}
@@ -2567,11 +2603,11 @@ sub pass1 {
my ($index,$block,$cnt)=@{ shift(@$addtextblocks) };
push(@$todo, [-1,$index,$cnt,@$block]);
}
-
+
$addblock=[];
$delblock=[];
}
- push(@$block,$seq2->[$_[1]]);
+ push(@$block,$seq2->[$_[1]]);
$cnt++ };
my $keyfunc = sub { join(" ",split(" ",shift())) };
@@ -2579,7 +2615,7 @@ sub pass1 {
traverse_sequences($seq1,$seq2, { MATCH=>$match, DISCARD_A=>$discard, DISCARD_B=>$add }, $keyfunc );
- # now carry out the merging/splitting. Refer to elements relative from
+ # now carry out the merging/splitting. Refer to elements relative from
# the end (with negative indices) as these offsets don't change before the instruction is executed
# cnt>0: merged small unchanged groups with previous changed blocks
# cnt==-1: split textual commands into components
@@ -2594,7 +2630,7 @@ sub pass1 {
}
}
- if ($verbose) {
+ if ($verbose) {
print STDERR "\n";
print STDERR " $mattokcnt matching tokens in $matblkcnt blocks.\n";
print STDERR " $deltokcnt discarded tokens in $delblkcnt blocks.\n";
@@ -2604,10 +2640,10 @@ sub pass1 {
# extracttextblocks(\@blockindex)
-# $blockindex has the following format
-# [ [ token1, index1 ], [token2, index2],.. ]
-# where index refers to the index in the original old or new word sequence
-# Returns: reference to an array of the form
+# $blockindex has the following format
+# [ [ token1, index1 ], [token2, index2],.. ]
+# where index refers to the index in the original old or new word sequence
+# Returns: reference to an array of the form
# [[ $index, $textblock, $cnt ], ..
# where $index index of block to be merged
# $textblock contains all the words to be merged with the word at $index (but does not contain this word)
@@ -2615,7 +2651,7 @@ sub pass1 {
#
# requires: iscmd
#
-sub extracttextblocks {
+sub extracttextblocks {
my $block=shift;
my ($i,$token,$index);
my $textblock=[];
@@ -2625,13 +2661,13 @@ sub extracttextblocks {
# we redefine locally $extraspace (shadowing the global definition) to capture command sequences with intervening spaces no matter what the global setting
# this is done so we can capture those commands with a predefined number of arguments without having to introduce them again explicitly here
- my $extraspace='\s*';
+ my $extraspace='\s*';
for ($i=0;$i< scalar @$block;$i++) {
($token,$index)=@{ $block->[$i] };
# store pure text blocks
- if ($token =~ /$wpat/ || ( $token =~/^\\((?:[`'^"~=.]|[\w\d@\*]+))((?:${extraspace}\[$brat_n\]${extraspace}|${extraspace}\{$pat_n\})*)/
- && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
+ if ($token =~ /$wpat/ || ( $token =~/^\\((?:[`'^"~=.]|[\w\d@\*]+))((?:${extraspace}\[$brat_n\]${extraspace}|${extraspace}\{$pat_n\})*)/
+ && iscmd($1,\@SAFECMDLIST,\@SAFECMDEXCL)
&& !iscmd($1,\@TEXTCMDLIST,\@TEXTCMDEXCL))) {
# we have text or a command which can be treated as text
if ($last<0) {
@@ -2639,7 +2675,7 @@ sub extracttextblocks {
$last=$index;
} else {
# add to pure-text block
- push(@$textblock, $token);
+ push(@$textblock, $token);
}
} else {
# it is not text
@@ -2660,29 +2696,29 @@ sub extracttextblocks {
# extractcommands( \@blockindex )
-# $blockindex has the following format
-# [ [ token1, index1 ], [token2, index2],.. ]
-# where index refers to the index in the original old or new word sequence
-# Returns: reference to an array of the form
-# [ [ "\cmd1", index, "\cmd1[optarg]{arg1}{", "arg2" ,"} " ],..
-# where index is just taken from input array
-# command must have a textual argument as last argument
-#
-# requires: iscmd
-#
-sub extractcommands {
+# $blockindex has the following format
+# [ [ token1, index1 ], [token2, index2],.. ]
+# where index refers to the index in the original old or new word sequence
+# Returns: reference to an array of the form
+# [ [ "\cmd1", index, "\cmd1[optarg]{arg1}{", "arg2" ,"} " ],..
+# where index is just taken from input array
+# command must have a textual argument as last argument
+#
+# requires: iscmd
+#
+sub extractcommands {
my $block=shift;
my ($i,$token,$index,$cmd,$open,$mid,$closing);
my $retval=[];
# we redefine locally $extraspace (shadowing the global definition) to capture command sequences with intervening spaces no matter what the global setting
# this is done so we can capture those commands with a predefined number of arguments without having to introduce them again explicitly here
- my $extraspace='\s*';
+ my $extraspace='\s*';
for ($i=0;$i< scalar @$block;$i++) {
($token,$index)=@{ $block->[$i] };
# check if token is an alphanumeric command sequence with at least one non-optional argument
- # \cmd[...]{...}{last argument}
+ # \cmd[...]{...}{last argument}
# Capturing in the following results in these associations
# $1: \cmd[...]{...}{
# $2: \cmd
@@ -2690,7 +2726,7 @@ sub extractcommands {
# $4: } + trailing spaces
if ( ( $token =~ m/^(\\([\w\d\*]+)(?:${extraspace}\[$brat_n\]|${extraspace}\{$pat_n\})*${extraspace}\{)($pat_n)(\}\s*)$/so )
&& iscmd($2,\@TEXTCMDLIST,\@TEXTCMDEXCL) ) {
- print STDERR "DEBUG EXTRACTCOMMANDS Match |$1|$2|$3|$4|$index \n" if $debug;
+ print STDERR "DEBUG EXTRACTCOMMANDS Match |$1|$2|$3|$4|$index \n" if $debug;
# push(@$retval,[ $2,$index,$1,$3,$4 ]);
($cmd,$open,$mid,$closing) = ($2,$1,$3,$4) ;
$closing =~ s/\}/\\RIGHTBRACE/ ;
@@ -2701,7 +2737,7 @@ sub extractcommands {
}
# iscmd($cmd,\@regexarray,\@regexexcl) checks
-# return 1 if $cmd matches any of the patterns in the
+# return 1 if $cmd matches any of the patterns in the
# array $@regexarray, and none of the patterns in \@regexexcl, otherwise return 0
sub iscmd {
my ($cmd,$regexar,$regexexcl)=@_;
@@ -2709,7 +2745,7 @@ sub iscmd {
### print STDERR "DEBUG: iscmd($cmd)=" if $debug;
foreach $pat ( @$regexar ) {
if ( $cmd =~ m/^${pat}$/ ) {
- $ret=1 ;
+ $ret=1 ;
last;
}
}
@@ -2725,13 +2761,13 @@ sub iscmd {
# pass2( \@seq1,\@seq2)
-# Look for differences between seq1 and seq2.
+# Look for differences between seq1 and seq2.
# Mark begin and end of deleted and appended sequences with tags $DELOPEN and $DELCLOSE
# and $ADDOPEN and $ADDCLOSE, respectively, however exclude { } & and all comands, unless
# they match an element of the whitelist (SAFECMD)
# For words in TEXTCMD but not in SAFECMD, enclose interior with $ADDOPEN and $ADDCLOSE brackets
-# Deleted comment lines are marked with %DIF <
-# Added comment lines are marked with %DIF >
+# Deleted comment lines are marked with %DIF <
+# Added comment lines are marked with %DIF >
sub pass2 {
my $seq1 = shift ;
my $seq2 = shift ;
@@ -2763,7 +2799,7 @@ sub pass2 {
$addhunk = [];
}
push(@$retval,$seq2->[$_[1]]) };
-
+
my $keyfunc = sub { join(" ",split(" ",shift())) };
traverse_sequences($seq1,$seq2, { MATCH=>$match, DISCARD_A=>$discard, DISCARD_B=>$add }, $keyfunc );
@@ -2772,7 +2808,7 @@ sub pass2 {
push @$retval,marktags($ADDMARKOPEN,$ADDMARKCLOSE,$ADDOPEN,$ADDCLOSE,"","",$ADDCOMMENT,$addhunk) if scalar @$addhunk;
- if ($verbose) {
+ if ($verbose) {
print STDERR "\n";
print STDERR " $mattokcnt matching tokens. \n";
print STDERR " $deltokcnt discarded tokens in $delblkcnt blocks.\n";
@@ -2794,7 +2830,7 @@ sub marktags {
my (@argtext);
my $retval=[];
my $noncomment=0;
- my $cmd=-1; # -1 at beginning 0: last token written is a ordinary word
+ my $cmd=-1; # -1 at beginning 0: last token written is a ordinary word
# 1: last token written is a command
# for keeping track whether we are just in a command sequence or in a word sequence
my $cmdcomment= ($opencmd =~ m/^%/); # Flag to indicate whether opencmd is a comment (i.e. if we intend to simply comment out changed commands)
@@ -2810,31 +2846,31 @@ sub marktags {
# we redefine locally $extraspace (shadowing the global definition) to capture command sequences with intervening spaces no matter what the global setting
# this is done so we can capture those commands with a predefined number of arguments without having to introduce them again explicitly here
- my $extraspace_mt='\s*';
+ my $extraspace_mt='\s*';
foreach (@$block) {
- $word=$_;
+ $word=$_;
if ( $word =~ s/^%/%$comment/ ) {
# a comment
if ($cmd==1) {
push (@$retval,$closecmd) ;
$cmd=-1;
}
- push (@$retval,$word);
+ push (@$retval,$word);
next;
}
if ( $word =~ m/^\s*$/ ) {
### print STDERR "DEBUG MARKTAGS: whitespace detected |$word| cmdcom |$cmdcomment| |$opencmd|\n" if $debug;
# a sequence of white-space characters - this should only ever happen for the first element of block.
- # in deleted block, omit, otherwise just copy it in
+ # in deleted block, omit, otherwise just copy it in
if ( ! $cmdcomment) { # ignore in deleted blocks
push(@$retval,$word);
}
next;
}
if (! $noncomment) {
- push (@$retval,$openmark);
+ push (@$retval,$openmark);
$noncomment=1;
}
# negative lookahead pattern (?!) in second clause is put in to avoid matching \( .. \) patterns
@@ -2844,7 +2880,7 @@ sub marktags {
# word is a command or other significant token (not in SAFECMDLIST)
## same conditions as in subroutine extractcommand:
# check if token is an alphanumeric command sequence with at least one non-optional argument
- # \cmd[...]{...}{last argument}
+ # \cmd[...]{...}{last argument}
# Capturing in the following results in these associations
# $1: \cmd[...]{...}{
# $2: cmd
@@ -2861,11 +2897,11 @@ sub marktags {
# Condition 3: But if we are in a deleted block ($cmdcomment=1) and
# $2 (the command) is in context2, just treat it as an ordinary command (i.e. comment it open with $opencmd)
# Because we do not want to disable this command
- # here we do not use $opencmd and $closecmd($opencmd is empty)
+ # here we do not use $opencmd and $closecmd($opencmd is empty)
print STDERR "DEBUG: Detected text |$word| but not safe command \$2: $2 \$3: $3\n." if $debug;
if ($cmd==1) {
push (@$retval,$closecmd) ;
- } elsif ($cmd==0) {
+ } elsif ($cmd==0) {
push (@$retval,$close) ;
}
$command=$1; $commandword=$2; $closingbracket=$4;
@@ -2881,16 +2917,16 @@ sub marktags {
# for latexrevise
push (@$retval,$command,"%\n{$AUXCMD\n",marktags("","",$open,$close,$opencmd,$closecmd,$comment,\@argtext),$closingbracket);
} elsif ( iscmd($commandword,,\@MATHTEXTCMDLIST, \@MATHTEXTCMDEXCL) ) {
- # MATHBLOCK pseudo command: consider all commands safe, except & and \\, \begin and \end and a few package sprcific one (look at UNSAFEMATHCMD definition)
- # Keep these commands even in deleted blocks, hence set $opencmd and $closecmd (5th and 6th argument of marktags) to
+ # MATHBLOCK pseudo command: consider all commands safe, except & and \\, \begin and \end and a few package sprcific one (look at UNSAFEMATHCMD definition)
+ # Keep these commands even in deleted blocks, hence set $opencmd and $closecmd (5th and 6th argument of marktags) to
# ""
- local @SAFECMDLIST=(".*");
+ local @SAFECMDLIST=(".*");
local @SAFECMDEXCL=('\\','\\\\',@UNSAFEMATHCMD);
push(@$retval,$command,marktags("","",$open,$close,"","",$comment,\@argtext)#@argtext
,$closingbracket);
} else {
# normal textcmd or context1cmd in an added block
- push (@$retval,$command,marktags("","",$open,$close,$opencmd,$closecmd,$comment,\@argtext),$closingbracket);
+ push (@$retval,$command,marktags("","",$open,$close,$opencmd,$closecmd,$comment,\@argtext),$closingbracket);
}
push (@$retval,$AUXCMD,"\n") if $cmdcomment ;
$cmd=-1 ;
@@ -2976,10 +3012,10 @@ sub take_comments_and_newline_from_frac() {
# names or labels but it does not matter because they are converted back in the postprocessing step
# Returns: leading white space removed in step 1
sub preprocess {
- for (@_) {
+ for (@_) {
- # change in \verb and similar commands - note that I introduce an extra space here so that the
+ # change in \verb and similar commands - note that I introduce an extra space here so that the
# already hashed variants do not trigger again
# transform \lstinline{...}
# s/\\lstinline(\[$brat0\])?(\{(?:.*?)\})/"\\DIFlstinline". $1 ."{". tohash(\%verbhash,"$2") ."}"/esg;
@@ -3009,7 +3045,7 @@ sub preprocess {
1 while s/(?<!\\)_(\s*{($pat_n)})/\\SUBSCRIPT$1/g ;
# Convert ^n into \SUPERSCRIPTNB{n} and ^{nnn} into \SUPERSCRIPT{nn}
1 while s/(?<!\\)\^(\s*([^{\\\s]|\\\w+))/\\SUPERSCRIPTNB{$1}/g ;
- 1 while s/(?<!\\)\^(\s*{($pat_n)})/\\SUPERSCRIPT$1/g ;
+ 1 while s/(?<!\\)\^(\s*{($pat_n)})/\\SUPERSCRIPT$1/g ;
# Convert \sqrt{n} into \SQRT{n} and \sqrt nn into SQRTNB{nn}
1 while s/(?<!\\)\\sqrt(\s*([^{\\\s]|\\\w+))/\\SQRTNB{$1}/g ;
1 while s/(?<!\\)\\sqrt(\s*{($pat_n)})/\\SQRT$1/g ;
@@ -3029,16 +3065,16 @@ sub preprocess {
if ( $mathmarkup != FINE ) {
# DIFANCHORARRB and DIFANCHORARRE, DIFANCHORMATHB and DIFANCHORMATHE markers are inserted here to encourage the matching algorithm
# to always match up the closing brace. Otherwise sometimes one ends up with a situation where
- # the closing brace is deleted and added at another point. The deleted closing brace is then
+ # the closing brace is deleted and added at another point. The deleted closing brace is then
# prevented by a %DIFDELCMD, leading to material leaking in or out of the math environment.
# The anchors are removed in post-processing again. (note that they are simple text to cause least amount of complications
- # Admittedly, this is something of a hack and will not always work. If it does not, then one needs to
+ # Admittedly, this is something of a hack and will not always work. If it does not, then one needs to
# resort to WHOLE or FINE, or NONE math mode processing.
s/\\begin\{($ARRENV)}(.*?)\\end\{\1}/\\ARRAYBLOCK$1\{$2\\DIFANCHORARRB \}\\DIFANCHORARRE /sg;
take_comments_and_newline_from_frac();
- # Convert Math environments with arguments
+ # Convert Math environments with arguments
s/\\begin\{($MATHENV|$MATHARRENV|SQUAREBRACKET)\}((?:\[$brat_n\])|(?:\{$pat_n\}))+(.*?)\\end\{\1\}/\\MATHBLOCK$1\[$2\]\{$3\\DIFANCHORMATHB \}\\DIFANCHORMATHE /sg;
# Convert Math environments without arguments
s/\\begin\{($MATHENV|$MATHARRENV|SQUAREBRACKET)\}(.*?)\\end\{\1\}/\\MATHBLOCK$1\{$2\\DIFANCHORMATHB \}\\DIFANCHORMATHE /sg;
@@ -3052,7 +3088,7 @@ sub preprocess {
# $expanded=linecomment($string)
#preface all lines with verbatim marker (usually DIFVRB)
-sub linecomment {
+sub linecomment {
my @verbatimlines=split("\n",$_[0]);
# the first line needs special treatment - we do want to retain optional arguments as is but wrap the remainder also with VERBCOMMENT
### print STDERR "DEBUG: before verbatimlines[0] = ",$verbatimlines[0],"\n";
@@ -3062,7 +3098,7 @@ sub linecomment {
}
# $simple=reverselinecomment($env $string)
-# remove DIFVRB comments but leave changed lines marked
+# remove DIFVRB comments but leave changed lines marked
sub reverselinecomment {
my ($environment, $verbatimtext)=@_;
### print STDERR "DEBUG REVERSELINECOMMENT input: $environment,|$verbatimtext|\n" if $debug;
@@ -3077,7 +3113,7 @@ sub reverselinecomment {
$verbatimtext =~ s/\\DIFdelend //g;
$verbatimtext =~ s/$DELCMDOPEN.*//g;
- # remove DIFVRB mark
+ # remove DIFVRB mark
$verbatimtext=~ s/%$VERBCOMMENT//g;
# remove part of the markup in changed lines
@@ -3168,7 +3204,7 @@ sub writedebugfile {
# * Remove STOP token from the end
# * Replace \RIGHTBRACE by }
# * If option --no-del is set delete all deleted blocks
-# 1. Check all deleted blocks:
+# 1. Check all deleted blocks:
# a.where a deleted block contains a matching \begin and
# \end environment (these will be disabled by a %DIFDELCMD statements), for selected environments enable
# these commands again (such that for example displayed math in a deleted equation
@@ -3189,14 +3225,14 @@ sub writedebugfile {
# For added blocks:
# c. If in-line math mode contains array environment, enclose the whole environment in \mbox'es
# d. place \cite commands in mbox'es (for UNDERLINE style)
-#
+#
# 2. If math-mode COARSE,WHOLE or NONE option set: Convert \MATHBLOCKmath{..} commands back to environments
#
# Convert all PICTUREblock{..} commands back to the appropriate environments
# 3. Convert DIFadd, DIFdel, DIFaddbegin , ... into FL varieties
# within floats (currently recognised float environments: plate,table,figure
# plus starred varieties).
-# 4. Remove empty %DIFDELCMD < lines
+# 4. Remove empty %DIFDELCMD < lines
# 4. Convert \begin{SQUAREBRACKET} \end{SQUAREBRACKET} into \[ \]
# Convert \begin{DOLLARDOLLAR} \end{DOLLARDOLLAR} into $$ $$
# 5. Convert \SUPERSCRIPTNB{n} into ^n and \SUPERSCRIPT{nn} into ^{nnn}
@@ -3209,7 +3245,7 @@ sub writedebugfile {
# 4, undo renaming of the \begin, \end,{,} in comments
# Change \QLEFTBRACE, \QRIGHTBRACE,\AMPERSAND to \{,\},\&
#
-# Note have to manually synchronize substitution commands below and
+# Note have to manually synchronize substitution commands below and
# DIF.. command names in the header
sub postprocess {
my ($begin,$len,$float,$delblock,$addblock); ### $cnt
@@ -3221,7 +3257,7 @@ sub postprocess {
my (@itemargs, $itemarg);
- for (@_) {
+ for (@_) {
# change $'s in comments to something harmless
1 while s/(%.*)\$/$1DOLLARDIF/mg ;
@@ -3231,7 +3267,7 @@ sub postprocess {
# the only way to get these is as %DIFDELCMD < \RIGHTBRACE construction
# This essentially marks closing right braces of MATHBLOCK environments, which did not get matched
# up. This case should be rare, so I just leave this in the diff file output. Not really elegant
- # but can still be dealt with later if it results in problems.
+ # but can still be dealt with later if it results in problems.
s/%DIFDELCMD < \\RIGHTBRACE/%DIFDELCMD < \\MBLOCKRIGHTBRACE/g ;
# Replace \RIGHTBRACE by }
s/\\RIGHTBRACE/}/g;
@@ -3259,7 +3295,7 @@ sub postprocess {
$len=length($&);
$begin=pos($_) - $len;
$delblock=$&;
- ### A much simpler method for math replacement might follow this strategy (can recycle part of the commands below for following
+ ### A much simpler method for math replacement might follow this strategy (can recycle part of the commands below for following
### this strategy:
### 1. a Insert aux commands \begin{MATHMODE} or \end{MATHMODE} for all deleted commands opening or closing displayed math mode
### b Insert aux commands \begin{MATHARRMODE} or \end{MATHARRMODE} for all deleted commands opening or closing math array mode
@@ -3285,14 +3321,14 @@ sub postprocess {
###0.5: $delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \s*\\end\{((?:$MATHENV)|SQUAREBRACKET)\}\s*?(?:$DELCMDCLOSE|\n))(.*?[^\n]?)\n?(?<!${AUXCMD}\n)(\%DIFDELCMD < \s*\\begin\{\2\})/\\end{MATHMODE}$AUXCMD\n$1$3\n\\begin{MATHMODE}$AUXCMD\n$4/sg;
$delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{((?:$MATHENV)|SQUAREBRACKET)\}.*?(?:$DELCMDCLOSE|\n))(.*?[^\n]?)\n?(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{\2\})/\\end\{MATHMODE\}$AUXCMD\n$1$3\n\\begin\{MATHMODE\}$AUXCMD\n$4/sg;
- # now look for unpaired %DIFDELCMD < \begin{MATHENV}; if found add \begin{$MATHREPL} and insert \end{$MATHREPL}
+ # now look for unpaired %DIFDELCMD < \begin{MATHENV}; if found add \begin{$MATHREPL} and insert \end{$MATHREPL}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{((?:$MATHENV)|SQUAREBRACKET)\}\s*?(?:$DELCMDCLOSE|\n))/$1\\begin{$MATHREPL}$AUXCMD\n/sg ) {
### print STDERR "BINGO: begin block: \nBefore: |" . substr($_,$begin,$len) . "|\n" if $debug ;
$delblock =~ s/(\\DIFdelend$)/\\end{$MATHREPL}$AUXCMD\n$1/s ;
### print STDERR "After: |" . $delblock . "|\n\n" if $debug ;
}
- # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
+ # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{((?:$MATHENV)|SQUAREBRACKET)\}\s*?(?:$DELCMDCLOSE|\n))/$1\\end\{MATHMODE\}$AUXCMD\n/sg ) {
### print STDERR "BINGO: end block:\nBefore: |" . substr($_,$begin,$len) . "|\n" if $debug;
@@ -3315,15 +3351,15 @@ sub postprocess {
$delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{($MATHARRENV)\}\s*?(?:$DELCMDCLOSE|\n))(.*?[^\n]?)\n?(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{\2\})/\\end{MATHMODE}$AUXCMD\n$1$3\n\\begin{MATHMODE}$AUXCMD\n$4/sg;
### print STDERR "STEP1: |" . $delblock . "|\n\n" if $debug ;
- # now look for unpaired %DIFDELCMD < \begin{MATHARRENV}; if found add \begin{$MATHARRREPL} and insert \end{$MATHARRREPL}
+ # now look for unpaired %DIFDELCMD < \begin{MATHARRENV}; if found add \begin{$MATHARRREPL} and insert \end{$MATHARRREPL}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\begin\{($MATHARRENV)\}(.*?)(?:$DELCMDCLOSE|\n))/$1\\begin{$2*}$3$AUXCMD\n/sg ) {
$arrenv=$2;
- $delblock =~ s/(\\DIFdelend$)/\\end{$arrenv*}}$AUXCMD\n$1/s ;
+ $delblock =~ s/(\\DIFdelend$)/\\end{$arrenv*}$AUXCMD\n$1/s ;
}
### print STDERR "STEP2: |" . $delblock . "|\n\n" if $debug ;
- # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
+ # now look for unpaired %DIFDELCMD < \end{MATHENV}; if found add \end{MATHMODE} and insert \begin{MATHMODE}
# just before end of block; again we use look-behind assertion to avoid matching constructions which have already been converted
if ($delblock=~ s/(?<!${AUXCMD}\n)(\%DIFDELCMD < \h*\\end\{($MATHARRENV)\}\s*?(?:$DELCMDCLOSE|\n))/$1\\end{MATHMODE}$AUXCMD\n/sg ) {
$delblock =~ s/(\\DIFdelend$)/\\begin{MATHMODE}$AUXCMD\n$1/s ;
@@ -3341,7 +3377,7 @@ sub postprocess {
### $eqarrayblock=~ s/(\%DIFDELCMD < \s*(\&|\\\\)\s*?(?:$DELCMDCLOSE|\n))/$1$2$AUXCMD\n/sg ;
$eqarrayblock =~ s/(\%DIFDELCMD < (.*?(?:\&|\\\\).*)(?:$DELCMDCLOSE|\n))/
# The pattern captures comments with at least one of & or \\
- @symbols= split(m@((?:&|\\\\)\s*)@,$2); # extract & and \\ and other material from sequence
+ @symbols= split(m@((?:&|\\\\)\s*)@,$2); # extract & and \\ and other material from sequence
@symbols= grep ( m@&|\\\\\s*@, @symbols); # select & and \\ (and subsequent spaces)
"$1@symbols$AUXCMD\n"
/eg ;
@@ -3354,7 +3390,7 @@ sub postprocess {
} elsif ( $mathmarkup == COARSE || $mathmarkup == WHOLE ) {
# Convert MATHBLOCKmath commands to their uncounted numbers (e.g. convert equation -> displaymath
# (environments defined in $MATHENV will be replaced by $MATHREPL, and environments in $MATHARRENV
- # will be replaced by their starred variety
+ # will be replaced by their starred variety
$delblock=~ s/\\MATHBLOCK($MATHENV)((?:\[$brat_n\])?)\{($pat_n)\}/\\MATHBLOCK$MATHREPL$2\{$3\}/sg;
$delblock=~ s/\\MATHBLOCK($MATHARRENV)((?:\[$brat_n\])?)\{($pat_n)\}/\\MATHBLOCK$1\*$2\{$3\}/sg;
}
@@ -3368,10 +3404,10 @@ sub postprocess {
print STDERR "DELBLOCK after maths processing: |" . $delblock . "|\n\n" if $debug ;
- # Reinstate completely deleted list environments. note that items within the
+ # Reinstate completely deleted list environments. note that items within the
# environment will still be commented out. They will be restored later
$delblock=~ s/(\%DIFDELCMD < \s*\\begin\{($LISTENV)\}\s*?(?:\n|$DELCMDCLOSE))(.*?)(\%DIFDELCMD < \s*\\end\{\2\})/{
- ### # block within the search; replacement environment
+ ### # block within the search; replacement environment
### "$1\\begin{$2}$AUXCMD\n". restore_item_commands($3). "\n\\end{$2}$AUXCMD\n$4";
"$1\\begin{$2}$AUXCMD\n$3\n\\end{$2}$AUXCMD\n$4";
}/esg;
@@ -3405,7 +3441,7 @@ sub postprocess {
### if ($CITE2CMD) {
###### ${extraspace}(?:\[$brat0\]${extraspace}){0,2}\{$pat_n\})) .*?%%%\n
### $delblock=~s/($DELCMDOPEN\s*\\($CITE2CMD)(.*)$DELCMDCLOSE)/
- ### # Replacement code
+ ### # Replacement code
### {my ($aux,$all);
### $aux=$all=$1;
### $aux=~s#\n?($DELCMDOPEN|$DELCMDCLOSE)##g;
@@ -3415,7 +3451,7 @@ sub postprocess {
### if ($CITECMD) {
###### $delblock=~s/(\\($CITECMD)${extraspace}(?:\[$brat0\]${extraspace}){0,2}\{$pat_n\})(\s*)/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/msg ;
### $delblock=~s/(\\($CITECMD)${extraspace}(?:<$abrat0>${extraspace})?(?:\[$brat0\]${extraspace}){0,2}\{$pat_n\})(\s*)/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/msg ;
- ### }
+ ### }
# if MBOXINLINEMATH is set, protect inlined math environments with an extra mbox
@@ -3423,7 +3459,7 @@ sub postprocess {
# note additional \newline after command is omitted from output if right at the end of deleted block (otherwise a spurious empty line is generated)
$delblock=~s/($math)(?:[\s\n]*)?/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/sg;
}
- ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/)) {
+ ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/)) {
### # change included verbatim environments
### $delblock =~ s/\\DIFverb\{/\\DIFDIFdelverb\{/g;
### $delblock =~ s/\\DIFlstinline/\\DIFDIFdellstinline/g;
@@ -3465,7 +3501,7 @@ sub postprocess {
##$addblock=~s/($math)/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/sg;
$addblock=~s/($math)(?:[\s\n]*)?/\\mbox{$AUXCMD\n$1\n}$AUXCMD\n/sg;
}
- ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat0\])?\{color\}/)) {
+ ###if ( defined($packages{"listings"} and $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat0\])?\{color\}/)) {
# mark added verbatim commands
$addblock =~ s/\\DIFverb/\\DIFDIFaddverb/g;
$addblock =~ s/\\DIFlstinline/\\DIFDIFaddlstinline/g;
@@ -3483,11 +3519,11 @@ sub postprocess {
pos = $begin + length($addblock);
}
- # Go through whole text, and by counting list environment commands, find out when we are within a list environment.
+ # Go through whole text, and by counting list environment commands, find out when we are within a list environment.
# Within those restore deleted \item commands
- @textparts=split /(?<!$DELCMDOPEN)(\\(?:begin|end)\{$LISTENV\})/ ;
+ @textparts=split /(?<!$DELCMDOPEN)(\\(?:begin|end)\{$LISTENV\})/ ;
@liststack=();
- @newtextparts=map {
+ @newtextparts=map {
### print STDERR ":::::::: $_\n";
if ( ($listtype) = m/^\\begin\{($LISTENV)\}$/ ) {
print STDERR "DEBUG: postprocess \\begin{$listtype}\n" if $debug;
@@ -3503,7 +3539,7 @@ sub postprocess {
} else {
print STDERR "DEBUG: postprocess \@liststack=(",join(",",@liststack),")\n" if $debug;
if (scalar @liststack > 0 ) {
- # we are within a list environment and should replace all item commands
+ # we are within a list environment and should replace all item commands
$_=restore_item_commands($_);
}
# else: we are outside a list environment and do not need to do anything
@@ -3516,17 +3552,17 @@ sub postprocess {
# Replace MATHMODE environments from step 1a above by the correct Math environment and remove unncessary pairings
-
+
if ( $mathmarkup == FINE ) {
# look for AUXCMD math-mode pairs which have only comments (or empty lines between them), and remove the added commands
# \begin{..} ... \end{..} pairs
- s/\\begin\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\end\{\1\}$AUXCMD\n/$2/sg;
+ s/\\begin\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\end\{\1\}$AUXCMD\n/$2/sg;
# \end{..} .... \begin{..} pairs
- s/\\end\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\begin\{\1\}$AUXCMD\n/$2/sg;
+ s/\\end\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET|MATHMODE)\}$AUXCMD\n((?:\s*%.[^\n]*\n)*)\\begin\{\1\}$AUXCMD\n/$2/sg;
writedebugfile($_,'postprocess15');
# The next line is complicated. The negative look-ahead insertion makes sure that no \end{$MATHENV} (or other mathematical
- # environments) are between the \begin{$MATHENV} and \end{MATHMODE} commands. This is necessary as the minimal matching
+ # environments) are between the \begin{$MATHENV} and \end{MATHMODE} commands. This is necessary as the minimal matching
# is not globally minimal but only 'locally' (matching is beginning from the left side of the string)
# [NB: Do not be tempted to prettify the expression with /x modified. It seems this is applied after strings are expanded so will ignore spaces in strings
1 while s/(?<!$DELCMDOPEN)\\begin\{((?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET)}((?:${DELCMDOPEN}[^\n]*|.(?!(?:\\end\{(?:(?:$MATHENV)|(?:$MATHARRENV)|SQUAREBRACKET)}|\\begin\{MATHMODE})))*?)\\end\{MATHMODE}/\\begin{$1}$2\\end{$1}/s;
@@ -3601,7 +3637,7 @@ sub postprocess {
# remove empty DIFCMD < lines
s/^\Q${DELCMDOPEN}\E\n//msg;
- # Expand hashes of verb and verbatim environments
+ # Expand hashes of verb and verbatim environments
s/${DELCMDOPEN}\\($VERBATIMENV)\{([-\d]*?)\}/"${DELCMDOPEN}\\begin{${1}}".fromhash(\%verbhash,$2,$DELCMDOPEN)."${DELCMDOPEN}\\end{${1}}"/esg;
# revert changes to verbatim environments for line diffs (and add code to mark up changes) (note negative look behind assertions to not leak out of DIFDELCMD comments)
# Example:
@@ -3627,8 +3663,8 @@ sub postprocess {
((?:\%\Q$DELCOMMENT$VERBCOMMENT\E[^\n]*?\n)*)
# Deleted \end command of verbatim environment. Note that the type is forced to match the opening. Captures: $5: Whole deleted environment (previous way this line was written: (\Q$DELCMDOPEN\E\\end\{\2\}(?:\n|\s|\Q$DELCMDOPEN\E)*\Q$DELCMDCLOSE\E)
(\Q$DELCMDOPEN\E\\end\{\2\})
- / # Substitution part
- $1 # Leave expression as is
+ / # Substitution part
+ $1 # Leave expression as is
. "$AUXCMD NEXT\n" # Mark the following line as an auxiliary command
. "" # reinstate the original environment without options
. reverselinecomment($2, "$3$4") # modify the body to change the markup; reverselinecomment parses for options
@@ -3637,7 +3673,7 @@ sub postprocess {
/esgx; # Modifiers of substitution command
writedebugfile($_,'postprocess2');
# where changes have occurred in verbatim environment, change verbatim to DIFverbatim to allow mark-up
- # (I use the presence of optional paramater to verbatim environment as the marker - normal verbatim
+ # (I use the presence of optional paramater to verbatim environment as the marker - normal verbatim
# environment does not take optional arguments)
s/(?<!$DELCMDOPEN)\\begin\{(verbatim[*]?)\}(\[$brat_n\].*?)\\end\{\1\}/\\begin{DIF$1}$2\\end{DIF$1}/sg;
@@ -3651,7 +3687,7 @@ sub postprocess {
# convert remaining PAR commands (which are preceded by non-white space characters, usually "}" ($ADDCLOSE)
s/\\PAR\n/\n\n/sg;
- # package specific processing:
+ # package specific processing:
if ( defined($packages{"endfloat"})) {
#endfloat: make sure \begin{figure} and \end{figure} are always
# on a line by themselves, similarly for table environment
@@ -3664,12 +3700,16 @@ sub postprocess {
s/^((?:[^%]+)\\(?:begin|end)\{(?:figure|table)\}(?:\[[a-zA-Z]+\])?)(.+)((?:%.*)?)$/$1\n$2$3/mg;
}
- # Convert '\PERCENTAGE ' back into '\%' (the final question mark catches a special situation where due to a latter pre-processing step the ' ' becomes separated
+ # Remove empty auxiliary LISTENV (sometmes these are generated if list environment occurs within the argument of a deleted comment)
+ # (slightly hacky but I could not see an easy way to see if in argument of another command when this extra markup is added)
+ s/\\begin\{($LISTENV)\}$AUXCMD\n((?:\s*\%[^\n]*\n)*\n?)\\end\{\1\}$AUXCMD\n/$2\n/msg ;
+
+ # Convert '\PERCENTAGE ' back into '\%' (the final question mark catches a special situation where due to a latter pre-processing step the ' ' becomes separated
s/\\PERCENTAGE ?/\\%/g;
- # Convert '\DOLLAR ' back into '\$'
+ # Convert '\DOLLAR ' back into '\$'
s/\\DOLLAR /\\\$/g;
- # undo renaming of the \begin and \end,{,} and dollars in comments
+ # undo renaming of the \begin and \end,{,} and dollars in comments
# although we only renamed $ in comments to DOLLARDIFF, we might have lost the % in unchanged verbatim blocks, so rename all
s/DOLLARDIF/\$/g;
@@ -3687,7 +3727,7 @@ sub postprocess {
# Convert \SQRT{n} into \sqrt{n} and \SQRTNB{nn} into \sqrt nn
1 while s/\\SQRT(\s*\{($pat_n)\})/\\sqrt$1/g ;
1 while s/\\SQRTNB\{(\s*$pat0)\}/\\sqrt$1/g ;
-
+
1 while s/(%.*)\\CFRAC (.*)$/$1\\frac$2/mg ;
1 while s/(%.*)\\CRIGHTBRACE (.*)$/$1\}$2/mg ;
1 while s/(%.*)\\CLEFTBRACE (.*)$/$1\{$2/mg ;
@@ -3698,7 +3738,7 @@ sub postprocess {
s/\\QRIGHTBRACE /\\\}/sg;
s/\\AMPERSAND /\\&/sg;
# Highlight added inline verbatim commands if possible
- if ( $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/ ) {
+ if ( $latexdiffpreamble =~ /\\RequirePackage(?:\[$brat_n\])?\{color\}/ ) {
# wrap added verb commands with color commands
s/\\DIFDIFadd((?:verb\*?|lstinline(?:\[$brat_n\])?)\{[-\d]*?\}[\s\n]*)/\{\\color{blue}$AUXCMD\n\\DIF$1%\n\}$AUXCMD\n/sg;
s/\\DIFDIFdel((?:verb\*?|lstinline(?:\[$brat_n\])?)\{[-\d]*?\}[\s\n]*$AUXCMD)/\{\\color{red}${AUXCMD}\n\\DIF$1\n\}${AUXCMD}/sg;
@@ -3713,8 +3753,8 @@ sub postprocess {
# finally add the comment to the ones not having an optional argument before
###s/\\DIFaddlstinline(?!\[)/\\lstinline\n[basicstyle=\\color{blue}]$AUXCMD\n/g;
- return;
}
+ return;
}
# $out = restore_item_commands($listenviron)
@@ -3738,13 +3778,13 @@ sub restore_item_commands {
# @auxlines=preprocess_preamble($oldpreamble,$newpreamble);
- # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
- # the list of commands is defined in CONTEXT2CMD
- # if found then use a bodydiff to mark up content, and replace the corresponding commands
+ # pre-process preamble by looking for commands used in \maketitle (title, author, date etc commands)
+ # the list of commands is defined in CONTEXT2CMD
+ # if found then use a bodydiff to mark up content, and replace the corresponding commands
# in both preambles by marked up version to 'fool' the linediff (such that only body is marked up).
# A special case are e.g. author commands being added (or removed)
# 1. If commands are added, then the entire content is marked up as new, but also the lines are marked as new in the linediff
- # 2. If commands are removed, then the linediff will mark the line as deleted. The program returns
+ # 2. If commands are removed, then the linediff will mark the line as deleted. The program returns
# with $auxlines a text to be appended at the end of the preamble, which shows the respective fields as deleted
sub preprocess_preamble {
my ($oldpreambleref,$newpreambleref)=(\$_[0],\$_[1]) ;
@@ -3766,7 +3806,7 @@ EOF
$titlecmd = "(?:".join("|",@CONTEXT2CMDLIST).")";
# as context2cmdlist is stored as regex, e.g. ((?-xism:^title$), we need to remove ^- fo
# resue in a more complex regex
- $titlecmd =~ s/[\$\^]//g;
+ $titlecmd =~ s/[\$\^]//g;
# make sure to not match on comment lines:
$titlecmdpat=qr/^(?:[^%\n]|\\%)*(\\($titlecmd)$extraspace(?:\[($brat_n)\])?(?:\{($pat_n)\}))/ms;
###print STDERR "DEBUG:",$titlecmdpat,"\n";
@@ -3792,7 +3832,7 @@ EOF
$cmd=shift @newtitlecommands;
$optarg=shift @newtitlecommands;
$arg=shift @newtitlecommands;
-
+
if ( defined($newhash{$cmd})) {
warn "$cmd is used twice in preamble of new file. Reverting to pure line diff mode for preamble.\n";
print STDERR $warnmsgdetail;
@@ -3819,7 +3859,7 @@ EOF
}
$argnew=$newhash{$cmd}->[2];
$argdiff="{" . join("",bodydiff($argold,$argnew)) ."}";
- # Replace \RIGHTBRACE by }
+ # Replace \RIGHTBRACE by }
$argdiff =~ s/\\RIGHTBRACE/}/g;
if ( length $optargnew ) {
@@ -3834,7 +3874,7 @@ EOF
$optargdiff="";
}
### print STDERR "DEBUG s/\\Q$newhash{$cmd}->[0]\\E/\\$cmd$optargdiff$argdiff/s\n";
- # Note: \Q and \E force literal interpretation of what it between them but allow
+ # Note: \Q and \E force literal interpretation of what it between them but allow
# variable interpolation, such that e.g. \title matches just that and not TAB-itle
$$newpreambleref=~s/\Q$newhash{$cmd}->[0]\E/\\$cmd$optargdiff$argdiff/s;
# replace this in old preamble if necessary
@@ -3874,7 +3914,7 @@ EOF
#%< old deleted line(s)
#%DIF -------
#%DIF mmann-nn
-#new appended line %<
+#new appended line %<
#%DIF -------
# Future extension: mark change explicitly
# Assumes: traverse_sequence traverses deletions before insertions in changed sequences
@@ -3886,9 +3926,9 @@ sub linediff {
my $block = [];
my $retseq = [];
my @begin=('','',''); # dummy initialisation
- my $instring ;
+ my $instring ;
- my $discard = sub { @begin=('d',$_[0],$_[1]) unless scalar @$block ;
+ my $discard = sub { @begin=('d',$_[0],$_[1]) unless scalar @$block ;
push(@$block, "%DIF < " . $seq1->[$_[0]]) };
my $add = sub { if (! scalar @$block) {
@begin=('a',$_[0],$_[1]) ;}
@@ -3903,12 +3943,12 @@ sub linediff {
$instring = sprintf "%%DIF %da%d-%d",$begin[1],$begin[2],$_[1]-1; }
elsif ( $begin[0] eq 'c' ) {
$instring = sprintf "%%DIF %sc%s",
- ($begin[1]==$_[0]-1) ? "$begin[1]" : $begin[1]."-".($_[0]-1) ,
+ ($begin[1]==$_[0]-1) ? "$begin[1]" : $begin[1]."-".($_[0]-1) ,
($begin[2]==$_[1]-1) ? "$begin[2]" : $begin[2]."-".($_[1]-1) ; }
else {
$instring = sprintf "%%DIF %d%s%d",$begin[1],$begin[0],$begin[2]; }
- push @$retseq, $instring,@$block, "%DIF -------" ;
- $block = [];
+ push @$retseq, $instring,@$block, "%DIF -------" ;
+ $block = [];
}
push @$retseq, $seq2->[$_[1]]
};
@@ -3916,7 +3956,7 @@ sub linediff {
my $keyfunc = sub { join(" ",split(" ",shift())) };
traverse_sequences($seq1,$seq2, { MATCH=>$match, DISCARD_A=>$discard, DISCARD_B=>$add }, $keyfunc );
- push @$retseq, @$block if scalar @$block;
+ push @$retseq, @$block if scalar @$block;
return wantarray ? @$retseq : $retseq ;
}
@@ -3926,23 +3966,23 @@ sub linediff {
# init_regex_arr_data(\@array,"TOKEN INIT")
# scans DATA file handel for line "%% TOKEN INIT" line
# then appends each line not beginning with % into array (as a quoted regex)
-# This is used for command lists and configuration variables, but the processing is slightly
-# different:
+# This is used for command lists and configuration variables, but the processing is slightly
+# different:
# For lists, the regular expression is extended to include beginning (^) and end ($) markers, to require full-string matching
# For configuration variables (and all others), simply an unadorned list is copied
sub init_regex_arr_data {
my ($arr,$token)=@_;
my $copy=0;
my ($mode);
- if ($token =~ m/COMMANDS/ ) {
- $mode=0; # Reading command list
+ if ($token =~ m/COMMANDS/ ) {
+ $mode=0; # Reading command list
} else {
$mode=1; # Reading configuration variables
}
while (<DATA>) {
if ( m/^%%BEGIN $token\s*$/ ) {
- $copy=1;
+ $copy=1;
next;
} elsif ( m/^%%END $token\s*$/ ) {
last; }
@@ -4023,17 +4063,18 @@ sub exetime {
sub usage {
- print STDERR <<"EOF";
+ print STDERR <<"EOF";
Usage: $0 [options] old.tex new.tex > diff.tex
-Compares two latex files and writes tex code to stdout, which has the same format as new.tex but
+Compares two latex files and writes tex code to stdout, which has the same format as new.tex but
has all changes relative to old.tex marked up or commented. Note that old.tex and new.tex need to
-be real files (not pipes or similar) as they are opened twice.
+be real files (not pipes or similar) as they are opened twice.
--type=markupstyle
-t markupstyle Add code to preamble for selected markup style
- Available styles: UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
+ Available styles: UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT
+ LUAUNDERLINE
[ Default: UNDERLINE ]
--subtype=markstyle
@@ -4044,7 +4085,7 @@ be real files (not pipes or similar) as they are opened twice.
* LABEL subtype is deprecated
--floattype=markstyle
--f markstyle Add code to preamble for selected style which
+-f markstyle Add code to preamble for selected style which
replace standard marking and markup commands within floats
(e.g., marginal remarks cause an error within floats
so marginal marking can be disabled thus)
@@ -4053,11 +4094,11 @@ be real files (not pipes or similar) as they are opened twice.
--encoding=enc
-e enc Specify encoding of old.tex and new.tex. Typical encodings are
- ascii, utf8, latin1, latin9. A list of available encodings can be
- obtained by executing
+ ascii, utf8, latin1, latin9. A list of available encodings can be
+ obtained by executing
perl -MEncode -e 'print join ("\\n",Encode->encodings( ":all" )) ;'
[Default encoding is utf8 unless the first few lines of the preamble contain
- an invocation "\\usepackage[..]{inputenc} in which case the
+ an invocation "\\usepackage[..]{inputenc} in which case the
encoding chosen by this command is asssumed. Note that ASCII (standard
latex) is a subset of utf8]
@@ -4074,22 +4115,22 @@ be real files (not pipes or similar) as they are opened twice.
--exclude-safecmd=exclude-file
--exclude-safecmd="cmd1,cmd2,..."
--A exclude-file
+-A exclude-file
--replace-safecmd=replace-file
--append-safecmd=append-file
--append-safecmd="cmd1,cmd2,..."
-a append-file Exclude from, replace or append to the list of regex
- matching commands which are safe to use within the
+ matching commands which are safe to use within the
scope of a \\DIFadd or \\DIFdel command. The file must contain
one Perl-RegEx per line (Comment lines beginning with # or % are
ignored). A literal comma within the comma-separated list must be
- escaped thus "\\,", Note that the RegEx needs to match the whole of
+ escaped thus "\\,", Note that the RegEx needs to match the whole of
the token, i.e., /^regex\$/ is implied and that the initial
"\\" of the command is not included. The --exclude-safecmd
- and --append-safecmd options can be combined with the --replace-safecmd
+ and --append-safecmd options can be combined with the --replace-safecmd
option and can be used repeatedly to add cumulatively to the lists.
---exclude-textcmd=exclude-file
+--exclude-textcmd=exclude-file
--exclude-textcmd="cmd1,cmd2,..."
-X exclude-file
--replace-textcmd=replace-file
@@ -4105,7 +4146,7 @@ be real files (not pipes or similar) as they are opened twice.
Replace or append to the list of regex matching commands
whose last argument is text but which require a particular
context to work, e.g. \\caption will only work within a figure
- or table. These commands behave like text commands, except when
+ or table. These commands behave like text commands, except when
they occur in a deleted section, when they are disabled, but their
argument is shown as deleted text.
@@ -4115,7 +4156,7 @@ be real files (not pipes or similar) as they are opened twice.
As corresponding commands for context1. The only difference is that
context2 commands are completely disabled in deleted sections, including
their arguments.
- context2 commands are also the only commands in the preamble, whose argument will
+ context2 commands are also the only commands in the preamble, whose argument will
be processed in word-by-word mode (which only works, if they occur no more than
once in the preamble).
@@ -4124,15 +4165,15 @@ be real files (not pipes or similar) as they are opened twice.
--append-mboxsafecmd=append-file
--append-mboxsafecmd="cmd1,cmd2,..."
Define safe commands, which additionally need to be protected by encapsulating
- in an \\mbox{..}. This is sometimes needed to get around incompatibilities
+ in an \\mbox{..}. This is sometimes needed to get around incompatibilities
between external packages and the ulem package, which is used for highlighting
in the default style UNDERLINE as well as CULINECHBAR CFONTSTRIKE
-
+
--config var1=val1,var2=val2,...
-c var1=val1,.. Set configuration variables.
--c configfile Available variables:
+-c configfile Available variables:
ARRENV (RegEx)
COUNTERCMD (RegEx)
FLOATENV (RegEx)
@@ -4151,15 +4192,15 @@ be real files (not pipes or similar) as they are opened twice.
--add-to-config varenv1=pattern1,varenv2=pattern2
For configuration variables containing a regular expression (essentially those ending
- in ENV, and COUNTERCMD) this provides an alternative way to modify the configuration
+ in ENV, and COUNTERCMD) this provides an alternative way to modify the configuration
variables. Instead of setting the complete pattern, with this option it is possible to add an
alternative pattern. varenv must be one of the variables listed above that take a regular
- expression as argument, and pattern is any regular expression (which might need to be
+ expression as argument, and pattern is any regular expression (which might need to be
protected from the shell by quotation). Several patterns can be added at once by using semi-colons
to separate them, e.g. --add-to-config "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote"
--packages=pkg1,pkg2,..
- Tell latexdiff that .tex file is processed with the packages in list
+ Tell latexdiff that .tex file is processed with the packages in list
loaded. This is normally not necessary if the .tex file includes the
preamble, as the preamble is automatically scanned for \\usepackage commands.
Use of the --packages option disables automatic scanning, so if for any
@@ -4180,57 +4221,57 @@ be real files (not pipes or similar) as they are opened twice.
--show-all Show all of the above
- NB For all --show commands, no old.tex or new.tex file needs to be given, and no
+ NB For all --show commands, no old.tex or new.tex file needs to be given, and no
differencing takes place.
Other configuration options:
--allow-spaces Allow spaces between bracketed or braced arguments to commands
- [Default requires arguments to directly follow each other without
+ [Default requires arguments to directly follow each other without
intervening spaces]
--math-markup=level Determine granularity of markup in displayed math environments:
Possible values for level are (both numerical and text labels are acceptable):
- off or 0: suppress markup for math environments. Deleted equations will not
- appear in diff file. This mode can be used if all the other modes
+ off or 0: suppress markup for math environments. Deleted equations will not
+ appear in diff file. This mode can be used if all the other modes
cause invalid latex code.
whole or 1: Differencing on the level of whole equations. Even trivial changes
- to equations cause the whole equation to be marked changed. This
- mode can be used if processing in coarse or fine mode results in
+ to equations cause the whole equation to be marked changed. This
+ mode can be used if processing in coarse or fine mode results in
invalid latex code.
coarse or 2: Detect changes within equations marked up with a coarse
- granularity; changes in equation type (e.g.displaymath to equation)
+ granularity; changes in equation type (e.g.displaymath to equation)
appear as a change to the complete equation. This mode is recommended
for situations where the content and order of some equations are still
being changed. [Default]
fine or 3: Detect small change in equations and mark up and fine granularity.
This mode is most suitable, if only minor changes to equations are
- expected, e.g. correction of typos.
+ expected, e.g. correction of typos.
--graphics-markup=level Change highlight style for graphics embedded with \\includegraphics commands
Possible values for level:
none,off or 0: no highlighting for figures
new-only or 1: surround newly added or changed figures with a blue frame [Default]
- both or 2: highlight new figures with a blue frame and show deleted figures
+ both or 2: highlight new figures with a blue frame and show deleted figures
at reduced scale, and crossed out with a red diagonal cross. Use configuration
variable SCALEDELGRAPHICS to set size of deleted figures.
- Note that changes to the optional parameters will make the figure appear as changed
+ Note that changes to the optional parameters will make the figure appear as changed
to latexdiff, and this figure will thus be highlighted.
In some circumstances "Misplaced \\noalign" errors can occur if there are certain types
- of changes in tables. In this case please use option --graphics-markup=none as a
- work-around.
+ of changes in tables. In this case please use option --graphics-markup=none as a
+ work-around.
---no-del Suppress deleted text from the diff. It is similar in effect to the BOLD style,
+--no-del Suppress deleted text from the diff. It is similar in effect to the BOLD style,
but the deleted text ist not just invisible in the output, it is also not included in the
- diff text file. This can be more robust than just making it invisible.
+ diff text file. This can be more robust than just making it invisible.
---disable-citation-markup
---disable-auto-mbox Suppress citation markup and markup of other vulnerable commands in styles
+--disable-citation-markup
+--disable-auto-mbox Suppress citation markup and markup of other vulnerable commands in styles
using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR)
(the two options are identical and are simply aliases)
--enable-citation-markup
---enforce-auto-mbox Protect citation commands and other vulnerable commands in changed sections
+--enforce-auto-mbox Protect citation commands and other vulnerable commands in changed sections
with \\mbox command, i.e. use default behaviour for ulem package for other packages
(the two options are identical and are simply aliases)
@@ -4246,14 +4287,14 @@ Miscellaneous options
--no-label Suppress inclusion of old and new file names as comment in output file
---visible-label Include old and new filenames (or labels set with --label option) as
+--visible-label Include old and new filenames (or labels set with --label option) as
visible output
--flatten Replace \\input and \\include commands within body by the content
of the files in their argument. If \\includeonly is present in the
- preamble, only those files are expanded into the document. However,
- no recursion is done, i.e. \\input and \\include commands within
- included sections are not expanded. The included files are assumed to
+ preamble, only those files are expanded into the document. However,
+ no recursion is done, i.e. \\input and \\include commands within
+ included sections are not expanded. The included files are assumed to
be located in the same directories as the old and new master files,
respectively, making it possible to organise files into old and new directories.
--flatten is applied recursively, so inputted files can contain further
@@ -4276,7 +4317,7 @@ Miscellaneous options
-h Show this help text.
--ignore-warnings Suppress warnings about inconsistencies in length between input
- and parsed strings and missing characters.
+ and parsed strings and missing characters.
--verbose
-V Output various status information to stderr during processing.
@@ -4288,10 +4329,10 @@ Internal options:
These options are mostly for automated use by latexdiff-vc. They can be used directly, but
the API should be considered less stable than for the other options.
---no-links Suppress generation of hyperreferences, used for minimal diffs
+--no-links Suppress generation of hyperreferences, used for minimal diffs
(option --only-changes of latexdiff-vc).
EOF
- exit 0;
+ exit 0;
}
=head1 NAME
@@ -4317,8 +4358,8 @@ be real files (not pipes or similar) as they are opened twice (unless C<--encodi
The program treats the preamble differently from the main document.
Differences between the preambles are found using line-based
differencing (similarly to the Unix diff command, but ignoring white
-spaces). A comment, "S<C<%DIF E<gt>>>" is appended to each added line, i.e. a
-line present in C<new.tex> but not in C<old.tex>. Discarded lines
+spaces). A comment, "S<C<%DIF E<gt>>>" is appended to each added line, i.e. a
+line present in C<new.tex> but not in C<old.tex>. Discarded lines
are deactivated by prepending "S<C<%DIF E<lt>>>". Changed blocks are preceded by
comment lines giving information about line numbers in the original files. Where there are insignificant
differences, the resulting file C<diff.tex> will be similar to
@@ -4371,7 +4412,7 @@ curly braces immediately following a command (i.e. a sequence of
letters beginning with a backslash) are arguments for that command.
As a restriction to condition 1 above it is thus necessary to surround
all arguments with curly braces, and to not insert
-extraneous spaces. For example, write
+extraneous spaces. For example, write
\section{\textem{This is an emphasized section title}}
@@ -4403,7 +4444,7 @@ but the choice is yours. Any markup within the environment will be
removed, and generally everything within the environment will just be
taken from the new file.
-It is also possible to difference files which do not have a preamble.
+It is also possible to difference files which do not have a preamble.
In this case, the file is processed in the main document
mode, but the definitions of the markup commands are not inserted.
@@ -4421,7 +4462,7 @@ the scope of C<\DIFadd>. Added comments are marked by prepending
Within deleted blocks text is highlighted with C<\DIFdel>. Deleted
comments are marked by prepending "S<C<%DIF E<lt> >>". Non-safe command
-and curly braces within deleted blocks are commented out with
+and curly braces within deleted blocks are commented out with
"S<C<%DIFDELCMD E<lt> >>".
@@ -4431,7 +4472,7 @@ and curly braces within deleted blocks are commented out with
=head2 Preamble
The following options determine the visual markup style by adding the appropriate
-command definitions to the preamble. See the end of this section for a description of
+command definitions to the preamble. See the end of this section for a description of
available styles.
=over 4
@@ -4441,15 +4482,16 @@ B<-t markupstyle>
Add code to preamble for selected markup style. This option defines
C<\DIFadd> and C<\DIFdel> commands.
-Available styles:
+Available styles:
-C<UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
-CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT>
+C<UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
+CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT
+LUAUNDERLINE>
[ Default: C<UNDERLINE> ]
=item B<--subtype=markstyle> or
-B<-s markstyle>
+B<-s markstyle>
Add code to preamble for selected style for bracketing
commands (e.g. to mark changes in margin). This option defines
@@ -4462,27 +4504,27 @@ Available styles: C<SAFE MARGIN COLOR DVIPSCOL ZLABEL ONLYCHANGEDPAGE (LABEL)*>
=item B<--floattype=markstyle> or
B<-f markstyle>
-Add code to preamble for selected style which
+Add code to preamble for selected style which
replace standard marking and markup commands within floats
(e.g., marginal remarks cause an error within floats
-so marginal marking can be disabled thus). This option defines all
+so marginal marking can be disabled thus). This option defines all
C<\DIF...FL> commands.
Available styles: C<FLOATSAFE TRADITIONALSAFE IDENTICAL>
[ Default: C<FLOATSAFE> ]
-=item B<--encoding=enc> or
+=item B<--encoding=enc> or
B<-e enc>
Specify encoding of old.tex and new.tex. Typical encodings are
-C<ascii>, C<utf8>, C<latin1>, C<latin9>. A list of available encodings can be
-obtained by executing
+C<ascii>, C<utf8>, C<latin1>, C<latin9>. A list of available encodings can be
+obtained by executing
C<perl -MEncode -e 'print join ("\n",Encode->encodings( ":all" )) ;' >
If this option is used, then old.tex, new.tex are only opened once.
[Default encoding is utf8 unless the first few lines of the preamble contain
-an invocation C<\usepackage[..]{inputenc}> in which case the
+an invocation C<\usepackage[..]{inputenc}> in which case the
encoding chosen by this command is asssumed. Note that ASCII (standard
latex) is a subset of utf8]
@@ -4499,7 +4541,7 @@ C<\DIFaddbeginFL, \DIFaddendFL, \DIFaddFL{..},
(If this option is set B<-t>, B<-s>, and B<-f> options
are ignored.)
-=item B<--packages=pkg1,pkg2,..>
+=item B<--packages=pkg1,pkg2,..>
Tell latexdiff that .tex file is processed with the packages in list
loaded. This is normally not necessary if the .tex file includes the
@@ -4510,13 +4552,13 @@ The following packages trigger special behaviour:
=over 8
-=item C<endfloat>
+=item C<endfloat>
Ensure that C<\begin{figure}> and C<\end{figure}> always appear by themselves on a line.
=item C<hyperref>
-Change name of C<\DIFadd> and C<\DIFdel> commands to C<\DIFaddtex> and C<\DIFdeltex> and
+Change name of C<\DIFadd> and C<\DIFdel> commands to C<\DIFaddtex> and C<\DIFdeltex> and
define new C<\DIFadd> and C<\DIFdel> commands, which provide a wrapper for these commands,
using them for the text but not for the link defining command (where any markup would cause
errors).
@@ -4568,17 +4610,17 @@ B<-A exclude-file> or B<--exclude-safecmd="cmd1,cmd2,...">
=item B<--replace-safecmd=replace-file>
-=item B<--append-safecmd=append-file> or
+=item B<--append-safecmd=append-file> or
B<-a append-file> or B<--append-safecmd="cmd1,cmd2,...">
Exclude from, replace or append to the list of regular expressions (RegEx)
-matching commands which are safe to use within the
+matching commands which are safe to use within the
scope of a C<\DIFadd> or C<\DIFdel> command. The file must contain
one Perl-RegEx per line (Comment lines beginning with # or % are
-ignored). Note that the RegEx needs to match the whole of
+ignored). Note that the RegEx needs to match the whole of
the token, i.e., /^regex$/ is implied and that the initial
-"\" of the command is not included.
-The B<--exclude-safecmd> and B<--append-safecmd> options can be combined with the -B<--replace-safecmd>
+"\" of the command is not included.
+The B<--exclude-safecmd> and B<--append-safecmd> options can be combined with the -B<--replace-safecmd>
option and can be used repeatedly to add cumulatively to the lists.
B<--exclude-safecmd>
and B<--append-safecmd> can also take a comma separated list as input. If a
@@ -4591,7 +4633,7 @@ B<-X exclude-file> or B<--exclude-textcmd="cmd1,cmd2,...">
=item B<--replace-textcmd=replace-file>
-=item B<--append-textcmd=append-file> or
+=item B<--append-textcmd=append-file> or
B<-x append-file> or B<--append-textcmd="cmd1,cmd2,...">
Exclude from, replace or append to the list of regular expressions
@@ -4599,7 +4641,7 @@ matching commands whose last argument is text. See
entry for B<--exclude-safecmd> directly above for further details.
-=item B<--replace-context1cmd=replace-file>
+=item B<--replace-context1cmd=replace-file>
=item B<--append-context1cmd=append-file> or
@@ -4608,11 +4650,11 @@ entry for B<--exclude-safecmd> directly above for further details.
Replace or append to the list of regex matching commands
whose last argument is text but which require a particular
context to work, e.g. C<\caption> will only work within a figure
-or table. These commands behave like text commands, except when
+or table. These commands behave like text commands, except when
they occur in a deleted section, when they are disabled, but their
argument is shown as deleted text.
-=item B<--replace-context2cmd=replace-file>
+=item B<--replace-context2cmd=replace-file>
=item B<--append-context2cmd=append-file> or
@@ -4622,9 +4664,9 @@ As corresponding commands for context1. The only difference is that
context2 commands are completely disabled in deleted sections, including
their arguments.
-context2 commands are also the only commands in the preamble, whose argument will be processed in
+context2 commands are also the only commands in the preamble, whose argument will be processed in
word-by-word mode (which only works, if they occur no more than once in the preamble). The algorithm currently cannot cope with repeated context2 commands in the preamble, as they occur e.g. for the C<\author> argument in some journal styles (not in the standard styles, though
-If such a repetition is detected, the whole preamble will be processed in line-by-line mode. In such a case, use C<--replace-context2cmd> option to just select the commands, which should be processed and are not used repeatedly in the preamble.
+If such a repetition is detected, the whole preamble will be processed in line-by-line mode. In such a case, use C<--replace-context2cmd> option to just select the commands, which should be processed and are not used repeatedly in the preamble.
@@ -4633,7 +4675,7 @@ If such a repetition is detected, the whole preamble will be processed in line-b
=item B<--append-mboxsafecmd=append-file> or B<--append-mboxsafecmd="cmd1,cmd2,...">
Define safe commands, which additionally need to be protected by encapsulating
-in an C<\mbox{..}>. This is sometimes needed to get around incompatibilities
+in an C<\mbox{..}>. This is sometimes needed to get around incompatibilities
between external packages and the ulem package, which is used for highlighting
in the default style UNDERLINE as well as CULINECHBAR CFONTSTRIKE
@@ -4647,7 +4689,7 @@ in the default style UNDERLINE as well as CULINECHBAR CFONTSTRIKE
Set configuration variables. The option can be repeated to set different
variables (as an alternative to the comma-separated list).
-Available variables (see below for further explanations):
+Available variables (see below for further explanations):
C<ARRENV> (RegEx)
@@ -4677,10 +4719,10 @@ C<SCALEDELGRAPHICS> (Float)
=item B<--add-to-config varenv1=pattern1,varenv2=pattern2,...>
For configuration variables, which are a regular expression (essentially those ending
-in ENV, COUNTERCMD and CUSTOMDIFCMD, see list above) this option provides an alternative way to modify the configuration
+in ENV, COUNTERCMD and CUSTOMDIFCMD, see list above) this option provides an alternative way to modify the configuration
variables. Instead of setting the complete pattern, with this option it is possible to add an
alternative pattern. C<varenv> must be one of the variables listed above that take a regular
-expression as argument, and pattern is any regular expression (which might need to be
+expression as argument, and pattern is any regular expression (which might need to be
protected from the shell by quotation). Several patterns can be added at once by using semi-colons
to separate them, e.g. C<--add-to-config "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote">
@@ -4700,7 +4742,7 @@ Show values of configuration variables.
Combine all --show commands.
-NB For all --show commands, no C<old.tex> or C<new.tex> file needs to be specified, and no
+NB For all --show commands, no C<old.tex> or C<new.tex> file needs to be specified, and no
differencing takes place.
=back
@@ -4717,29 +4759,29 @@ might get lumpeded with preceding commands) so should only be used if the
default produces erroneous results. (Default requires arguments to
directly follow each other without intervening spaces).
-=item B<--math-markup=level>
+=item B<--math-markup=level>
-Determine granularity of markup in displayed math environments:
+Determine granularity of markup in displayed math environments:
Possible values for level are (both numerical and text labels are acceptable):
-C<off> or C<0>: suppress markup for math environments. Deleted equations will not
-appear in diff file. This mode can be used if all the other modes
+C<off> or C<0>: suppress markup for math environments. Deleted equations will not
+appear in diff file. This mode can be used if all the other modes
cause invalid latex code.
C<whole> or C<1>: Differencing on the level of whole equations. Even trivial changes
-to equations cause the whole equation to be marked changed. This
-mode can be used if processing in coarse or fine mode results in
+to equations cause the whole equation to be marked changed. This
+mode can be used if processing in coarse or fine mode results in
invalid latex code.
C<coarse> or C<2>: Detect changes within equations marked up with a coarse
-granularity; changes in equation type (e.g.displaymath to equation)
+granularity; changes in equation type (e.g.displaymath to equation)
appear as a change to the complete equation. This mode is recommended
for situations where the content and order of some equations are still
being changed. [Default]
C<fine> or C<3>: Detect small change in equations and mark up at fine granularity.
This mode is most suitable, if only minor changes to equations are
-expected, e.g. correction of typos.
+expected, e.g. correction of typos.
=item B<--graphics-markup=level>
@@ -4751,33 +4793,33 @@ C<none>, C<off> or C<0>: no highlighting for figures
C<new-only> or C<1>: surround newly added or changed figures with a blue frame [Default if graphicx package loaded]
-C<both> or C<2>: highlight new figures with a blue frame and show deleted figures at reduced
+C<both> or C<2>: highlight new figures with a blue frame and show deleted figures at reduced
scale, and crossed out with a red diagonal cross. Use configuration
variable SCALEDELGRAPHICS to set size of deleted figures.
-Note that changes to the optional parameters will make the figure appear as changed
+Note that changes to the optional parameters will make the figure appear as changed
to latexdiff, and this figure will thus be highlighted.
In some circumstances "Misplaced \noalign" error can occur if there are certain types
-of changes in tables. In this case please use C<--graphics-markup=none> as a
-work-around.
+of changes in tables. In this case please use C<--graphics-markup=none> as a
+work-around.
-=item B<--no-del>
+=item B<--no-del>
-Suppress deleted text from the diff. It is similar in effect to the BOLD style,
-but the deleted text ist not just invisible in the output, it is also not included in the diff text file.
-This can be more robust than just making it invisible.
+Suppress deleted text from the diff. It is similar in effect to the BOLD style,
+but the deleted text ist not just invisible in the output, it is also not included in the diff text file.
+This can be more robust than just making it invisible.
=item B<--disable-citation-markup> or B<--disable-auto-mbox>
-Suppress citation markup and markup of other vulnerable commands in styles
+Suppress citation markup and markup of other vulnerable commands in styles
using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR)
(the two options are identical and are simply aliases)
=item B<--enable-citation-markup> or B<--enforce-auto-mbox>
-Protect citation commands and other vulnerable commands in changed sections
+Protect citation commands and other vulnerable commands in changed sections
with C<\mbox> command, i.e. use default behaviour for ulem package for other packages
(the two options are identical and are simply aliases)
@@ -4823,18 +4865,18 @@ Suppress inclusion of old and new file names as comment in output file
=item B<--visible-label>
-Include old and new filenames (or labels set with C<--label> option) as
+Include old and new filenames (or labels set with C<--label> option) as
visible output.
=item B<--flatten>
Replace C<\input> and C<\include> commands within body by the content
of the files in their argument. If C<\includeonly> is present in the
-preamble, only those files are expanded into the document. However,
-no recursion is done, i.e. C<\input> and C<\include> commands within
-included sections are not expanded. The included files are assumed to
+preamble, only those files are expanded into the document. However,
+no recursion is done, i.e. C<\input> and C<\include> commands within
+included sections are not expanded. The included files are assumed to
be located in the same directories as the old and new master files,
-respectively, making it possible to organise files into old and new directories.
+respectively, making it possible to organise files into old and new directories.
--flatten is applied recursively, so inputted files can contain further
C<\input> statements. Also handles files included by the import package
(C<\import> and C<\subimport>), and C<\subfile> command.
@@ -4881,7 +4923,7 @@ Suppress generation of hyperreferences, used for minimal diffs (option --only-ch
=back
-=head2 Predefined styles
+=head2 Predefined styles
=head2 Major types
@@ -4894,9 +4936,14 @@ The major type determine the markup of plain text and some selected latex comman
Added text is wavy-underlined and blue, discarded text is struck out and red
(Requires color and ulem packages). Overstriking does not work in displayed math equations such that deleted parts of equation are underlined, not struck out (this is a shortcoming inherent to the ulem package).
+=item C<LUAUNDERLINE>
+
+Added text is underlined and blue, discarded text is struck out and red
+(Requires lua-ul package + LuaLaTeX).
+
=item C<CTRADITIONAL>
-Added text is blue and set in sans-serif, and a red footnote is created for each discarded
+Added text is blue and set in sans-serif, and a red footnote is created for each discarded
piece of text. (Requires color package)
=item C<TRADITIONAL>
@@ -4937,13 +4984,13 @@ Added text is set in bold face, discarded is not shown. (also see --no-del optio
=item C<PDFCOMMENT>
-The pdfcomment package is used to underline new text, and mark deletions with a PDF comment. Note that this markup might appear differently or not at all based on the pdf viewer used. The viewer with best support for pdf markup is probably acroread. This style is only recommended if the number of differences is small.
+The pdfcomment package is used to underline new text, and mark deletions with a PDF comment. Note that this markup might appear differently or not at all based on the pdf viewer used. The viewer with best support for pdf markup is probably acroread. This style is only recommended if the number of differences is small.
=back
=head2 Subtypes
-The subtype defines the commands that are inserted at the begin and end of added or discarded blocks, irrespectively of whether these blocks contain text or commands (Defined commands: C<\DIFaddbegin, \DIFaddend, \DIFdelbegin, \DIFdelend>)
+The subtype defines the commands that are inserted at the begin and end of added or discarded blocks, irrespectively of whether these blocks contain text or commands (Defined commands: C<\DIFaddbegin, \DIFaddend, \DIFdelbegin, \DIFdelend>)
=over 10
@@ -4961,7 +5008,7 @@ from the intended position.
An alternative way of marking added passages in blue, and deleted ones in red.
(It is recommeneded to use instead the main types to effect colored markup,
-although in some cases coloring with dvipscol can be more complete, for example
+although in some cases coloring with dvipscol can be more complete, for example
with citation commands).
=item C<DVIPSCOL>
@@ -4976,12 +5023,12 @@ although in some cases coloring with dvipscol can be more complete).
can be used to highlight only changed pages, but requires post-processing. It is recommend to not call this option manually but use C<latexdiff-vc> with C<--only-changes> option. Alternatively, use the script given within preamble of diff files made using this style.
-=item C<ONLYCHANGEDPAGE>
+=item C<ONLYCHANGEDPAGE>
also highlights changed pages, without the need for post-processing, but might not work reliably if
there is floating material (figures, tables).
-=item C<LABEL>
+=item C<LABEL>
is similar to C<ZLABEL>, but does not need the zref package and works less reliably (deprecated).
@@ -4989,7 +5036,7 @@ is similar to C<ZLABEL>, but does not need the zref package and works less relia
=head2 Float Types
-Some of the markup used in the main text might cause problems when used within
+Some of the markup used in the main text might cause problems when used within
floats (e.g. figures or tables). For this reason alternative versions of all
markup commands are used within floats. The float type defines these alternative commands.
@@ -5016,7 +5063,7 @@ Make no difference between the main text and floats.
=item C<ARRENV>
-If a match to C<ARRENV> is found within an inline math environment within a deleted or added block, then the inlined math
+If a match to C<ARRENV> is found within an inline math environment within a deleted or added block, then the inlined math
is surrounded by C<\mbox{>...C<}>. This is necessary as underlining does not work within inlined array environments.
[ Default: C<ARRENV>=S<C<(?:array|[pbvBV]matrix)> >
@@ -5036,9 +5083,9 @@ C<|subsubsection|paragraph|subparagraph)> ]
This option is for advanced users and allows definition of special versions of commands, which do not work as safe commands.
Commands in C<CUSTOMDIFCMD> that occur in added or deleted blocks will be given an ADD or DEL prefix.
-The prefixed versions of the command must be defined in the preamble, either by putting them
+The prefixed versions of the command must be defined in the preamble, either by putting them
in the preamble of at least the new file, or by creating a custom preamble file (Option --preamble).
-For example the command C<\blindtext> (from package blindtext) does not interact well with underlining, so that
+For example the command C<\blindtext> (from package blindtext) does not interact well with underlining, so that
for the standard markup type, it is not satisfactory to define it as a safe command. Instead, a customised versions
without underlining can be defined in the preamble:
@@ -5052,7 +5099,7 @@ and then latexdiff should be invoked with the option C<-c CUSTOMDIFCMD=blindtext
=item C<FLOATENV>
-Environments whose name matches the regular expression in C<FLOATENV> are
+Environments whose name matches the regular expression in C<FLOATENV> are
considered floats. Within these environments, the I<latexdiff> markup commands
are replaced by their FL variaties.
@@ -5101,17 +5148,17 @@ If C<--graphics-markup=both> is chosen, C<SCALEDELGRAPHICS> is the factor, by wh
=item C<VERBATIMENV>
-RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of these environments will not be processed in any way:
+RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of these environments will not be processed in any way:
deleted content is commented out, new content is not marked up
[ Default: S<C<comment> > ]
=item C<VERBATIMLINEENV>
-RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of environments described by VERBATIMLINEENV are compared in
+RegEx describing environments like verbatim, whose contents should be taken verbatim. The content of environments described by VERBATIMLINEENV are compared in
line mode, and changes are marked up using the listings package. The markup style is set based on the chosen mains markup type (Option -t), or on an analysis
of the preamble.
-Note that "listings.sty" must be installed. If this file is not found the fallback solution is to
+Note that "listings.sty" must be installed. If this file is not found the fallback solution is to
treat VERBATIMLINEENV environments treated exactly the same way as VERBATIMENV environments.
[ Default: S<C<(?:verbatim[*]?|lstlisting> > ]
@@ -5122,30 +5169,40 @@ treat VERBATIMLINEENV environments treated exactly the same way as VERBATIMENV e
=over 10
-=item Citations result in overfull boxes
+=item Changed citations result in overfull boxes
There is an incompatibility between the C<ulem> package, which C<latexdiff> uses for underlining and striking out in the UNDERLINE style,
-the default style, and the way citations are generated. In order to be able to mark up citations properly, they are enclosed with an C<\mbox>
-command. As mboxes cannot be broken across lines, this procedure frequently results in overfull boxes, possibly obscuring the content as it extends beyond the right margin. The same occurs for some other packages (e.g., siunitx). If this is a problem, you have two possibilities.
+the default style, and the way citations are generated. In order to be able to mark up citations properly, they are enclosed with an C<\mbox>
+command. As mboxes cannot be broken across lines, this procedure frequently results in overfull boxes, possibly obscuring the content as it extends beyond the right margin. The same occurs for some other packages (e.g., siunitx). If this is a problem, you have several possibilities.
1. Use C<CFONT> type markup (option C<-t CFONT>): If this markup is chosen, then changed citations are no longer marked up
-with the wavy line (additions) or struck out (deletions), but are still highlighted in the appropriate color, and deleted text is shown with a different font. Other styles not using the C<ulem> package will also work.
+with the wavy line (additions) or struck out (deletions), but are still highlighted in the appropriate color, and deleted text is shown with a different font. Other styles not using the C<ulem> package will also work.
2. Choose option C<--disable-citation-markup> which turns off the marking up of citations: deleted citations are no longer shown, and
-added citations are shown without markup. (This was the default behaviour of latexdiff at versions 0.6 and older)
-
+added citations are shown without markup. (This was the default behaviour of latexdiff at versions 0.6 and older).
For custom packages you can define the commands which need to be protected by C<\mbox> with C<--append-mboxsafecmd> and C<--excludemboxsafecmd> options
(submit your lists of command as feature request at github page to set the default behaviour of future versions, see section 6)
-=item Changes in complicated mathematical equations result in latex processing errors
+3. If you are using luatex >= 1.12.0 you can use option LUAUNDERLINE that uses lua-ul instead of ulem for underlining, which does not have this problem (experimental feature).
+
+=item Changes in complicated mathematical equations result in latex processing errors.
+
+Try option C<--math-markup=whole>. If even that fails, you can turn off mark up for equations with C<--math-markup=off>.
-Try options C<--math-markup=whole>. If even that fails, you can turn off mark up for equations with C<--math-markup=off>.
+=item Deleted parts in equations are not struck out but underlined.
-=item How can I just show the pages where changes had been made
+This is a limitation of the ulem package that implements the strike-out. If you use the amsmath package, then the strike-out command is redefined in such a way that deleted passages are wrapped with C<\text> command; adding C<\usepackage{amsmath}> to your preamble will trigger this behaviour. (If amsmath is not included directly, but imported by another package, latexdiff will not be able to detect its availability; in this case you can give latexdiff a hint with option C<--packages=amsmath>.
-Use options -C<-s ZLABEL> (some postprocessing required) or C<-s ONLYCHANGEDPAGE>. C<latexdiff-vc --ps|--pdf> with C<--only-changes> option takes care of
+
+=item How can I just show the pages where changes had been made?
+
+Use options C<--s ZLABEL> (some postprocessing required) or C<-s ONLYCHANGEDPAGE>. C<latexdiff-vc --ps|--pdf> with C<--only-changes> option takes care of
the post-processing for you (requires zref package to be installed).
+=item The character encoding breaks when running latexdiff from powershell.
+
+This problem is not limited to C<latexdiff> and has to do with the default settings of C<powershell> in Windows. It is recommended to use C<cmd> instead.
+
=back
=head1 BUGS
@@ -5158,13 +5215,13 @@ different numbers of inter-argument spaces are treated as significant.
=back
-Please submit bug reports using the issue tracker of the github repository page I<https://github.com/ftilmann/latexdiff.git>,
+Please submit bug reports using the issue tracker of the github repository page I<https://github.com/ftilmann/latexdiff.git>,
or send them to I<tilmann -- AT -- gfz-potsdam.de>. Include the version number of I<latexdiff>
(from comments at the top of the source or use B<--version>). If you come across latex
files that are error-free and conform to the specifications set out
above, and whose differencing still does not result in error-free
latex, please send me those files, ideally edited to only contain the
-offending passage as long as that still reproduces the problem. If your
+offending passage as long as that still reproduces the problem. If your
file relies on non-standard class files, you must include those. I will not
look at examples where I have trouble to latex the original files.
@@ -5175,24 +5232,24 @@ L<latexrevise>, L<latexdiff-vc>
=head1 PORTABILITY
I<latexdiff> does not make use of external commands and thus should run
-on any platform supporting Perl 5.6 or higher. If files with encodings
+on any platform supporting Perl 5.6 or higher. If files with encodings
other than ASCII or UTF-8 are processed, Perl 5.8 or higher is required.
The standard version of I<latexdiff> requires installation of the Perl package
-C<Algorithm::Diff> (available from I<www.cpan.org> -
+C<Algorithm::Diff> (available from I<www.cpan.org> -
I<http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15>) but a stand-alone
version, I<latexdiff-so>, which has this package inlined, is available, too.
I<latexdiff-fast> requires the I<diff> command to be present.
=head1 AUTHOR
-Version 1.3.3
-Copyright (C) 2004-2022 Frederik Tilmann
+Version 1.3.4
+Copyright (C) 2004-2024 Frederik Tilmann
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License Version 3
-Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N. Becker, T. Doerges, K. Huebner,
+Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N. Becker, T. Doerges, K. Huebner,
T. Connors, Sebastian Gouezel and many others.
Thanks to the many people who sent in bug reports, feature suggestions, and other feedback.
@@ -5463,13 +5520,14 @@ value
underline
sqrt
(SUPER|SUB)SCRIPT
-%%END TEXT COMMANDS
+%%END TEXT COMMANDS
%%BEGIN CONTEXT1 COMMANDS
% Regex matching commands with a text argument (leave out the \), which will fail out of context. These commands behave like text commands, except when they occur in a deleted section, where they are disabled, but their argument is shown as deleted text.
caption
subcaption
-%%END CONTEXT1 COMMANDS
+multicolumn
+%%END CONTEXT1 COMMANDS
%%BEGIN CONTEXT2 COMMANDS
% Regex matching commands with a text argument (leave out the \), which will fail out of context. As corresponding commands for context1. The only difference is that context2 commands are completely disabled in deleted sections, including their arguments.
@@ -5477,7 +5535,7 @@ title
author
date
institute
-%%END CONTEXT2 COMMANDS
+%%END CONTEXT2 COMMANDS
%% CONFIGURATION variabe defaults
%%BEGIN LISTENV CONFIG
@@ -5555,9 +5613,16 @@ verbatim[*]?
\RequirePackage[normalem]{ulem}
\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1}
\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}}
-\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}
+\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}
%DIF END UNDERLINE PREAMBLE
+%DIF LUAUNDERLINE PREAMBLE
+\RequirePackage{lua-ul}
+\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1}
+\providecommand{\DIFadd}[1]{{\protect\color{blue}\underLine{#1}}}
+\providecommand{\DIFdel}[1]{{\protect\color{red}\strikeThrough{#1}}}
+%DIF END LUAUNDERLINE PREAMBLE
+
%DIF CTRADITIONAL PREAMBLE
\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1}
\RequirePackage[stable]{footmisc}
@@ -5729,7 +5794,7 @@ verbatim[*]?
% To show only pages with changes (dvips/dvipdf)
% latex diff.tex
% latex diff.tex
-% dvips -pp `perl -lne 'if (m/\\newlabel{DIFchg[be]\d*}{{.*}{(.*)}}/) { print $1 }' diff.aux | uniq | tr -s \\n ','` diff.dvi
+% dvips -pp `perl -lne 'if (m/\\newlabel{DIFchg[be]\d*}{{.*}{(.*)}}/) { print $1 }' diff.aux | uniq | tr -s \\n ','` diff.dvi
\typeout{Check comments in preamble of output for instructions how to show only pages where changes have been made}
\usepackage[user,abspage]{zref}
\newcount\DIFcounterb
@@ -5749,10 +5814,10 @@ verbatim[*]?
\RequirePackage{etoolbox}
\RequirePackage{zref}
% redefine label command to write immediately to aux file - page references will be lost
-\makeatletter \let\oldlabel\label% Store \label
-\renewcommand{\label}[1]{% Update \label to write to the .aux immediately
-\zref@wrapper@immediate{\oldlabel{#1}}}
-\makeatother
+\makeatletter \let\oldlabel\label% Store \label
+\renewcommand{\label}[1]{% Update \label to write to the .aux immediately
+\zref@wrapper@immediate{\oldlabel{#1}}}
+\makeatother
\newbool{DIFkeeppage}
\newbool{DIFchange}
\boolfalse{DIFkeeppage}
@@ -5770,7 +5835,7 @@ verbatim[*]?
\providecommand{\DIFmodend}{\global\booltrue{DIFkeeppage}\global\boolfalse{DIFchange}}
%DIF END ONLYCHANGEDPAGE PREAMBLE
-%% FLOAT TYPES
+%% FLOAT TYPES
%DIF FLOATSAFE PREAMBLE
\providecommand{\DIFaddFL}[1]{\DIFadd{#1}}
@@ -5802,7 +5867,7 @@ verbatim[*]?
%DIF END TRADITIONALSAFE PREAMBLE
% see:
-% http://tex.stackexchange.com/questions/47351/can-i-redefine-a-command-to-contain-itself
+% http://tex.stackexchange.com/questions/47351/can-i-redefine-a-command-to-contain-itself
%DIF HIGHLIGHTGRAPHICS PREAMBLE
\RequirePackage{settobox}
@@ -5848,6 +5913,15 @@ verbatim[*]?
%% SPECIAL PACKAGE PREAMBLE COMMANDS
+%% Redefine strike out command to wrap in text box if amsmath is used and markup style with ulem is used
+%DIF AMSMATHULEM PREAMBLE
+\makeatletter
+\let\sout@orig\sout
+\renewcommand{\sout}[1]{\ifmmode\text{\sout@orig{\ensuremath{#1}}}\else\sout@orig{#1}\fi}
+\makeatother
+%DIF END AMSMATHULEM PREAMBLE
+
+
% Standard \DIFadd and \DIFdel are redefined as \DIFaddtex and \DIFdeltex
% when hyperref package is included.
%DIF HYPERREF PREAMBLE
@@ -5950,7 +6024,7 @@ verbatim[*]?
%DIF END DIFCODE_BOLD
%DIF DIFCODE_PDFCOMMENT
-
+
moredelim=[il][\color{white}\tiny]{\%DIF\ <\ },
moredelim=[il][\sffamily\bfseries]{\%DIF\ >\ }
%DIF END DIFCODE_PDFCOMMENT
diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES
index cd531f14162..a8f5e9d17bd 100644
--- a/Master/texmf-dist/doc/support/latexmk/CHANGES
+++ b/Master/texmf-dist/doc/support/latexmk/CHANGES
@@ -926,3 +926,27 @@ From v. 4.84 to 4.85
reported an error, and latexmk treated that incorrectly as a fatal
error.
+From v. 4.85 to 4.86
+ Document variable $user_deleted_file_treated_as_changed.
+ Correct problems when main pdf output file is detected as an INPUT file in
+ the .fls file. (That sometimes affected dependency detection of
+ included graphics files with the same basename as the main .tex
+ document.)
+ Updates to example_rcfiles/xr_latexmkrc, example_rcfiles/pythontex_latexmkrc,
+ example_rcfiles/splitindex_latexmkrc, example_rcfiles/bib2gls_latexmkrc.
+ Correct detection of graphics includes in .log file.
+ Apply autoflush to STDOUT, so that when STDERR and STDOUT are redirected
+ to the same place, the output is correctly ordered.
+ Add base name to the list of items reported with the -dir-report and
+ -dir-report-only options.
+ With -dir-report-only make report for each tex file to be processed.
+ Fix failure of -c and -C with $cleanup_includes_generated = 1; when
+ engine is lualatex or hilatex.
+ Documentation updates.
+ Correct problem that necessary necessary directory/ies not created in aux
+ dir when \include'd file has more than one level of subdirectory.
+ Correct message about up-to-date files when $max_repeat runs exceeded.
+
+From v. 4.86 to 4.86a
+ Correct instructions for remaking the documentation files in INSTALL.
+
diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL
index a0cecb7b134..e6f0205c67c 100644
--- a/Master/texmf-dist/doc/support/latexmk/INSTALL
+++ b/Master/texmf-dist/doc/support/latexmk/INSTALL
@@ -1,6 +1,6 @@
INSTALLING latexmk
==================
- (Version 4.85, 7 Apr. 2024)
+ (Version 4.86a, 27 Dec. 2024)
John Collins
Physics Department
@@ -373,19 +373,19 @@ Tricky points
4. If you need to remake documentation files, e.g., latexmk.pdf or
latexmk.txt, from the man page file latexmk.1, the following
- commands work (on my linux and OS-X systems at least):
+ commands work if your groff is of version at least 1.23.0.:
- Postscript file from latexmk.1:
+ Pdf file from latexmk.1:
- groff -Tps -man-old -rcR=0 latexmk.1 > latexmk.ps
-
- Pdf file from postscript:
+ groff -Tpdf -man -rcR=0 latexmk.1 > latexmk.pdf
+ Alternatively to make postscript and pdf files:
+ groff -Tps -man -rcR=0 latexmk.1 > latexmk.ps
ps2pdf latexmk.ps latexmk.pdf
Text file:
- groff -Tascii -man-old -rcR=0 latexmk.1 > latexmk.txt
+ groff -Tascii -man -rcR=0 -P -cbuo latexmk.1 > latexmk.txt
diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README
index 19924691678..264e580acb5 100644
--- a/Master/texmf-dist/doc/support/latexmk/README
+++ b/Master/texmf-dist/doc/support/latexmk/README
@@ -1,5 +1,5 @@
-Latexmk, version 4.85, 7 Apr 2024
----------------------------------
+Latexmk, version 4.86a, 27 Dec 2024
+-----------------------------------
Latexmk completely automates the process of generating a LaTeX
document. Essentially, it is a highly specialized cousin of the
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/bib2gls_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/bib2gls_latexmkrc
index fccca2109f6..5319fdc4f04 100644
--- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/bib2gls_latexmkrc
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/bib2gls_latexmkrc
@@ -1,51 +1,61 @@
# Implements use of bib2gls with glossaries-extra.
-# Version of 4 Feb 2024.
+# Version of 14 Oct 2024.
# Thanks to Marcel Ilg for a suggestion.
-# !!! ONLY WORKS WITH VERSION 4.54 or higher of latexmk
-
-push @generated_exts, 'glstex', 'glg';
+push @generated_exts, 'glg', '%R*.glstex';
# For case that \GlsXtrLoadResources is used and so glstex file (first one)
# has same name as .aux file.
-add_cus_dep('aux', 'glstex', 0, 'run_bib2gls');
+add_cus_dep( 'aux', 'glstex', 0, 'run_bib2gls' );
# For case that \glsxtrresourcefile is used and so glstex file (first one)
# has same name as .bib file.
-add_cus_dep('bib', 'glstex', 0, 'run_bib2gls_alt');
+add_cus_dep( 'bib', 'glstex', 0, 'run_bib2gls_alt' );
sub run_bib2gls {
my $ret = 0;
- if ( $silent ) {
- $ret = system "bib2gls --silent --group '$_[0]'";
- } else {
- $ret = system "bib2gls --group '$_[0]'";
- };
-
- # bib2gls puts output files in current directory.
- # At least put main glstex in same directory as aux file to satisfy
- # definition of custom dependency.
my ($base, $path) = fileparse( $_[0] );
- if ($path && -e "$base.glstex") {
- rename "$base.glstex", "$path$base.glstex";
- }
-
+ # Default encoding assumed by bib2gls is the system CS, which on
+ # Windows is normally *not* CP65001 (aka UTF-8). But the aux and log
+ # files are UTF-8, at least with the default settings of TeX Live.
+ # So we tell bib2gls about this.
+ # With the options as given here, the .glg will be encoded in the system
+ # CS, which will be suitable for latexmk's use, since that is the CS for
+ # communicating with the file system.
+ # (**Warning**, it is simpler to do this rather than using, the option
+ # --default-encoding to set everything to UTF-8, for then that would
+ # apply also to the .glg, which would entail having to convert filenames
+ # in the .glg file to the system CS.)
+ my @bib2gls_cmd = (
+ "--tex-encoding", "UTF-8",
+ "--log-encoding", "UTF-8",
+ "--group",
+ "--dir",
+ $path,
+ $base
+ );
+ if ($silent) { unshift @bib2gls_cmd, "--silent"; }
+ unshift @bib2gls_cmd, "bib2gls";
+ print "Running '@bib2gls_cmd'...\n";
+ $ret = system @bib2gls_cmd;
+
if ($ret) {
warn "Run_bib2gls: Error, so I won't analyze .glg file\n";
return $ret;
}
- # Analyze log file.
- my $log = "$_[0].glg";
- if ( open( my $log_fh, '<', $log) ) {
- while (<$log_fh>) {
+ # Analyze bib2gls's log file:
+ my $glg = "$_[0].glg";
+ if ( open( my $glg_fh, '<', $glg) ) {
+ rdb_add_generated( $glg );
+ while (<$glg_fh>) {
s/\s*$//;
if (/^Reading\s+(.+)$/) { rdb_ensure_file( $rule, $1 ); }
if (/^Writing\s+(.+)$/) { rdb_add_generated( $1 ); }
}
- close $log_fh;
+ close $glg_fh;
}
else {
- warn "Run_bib2gls: Cannot read log file '$log': $!\n";
+ warn "Run_bib2gls: Cannot read log file '$glg': $!\n";
}
return $ret;
}
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc
index 458c5a40706..83aa90d22a2 100644
--- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc
@@ -1,15 +1,23 @@
# Support for pythontex in v. 0.16 or higher, with latexmk 4.62 or higher
#
# What these definitions provide/do:
-# 1. Variable specifying command string for invoking pythontex
+# 1. Variable specifying command string for invoking the pythontex program.
# 2. Addition to %extra_rule_spec of template for pythontex rule. This
-# tells latexmkrc to create the rule when it is initializing for
-# processing a TeX file.
+# tells latexmk to create the rule when it is initializing its rule
+# network for processing a .tex file.
# 3. A subroutine mypythontex that the pythontex rule is defined to
# call. This runs pythontex and then sets dependency information.
# 4. Settings for the files generated by the pythontex package and the
# pythontex program so that the files are deleted in a clean-up
# operation.
+#
+# 5. There are two parts to the dependency information
+# a. The files **generated** by pythontex.
+# This happens without any special assistance from the document.
+# b. The files **read** by python.
+# At present this needs support with some code in the document.
+# See the document at the end of this file for an example.
+
$clean_ext .= " pythontex-files-%R/* pythontex-files-%R";
push @generated_exts, 'pytxcode';
@@ -44,3 +52,53 @@ sub mypythontex {
}
return $ret;
}
+
+# ==============================================
+# Sample document that writes dependency information
+# To use it you need to save this file as e.g., test.tex,
+# and to create a data file name data.txt, with whatever content you like.
+#
+#\documentclass{article}
+#\usepackage{pythontex}
+#
+#%================
+#% Macro to write list of dependent files to where latexmk will find it,
+#% when configured with the code in pythontex_latexmkrc.
+#\newcommand{\pycachedeps}{\py{cache_dependencies()}}
+#%\AtEndDocument{\pycachedeps}
+#
+#% Python code used by above.
+#\begin{pycode}
+#def cache_dependencies():
+# s = '';
+# for item in pytex._dependencies:
+# s += "%PythonTeX dependency: '" + item + "';\n"
+# return s;
+#\end{pycode}
+#%================
+#
+#\begin{document}
+#
+#Test of using pythontex with dependency information.
+#
+#% Python code to access a particular file, together with use of a pythontex
+#% subroutine to add the file to pythontex's list of source files.
+#\begin{pycode}
+#pytex.add_dependencies("data.txt")
+#n = "data.txt"
+#f = open( n, "r" )
+#print( "From '", n, "', first line is: \\\\", f.readline(), "" )
+#f.close
+#\end{pycode}
+#
+#A big loop, which takes a few seconds to run in python. This is just to illustra
+#\begin{pycode}
+#j = -20
+#for i in range(0,15000000):
+# j = j + i
+#print(j)
+#\end{pycode}
+#
+#% Cache dependencies (in .pytxmcr file):
+#\pycachedeps
+#\end{document}
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/splitindex_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/splitindex_latexmkrc
index 5ee22730621..76e4bda5124 100644
--- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/splitindex_latexmkrc
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/splitindex_latexmkrc
@@ -1,32 +1,112 @@
-$makeindex = 'internal splitindex2 %S %D %R %B %O';
+# Definitions for use of splitindex package: Arrange to use the splitindex
+# program instead of makeindex when needed, otherwise to do standard run of
+# makeindex.
+
+# John Collins and Ernst Reissner, 2024-09-27.
+
+
+# Specify extra files that need to be cleaned up when splitindex is in use:
$clean_ext .= " %R-*.ind %R-*.idx %R-*.ilg %R-*.ind";
-sub splitindex2 {
- # Use splitindex instead of makeindex.
- # The splitindex programe starts from an .idx file, makes a set of
- # other .idx files for separate indexes, and then runs makeindex to
- # make corresponding .ind files.
- # However, it is possible that the document uses the splitindex
- # package, but in a way compatible with the standard methods
- # compatible with makeindex, i.e., with a single index and with the
- # use of the \printindex command.
- # Then we need to invoke makeindex.
- # In addition, latexmk assumes that makeindex or its replacement makes
- # an .ind file from an .idx file, and latexmk gives an error if it
- # doesn't exist, so we need to make an .ind file.
- # Both problems are solved by running makeindex and then splitindex.
- # Note: errors are returned by makeindex and splitindex for things
- # like a missing input file. No error is returned for lines in an
- # input file that are in an incorrect format; they are simply
- # ignored. So no problem is caused by lines in the .idx file
- # that are generated by splitindex in a format incompatible with
- # makeindex.
- my ($source, $dest, $root, $base, @opts) = @_;
-
- my $ret1 = system( "makeindex", $source );
- my $ret2 = system( "splitindex", $source );
- return $ret1 || $ret2;
+# Use an internal subroutine to do the processing. **Important**: Pass the
+# name of the source file, etc as arguments obtained by place-holder
+# substitution instead of having the subroutine use variables like
+# $$Psource. This is because by default latexmk temporarily changes
+# directory to the aux directory before the invoking the command (or
+# whatever) specified by $makeindex. The change of directory is to avoid
+# some deficiencies in the standard makeindex program. See the latexmk
+# documentation for further information. After the change of directory, the
+# value of $$Psource will typically be wrong. Instead we use placeholders
+# for the relevant quantities, since after doing the change of directory,
+# latexmk's internal processing adjusts the substitutions for %S, %D etc
+# appropriately. Also, include the string for aux_dir in the arguments, as
+# needed for the treatment of dependencies.
+
+$makeindex = 'internal splitindex3 %S %D %Y %R %B %O';
+
+#-------------
+
+sub HaveMultiIdx {
+ # Subroutine to test whether (.idx) file has entries of the form given by
+ # splitindex package with multiple indexes.
+ use strict;
+ my $fileName = $_[0];
+
+ # Use a precompiled RE:
+ my $patternMultiIndex = qr/^\\indexentry\[[^\]]*\]\{/;
+
+ my $info;
+ if (! open $info, '<', $fileName ) {
+ die "In splitindex processing, the file '$fileName' was supposed to\n",
+ "exist, but I could not read it:\n$!";
+ return 0;
+ }
+ while (my $line = <$info>) {
+ if ( $line =~ $patternMultiIndex ) {
+ # We have a multi-index
+ close $info;
+ return 1;
+ }
+ }
+ close $info;
+ # There was no multi-index:
+ return 0;
}
+#-------------
+
+sub splitindex3 {
+ use strict;
+ my ($source, $dest, $auxdir, $root, $base, @opts) = @_;
+
+ if (! HaveMultiIdx($source)) {
+ print "Running standard makeindex program:\n";
+ return system( "makeindex", @opts, '-o', $dest, $source );
+ }
+ # Else:
+ print "Running splitindex program:\n";
+
+ # Ensure dummy file for standard destination file exists, so that
+ # latexmk is satisfied that its expectation for the main generated file
+ # is satisfied.
+ open( my $ind_fh, '>>', $dest );
+ close $ind_fh;
+
+ # Arrange to obtain dependency information from splitindex by invoking
+ # it in a verbose mode, and redirecting its output to the standard .ilg
+ # file, and later parsing it for the relevant lines.
+ my $ilg = $dest;
+ $ilg =~ s/\.[^\.]+$/\.ilg/;
+ my $ret2 = system "splitindex -v -v \"$source\" >> \"$ilg\"";
+ if ($ret2) { return $ret2;}
+
+
+ my $ilg_fh;
+ if (! open( $ilg_fh, '<', $ilg ) ) {
+ warn "In sub splitindex, could not read '$ilg'\n";
+ return 1;
+ }
+ while (<$ilg_fh>) {
+ if ( /^New index file (.*)\s*$/ ) {
+ # .idx file generated by splitindex
+ my $idx = $1;
+ # Ensure path to idx file is correct if we've done the change of
+ # directory caused by the setting of $makeindex_fudge:
+ if ($makeindex_fudge) { $idx = $auxdir.$idx; }
+ # In addition to the .idx files that the splitindex program
+ # reports that it generates, there are corresponding .ind files
+ # generated by the instances of makeindex that are invoked by
+ # splitindex. These are important to latexmk's knowledge of
+ # the network of dependencies because they are read in by the
+ # next run of *latex.
+ my $ind = $idx;
+ $ind =~ s/\.idx$/\.ind/;
+ print "splitindex generated files '$idx' '$ind'\n";
+ rdb_add_generated( $ind, $idx );
+ }
+ }
+ close $ilg_fh;
+ return $ret2;
+}
-print "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n"; \ No newline at end of file
+#-------------
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xr_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xr_latexmkrc
index bd860852301..25e21e09261 100644
--- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xr_latexmkrc
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xr_latexmkrc
@@ -1,5 +1,5 @@
# This shows how to use the xr package with latexmk.
-# John Collins 2023-03-29
+# John Collins 2023-06-25
#
# The xr package ("a system for eXternal References") is used by a document
# to make references to sections, equations, etc in other external
@@ -43,7 +43,7 @@ push @sub_doc_options, '-pdf'; # Use pdflatex for compilation of external docume
#--------------------
# Add a pattern for xr's log-file message about missing files to latexmk's
-# list. Latexmk's variable @file_not_found is not yet documented.
+# list.
# This line isn't necessary for v. 4.80 or later of latexmk.
push @file_not_found, '^No file\\s*(.+)\s*$';
@@ -57,7 +57,7 @@ sub makeexternaldocument {
"-aux-directory=$sub_doc_output",
"-output-directory=$sub_doc_output",
$base_name;
- if ( ($sub_doc_output ne ' ') && ($sub_doc_output ne '.') ) {
+ if ( ($sub_doc_output ne '') && ($sub_doc_output ne '.') ) {
# In this case, .aux file generated by pdflatex isn't in same
# directory as the .tex file.
# Therefore:
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
index 593652f2096..20c7a104784 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
index 7360edad9bc..1658d725a48 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
@@ -61,7 +61,7 @@ DESCRIPTION
- 7 April 2024 1
+ 27 December 2024 1
@@ -127,7 +127,7 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
- 7 April 2024 2
+ 27 December 2024 2
@@ -193,7 +193,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 3
+ 27 December 2024 3
@@ -259,7 +259,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 4
+ 27 December 2024 4
@@ -325,7 +325,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 5
+ 27 December 2024 5
@@ -391,7 +391,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 6
+ 27 December 2024 6
@@ -457,7 +457,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 7
+ 27 December 2024 7
@@ -523,7 +523,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 8
+ 27 December 2024 8
@@ -568,12 +568,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
ily used for debugging configuration issues.
- -dvi Generate dvi version of document using latex.
+ -dvi Generate dvi version of document using latex. (And turn off any
+ incompatible requests.)
-dvilua
Generate dvi version of document using lualatex instead of la-
- tex.
+ tex. (And turn off any incompatible requests.)
-dvi- Turn off generation of dvi version of document. (This may get
@@ -585,11 +586,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-dvilualatex="COMMAND"
This sets the string specifying the command to run dvi lualatex.
It behaves like the -pdflatex option, but sets the variable
- $dvilualatex.
- 7 April 2024 9
+ 27 December 2024 9
@@ -598,6 +598,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ $dvilualatex.
+
Note: This option when provided with the COMMAND argument only
sets the command for invoking dvilualatex; it does not turn on
the use of dvilualatex. That is done by other options or in an
@@ -650,12 +652,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
(Note: the above examples show are to show how to use the -e to
specify initialization code to be executed. But the particular
effect can be achieved also by the use of the -latex option with
- less problems in dealing with quoting.)
-
- 7 April 2024 10
+ 27 December 2024 10
@@ -664,6 +664,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ less problems in dealing with quoting.)
+
+
-emulate-aux-dir
Emulate the use of an aux directory instead of leaving it to the
*latex programs to do it. (MiKTeX supports -aux-directory, but
@@ -715,13 +718,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-C had been given, and then do a regular make.
- -h or-non-help
- Print help information.
-
- 7 April 2024 11
+ 27 December 2024 11
@@ -730,8 +730,12 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ -h or-non-help
+ Print help information.
+
+
-hnt Generate hnt (HINT) version of document using hilatex. (And
- turn off dvi, postscript, and pdf modes.)
+ turn off any incompatible requests.)
-jobname=STRING
@@ -781,19 +785,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-latex This sets the generation of dvi files by latex, and turns off
the generation of pdf and ps files.
- Note: to set the command used when latex is specified, see the
- -latex="COMMAND" option.
+ 27 December 2024 12
- 7 April 2024 12
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ Note: to set the command used when latex is specified, see the
+ -latex="COMMAND" option.
-latex="COMMAND"
@@ -835,8 +839,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-lualatex
Use lualatex. That is, use lualatex to process the source
- file(s) to pdf. The generation of dvi and postscript files is
- turned off.
+ file(s) to pdf. The generation of dvi, hnt, postscript and xdv
+ files is turned off.
This option is equivalent to using the following set of options
@@ -847,13 +851,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
of latexmk.)
- -lualatex="COMMAND"
- This sets the string specifying the command to run lualatex. It
- behaves like the -pdflatex option, but sets the variable
-
- 7 April 2024 13
+ 27 December 2024 13
@@ -862,31 +862,34 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- $lualatex.
+ -lualatex="COMMAND"
+ This sets the string specifying the command to run lualatex. It
+ behaves like the -pdflatex option, but sets the variable $luala-
+ tex.
- Note: This option when provided with the COMMAND argument only
- sets the command for invoking lualatex; it does not turn on the
+ Note: This option when provided with the COMMAND argument only
+ sets the command for invoking lualatex; it does not turn on the
use of lualatex. That is done by other options or in an initial-
ization file.
- -M Show list of dependent files after processing. This is equiva-
+ -M Show list of dependent files after processing. This is equiva-
lent to the -deps option.
-MF file
- If a list of dependents is made, the -MF specifies the file to
+ If a list of dependents is made, the -MF specifies the file to
write it to.
-MP If a list of dependents is made, include a phony target for each
- source file. If you use the dependents list in a Makefile, the
+ source file. If you use the dependents list in a Makefile, the
dummy rules work around errors the program make gives if you re-
move header files without updating the Makefile to match.
-makeindexfudge
- Turn on the change-directory fudge for makeindex. See documen-
+ Turn on the change-directory fudge for makeindex. See documen-
tation of $makeindex_fudge for details.
@@ -902,24 +905,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-MSWinBackSlash
This option only has an effect when latexmk is running under MS-
Windows. This is that when latexmk runs a command under MS-Win-
- dows, the Windows standard directory separator "\" is used to
- separate directory components in a file name. Internally, la-
- texmk uses "/" for the directory separator character, which is
+ dows, the Windows standard directory separator "\" is used to
+ separate directory components in a file name. Internally, la-
+ texmk uses "/" for the directory separator character, which is
the character used by Unix-like systems.
This is the default behavior. However the default may have been
- overridden by a configuration file (latexmkrc file) which sets
+ overridden by a configuration file (latexmkrc file) which sets
$MSWin_back_slash=0.
- -MSWinBackSlash-
- This option only has an effect when latexmk is running under MS-
- Windows. This is that when latexmk runs a command under MS-Win-
- dows, the substitution of "\" for the separator character
- 7 April 2024 14
+
+ 27 December 2024 14
@@ -928,7 +928,11 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- between directory components of a file name is not done. Instead
+ -MSWinBackSlash-
+ This option only has an effect when latexmk is running under MS-
+ Windows. This is that when latexmk runs a command under MS-Win-
+ dows, the substitution of "\" for the separator character be-
+ tween directory components of a file name is not done. Instead
the forward slash "/" is used, the same as on Unix-like systems.
This is acceptable in most situations under MS-Windows, provided
that filenames are properly quoted, as latexmk does by default.
@@ -980,12 +984,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
on first, no matter where it occurs on the command line.
- -outdir=FOO or -output-directory=FOO
-
-
-
- 7 April 2024 15
+ 27 December 2024 15
@@ -994,6 +994,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ -outdir=FOO or -output-directory=FOO
+
Sets the directory for the output files of *latex.
If the aux directory is not set or is the same as the output di-
@@ -1041,17 +1043,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
texmk emulates it in a way suitable for the context of latexmk
and its workflows.
- If FORMAT is dvi, then dvi output is turned on, and postscript
- and pdf output are turned off. This is equivalent to using the
- options -dvi -ps- -pdf-.
+ -If FORMAT is dvi, then dvi output is turned on, and postscript,
+ pdf and xdv output are turned off. This is equivalent to using
+ the options -dvi -ps- -pdf- -xdv-.
- If FORMAT is pdf, then pdf output is turned on, and dvi and
- postscript output are turned off. This is equivalent to using
- the options -pdf -ps- -dvi-.
+ If FORMAT is pdf, then pdf output is turned on, and dvi,
- 7 April 2024 16
+ 27 December 2024 16
@@ -1060,22 +1060,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ postscript and xdv output are turned off. This is equivalent to
+ using the options -pdf -ps- -dvi- -xdv-.
+
If FORMAT is anything else, latexmk gives an error.
- -p Print out the document. By default the file to be printed is
- the first in the list postscript, pdf, dvi that is being made.
+ -p Print out the document. By default the file to be printed is
+ the first in the list postscript, pdf, dvi that is being made.
But you can use the -print=... option to change the type of file
to be printed, and you can configure this in a start up file (by
setting the $print_type variable).
- However, printing is enabled by default only under UNIX/Linux
+ However, printing is enabled by default only under UNIX/Linux
systems, where the default is to use the lpr command and only on
postscript files. In general, the correct behavior for printing
very much depends on your system's software. In particular, un-
- der MS-Windows you must have suitable program(s) available, and
- you must have configured the print commands used by latexmk.
- This can be non-trivial. See the documentation on the $lpr,
+ der MS-Windows you must have suitable program(s) available, and
+ you must have configured the print commands used by latexmk.
+ This can be non-trivial. See the documentation on the $lpr,
$lpr_dvi, and $lpr_pdf configuration variables to see how to set
the commands for printing.
@@ -1083,51 +1086,58 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
turns them off.
- -pdf Generate pdf version of document using pdflatex. (If you wish
- to use lualatex or xelatex, you can use whichever of the options
- -pdflua, -pdfxe, -lualatex or -xelatex applies.) To configure
- latexmk to have such behavior by default, see the section on
- "Configuration/initialization (rc) files".
+ -pdf Generate pdf version of document using pdflatex. (And turn off
+ any incompatible requests.)
+
+ (If you wish to use lualatex or xelatex, you can use whichever
+ of the options -pdflua, -pdfxe, -lualatex or -xelatex applies.)
+ To configure latexmk to have such behavior by default, see the
+ section on "Configuration/initialization (rc) files".
-pdfdvi
Generate dvi file and then pdf version of document from the dvi
- file, by default using dvipdf.
+ file, by default using dvipdf. (And turn off any incompatible
+ requests.)
- The program used to compile the document to dvi is latex by de-
- fault, but this can be changed to dvilulatex by the use of the
+ The program used to compile the document to dvi is latex by de-
+ fault, but this can be changed to dvilulatex by the use of the
-dvilua option or by setting $dvi_mode to 2.
-pdflua
- Generate pdf version of document using lualatex.
+ Generate pdf version of document using lualatex. (And turn off
+ any incompatible requests.)
-pdfps Generate dvi file, ps file from the dvi file, and then pdf file
- from the ps file.
+ from the ps file. (And turn off any incompatible requests.)
- The program used to compile the document to dvi is latex by de-
- fault, but this can be changed to dvilulatex by the use of the
- -dvilua option or by setting $dvi_mode to 2.
+ The program used to compile the document to dvi is latex by
- -pdfxe Generate pdf version of document using xelatex. Note that to
- optimize processing time, latexmk uses xelatex to generate an
- .xdv file rather than a pdf file directly. Only after possibly
+ 27 December 2024 17
- 7 April 2024 17
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ default, but this can be changed to dvilulatex by the use of the
+ -dvilua option or by setting $dvi_mode to 2.
- multiple runs to generate a fully up-to-date .xdv file does la-
- texmk then call xdvipdfmx to generate the final .pdf file.
+ -pdfxe Generate pdf version of document using xelatex. (And turn off
+ any incompatible requests.)
+
+ Note that to optimize processing time, latexmk uses xelatex to
+ generate an .xdv file rather than a pdf file directly. Only af-
+ ter possibly multiple runs to generate a fully up-to-date .xdv
+ file does latexmk then call xdvipdfmx to generate the final .pdf
+ file.
(Note: The reason why latexmk arranges for xelatex to make an
.xdv file instead of the xelatex's default of a .pdf file is as
@@ -1152,10 +1162,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-pdflatex
- This sets the generation of pdf files by pdflatex, and turns off
- the generation of dvi and ps files.
+ Set the generation of pdf files by pdflatex. (And turn off any
+ incompatible requests.)
- Note: to set the command used when pdflatex is specified, see
+ Note: to set the command used when pdflatex is specified, see
the -pdflatex="COMMAND" option.
@@ -1167,31 +1177,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S"
foo.tex
- The specification of the contents of the string are the same as
+ The specification of the contents of the string are the same as
for the $pdflatex configuration variable. (The option -pdflatex
- in fact sets the variable $pdflatex.) Depending on your operat-
- ing system and the command-line shell you are using, you may
- need to change the single quotes to double quotes (or something
- else).
+ in fact sets the variable $pdflatex.) Depending on your
- Note: This option when provided with the COMMAND argument only
- sets the command for invoking pdflatex; it does not turn on the
- use of pdflatex. That is done by other options or in an initial-
- ization file.
- To set the command for running latex (rather than the command
+ 27 December 2024 18
- 7 April 2024 18
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ operating system and the command-line shell you are using, you
+ may need to change the single quotes to double quotes (or some-
+ thing else).
+ Note: This option when provided with the COMMAND argument only
+ sets the command for invoking pdflatex; it does not turn on the
+ use of pdflatex. That is done by other options or in an initial-
+ ization file.
+ To set the command for running latex (rather than the command
for pdflatex) see the -latex option.
@@ -1238,28 +1248,28 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
to be made is the one used for print out.
- -ps Generate postscript version of document.
+ 27 December 2024 19
- -ps- Turn off generation of postscript version of document. This can
- be used to override a setting in a configuration file. (It may
- get overridden by some other option that requires a postscript
- file, for example a request for printing.)
- 7 April 2024 19
-
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ -ps Generate postscript version of document. (And turn off any in-
+ compatible requests.)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ -ps- Turn off generation of postscript version of document. This can
+ be used to override a setting in a configuration file. (It may
+ get overridden by some other option that requires a postscript
+ file, for example a request for printing.)
- -pF Postscript file filtering. The argument to this option is a
- filter which will generate a filtered postscript file with the
+ -pF Postscript file filtering. The argument to this option is a
+ filter which will generate a filtered postscript file with the
extension ".psF". All extra processing (e.g. preview, printing)
will then be performed on this filtered postscript file.
@@ -1272,50 +1282,40 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
latexmk -ps -pF "psnup -2" foo.tex
Whether to use single or double quotes round the "psnup -2" will
- depend on your command interpreter, as used by the particular
+ depend on your command interpreter, as used by the particular
version of perl and the operating system on your computer.
- -pv Run file previewer. If the -view option is used, that will se-
+ -pv Run file previewer. If the -view option is used, that will se-
lect the kind of file to be previewed (.pdf, .ps or .dvi). Oth-
- erwise the viewer views the "highest" kind of output file that
- is made, with the ordering being .pdf, .ps, .dvi (high to low).
- This option is incompatible with the -p and -pvc options, so it
+ erwise the viewer views the "highest" kind of output file that
+ is made, with the ordering being .pdf, .ps, .dvi (high to low).
+ This option is incompatible with the -p and -pvc options, so it
turns them off.
-pv- Turn off -pv.
- -pvc Run a file previewer and continually update the .dvi, .ps,
+ -pvc Run a file previewer and continually update the .dvi, .ps,
and/or .pdf files whenever changes are made to source files (see
- the Description above). Which of these files is generated and
- which is viewed is governed by the other options, and is the
- same as for the -pv option. The preview-continuous option -pvc
- can only work with one file. So in this case you will normally
- only specify one filename on the command line. It is also in-
- compatible with the -p and -pv options, so it turns these op-
+ the Description above). Which of these files is generated and
+ which is viewed is governed by the other options, and is the
+ same as for the -pv option. The preview-continuous option -pvc
+ can only work with one file. So in this case you will normally
+ only specify one filename on the command line. It is also in-
+ compatible with the -p and -pv options, so it turns these op-
tions off.
- The -pvc option also turns off force mode (-f), as is normally
- best for continuous preview mode. If you really want force
+ The -pvc option also turns off force mode (-f), as is normally
+ best for continuous preview mode. If you really want force
mode, use the options in the order -pvc -f.
With a good previewer the display will be automatically updated.
- (Under some but not all versions of UNIX/Linux "gv -watch" does
- this for postscript files; this can be set by a configuration
- variable. This would also work for pdf files except for an ap-
- parent bug in gv that causes an error when the newly updated pdf
- file is read.) Many other previewers will need a manual update.
-
- Important note: the acroread program on MS-Windows locks the pdf
- file, and prevents new versions being written, so it is a bad
- idea to use acroread to view pdf files in preview-continuous
- mode. It is better to use a different viewer: SumatraPDF and
- 7 April 2024 20
+ 27 December 2024 20
@@ -1324,18 +1324,28 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ (Under some but not all versions of UNIX/Linux "gv -watch" does
+ this for postscript files; this can be set by a configuration
+ variable. This would also work for pdf files except for an ap-
+ parent bug in gv that causes an error when the newly updated pdf
+ file is read.) Many other previewers will need a manual update.
+
+ Important note: the acroread program on MS-Windows locks the pdf
+ file, and prevents new versions being written, so it is a bad
+ idea to use acroread to view pdf files in preview-continuous
+ mode. It is better to use a different viewer: SumatraPDF and
gsview are good possibilities.
- There are some other methods for arranging an update, notably
- useful for many versions of xdvi and xpdf. These are best set
+ There are some other methods for arranging an update, notably
+ useful for many versions of xdvi and xpdf. These are best set
in latexmk's configuration; see below.
- Note that if latexmk dies or is stopped by the user, the
+ Note that if latexmk dies or is stopped by the user, the
"forked" previewer will continue to run. Successive invocations
- with the -pvc option will not fork new previewers, but latexmk
- will normally use the existing previewer. (At least this will
- happen when latexmk is running under an operating system where
- it knows how to determine whether an existing previewer is run-
+ with the -pvc option will not fork new previewers, but latexmk
+ will normally use the existing previewer. (At least this will
+ happen when latexmk is running under an operating system where
+ it knows how to determine whether an existing previewer is run-
ning.)
@@ -1343,9 +1353,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-pvctimeout
- Do timeout in pvc mode after period of inactivity, which is 30
+ Do timeout in pvc mode after period of inactivity, which is 30
min. by default. Inactivity means a period when latexmk has de-
- tected no file changes and hence has not taken any actions like
+ tected no file changes and hence has not taken any actions like
compiling the document.
@@ -1361,27 +1371,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-r <rcfile>
- Read the specified initialization file ("RC file") before pro-
+ Read the specified initialization file ("RC file") before pro-
cessing.
Be careful about the ordering: (1) Standard initialization files
- -- see the section below on "Configuration/initialization (RC)
- files" -- are read first. (2) Then the options on the command
- line are acted on in the order they are given. Therefore if an
- initialization file is specified by the -r option, it is read
- during this second step. Thus an initialization file specified
- with the -r option can override both the standard initialization
- files and previously specified options. But all of these can be
- overridden by later options.
+ -- see the section below on "Configuration/initialization (RC)
+ files" -- are read first. (2) Then the options on the command
+ line are acted on in the order they are given. Therefore if an
- The contents of the RC file just comprise a piece of code in the
- Perl programming language (typically a sequence of assignment
- statements); they are executed when the -r option is encountered
- during latexmk's parsing of its command line. See the -e option
-
- 7 April 2024 21
+ 27 December 2024 21
@@ -1390,14 +1390,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- for a way of giving initialization code directly on latexmk's
- command line. An error results in latexmk stopping. Multiple
+ initialization file is specified by the -r option, it is read
+ during this second step. Thus an initialization file specified
+ with the -r option can override both the standard initialization
+ files and previously specified options. But all of these can be
+ overridden by later options.
+
+ The contents of the RC file just comprise a piece of code in the
+ Perl programming language (typically a sequence of assignment
+ statements); they are executed when the -r option is encountered
+ during latexmk's parsing of its command line. See the -e option
+ for a way of giving initialization code directly on latexmk's
+ command line. An error results in latexmk stopping. Multiple
instances of the -r and -e options can be used, and they are ex-
ecuted in the order they appear on the command line.
-rc-report
- After initialization, give a list of the RC files read. (De-
+ After initialization, give a list of the RC files read. (De-
fault)
@@ -1406,10 +1416,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-recorder
- Give the -recorder option with *latex. In (most) modern ver-
- sions of these programs, this results in a file of extension
- .fls containing a list of the files that these programs have
- read and written. Latexmk will then use this file to improve
+ Give the -recorder option with *latex. In (most) modern ver-
+ sions of these programs, this results in a file of extension
+ .fls containing a list of the files that these programs have
+ read and written. Latexmk will then use this file to improve
its detection of source files and generated files after a run of
*latex. This is the default setting of latexmk, unless overrid-
den in an initialization file.
@@ -1426,28 +1436,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-rules-
- Do not show a list of latexmk's rules and dependencies after
+ Do not show a list of latexmk's rules and dependencies after
processing. (This is the default.)
-showextraoptions
- Show the list of extra *latex options that latexmk recognizes,
- but that it simply passes through to the programs *latex when
- they are run. These options are (currently) a combination of
- those allowed by the TeXLive and MiKTeX implementations. (If a
- particular option is given to latexmk but is not handled by the
- particular implementation of *latex that is being used, that
- program will probably give a warning or an error.) These op-
- tions are very numerous, but are not listed in this documenta-
- tion because they have no effect on latexmk's actions.
+ Show the list of extra *latex options that latexmk recognizes,
+ but that it simply passes through to the programs *latex when
+ they are run. These options are (currently) a combination of
- There are a few options (e.g., -includedirectory=dir, -initial-
- ize, -ini) that are not recognized, either because they don't
- fit with latexmk's intended operations, or because they need
-
- 7 April 2024 22
+ 27 December 2024 22
@@ -1456,105 +1456,117 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- special processing by latexmk that isn't implemented (at least,
+ those allowed by the TeXLive and MiKTeX implementations. (If a
+ particular option is given to latexmk but is not handled by the
+ particular implementation of *latex that is being used, that
+ program will probably give a warning or an error.) These op-
+ tions are very numerous, but are not listed in this documenta-
+ tion because they have no effect on latexmk's actions.
+
+ There are a few options (e.g., -includedirectory=dir, -initial-
+ ize, -ini) that are not recognized, either because they don't
+ fit with latexmk's intended operations, or because they need
+ special processing by latexmk that isn't implemented (at least,
not yet).
- There are certain options for *latex (e.g., -recorder) that
+ There are certain options for *latex (e.g., -recorder) that
trigger special actions or behavior by latexmk itself. Depending
- on the action, they may also be passed in some form to the
+ on the action, they may also be passed in some form to the
called *latex program, and/or may affect other programs as well.
- These options do have entries in this documentation. Among
+ These options do have entries in this documentation. Among
these options are: -jobname=STRING, -aux-directory=dir, -output-
directory=DIR, -quiet, and -recorder.
- There are also options that are accepted by *latex, but instead
+ There are also options that are accepted by *latex, but instead
trigger actions purely by latexmk: -help, -version.
-silent
Run commands silently, i.e., with options that reduce the amount
- of diagnostics generated. For example, with the default set-
- tings, the command "latex -interaction=batchmode" is used for
+ of diagnostics generated. For example, with the default set-
+ tings, the command "latex -interaction=batchmode" is used for
latex, and similarly for its friends.
- See also the -logfilewarninglist and -logfilewarninglist- op-
+ See also the -logfilewarninglist and -logfilewarninglist- op-
tions.
- Also reduce the number of informational messages that latexmk
+ Also reduce the number of informational messages that latexmk
itself generates.
- To change the options used to make the commands run silently,
+ To change the options used to make the commands run silently,
you need to configure latexmk with changed values of its config-
- uration variables, the relevant ones being $bib-
- tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch,
+ uration variables, the relevant ones being $bib-
+ tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch,
$dvips_silent_switch, $dvilualatex_silent_switch, $la-
- tex_silent_switch, $lualatex_silent_switch $makein-
- dex_silent_switch, $pdflatex_silent_switch, and $xela-
+ tex_silent_switch, $lualatex_silent_switch $makein-
+ dex_silent_switch, $pdflatex_silent_switch, and $xela-
tex_silent_switch
-stdtexcmds
- Sets the commands for latex, etc, so that they are the standard
+ Sets the commands for latex, etc, so that they are the standard
ones. This is useful to override special configurations.
- The result is that $latex = 'latex %O %S', and similarly for
- $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed
+ The result is that $latex = 'latex %O %S', and similarly for
+ $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed
for $xelatex is provided automatically, given that %O appears in
- the definition.)
- -time Show time used. (On MS Windows, what is shown is clock time; on
- other systems CPU time.) See also the configuration variable
- $show_time.
+ 27 December 2024 23
- -time- Do not show time used. See also the configuration variable
- $show_time.
- 7 April 2024 23
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ the definition.)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ -time Show time used. (On MS Windows, what is shown is clock time; on
+ other systems CPU time.) See also the configuration variable
+ $show_time.
+
+
+ -time- Do not show time used. See also the configuration variable
+ $show_time.
-use-make
- When after a run of *latex, there are warnings about missing
- files (e.g., as requested by the LaTeX \input, \include, and
- \includgraphics commands), latexmk tries to make them by a cus-
- tom dependency. If no relevant custom dependency with an appro-
+ When after a run of *latex, there are warnings about missing
+ files (e.g., as requested by the LaTeX \input, \include, and
+ \includgraphics commands), latexmk tries to make them by a cus-
+ tom dependency. If no relevant custom dependency with an appro-
priate source file is found, and if the -use-make option is set,
- then as a last resort latexmk will try to use the make program
+ then as a last resort latexmk will try to use the make program
to try to make the missing files.
- Note that the filename may be specified without an extension,
- e.g., by \includegraphics{drawing} in a LaTeX file. In that
- case, latexmk will try making drawing.ext with ext set in turn
- to the possible extensions that are relevant for latex (or as
+ Note that the filename may be specified without an extension,
+ e.g., by \includegraphics{drawing} in a LaTeX file. In that
+ case, latexmk will try making drawing.ext with ext set in turn
+ to the possible extensions that are relevant for latex (or as
appropriate pdflatex, lualatex, xelatex).
- See also the documentation for the $use_make_for_missing_files
+ See also the documentation for the $use_make_for_missing_files
configuration variable.
-use-make-
- Do not use the make program to try to make missing files. (De-
+ Do not use the make program to try to make missing files. (De-
fault.)
-usepretex
Sets the command lines for latex, etc, so that they use the code
- that is defined by the variable $pre_tex_code or that is set by
+ that is defined by the variable $pre_tex_code or that is set by
the option -pretex=CODE to execute the specified TeX code before
the source file is read. This option overrides any previous de-
finition of the command lines.
- The result is that $latex = 'latex %O %P', and similarly for
- $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed
+ The result is that $latex = 'latex %O %P', and similarly for
+ $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed
for $xelatex is provided automatically, given that %O appears in
the definition.)
@@ -1565,113 +1577,112 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
latexmk -usepretex='\AtBeginDocument{Message\par}' foo.tex
- -v or -version
- Print version number of latexmk.
-
- -verbose
- Opposite of -silent. This is the default setting.
+ 27 December 2024 24
- -view=default, -view=dvi, -view=ps, -view=pdf, -view=none
- Set the kind of file used when previewing is requested (e.g., by
- the -pv or -pvc switches). The default is to view the "highest"
- 7 April 2024 24
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ -v or -version
+ Print version number of latexmk.
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ -verbose
+ Opposite of -silent. This is the default setting.
- kind of requested file (in the low-to-high order .dvi, .ps,
- .pdf).
+ -view=default, -view=dvi, -view=hnt, -view=ps, -view=pdf, -view=none
+ Set the kind of file used when previewing is requested (e.g., by
+ the -pv or -pvc switches). The default is to view the "highest"
+ kind of requested file (in the low-to-high order .dvi, .hnt,
+ .ps, .pdf).
- Note the possibility -view=none where no viewer is opened at
- all. One example of is use is in conjunction with the -pvc op-
- tion, when you want latexmk to do a compilation automatically
- whenever source file(s) change, but do not want a previewer to
+ Note the possibility -view=none where no viewer is opened at
+ all. One example of is use is in conjunction with the -pvc op-
+ tion, when you want latexmk to do a compilation automatically
+ whenever source file(s) change, but do not want a previewer to
be opened.
-Werror
- This causes latexmk to return a non-zero status code if any of
- the files processed gives a warning about problems with cita-
- tions or references (i.e., undefined citations or references or
- about multiply defined references). This is after latexmk has
- completed all the runs it needs to try and resolve references
- and citations. Thus -Werror causes latexmk to treat such warn-
+ This causes latexmk to return a non-zero status code if any of
+ the files processed gives a warning about problems with cita-
+ tions or references (i.e., undefined citations or references or
+ about multiply defined references). This is after latexmk has
+ completed all the runs it needs to try and resolve references
+ and citations. Thus -Werror causes latexmk to treat such warn-
ings as errors, but only when they occur on the last run of *la-
- tex and only after processing is complete. Also can be set by
+ tex and only after processing is complete. Also can be set by
the configuration variable $warnings_as_errors.
- -xdv Generate xdv version of document using xelatex.
+ -xdv Generate xdv version of document using xelatex. (And turn off
+ any incompatible requests.)
-xelatex
- Use xelatex. That is, use xelatex to process the source file(s)
- to pdf. The generation of dvi and postscript files is turned
- off.
+ Use xelatex. That is, use xelatex to process the source
+ file(s). This will cause generation of a pdf (but indirectly
+ through a xdv file). (And turn off any incompatible requests.)
- This option is equivalent to using the following set of options
+ This option is equivalent to using the following option
- -pdfxe -dvi- -ps-
+ -pdfxe
- [Note: Note that the method of implementation of this option,
- but not its intended primary effect, differ from some earlier
- versions of latexmk. Latexmk first uses xelatex to make an .xdv
- file, and does all the extra runs needed (including those of
- bibtex, etc). Only after that does it make the pdf file from
- the .xdv file, using xdvipdfmx. See the documentation for the
+ [Note: Note that the method of implementation of this option,
+ but not its intended primary effect, differ from some earlier
+ versions of latexmk. Latexmk first uses xelatex to make an .xdv
+ file, and does all the extra runs needed (including those of
+ bibtex, etc). Only after that does it make the pdf file from
+ the .xdv file, using xdvipdfmx. See the documentation for the
-pdfxe for why this is done.]
- -xelatex="COMMAND"
- This sets the string specifying the command to run xelatex. It
- sets the variable $xelatex.
-
- Warning: It is important to ensure that the -no-pdf is used when
- xelatex is invoked, since latexmk expects xelatex to produce an
- .xdv file, not a .pdf file. If you provide %O in the command
- specification, this will be done automatically. See the docu-
- mentation for the -pdfxe option for why latexmk makes a .xdv
- file rather than a .pdf file when xelatex is used.
+ 27 December 2024 25
- 7 April 2024 25
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ -xelatex="COMMAND"
+ This sets the string specifying the command to run xelatex. It
+ sets the variable $xelatex.
+ Warning: It is important to ensure that the -no-pdf is used when
+ xelatex is invoked, since latexmk expects xelatex to produce an
+ .xdv file, not a .pdf file. If you provide %O in the command
+ specification, this will be done automatically. See the docu-
+ mentation for the -pdfxe option for why latexmk makes a .xdv
+ file rather than a .pdf file when xelatex is used.
- An example of the use of the -pdfxelatex option:
+ An example of the use of the -xelatex option:
- latexmk -pdfxe -pdfxelatex="xelatex --shell-escape %O %S"
+ latexmk -pdfxe -xelatex="xelatex --shell-escape %O %S"
foo.tex
- Note: This option when provided with the COMMAND argument only
- sets the command for invoking lualatex; it does not turn on the
+ Note: This option when provided with the COMMAND argument only
+ sets the command for invoking xelatex; it does not turn on the
use of lualatex. That is done by other options or in an initial-
ization file.
Compatibility between options
- The preview-continuous option -pvc can only work with one file. So in
- this case you will normally only specify one filename on the command
+ The preview-continuous option -pvc can only work with one file. So in
+ this case you will normally only specify one filename on the command
line.
- Options -p, -pv and -pvc are mutually exclusive. So each of these op-
+ Options -p, -pv and -pvc are mutually exclusive. So each of these op-
tions turns the others off.
@@ -1696,22 +1707,11 @@ EXAMPLES
-DEALING WITH ERRORS, PROBLEMS, ETC
- Some possibilities:
- a. If you get a strange error, do look carefully at the output that is
- on the screen and in log files. While there is much that is notori-
- ously verbose in the output of latex (and that is added to by latexmk),
- the verbosity is there for a reason: to enable the user to diagnose
- problems. Latexmk does repeat some messages at the end of a run that
- it thinks would otherwise be easy to miss in the middle of other out-
- put.
- b. Generally, remember that latexmk does its work by running other
-
- 7 April 2024 26
+ 27 December 2024 26
@@ -1720,11 +1720,23 @@ DEALING WITH ERRORS, PROBLEMS, ETC
LATEXMK(1) General Commands Manual LATEXMK(1)
- programs. Your first priority in dealing with errors should be to ex-
- amine what went wrong with the individual programs. Then you need to
- correct the causes of errors in the runs of these programs. (Often
- these come from errors in the source document, but they could also be
- about missing LaTeX packages, etc.)
+DEALING WITH ERRORS, PROBLEMS, ETC
+ Some possibilities:
+
+ a. If you get a strange error, do look carefully at the output that is
+ on the screen and in log files. While there is much that is notori-
+ ously verbose in the output of latex (and that is added to by latexmk),
+ the verbosity is there for a reason: to enable the user to diagnose
+ problems. Latexmk does repeat some messages at the end of a run that
+ it thinks would otherwise be easy to miss in the middle of other out-
+ put.
+
+ b. Generally, remember that latexmk does its work by running other pro-
+ grams. Your first priority in dealing with errors should be to examine
+ what went wrong with the individual programs. Then you need to correct
+ the causes of errors in the runs of these programs. (Often these come
+ from errors in the source document, but they could also be about miss-
+ ing LaTeX packages, etc.)
c. If latexmk doesn't run the programs the way you would like, then you
need to look in this documentation at the list of command line options
@@ -1762,29 +1774,28 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
g. See also the section "Advanced Configuration: Some extra resources".
- h. Look on tex.stackexchange, i.e., at http://tex.stackex-
- change.com/questions/tagged/latexmk Someone may have already solved
- your problem.
- i. Ask a question at tex.stackexchange.com.
- j. Or ask me (the author of latexmk). My e-mail is at the end of this
- documentation.
+ 27 December 2024 27
+LATEXMK(1) General Commands Manual LATEXMK(1)
- 7 April 2024 27
+ h. Look on tex.stackexchange, i.e., at http://tex.stackex-
+ change.com/questions/tagged/latexmk Someone may have already solved
+ your problem.
+ i. Ask a question at tex.stackexchange.com.
+ j. Or ask me (the author of latexmk). My e-mail is at the end of this
+ documentation.
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
AUXILIARY AND OUTPUT DIRECTORIES
Running *latex and the associated programs generate a number of files,
@@ -1829,21 +1840,10 @@ AUXILIARY AND OUTPUT DIRECTORIES
separate aux and output directories. Latexmk deals with this by being
able to emulating a separate aux directory: In this method it invokes
*latex with just an -output-directory option, with the directory set
- not to the desired output directory, but to the aux directory. After
- running *latex, it moves the relevant final output file(s) to the in-
- tended output directory. Emulation can be turned on by setting the
- configuration variable $emulate_aux to one in a configuration file or
- by using latexmk's -emulate-aux-dir option. The emulation method works
- equally well if MiKTeX is used.
-
- Latexmk also turns emulation on if it is found to be needed, as fol-
- lows. Suppose emulation is initially off, but the aux and output di-
- rectories are different. Then latexmk invokes *latex with an -aux-di-
- rectory option and after the run finds that it hasn't been obeyed,
- 7 April 2024 28
+ 27 December 2024 28
@@ -1852,12 +1852,23 @@ AUXILIARY AND OUTPUT DIRECTORIES
LATEXMK(1) General Commands Manual LATEXMK(1)
- notably because the .log file is in the output directory rather than
- the aux directory. Latexmk then sets emulation on, and retries. Con-
- ceivably, it could move all the appropriate generated files from the
- output directory to the aux directory; but there is such a large vari-
- ety of possibilities for these files that this is hard to identify all
- of them reliably except for simple cases.
+ not to the desired output directory, but to the aux directory. After
+ running *latex, it moves the relevant final output file(s) to the in-
+ tended output directory. Emulation can be turned on by setting the
+ configuration variable $emulate_aux to one in a configuration file or
+ by using latexmk's -emulate-aux-dir option. The emulation method works
+ equally well if MiKTeX is used.
+
+ Latexmk also turns emulation on if it is found to be needed, as fol-
+ lows. Suppose emulation is initially off, but the aux and output di-
+ rectories are different. Then latexmk invokes *latex with an -aux-di-
+ rectory option and after the run finds that it hasn't been obeyed, no-
+ tably because the .log file is in the output directory rather than the
+ aux directory. Latexmk then sets emulation on, and retries. Conceiv-
+ ably, it could move all the appropriate generated files from the output
+ directory to the aux directory; but there is such a large variety of
+ possibilities for these files that this is hard to identify all of them
+ reliably except for simple cases.
Note that the emulation issue only arises when the user has arranged
for the the aux and output directories to be different. When instead
@@ -1895,29 +1906,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
the default is to set it equal to the output directory. For the output
directory, the default is to be the current directory.
- For the turning on and off of the emulation mode, there is the configu-
- ration variable $emulate_aux and the options -emulate-aux-dir, -emu-
- late-aux-dir-, -noemulate-aux-dir.
- Interaction with -cd option: When the -cd option is used (or the equiv-
- alent setting of $do_cd variable), then latexmk changes the working di-
- rectory to the document directory before invoking *latex. If the aux
- and/or output directories are given by relative paths, e.g., by -out-
- dir=output for a directory named "output", then the directories are
- relative to the document directory, rather than relative to the working
+ 27 December 2024 29
- 7 April 2024 29
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ For the turning on and off of the emulation mode, there is the configu-
+ ration variable $emulate_aux and the options -emulate-aux-dir, -emu-
+ late-aux-dir-, -noemulate-aux-dir.
+ Interaction with -cd option: When the -cd option is used (or the equiv-
+ alent setting of $do_cd variable), then latexmk changes the working di-
+ rectory to the document directory before invoking *latex. If the aux
+ and/or output directories are given by relative paths, e.g., by -out-
+ dir=output for a directory named "output", then the directories are
+ relative to the document directory, rather than relative to the working
directory that was in effect when latexmk was invoked. This matches the
behavior of *latex as invoked with the provided command line directory
argument(s) after the change of working directory to the document di-
@@ -1962,20 +1973,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
variable openout_any to "a" (as in "all"), to override the default
"paranoid" setting.
- Certain names of aux and output directories not allowed on Microsoft
- Windows: It is natural to want to use the name "aux" for the aux direc-
- tory, e.g., by using the option -auxdir=aux. But on Microsoft operat-
- ing systems "aux" is one of the names that is not allowed for a file or
- directory. I find it useful to standardize on a name like "auxdir"
- (e.g., by -auxdir=auxdir); this works independently of operating sys-
- tem.
-
- Location of .fls file: Much of the dependency information that latexmk
- uses comes from the .fls file generated when *latex is invoked with the
-
- 7 April 2024 30
+ 27 December 2024 30
@@ -1984,6 +1984,16 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ Certain names of aux and output directories not allowed on Microsoft
+ Windows: It is natural to want to use the name "aux" for the aux direc-
+ tory, e.g., by using the option -auxdir=aux. But on Microsoft operat-
+ ing systems "aux" is one of the names that is not allowed for a file or
+ directory. I find it useful to standardize on a name like "auxdir"
+ (e.g., by -auxdir=auxdir); this works independently of operating sys-
+ tem.
+
+ Location of .fls file: Much of the dependency information that latexmk
+ uses comes from the .fls file generated when *latex is invoked with the
-recorder option, which latexmk does by default. It may seem rational
that this is written to the aux directory. But in fact versions of
MiKTeX prior to Oct. 2020 wrote it to the output directory. Later ver-
@@ -2029,19 +2039,9 @@ ALLOWING FOR CHANGE OF OUTPUT FILE TYPE
useful to force output to be of the .dvi format by inserting \pdfout-
put=0 in the preamble of the document.
- Another example is where the document uses graphics file of the .pdf,
- .jpg, and png types. With the default setting for the graphicx pack-
- age, these can be processed in compilation to .pdf but not with compi-
- lation to .dvi. In this case, it is useful to insert \pdfoutput=1 in
- the preamble of the document to force compilation to .pdf output for-
- mat.
- In all of these cases, it is needed that latexmk has to adjust its pro-
- cessing to deal with a mismatch between the actual output format (out
-
-
- 7 April 2024 31
+ 27 December 2024 31
@@ -2050,6 +2050,15 @@ ALLOWING FOR CHANGE OF OUTPUT FILE TYPE
LATEXMK(1) General Commands Manual LATEXMK(1)
+ Another example is where the document uses graphics file of the .pdf,
+ .jpg, and png types. With the default setting for the graphicx pack-
+ age, these can be processed in compilation to .pdf but not with compi-
+ lation to .dvi. In this case, it is useful to insert \pdfoutput=1 in
+ the preamble of the document to force compilation to .pdf output for-
+ mat.
+
+ In all of these cases, it is needed that latexmk has to adjust its pro-
+ cessing to deal with a mismatch between the actual output format (out
of .pdf, .dvi, .xdv) and the initially expected output, if possible.
Latexmk does this provided the following conditions are met.
@@ -2095,19 +2104,10 @@ CONFIGURATION/INITIALIZATION (RC) FILES
The
directories are searched in the following order, and latexmk uses
the first such file it finds (if any):
- "/etc",
- "/opt/local/share/latexmk",
- "/usr/local/share/latexmk",
- "/usr/local/lib/latexmk".
- On a MS-Windows system it looks just in "C:\latexmk".
- On a cygwin system (i.e., a MS-Windows system in which Perl is that
- of cygwin), latexmk looks in the directories
- "/cygdrive/c/latexmk",
- "/etc",
- 7 April 2024 32
+ 27 December 2024 32
@@ -2116,6 +2116,15 @@ CONFIGURATION/INITIALIZATION (RC) FILES
LATEXMK(1) General Commands Manual LATEXMK(1)
+ "/etc",
+ "/opt/local/share/latexmk",
+ "/usr/local/share/latexmk",
+ "/usr/local/lib/latexmk".
+ On a MS-Windows system it looks just in "C:\latexmk".
+ On a cygwin system (i.e., a MS-Windows system in which Perl is that
+ of cygwin), latexmk looks in the directories
+ "/cygdrive/c/latexmk",
+ "/etc",
"/opt/local/share/latexmk",
"/usr/local/share/latexmk",
"/usr/local/lib/latexmk".
@@ -2161,25 +2170,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Note that command line options are obeyed in the order in which they
are written; thus any RC file specified on the command line with the -r
- option can override previous options but can be itself overridden by
- later options on the command line. There is also the -e option, which
- allows initialization code to be specified in latexmk's command line.
- For possible examples of code for in an RC file, see the directory ex-
- ample_rcfiles in the distribution of latexmk (e.g., at http://mir-
- ror.ctan.org/support/latexmk/example_rcfiles).
+ 27 December 2024 33
- 7 April 2024 33
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ option can override previous options but can be itself overridden by
+ later options on the command line. There is also the -e option, which
+ allows initialization code to be specified in latexmk's command line.
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ For possible examples of code for in an RC file, see the directory ex-
+ ample_rcfiles in the distribution of latexmk (e.g., at http://mir-
+ ror.ctan.org/support/latexmk/example_rcfiles).
HOW TO SET VARIABLES IN INITIALIZATION FILES
@@ -2228,26 +2237,25 @@ FORMAT OF COMMAND SPECIFICATIONS
bilities listed here do not apply to the $kpsewhich variable; see its
documentation.)
- Placeholders: Supposed you wanted latexmk to use the command elatex in
- place of the regular latex command, and suppose moreover that you
- wanted to give it the option "--shell-escape". You could do this by
- the following setting:
-
- $latex = 'elatex --shell-escape %O %S';
- The two items starting with the % character are placeholders. These
+ 27 December 2024 34
- 7 April 2024 34
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ Placeholders: Supposed you wanted latexmk to use the command elatex in
+ place of the regular latex command, and suppose moreover that you
+ wanted to give it the option "--shell-escape". You could do this by
+ the following setting:
+ $latex = 'elatex --shell-escape %O %S';
+ The two items starting with the % character are placeholders. These
are substituted by appropriate values before the command is run. Thus
%S will be replaced by the source file that elatex will be applied to,
and %O will be replaced by any options that latexmk has decided to use
@@ -2293,19 +2301,11 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
%T The name of the primary tex file.
- %U If the variable $pre_tex_code is non-empty, then its value is
- substituted for %U (appropriately quoted). Otherwise it is re-
- placed by a null string.
- %Y Name of directory for auxiliary output files (see the configura-
- tion variable $aux_dir). A directory separation character ('/')
- is appended if $aux_dir is non-empty and does not end in a suit-
- able character, with suitable characters being those appropriate
- to UNIX and MS-Windows, i.e., ':', '/' and '\'. Note that if
- 7 April 2024 35
+ 27 December 2024 35
@@ -2314,6 +2314,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ %U If the variable $pre_tex_code is non-empty, then its value is
+ substituted for %U (appropriately quoted). Otherwise it is re-
+ placed by a null string.
+
+ %Y Name of directory for auxiliary output files (see the configura-
+ tion variable $aux_dir). A directory separation character ('/')
+ is appended if $aux_dir is non-empty and does not end in a suit-
+ able character, with suitable characters being those appropriate
+ to UNIX and MS-Windows, i.e., ':', '/' and '\'. Note that if
after initialization, $out_dir is set, but $aux_dir is not set
(i.e., it is blank), then latexmk sets $aux_dir to the same
value $out_dir.
@@ -2359,19 +2368,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Notes: (1) In some circumstances, latexmk will always run a command de-
tached. This is the case for a previewer in preview continuous mode,
- since otherwise previewing continuously makes no sense. (2) This pre-
- cludes the possibility of running a command named start. (3) If the
- word start occurs more than once at the beginning of the command
- string, that is equivalent to having just one. (4) Under cygwin, some
- complications happen, since cygwin amounts to a complicated merging of
- UNIX and MS-Windows. See the source code for how I've handled the
- problem.
-
- Command names containing spaces: Under MS-Windows it is common that the
- 7 April 2024 36
+ 27 December 2024 36
@@ -2380,6 +2380,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ since otherwise previewing continuously makes no sense. (2) This pre-
+ cludes the possibility of running a command named start. (3) If the
+ word start occurs more than once at the beginning of the command
+ string, that is equivalent to having just one. (4) Under cygwin, some
+ complications happen, since cygwin amounts to a complicated merging of
+ UNIX and MS-Windows. See the source code for how I've handled the
+ problem.
+
+ Command names containing spaces: Under MS-Windows it is common that the
name of a command includes spaces, since software is often installed in
a subdirectory of "C:\Program Files". Such command names should be en-
closed in double quotes, as in
@@ -2425,26 +2434,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$lpr = 'NONE lpr';
- This typically is used when an appropriate command does not exist on
- your system. The string after the "NONE" is effectively a comment.
- Options to commands: Setting the name of a command can be used not only
- for changing the name of the command called, but also to add options to
- command. Suppose you want latexmk to use latex with source specials
- enabled. Then you might use the following line in an initialization
- file:
+ 27 December 2024 37
- 7 April 2024 37
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ This typically is used when an appropriate command does not exist on
+ your system. The string after the "NONE" is effectively a comment.
+ Options to commands: Setting the name of a command can be used not only
+ for changing the name of the command called, but also to add options to
+ command. Suppose you want latexmk to use latex with source specials
+ enabled. Then you might use the following line in an initialization
+ file:
$latex = 'latex --src-specials %O %S';
@@ -2491,26 +2500,27 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Here, the UNIX command separator ; is replaced by &&. In addition,
there is a problem that some versions of Perl on MS-Windows do not obey
- the command separator; this problem is overcome by explicitly invoking
- the MS-Windows command-line processor cmd.exe.
-LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
- In this section are specified the variables whose values can be ad-
- justed to configure latexmk. (See the earlier section "Configura-
- tion/Initialization (rc) Files" for the files where the configurations
- are done.)
+ 27 December 2024 38
- 7 April 2024 38
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ the command separator; this problem is overcome by explicitly invoking
+ the MS-Windows command-line processor cmd.exe.
+
+LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
+ In this section are specified the variables whose values can be ad-
+ justed to configure latexmk. (See the earlier section "Configura-
+ tion/Initialization (rc) Files" for the files where the configurations
+ are done.)
Default values are indicated in brackets. Note that for variables that
are boolean in character, concerning whether latexmk does or does not
@@ -2555,21 +2565,11 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$always_view_file_via_temporary [0]
Whether .ps and .pdf files are initially to be made in a tempo-
- rary directory and then moved to the final location. (This ap-
- plies to dvips, dvipdf, and ps2pdf operations, and the filtering
- operators on .dvi and .ps files. It does not apply to pdflatex,
- unfortunately, since pdflatex provides no way of specifying a
- chosen name for the output file.)
-
- This use of a temporary file solves a problem that the making of
- these files can occupy a substantial time. If a viewer (notably
- gv) sees that the file has changed, it may read the new file be-
- fore the program writing the file has not yet finished its work,
- which can cause havoc.
+ rary directory and then moved to the final location. (This
- 7 April 2024 39
+ 27 December 2024 39
@@ -2578,6 +2578,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ applies to dvips, dvipdf, and ps2pdf operations, and the filter-
+ ing operators on .dvi and .ps files. It does not apply to
+ pdflatex, unfortunately, since pdflatex provides no way of spec-
+ ifying a chosen name for the output file.)
+
+ This use of a temporary file solves a problem that the making of
+ these files can occupy a substantial time. If a viewer (notably
+ gv) sees that the file has changed, it may read the new file be-
+ fore the program writing the file has not yet finished its work,
+ which can cause havoc.
+
See the $pvc_view_file_via_temporary variable for a setting that
applies only if preview-continuous mode (-pvc option) is used.
See $tmpdir for the setting of the directory where the temporary
@@ -2622,28 +2633,27 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
The aux directory, i.e., the directory in which auxiliary files
(aux, log, etc) are to be written by a run of *latex.
- If this variable is not set, but $out_dir is set, then latexmk
- takes the aux directory to equal the output directory which is
- the directory to which final output files are to be written.
- If neither variable is set, then the current directory when *la-
- tex is invoked is used both for the aux and output directories.
- If the aux and output directories are distinct, then the aux di-
- rectory contains all generated files with the exception of "fi-
- nal output files", which are defined to be .dvi, .ps, .pdf,
+ 27 December 2024 40
- 7 April 2024 40
-
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ If this variable is not set, but $out_dir is set, then latexmk
+ takes the aux directory to equal the output directory which is
+ the directory to which final output files are to be written.
+ If neither variable is set, then the current directory when *la-
+ tex is invoked is used both for the aux and output directories.
+ If the aux and output directories are distinct, then the aux di-
+ rectory contains all generated files with the exception of "fi-
+ nal output files", which are defined to be .dvi, .ps, .pdf,
.synctex, and .synctex.gz files.
See the section AUXILIARY AND OUTPUT DIRECTORIES for more de-
@@ -2690,18 +2700,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
occurring inside constructs.
- $banner [0]
- If nonzero, the banner message is printed across each page when
- converting the dvi file to postscript. Without modifying the
- variable $banner_message, this is equivalent to specifying the
- -d option.
-
- Note that if $banner is nonzero, the $postscript_mode is assumed
- and the postscript file is always generated, even if it is newer
-
-
- 7 April 2024 41
+ 27 December 2024 41
@@ -2710,6 +2710,14 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ $banner [0]
+ If nonzero, the banner message is printed across each page when
+ converting the dvi file to postscript. Without modifying the
+ variable $banner_message, this is equivalent to specifying the
+ -d option.
+
+ Note that if $banner is nonzero, the $postscript_mode is assumed
+ and the postscript file is always generated, even if it is newer
than the dvi file.
$banner_intensity [0.95]
@@ -2756,24 +2764,23 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
rent version of latexmk, since it now uses a better method of
searching for files using the kpsewhich command. However, if
your system is an unusual one without the kpsewhich command, you
- may need to set the variable @BIBINPUTS.
-
- $biber ["biber %O %S"]
- The biber processing program.
+ 27 December 2024 42
- 7 April 2024 42
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ may need to set the variable @BIBINPUTS.
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ $biber ["biber %O %S"]
+ The biber processing program.
$biber_silent_switch ["--onlylog"]
@@ -2823,17 +2830,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
The possible values of $bibtex_use are:
0: never use bibtex or biber; never delete .bbl files in a
- cleanup.
- 1: only use bibtex or biber if the bib file(s) exist; never
- delete .bbl files in a cleanup.
- 1.5: only use bibtex or biber if the bib files exist;
- conditionally delete .bbl files in a cleanup (i.e., delete
- them only when
- the bib files all exist).
- 7 April 2024 43
+ 27 December 2024 43
@@ -2842,6 +2842,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ cleanup.
+ 1: only use bibtex or biber if the bib file(s) exist; never
+ delete .bbl files in a cleanup.
+ 1.5: only use bibtex or biber if the bib files exist;
+ conditionally delete .bbl files in a cleanup (i.e., delete
+ them only when
+ the bib files all exist).
2: run bibtex or biber whenever it appears necessary to update
the bbl file(s), without testing for the existence of the bib
files; always delete .bbl files in a cleanup.
@@ -2889,17 +2896,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
This variable is equivalent to specifying one of the -c or -C
options. But there should be no need to set this variable from
- an RC file.
-
- $clean_ext [""]
- Extra extensions of files for latexmk to remove when any of the
- clean-up options (-c or -C) is selected. The value of this
- variable is a string containing the extensions separated by
- spaces.
- 7 April 2024 44
+ 27 December 2024 44
@@ -2908,6 +2908,14 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ an RC file.
+
+ $clean_ext [""]
+ Extra extensions of files for latexmk to remove when any of the
+ clean-up options (-c or -C) is selected. The value of this
+ variable is a string containing the extensions separated by
+ spaces.
+
It is also possible to specify a more general pattern of file to
be deleted, by using the place holder %R, as in commands, and it
is also possible to use wildcards. Thus setting
@@ -2953,85 +2961,77 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
array @generated_exts.
$clean_full_ext [""]
- Extra extensions of files for latexmk to remove when the -C op-
- tion is selected, i.e., extensions of files to remove when the
- .dvi, etc files are to be cleaned-up.
+ Extra extensions of files for latexmk to remove when the -C
- More general patterns are allowed, as for $clean_ext.
- The files specified by $clean_full_ext to be deleted are rela-
- tive to the directory specified by $out_dir.
+ 27 December 2024 45
- 7 April 2024 45
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ option is selected, i.e., extensions of files to remove when the
+ .dvi, etc files are to be cleaned-up.
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ More general patterns are allowed, as for $clean_ext.
+
+ The files specified by $clean_full_ext to be deleted are rela-
+ tive to the directory specified by $out_dir.
$compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd
[""]
- These variables specify commands that are executed at certain
- points of compilations. One motivation for their existence is
- to allow very useful convenient visual indications of compila-
- tion status even when the window receiving the screen output of
- the compilation is hidden. This is particularly useful in pre-
+ These variables specify commands that are executed at certain
+ points of compilations. One motivation for their existence is
+ to allow very useful convenient visual indications of compila-
+ tion status even when the window receiving the screen output of
+ the compilation is hidden. This is particularly useful in pre-
view-continuous mode.
- The commands are executed at the following points: $compil-
- ing_cmd at the start of compilation, $success_cmd at the end of
- a completely successful compilation, $failure_cmd at the end of
+ The commands are executed at the following points: $compil-
+ ing_cmd at the start of compilation, $success_cmd at the end of
+ a completely successful compilation, $failure_cmd at the end of
an unsuccessful compilation, $warning_cmd at the of an otherwise
successful compilation that gives warnings about undefined cita-
tions or references or about multiply defined references. If any
- of above variables is undefined or blank (the default situa-
+ of above variables is undefined or blank (the default situa-
tion), then the corresponding command is not executed.
- However, when $warning_cmd is not set, then in the case of a
- compilation with warnings about references or citations, but
- with no other error, one or other of $success_cmd or $fail-
- ure_cmd is used (if it is set) according to the setting of
+ However, when $warning_cmd is not set, then in the case of a
+ compilation with warnings about references or citations, but
+ with no other error, one or other of $success_cmd or $fail-
+ ure_cmd is used (if it is set) according to the setting of
$warnings_as_errors.
An example of a simple setting of these variables is as follows
- $compiling_cmd = "xdotool search --name \"%D\" set_window
+ $compiling_cmd = "xdotool search --name \"%D\" set_window
--name \"%D compiling\"";
- $success_cmd = "xdotool search --name \"%D\" set_window
+ $success_cmd = "xdotool search --name \"%D\" set_window
--name \"%D OK\"";
$warning_cmd = "xdotool search --name \"%D\" ".
"set_window --name \"%D CITE/REF ISSUE\"";
- $failure_cmd = "xdotool search --name \"%D\" set_window
+ $failure_cmd = "xdotool search --name \"%D\" set_window
--name \"%D FAILURE\"";
- These assume that the program xdotool is installed, that the
- previewer is using an X-Window system for display, and that the
- title of the window contains the name of the displayed file, as
- it normally does. When the commands are executed, the place-
- holder string %D is replaced by the name of the destination
+ These assume that the program xdotool is installed, that the
+ previewer is using an X-Window system for display, and that the
+ title of the window contains the name of the displayed file, as
+ it normally does. When the commands are executed, the place-
+ holder string %D is replaced by the name of the destination
file, which is the previewed file. The above commands result in
an appropriate string being appended to the filename in the win-
dow title: " compiling", " OK", or " FAILURE".
- Other placeholders that can be used are %S, %T, and %R, with %S
- and %T normally being identical. These can be useful for a com-
- mand changing the title of the edit window. The visual indica-
- tion in a window title can useful, since the user does not have
- to keep shifting attention to the (possibly hidden) compilation
- window to know the status of the compilation.
- More complicated situations can best be handled by defining a
- Perl subroutine to invoke the necessary commands, and using the
-
- 7 April 2024 46
+ 27 December 2024 46
@@ -3040,12 +3040,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- "internal" keyword in the definitions to get the subroutine to
+ Other placeholders that can be used are %S, %T, and %R, with %S
+ and %T normally being identical. These can be useful for a com-
+ mand changing the title of the edit window. The visual indica-
+ tion in a window title can useful, since the user does not have
+ to keep shifting attention to the (possibly hidden) compilation
+ window to know the status of the compilation.
+
+ More complicated situations can best be handled by defining a
+ Perl subroutine to invoke the necessary commands, and using the
+ "internal" keyword in the definitions to get the subroutine to
be invoked. (See the section "Format of Command Specifications"
for how to do this.)
- Naturally, the above settings that invoke the xdotool program
- are only applicable when the X-Window system is used for the
+ Naturally, the above settings that invoke the xdotool program
+ are only applicable when the X-Window system is used for the
relevant window(s). For other cases, you will have to find what
software solutions are available.
@@ -3054,15 +3063,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Custom dependency list -- see section on "Custom Dependencies".
@default_excluded_files [()]
- When latexmk is invoked with no files specified on the command
+ When latexmk is invoked with no files specified on the command
line, then, by default, it will process all files in the current
directory with the extension .tex. (In general, it will process
the files specified in the @default_files variable.)
But sometimes you want to exclude particular files from this de-
- fault list. In that case you can specify the excluded files in
+ fault list. In that case you can specify the excluded files in
the array @default_excluded_files. For example if you wanted to
- process all .tex files with the exception of common.tex, which
+ process all .tex files with the exception of common.tex, which
is a not a standard alone LaTeX file but a file input by some or
all of the others, you could do
@@ -3072,32 +3081,23 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
If you have a variable or large number of files to be processed,
this method saves you from having to list them in detail in @de-
- fault_files and having to update the list every time you change
+ fault_files and having to update the list every time you change
the set of files to be processed.
- Notes: 1. This variable has no effect except when no files are
+ Notes: 1. This variable has no effect except when no files are
specified on the latexmk command line. 2. Wildcards are allowed
in @default_excluded_files.
@default_files [("*.tex")]
Default list of files to be processed.
- If no filenames are specified on the command line, latexmk
- processes all tex files specified in the @default_files vari-
- able, which by default is set to all tex files ("*.tex") in the
- current directory. This is a convenience: just run latexmk and
- it will process an appropriate set of files. But sometimes you
- want only some of these files to be processed. In this case you
- can list the files to be processed by setting @default_files in
- an initialization file (e.g., the file "latexmkrc" in the cur-
- rent directory). Then if no files are specified on the command
- line then the files you specify by setting @default_files are
- processed.
+ If no filenames are specified on the command line, latexmk
+ processes all tex files specified in the @default_files vari-
+ able, which by default is set to all tex files ("*.tex") in the
-
- 7 April 2024 47
+ 27 December 2024 47
@@ -3106,6 +3106,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ current directory. This is a convenience: just run latexmk and
+ it will process an appropriate set of files. But sometimes you
+ want only some of these files to be processed. In this case you
+ can list the files to be processed by setting @default_files in
+ an initialization file (e.g., the file "latexmkrc" in the cur-
+ rent directory). Then if no files are specified on the command
+ line then the files you specify by setting @default_files are
+ processed.
+
Three examples:
@default_files = ("paper_current");
@@ -3114,56 +3123,47 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
@default_files = ("*.tex", "*.dtx");
- Note that more than file may be given, and that the default ex-
+ Note that more than file may be given, and that the default ex-
tension is ".tex". Wild cards are allowed. The parentheses are
because @default_files is an array variable, i.e., a sequence of
filename specifications is possible.
- If you want latexmk to process all .tex files with a few excep-
+ If you want latexmk to process all .tex files with a few excep-
tions, see the @default_excluded_files array variable.
$dependents_phony [0]
- If a list of dependencies is output, this variable determines
- whether to include a phony target for each source file. If you
- use the dependents list in a Makefile, the dummy rules work
- around errors make gives if you remove header files without up-
+ If a list of dependencies is output, this variable determines
+ whether to include a phony target for each source file. If you
+ use the dependents list in a Makefile, the dummy rules work
+ around errors make gives if you remove header files without up-
dating the Makefile to match.
$dependents_list [0]
- Whether to display a list(s) of dependencies at the end of a
+ Whether to display a list(s) of dependencies at the end of a
run.
$deps_escape ["none"]
This variable determines which kind of escaping of space charac-
ters to use in dependency lists. The possible values are "none",
- "unix", "nmake", corresponding respectively to no escaping, es-
- caping with a "\" suitable for standard Unix make, and escaping
+ "unix", "nmake", corresponding respectively to no escaping, es-
+ caping with a "\" suitable for standard Unix make, and escaping
with "^", suitable for Microsoft's nmake.
- Currently the only character escaped is a space, since that is
- particularly common in file names and directory names. There
- are other characters that would need escaping if a dependency
+ Currently the only character escaped is a space, since that is
+ particularly common in file names and directory names. There
+ are other characters that would need escaping if a dependency
list is to be used as-is by a make program; but those characters
(e.g., "$") commonly cause difficulties when used for .tex docu-
- ments. Moreover, the detailed rules for which characters need
+ ments. Moreover, the detailed rules for which characters need
to be escaped depends on the version of make.
- $deps_file ["-"]
- Name of file to receive list(s) of dependencies at the end of a
- run, to be used if $dependents_list is set. If the filename is
- "-", then the dependency list is set to stdout (i.e., normally
- the screen).
- $do_cd [0]
- Whether to change working directory to the directory specified
- for the main source file before processing it. The default
-
- 7 April 2024 48
+ 27 December 2024 48
@@ -3172,7 +3172,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- behavior is not to do this, which is the same as the behavior of
+ $deps_file ["-"]
+ Name of file to receive list(s) of dependencies at the end of a
+ run, to be used if $dependents_list is set. If the filename is
+ "-", then the dependency list is set to stdout (i.e., normally
+ the screen).
+
+
+ $do_cd [0]
+ Whether to change working directory to the directory specified
+ for the main source file before processing it. The default be-
+ havior is not to do this, which is the same as the behavior of
*latex programs. This variable is set by the -cd and -cd- op-
tions on latexmk's command line.
@@ -3218,18 +3228,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
that equally applies to $dvilualatex_silent_switch.
- $dvi_previewer ["start xdvi %O %S" under UNIX]
- The command to invoke a dvi-previewer. [Under MS-Windows the
- default is "start"; then latexmk arranges to use the MS-Windows
- start program, which will cause to be run whatever command the
- system has associated with .dvi files.]
-
- Important note: Normally you will want to have a previewer run
- detached, so that latexmk doesn't wait for the previewer to
-
-
- 7 April 2024 49
+ 27 December 2024 49
@@ -3238,64 +3238,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- terminate before continuing its work. So normally you should
- prefix the command by "start ", which flags to latexmk that it
- should do the detaching of the previewer itself (by whatever
- method is appropriate to the operating system). But sometimes
+ $dvi_previewer ["start xdvi %O %S" under UNIX]
+ The command to invoke a dvi-previewer. [Under MS-Windows the
+ default is "start"; then latexmk arranges to use the MS-Windows
+ start program, which will cause to be run whatever command the
+ system has associated with .dvi files.]
+
+ Important note: Normally you will want to have a previewer run
+ detached, so that latexmk doesn't wait for the previewer to ter-
+ minate before continuing its work. So normally you should pre-
+ fix the command by "start ", which flags to latexmk that it
+ should do the detaching of the previewer itself (by whatever
+ method is appropriate to the operating system). But sometimes
letting latexmk do the detaching is not appropriate (for a vari-
- ety of non-trivial reasons), so you should put the "start " bit
+ ety of non-trivial reasons), so you should put the "start " bit
in yourself, whenever it is needed.
$dvi_previewer_landscape ["start xdvi %O %S"]
The command to invoke a dvi-previewer in landscape mode. [Under
- MS-Windows the default is "start"; then latexmk arranges to use
- the MS-Windows start program, which will cause to be run what-
+ MS-Windows the default is "start"; then latexmk arranges to use
+ the MS-Windows start program, which will cause to be run what-
ever command the system has associated with .dvi files.]
$dvipdf ["dvipdf -dALLOWPSTRANSPARENCY %O %S %D"]
- Command to convert .dvi to .pdf file. A common reconfiguration
- is to use the dvipdfm command, which needs its arguments in a
+ Command to convert .dvi to .pdf file. A common reconfiguration
+ is to use the dvipdfm command, which needs its arguments in a
different order:
$dvipdf = "dvipdfm %O -o %D %S";
- WARNING: The default dvipdf script generates pdf files with
+ WARNING: The default dvipdf script generates pdf files with
bitmapped fonts, which do not look good when viewed by acroread.
- That script should be modified to give dvips the options "-P
+ That script should be modified to give dvips the options "-P
pdf" to ensure that type 1 fonts are used in the pdf file.
$dvipdf_silent_switch ["-q"]
Switch(es) for dvipdf program when silent mode is on.
- N.B. The standard dvipdf program runs silently, so adding the
- silent switch has no effect, but is actually innocuous. But if
- an alternative program is used, e.g., dvipdfmx, then the silent
- switch has an effect. The default setting is correct for
+ N.B. The standard dvipdf program runs silently, so adding the
+ silent switch has no effect, but is actually innocuous. But if
+ an alternative program is used, e.g., dvipdfmx, then the silent
+ switch has an effect. The default setting is correct for
dvipdfm and dvipdfmx.
$dvips ["dvips %O -o %D %S"]
- The program to used as a filter to convert a .dvi file to a .ps
- file. If pdf is going to be generated from pdf, then the value
- of the $dvips_pdf_switch variable -- see below -- will be in-
+ The program to used as a filter to convert a .dvi file to a .ps
+ file. If pdf is going to be generated from pdf, then the value
+ of the $dvips_pdf_switch variable -- see below -- will be in-
cluded in the options substituted for "%O".
$dvips_landscape ["dvips -tlandscape %O -o %D %S"]
- The program to used as a filter to convert a .dvi file to a .ps
+ The program to used as a filter to convert a .dvi file to a .ps
file in landscape mode.
- $dvips_pdf_switch ["-P pdf"]
- Switch(es) for dvips program when pdf file is to be generated
- from .ps file.
-
- $dvips_silent_switch ["-q"]
- Switch(es) for dvips program when silent mode is on.
- $dvi_update_command [""]
- When the dvi previewer is set to be updated by running a
- 7 April 2024 50
+ 27 December 2024 50
@@ -3304,70 +3304,78 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- command, this is the command that is run. See the information
- for the variable $dvi_update_method for further information, and
- see information on the variable $pdf_update_method for an exam-
- ple for the analogous case of a pdf previewer.
+ $dvips_pdf_switch ["-P pdf"]
+ Switch(es) for dvips program when pdf file is to be generated
+ from .ps file.
+
+ $dvips_silent_switch ["-q"]
+ Switch(es) for dvips program when silent mode is on.
+
+ $dvi_update_command [""]
+ When the dvi previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
+ the variable $dvi_update_method for further information, and see
+ information on the variable $pdf_update_method for an example
+ for the analogous case of a pdf previewer.
$dvi_update_method [2 under UNIX, 1 under MS-Windows]
- How the dvi viewer updates its display when the dvi file has
- changed. The values here apply equally to the $pdf_up-
+ How the dvi viewer updates its display when the dvi file has
+ changed. The values here apply equally to the $pdf_up-
date_method and to the $ps_update_method variables.
0 => update is automatic,
1=> manual update by user, which may only mean a mouse click
on the viewer's window or may mean a more serious action.
- 2 => Send the signal, whose number is in the variable
- $dvi_update_signal. The default value under UNIX is suitable
+ 2 => Send the signal, whose number is in the variable
+ $dvi_update_signal. The default value under UNIX is suitable
for xdvi.
- 3 => Viewer cannot do an update, because it locks the file.
+ 3 => Viewer cannot do an update, because it locks the file.
(As with acroread under MS-Windows.)
- 4 => run a command to do the update. The command is speci-
+ 4 => run a command to do the update. The command is speci-
fied by the variable $dvi_update_command.
- See information on the variable $pdf_update_method for an exam-
+ See information on the variable $pdf_update_method for an exam-
ple of updating by command.
$dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent
value]
- The number of the signal that is sent to the dvi viewer when it
- is updated by sending a signal -- see the information on the
- variable $dvi_update_method. The default value is the one ap-
+ The number of the signal that is sent to the dvi viewer when it
+ is updated by sending a signal -- see the information on the
+ variable $dvi_update_method. The default value is the one ap-
propriate for xdvi on a UNIX system.
$emulate_aux [1]
- Whether to emulate the use of aux directory when $aux_dir and
+ Whether to emulate the use of aux directory when $aux_dir and
$out_dir are different, rather than using the -aux-directory op-
- tion for the *latex programs. (MiKTeX supports -aux-directory,
+ tion for the *latex programs. (MiKTeX supports -aux-directory,
but TeXLive doesn't.)
- If you use a version of *latex that doesn't support -aux-direc-
- tory, e.g., TeXLive, latexmk will automatically switch aux_dir
+ If you use a version of *latex that doesn't support -aux-direc-
+ tory, e.g., TeXLive, latexmk will automatically switch aux_dir
emulation on after the first run of *latex, because it will find
the .log file in the wrong place. But it is better to set $emu-
- late_aux to 1 in an rc file, or equivalently to use the -emu-
+ late_aux to 1 in an rc file, or equivalently to use the -emu-
late-aux-dir option. This emulation mode works equally well with
MiKTeX.
- Aux directory emulation means that when *latex is invoked, the
- output directory provided to *latex is set to be the desired aux
- directory. After that, any files that need to be in the output
- directory will be moved there by latexmk. (These are the files
- with extensions .dvi, .ps, .pdf, .synctex, .synctex.gz, and, de-
- pending on the setting of the $fls_uses_out_dir variable, also
- the .fls file.)
-
+ Aux directory emulation means that when *latex is invoked, the
+ 27 December 2024 51
- 7 April 2024 51
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ output directory provided to *latex is set to be the desired aux
+ directory. After that, any files that need to be in the output
+ directory will be moved there by latexmk. (These are the files
+ with extensions .dvi, .ps, .pdf, .synctex, .synctex.gz, and, de-
+ pending on the setting of the $fls_uses_out_dir variable, also
+ the .fls file.)
$failure_cmd [undefined]
@@ -3375,26 +3383,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$fdb_ext ["fdb_latexmk"]
- The extension of the file which latexmk generates to contain a
- database of information on source files. You will not normally
+ The extension of the file which latexmk generates to contain a
+ database of information on source files. You will not normally
need to change this.
@file_not_found
- This an array of Perl regular expressions that are patterns to
- find messages in the .log file from a run of *latex that indi-
- cate that a file was looked for and not found. To see the cur-
- rent default set, you should look at the definition of
+ This an array of Perl regular expressions that are patterns to
+ find messages in the .log file from a run of *latex that indi-
+ cate that a file was looked for and not found. To see the cur-
+ rent default set, you should look at the definition of
@file_not_found in the latexmk.pl file.
- In the regular expression, the string for the name of the miss-
- ing file should be enclosed in parentheses. That carries the
- implication that after latexmk gets a successful match to the
- pattern, the variable $1 is set to the filename, which is then
+ In the regular expression, the string for the name of the miss-
+ ing file should be enclosed in parentheses. That carries the
+ implication that after latexmk gets a successful match to the
+ pattern, the variable $1 is set to the filename, which is then
picked up by latexmk.
- If you happen to encounter a package that gives a missing file
- message of a different form than one that matches one of the
+ If you happen to encounter a package that gives a missing file
+ message of a different form than one that matches one of the
built-in patterns, you can add another pattern to the array. An
example would be
@@ -3407,27 +3415,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
But the corresponding string specification in the push statement
has to have the backslashes doubled.
- This regular expression matches a line that starts with 'No
- file', then has one or more white space characters, then any
- number of characters forming the filename, then possible white
- space, and finally the end of the line. (See documentation on
+ This regular expression matches a line that starts with 'No
+ file', then has one or more white space characters, then any
+ number of characters forming the filename, then possible white
+ space, and finally the end of the line. (See documentation on
Perl regular expressions for details.)
$filetime_causality_threshold [5]
- The use of this variable is as follows: At a number of places,
- latexmk needs to determine whether a particular file has been
- produced during a just-concluded run of some rule/program or is
- leftover from a previous run. (An example is the production of a
- .bcf file by the biblatex package during a run of *latex to pro-
- vide bibliographic information to the biber program. If a .bcf
- file is not produced during a current run of *latex, but is
- leftover from a previous run, then latexmk has to conclude that
- the .tex document has changed so that biber is no longer to be
+ The use of this variable is as follows: At a number of places,
- 7 April 2024 52
+ 27 December 2024 52
@@ -3436,130 +3436,130 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ latexmk needs to determine whether a particular file has been
+ produced during a just-concluded run of some rule/program or is
+ leftover from a previous run. (An example is the production of a
+ .bcf file by the biblatex package during a run of *latex to pro-
+ vide bibliographic information to the biber program. If a .bcf
+ file is not produced during a current run of *latex, but is
+ leftover from a previous run, then latexmk has to conclude that
+ the .tex document has changed so that biber is no longer to be
used.)
- Latexmk's criterion that a file has been produced during a run
- is that the modification time of the file is more recent than
- the system time at the beginning of the run. Bascially, if the
- modification time is earlier than this, then it is a leftover
+ Latexmk's criterion that a file has been produced during a run
+ is that the modification time of the file is more recent than
+ the system time at the beginning of the run. Bascially, if the
+ modification time is earlier than this, then it is a leftover
from a previous run. However, a naive use of the criterion can,
- among other things, run afoul of the granularity of how file
- times are stored in some file systems, which means it is possi-
- ble that the filesystem's reported time for a file might be a
- second or more earlier than the actual modification time, the
+ among other things, run afoul of the granularity of how file
+ times are stored in some file systems, which means it is possi-
+ ble that the filesystem's reported time for a file might be a
+ second or more earlier than the actual modification time, the
exact difference being quite random.
- The variable $filetime_causality_threshold allows an appopriate
- sloppiness in latexmk's use of file modification time. It can
- be quite generous; it should merely be less than the time scale
- on which a human user makes changes to source files for a docu-
+ The variable $filetime_causality_threshold allows an appopriate
+ sloppiness in latexmk's use of file modification time. It can
+ be quite generous; it should merely be less than the time scale
+ on which a human user makes changes to source files for a docu-
ment (or to configuration files, etc).
$fls_uses_out_dir [0]
- This variable determines whether or not the .fls file should be
- in the output directory instead of the natural directory, which
+ This variable determines whether or not the .fls file should be
+ in the output directory instead of the natural directory, which
is the aux directory. If the variable is nonzero, the .fls file
is to be in the output directory. See the section AUXILIARY AND
- OUTPUT DIRECTORIES for more details about these directories.
- The rationale for the existence of the variable
+ OUTPUT DIRECTORIES for more details about these directories.
+ The rationale for the existence of the variable
$fls_uses_aux_dir is explained there.
In all cases, if latexmk finds that an .fls file has been gener-
- ated in the opposite directory to the one specified by
- $fls_uses_out_dir, it copies the file to the other directory
- (aux or output directory as appropriate). The file is copied
- rather than simply moved, to avoid potential clashes with other
- software that assumes the .fls file is generated in the direc-
- tory it was written to by *latex. Thus the effect an incorrect
+ ated in the opposite directory to the one specified by
+ $fls_uses_out_dir, it copies the file to the other directory
+ (aux or output directory as appropriate). The file is copied
+ rather than simply moved, to avoid potential clashes with other
+ software that assumes the .fls file is generated in the direc-
+ tory it was written to by *latex. Thus the effect an incorrect
setting of $fls_uses_out_dir is only to cause a superfluous copy
of the .fls file to be generated.
$force_mode [0]
- If nonzero, continue processing past minor latex errors includ-
+ If nonzero, continue processing past minor latex errors includ-
ing unrecognized cross references. Equivalent to specifying the
-f option.
- @generated_exts [( 'aux', 'bcf', 'fls', 'idx', 'ind', 'lof', 'lot',
- 'out', 'toc', 'blg', 'ilg', 'log', 'xdv' )]
- This contains a list of extensions for files that are generated
- during processing, and that should be deleted during a main
- clean up operation, as invoked by the command line option -c.
- (The use of -C or -gg gives this clean up and more.)
+ 27 December 2024 53
- 7 April 2024 53
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ @generated_exts [( 'aux', 'bcf', 'fls', 'idx', 'ind', 'lof', 'lot',
+ 'out', 'toc', 'blg', 'ilg', 'log', 'xdv' )]
+ This contains a list of extensions for files that are generated
+ during processing, and that should be deleted during a main
+ clean up operation, as invoked by the command line option -c.
+ (The use of -C or -gg gives this clean up and more.)
- The default values are extensions for standard files generated
- by *latex, bibtex, and the like. (Note that the clean up also
- deletes the fdb_latexmk file, but that's separately coded into
+ The default values are extensions for standard files generated
+ by *latex, bibtex, and the like. (Note that the clean up also
+ deletes the fdb_latexmk file, but that's separately coded into
latexmk, currently.)
- After initialization of latexmk and the processing of its com-
- mand line, the items in clean_ext are appended to @gener-
- ated_exts. So these two variables have the same meaning (con-
+ After initialization of latexmk and the processing of its com-
+ mand line, the items in clean_ext are appended to @gener-
+ ated_exts. So these two variables have the same meaning (con-
trary to older versions of latexmk).
- The items in @generated_exts are normally extensions of files,
- whose base name is the same as the main tex file. But it is
- also possible to specify patterns including that basename ---
+ The items in @generated_exts are normally extensions of files,
+ whose base name is the same as the main tex file. But it is
+ also possible to specify patterns including that basename ---
see the explanation of the variable $clean_ext.
In addition to specifying files to be deleted in a clean up, la-
- texmk uses the same specification to assist its examination of
- changes in source files: Under some situations it needs to find
- those changes in files (since a previous run) that are expected
- to be due to the user editing a file. This contrasts with the
+ texmk uses the same specification to assist its examination of
+ changes in source files: Under some situations it needs to find
+ those changes in files (since a previous run) that are expected
+ to be due to the user editing a file. This contrasts with the
cases of files that are generated by some program run by latexmk
- and that differ from the results of the previous run. This use
- of @generated_exts is normally unimportant, given the usual ac-
- curacy of latexmk's other ways of determining these generated
+ and that differ from the results of the previous run. This use
+ of @generated_exts is normally unimportant, given the usual ac-
+ curacy of latexmk's other ways of determining these generated
files.
- A convenient way to add an extra extension to the list, without
- losing the already defined ones is to use a push command in the
+ A convenient way to add an extra extension to the list, without
+ losing the already defined ones is to use a push command in the
line in an RC file. E.g.,
push @generated_exts, "end";
adds the extension "end" to the list of predefined generated ex-
- tensions. (This extension is used by the RevTeX package, for
+ tensions. (This extension is used by the RevTeX package, for
example.)
$go_mode [0]
- If nonzero, process files regardless of timestamps, and is then
+ If nonzero, process files regardless of timestamps, and is then
equivalent to the -g option.
%hash_calc_ignore_pattern
!!!This variable is for experts only!!!
- The general rule latexmk uses for determining when an extra run
- of some program is needed is that one of the source files has
- changed. But consider for example a latex package that causes
- an encapsulated postscript file (an "eps" file) to be made that
- is to be read in on the next run. The file contains a comment
- line giving its creation date and time. On the next run the
- time changes, latex sees that the eps file has changed, and
- therefore reruns latex. This causes an infinite loop, that is
- only terminated because latexmk has a limit on the number of
+ The general rule latexmk uses for determining when an extra run
- 7 April 2024 54
+ 27 December 2024 54
@@ -3568,6 +3568,14 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ of some program is needed is that one of the source files has
+ changed. But consider for example a latex package that causes
+ an encapsulated postscript file (an "eps" file) to be made that
+ is to be read in on the next run. The file contains a comment
+ line giving its creation date and time. On the next run the
+ time changes, latex sees that the eps file has changed, and
+ therefore reruns latex. This causes an infinite loop, that is
+ only terminated because latexmk has a limit on the number of
runs to guard against pathological situations.
But the changing line has no real effect, since it is a comment.
@@ -3576,31 +3584,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
This creates a rule for files with extension .eps about lines to
- ignore. The left-hand side is a Perl idiom for setting an item
- in a hash. Note that the file extension is specified without a
+ ignore. The left-hand side is a Perl idiom for setting an item
+ in a hash. Note that the file extension is specified without a
period. The value, on the right-hand side, is a string contain-
- ing a regular expression. (See documentation on Perl for how
- they are to be specified in general.) This particular regular
- expression specifies that lines beginning with "%%CreationDate:
- " are to be ignored in deciding whether a file of the given ex-
+ ing a regular expression. (See documentation on Perl for how
+ they are to be specified in general.) This particular regular
+ expression specifies that lines beginning with "%%CreationDate:
+ " are to be ignored in deciding whether a file of the given ex-
tension .eps has changed.
- There is only one regular expression available for each exten-
- sion. If you need more one pattern to specify lines to ignore,
- then you need to combine the patterns into a single regular ex-
- pression. The simplest method is separate the different simple
- patterns by a vertical bar character (indicating "alternation"
+ There is only one regular expression available for each exten-
+ sion. If you need more one pattern to specify lines to ignore,
+ then you need to combine the patterns into a single regular ex-
+ pression. The simplest method is separate the different simple
+ patterns by a vertical bar character (indicating "alternation"
in the jargon of regular expressions). For example,
- $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: |^%%Ti-
+ $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: |^%%Ti-
tle: ';
causes lines starting with either "^%%CreationDate: " or "^%%Ti-
tle: " to be ignored.
- It may happen that a pattern to be ignored is specified in, for
- example, in a system or user initialization file, and you wish
- to remove this in a file that is read later. To do this, you
+ It may happen that a pattern to be ignored is specified in, for
+ example, in a system or user initialization file, and you wish
+ to remove this in a file that is read later. To do this, you
use Perl's delete function, e.g.,
delete $hash_calc_ignore_pattern{'eps'};
@@ -3611,170 +3619,170 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$hnt_mode [0]
- Whether to generate a hnt version of the document by use of hi-
+ Whether to generate a hnt version of the document by use of hi-
latex. Can be turned on by the use of the -hnt option.
- $jobname [""]
- This specifies the jobname, i.e., the basename that is used for
- generated files (.aux, .log, .dvi, .ps, .pdf, etc). If this
- variable is a null string, then the basename is the basename of
- the main tex file. (At present, the string in $jobname should
- not contain spaces.)
+ 27 December 2024 55
- 7 April 2024 55
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ $jobname [""]
+ This specifies the jobname, i.e., the basename that is used for
+ generated files (.aux, .log, .dvi, .ps, .pdf, etc). If this
+ variable is a null string, then the basename is the basename of
+ the main tex file. (At present, the string in $jobname should
+ not contain spaces.)
- The placeholder '%A' is permitted. This will be substituted by
+ The placeholder '%A' is permitted. This will be substituted by
the basename of the TeX file. The primary purpose is when a va-
- riety of tex files are to be processed, and you want to use a
- different jobname for each but one that is distinct for each.
- Thus if you wanted to compare compilations of a set of files on
+ riety of tex files are to be processed, and you want to use a
+ different jobname for each but one that is distinct for each.
+ Thus if you wanted to compare compilations of a set of files on
different operating systems, with distinct filenames for all the
cases, you could set
$jobname = "%A-$^O";
- in an initialization file. (Here $^O is a variable provided by
+ in an initialization file. (Here $^O is a variable provided by
perl that contains perl's name for the operating system.)
- Suppose you had .tex files test1.tex and test2.tex. Then when
+ Suppose you had .tex files test1.tex and test2.tex. Then when
you run
latexmk -pdf *.tex
- both files will be compiled. The .aux, .log, and .pdf files
- will have basenames test1-MSWin32 ante test2-MSWin32 on a MS-
+ both files will be compiled. The .aux, .log, and .pdf files
+ will have basenames test1-MSWin32 ante test2-MSWin32 on a MS-
Windows system, test1-darwin and test2-darwin on an OS-X system,
and a variety of similar cases on linux systems.
$kpsewhich ["kpsewhich %S"]
- The program called to locate a source file when the name alone
- is not sufficient. Most filenames used by latexmk have suffi-
+ The program called to locate a source file when the name alone
+ is not sufficient. Most filenames used by latexmk have suffi-
cient path information to be found directly. But sometimes, no-
tably when a .bib or a .bst file is found from the log file of a
- bibtex or biber run, only the base name of the file is known,
+ bibtex or biber run, only the base name of the file is known,
but not its path. The program specified by $kpsewhich is used to
find it.
- (For advanced users: Because of the different way in which la-
+ (For advanced users: Because of the different way in which la-
texmk uses the command specified in $kpsewhich, some of the pos-
sibilities listed in the FORMAT OF COMMAND SPECIFICATIONS do not
- apply. The internal and start keywords are not available. A
+ apply. The internal and start keywords are not available. A
simple command specification with possible options and then "%S"
- is all that is guaranteed to work. Note that for other com-
+ is all that is guaranteed to work. Note that for other com-
mands, "%S" is substituted by a single source file. In contrast,
for $kpsewhich, "%S" may be substituted by a long list of space-
- separated filenames, each of which is quoted. The result on
+ separated filenames, each of which is quoted. The result on
STDOUT of running the command is then piped to latexmk.)
- See also the @BIBINPUTS variable for another way that latexmk
+ See also the @BIBINPUTS variable for another way that latexmk
also uses to try to locate files; it applies only in the case of
- .bib files.
- $kpsewhich_show [0]
- Whether to show diagnostics about invocations of kpsewhich: the
- command line use to invoke it and the results. These diagnos-
- tics are shown if $kpsewhich_show is non-zero or if diagnostics
- mode is on. (But in the second case, lots of other diagnostics
+ 27 December 2024 56
- 7 April 2024 56
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ .bib files.
- are also shown.) Without these diagnostics there is nothing
- visible in latexmk's screen output about invocations of kpse-
+ $kpsewhich_show [0]
+ Whether to show diagnostics about invocations of kpsewhich: the
+ command line use to invoke it and the results. These diagnos-
+ tics are shown if $kpsewhich_show is non-zero or if diagnostics
+ mode is on. (But in the second case, lots of other diagnostics
+ are also shown.) Without these diagnostics there is nothing
+ visible in latexmk's screen output about invocations of kpse-
which.
$landscape_mode [0]
If nonzero, run in landscape mode, using the landscape mode pre-
- viewers and dvi to postscript converters. Equivalent to the -l
+ viewers and dvi to postscript converters. Equivalent to the -l
option. Normally not needed with current previewers.
$latex ["latex %O %S"]
- Specifies the command line for the LaTeX processing program.
- Note that as with other programs, you can use this variable not
- just to change the name of the program used, but also specify
+ Specifies the command line for the LaTeX processing program.
+ Note that as with other programs, you can use this variable not
+ just to change the name of the program used, but also specify
options to the program. E.g.,
$latex = "latex --src-specials %O %S";
- To do a coordinated setting of all of $dvilualatex, $hilatex,
+ To do a coordinated setting of all of $dvilualatex, $hilatex,
$latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad-
vanced Configuration".
%latex_input_extensions
- This variable specifies the extensions tried by latexmk when it
- finds that a LaTeX run resulted in an error that a file has not
- been found, and the file is given without an extension. This
- typically happens when LaTeX commands of the form \input{file}
- or \includegraphics{figure}, when the relevant source file does
+ This variable specifies the extensions tried by latexmk when it
+ finds that a LaTeX run resulted in an error that a file has not
+ been found, and the file is given without an extension. This
+ typically happens when LaTeX commands of the form \input{file}
+ or \includegraphics{figure}, when the relevant source file does
not exist.
- In this situation, latexmk searches for custom dependencies to
- make the missing file(s), but restricts it to the extensions
- specified by the variable %latex_input_extensions. The default
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %latex_input_extensions. The default
extensions are 'tex' and 'eps'.
- (For Perl experts: %latex_input_extensions is a hash whose keys
- are the extensions. The values are irrelevant.) Two subrou-
- tines are provided for manipulating this and the related vari-
- able %pdflatex_input_extensions, add_input_ext and remove_in-
- put_ext. They are used as in the following examples are possi-
+ (For Perl experts: %latex_input_extensions is a hash whose keys
+ are the extensions. The values are irrelevant.) Two subrou-
+ tines are provided for manipulating this and the related vari-
+ able %pdflatex_input_extensions, add_input_ext and remove_in-
+ put_ext. They are used as in the following examples are possi-
ble lines in an initialization file:
remove_input_ext( 'latex', 'tex' );
- removes the extension 'tex' from latex_input_extensions
- add_input_ext( 'latex', 'asdf' );
- add the extension 'asdf to latex_input_extensions. (Naturally
- with such an extension, you should have made an appropriate cus-
- tom dependency for latexmk, and should also have done the appro-
- priate programming in the LaTeX source file to enable the file
+ 27 December 2024 57
- 7 April 2024 57
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ removes the extension 'tex' from latex_input_extensions
+ add_input_ext( 'latex', 'asdf' );
- to be read. The standard extensions are handled by LaTeX and
+ add the extension 'asdf to latex_input_extensions. (Naturally
+ with such an extension, you should have made an appropriate cus-
+ tom dependency for latexmk, and should also have done the appro-
+ priate programming in the LaTeX source file to enable the file
+ to be read. The standard extensions are handled by LaTeX and
its graphics/graphicx packages.)
$latex_silent_switch ["-interaction=batchmode"]
- Switch(es) for the LaTeX processing program when silent mode is
+ Switch(es) for the LaTeX processing program when silent mode is
on.
- If you use MikTeX, you may prefer the results if you configure
- the options to include -c-style-errors, e.g., by the following
+ If you use MikTeX, you may prefer the results if you configure
+ the options to include -c-style-errors, e.g., by the following
line in an initialization file
$latex_silent_switch = "-interaction=batchmode -c-style-er-
@@ -3784,19 +3792,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$lpr ["lpr %O %S" under UNIX/Linux, "NONE lpr" under MS-Windows]
The command to print postscript files.
- Under MS-Windows (unlike UNIX/Linux), there is no standard pro-
+ Under MS-Windows (unlike UNIX/Linux), there is no standard pro-
gram for printing files. But there are ways you can do it. For
example, if you have gsview installed, you could use it with the
option "/p":
$lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
- If gsview is installed in a different directory, you will need
- to make the appropriate change. Note the combination of single
- and double quotes around the name. The single quotes specify
- that this is a string to be assigned to the configuration vari-
- able $lpr. The double quotes are part of the string passed to
- the operating system to get the command obeyed; this is neces-
+ If gsview is installed in a different directory, you will need
+ to make the appropriate change. Note the combination of single
+ and double quotes around the name. The single quotes specify
+ that this is a string to be assigned to the configuration vari-
+ able $lpr. The double quotes are part of the string passed to
+ the operating system to get the command obeyed; this is neces-
sary because one part of the command name ("Program Files") con-
tains a space which would otherwise be misinterpreted.
@@ -3806,24 +3814,16 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$lpr_pdf ["NONE lpr_pdf"]
The printing program to print pdf files.
- Under MS-Windows you could set this to use gsview, if it is in-
+ Under MS-Windows you could set this to use gsview, if it is in-
stalled, e.g.,
$lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
- If gsview is installed in a different directory, you will need
- to make the appropriate change. Note the double quotes around
- the name: this is necessary because one part of the command name
- ("Program Files") contains a space which would otherwise be mis-
- interpreted.
-
- $lualatex ["lualatex %O %S"]
- Specifies the command line for the LaTeX processing program that
- is to be used when the lualatex program is called for (e.g., by
+ If gsview is installed in a different directory, you will need
- 7 April 2024 58
+ 27 December 2024 58
@@ -3832,34 +3832,42 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ to make the appropriate change. Note the double quotes around
+ the name: this is necessary because one part of the command name
+ ("Program Files") contains a space which would otherwise be mis-
+ interpreted.
+
+ $lualatex ["lualatex %O %S"]
+ Specifies the command line for the LaTeX processing program that
+ is to be used when the lualatex program is called for (e.g., by
the option -lualatex.
- To do a coordinated setting of all of $dvilualatex, $hilatex,
+ To do a coordinated setting of all of $dvilualatex, $hilatex,
$latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad-
vanced Configuration".
%lualatex_input_extensions
- This variable specifies the extensions tried by latexmk when it
- finds that a lualatex run resulted in an error that a file has
- not been found, and the file is given without an extension.
- This typically happens when LaTeX commands of the form \in-
- put{file} or \includegraphics{figure}, when the relevant source
+ This variable specifies the extensions tried by latexmk when it
+ finds that a lualatex run resulted in an error that a file has
+ not been found, and the file is given without an extension.
+ This typically happens when LaTeX commands of the form \in-
+ put{file} or \includegraphics{figure}, when the relevant source
file does not exist.
- In this situation, latexmk searches for custom dependencies to
- make the missing file(s), but restricts it to the extensions
- specified by the variable %pdflatex_input_extensions. The de-
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %pdflatex_input_extensions. The de-
fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
See details of the %latex_input_extensions for other information
that equally applies to %lualatex_input_extensions.
$lualatex_silent_switch ["-interaction=batchmode"]
- Switch(es) for the lualatex program (specified in the variable
+ Switch(es) for the lualatex program (specified in the variable
$lualatex) when silent mode is on.
- See details of the $latex_silent_switch for other information
+ See details of the $latex_silent_switch for other information
that equally applies to $lualatex_silent_switch.
$make ["make"]
@@ -3869,27 +3877,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
The index processing program.
$makeindex_fudge [0]
- When using makeindex, whether to change directory to $aux_dir
- before running makeindex. Set to 1 if $aux_dir is not an ex-
- plicit subdirectory of current directory, otherwise makeindex
+ When using makeindex, whether to change directory to $aux_dir
+ before running makeindex. Set to 1 if $aux_dir is not an ex-
+ plicit subdirectory of current directory, otherwise makeindex
will refuse to write its output and log files, for security rea-
sons.
$makeindex_silent_switch ["-q"]
- Switch(es) for the index processing program when silent mode is
+ Switch(es) for the index processing program when silent mode is
on.
- $max_repeat [5]
- The maximum number of times latexmk will run *latex before de-
- ciding that there may be an infinite loop and that it needs to
- bail out, rather than rerunning *latex again to resolve cross-
- references, etc. The default value covers all normal cases.
-
- (Note that the "etc" covers a lot of cases where one run of
-
- 7 April 2024 59
+ 27 December 2024 59
@@ -3898,7 +3898,14 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- *latex generates files to be read in on a later run.)
+ $max_repeat [5]
+ The maximum number of times latexmk will run *latex before de-
+ ciding that there may be an infinite loop and that it needs to
+ bail out, rather than rerunning *latex again to resolve cross-
+ references, etc. The default value covers all normal cases.
+
+ (Note that the "etc" covers a lot of cases where one run of *la-
+ tex generates files to be read in on a later run.)
$MSWin_back_slash [1]
This configuration variable only has an effect when latexmk is
@@ -3944,54 +3951,55 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
fault, then other generated files are in effect written to the
output directory.
- If $out_dir is blank, the output directory is the current direc-
- tory at the invocation of *latex; this is equivalent to setting
- $out_dir to '.'.
+ If $out_dir is blank, the output directory is the current
- See the section AUXILIARY AND OUTPUT DIRECTORIES for more de-
- tails.
+ 27 December 2024 60
- 7 April 2024 60
+LATEXMK(1) General Commands Manual LATEXMK(1)
+ directory at the invocation of *latex; this is equivalent to
+ setting $out_dir to '.'.
+
+ See the section AUXILIARY AND OUTPUT DIRECTORIES for more de-
+ tails.
-LATEXMK(1) General Commands Manual LATEXMK(1)
$out2_dir [""]
(Experimental new feature.)
- If non-blank, this variable specifies the final-output direc-
- tory, i.e., the directory for the final output files. If this
- variable is blank (its default value), the final-output direc-
+ If non-blank, this variable specifies the final-output direc-
+ tory, i.e., the directory for the final output files. If this
+ variable is blank (its default value), the final-output direc-
tory is the same as the output directory.
See the description of the option -out2dir for an explanation of
- the rationale for the idea of separate output and final-output
+ the rationale for the idea of separate output and final-output
directories.
- If the final-output directory is different from the output di-
- rectory, then after a full round of compilations of the docu-
- ment, the relevant set of files is copied here from the output
- directory. The files copied are specified by the @out2_exts
+ If the final-output directory is different from the output di-
+ rectory, then after a full round of compilations of the docu-
+ ment, the relevant set of files is copied here from the output
+ directory. The files copied are specified by the @out2_exts
variable, and by default are those with extensions 'hnt', 'pdf',
- 'ps', 'synctex', 'synctex.gz', and a basename the same as for
+ 'ps', 'synctex', 'synctex.gz', and a basename the same as for
the main *latex compilation.
@out2_exts [( 'hnt', 'pdf', 'ps', 'synctex', 'synctex.gz' )]
- This variable lists the extensions of the files to be copied to
- the final-output directory. The basename of the files is that
- for the main *latex compilation (corresponding to the value
- specified by the placeholder %R). More general names may be
- specified in the same way as for the @generated_exts variable,
+ This variable lists the extensions of the files to be copied to
+ the final-output directory. The basename of the files is that
+ for the main *latex compilation (corresponding to the value
+ specified by the placeholder %R). More general names may be
+ specified in the same way as for the @generated_exts variable,
by inclusion of %R in a pattern, e.g.,
push @out2_exts, '%R-2up.pdf';
@@ -3999,37 +4007,37 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$pdf_mode [0]
- If zero, do NOT generate a pdf version of the document. If
- equal to 1, generate a pdf version of the document using pdfla-
- tex, using the command specified by the $pdflatex variable. If
- equal to 2, generate a pdf version of the document from the ps
- file, by using the command specified by the $ps2pdf variable.
- If equal to 3, generate a pdf version of the document from the
- dvi file, by using the command specified by the $dvipdf vari-
+ If zero, do NOT generate a pdf version of the document. If
+ equal to 1, generate a pdf version of the document using pdfla-
+ tex, using the command specified by the $pdflatex variable. If
+ equal to 2, generate a pdf version of the document from the ps
+ file, by using the command specified by the $ps2pdf variable.
+ If equal to 3, generate a pdf version of the document from the
+ dvi file, by using the command specified by the $dvipdf vari-
able. If equal to 4, generate a pdf version of the document us-
ing lualatex, using the command specified by the $lualatex vari-
- able. If equal to 5, generate a pdf version (and an xdv ver-
- sion) of the document using xelatex, using the commands speci-
- fied by the $xelatex and xdvipdfmx variables.
+ able. If equal to 5, generate a pdf version (and an xdv ver-
+ sion) of the document using xelatex, using the commands
- In $pdf_mode=2, it is ensured that .dvi and .ps files are also
- made. In $pdf_mode=3, it is ensured that a .dvi file is also
- made. But this may be overridden by the document.
- $pdflatex ["pdflatex %O %S"]
- Specifies the command line for the LaTeX processing program in a
+ 27 December 2024 61
- 7 April 2024 61
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ specified by the $xelatex and xdvipdfmx variables.
+ In $pdf_mode=2, it is ensured that .dvi and .ps files are also
+ made. In $pdf_mode=3, it is ensured that a .dvi file is also
+ made. But this may be overridden by the document.
+ $pdflatex ["pdflatex %O %S"]
+ Specifies the command line for the LaTeX processing program in a
version that makes a pdf file instead of a dvi file.
An example use of this variable is to add certain options to the
@@ -4037,57 +4045,49 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$pdflatex = "pdflatex --shell-escape %O %S";
- (In some earlier versions of latexmk, you needed to use an as-
- signment to $pdflatex to allow the use of lualatex or xelatex
+ (In some earlier versions of latexmk, you needed to use an as-
+ signment to $pdflatex to allow the use of lualatex or xelatex
instead of pdflatex. There are now separate configuration vari-
- ables for the use of lualatex or xelatex. See $lualatex and
+ ables for the use of lualatex or xelatex. See $lualatex and
$xelatex.)
- To do a coordinated setting of all of $dvilualatex, $hilatex,
+ To do a coordinated setting of all of $dvilualatex, $hilatex,
$latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad-
vanced Configuration".
%pdflatex_input_extensions
- This variable specifies the extensions tried by latexmk when it
- finds that a pdflatex run resulted in an error that a file has
- not been found, and the file is given without an extension.
- This typically happens when LaTeX commands of the form \in-
- put{file} or \includegraphics{figure}, when the relevant source
+ This variable specifies the extensions tried by latexmk when it
+ finds that a pdflatex run resulted in an error that a file has
+ not been found, and the file is given without an extension.
+ This typically happens when LaTeX commands of the form \in-
+ put{file} or \includegraphics{figure}, when the relevant source
file does not exist.
- In this situation, latexmk searches for custom dependencies to
- make the missing file(s), but restricts it to the extensions
- specified by the variable %pdflatex_input_extensions. The de-
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %pdflatex_input_extensions. The de-
fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
See details of the %latex_input_extensions for other information
that equally applies to %pdflatex_input_extensions.
$pdflatex_silent_switch ["-interaction=batchmode"]
- Switch(es) for the pdflatex program (specified in the variable
+ Switch(es) for the pdflatex program (specified in the variable
$pdflatex) when silent mode is on.
- See details of the $latex_silent_switch for other information
+ See details of the $latex_silent_switch for other information
that equally applies to $pdflatex_silent_switch.
$pdf_previewer ["start acroread %O %S"]
The command to invoke a pdf-previewer.
- On MS-Windows, the default is changed to "cmd /c start """; un-
- der more recent versions of Windows, this will cause to be run
- whatever command the system has associated with .pdf files. But
- this may be undesirable if this association is to acroread --
- see the notes in the explanation of the -pvc option.]
-
- On OS-X the default is changed to "open %S", which results in
- OS-X starting up (and detaching) the viewer associated with the
- file. By default, for pdf files this association is to OS-X's
- preview, which is quite satisfactory.
+ On MS-Windows, the default is changed to "cmd /c start """; un-
+ der more recent versions of Windows, this will cause to be run
- 7 April 2024 62
+ 27 December 2024 62
@@ -4096,35 +4096,44 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- WARNING: Problem under MS-Windows: if acroread is used as the
- pdf previewer, and it is actually viewing a pdf file, the pdf
- file cannot be updated. Thus makes acroread a bad choice of
- previewer if you use latexmk's previous-continuous mode (option
+ whatever command the system has associated with .pdf files. But
+ this may be undesirable if this association is to acroread --
+ see the notes in the explanation of the -pvc option.]
+
+ On OS-X the default is changed to "open %S", which results in
+ OS-X starting up (and detaching) the viewer associated with the
+ file. By default, for pdf files this association is to OS-X's
+ preview, which is quite satisfactory.
+
+ WARNING: Problem under MS-Windows: if acroread is used as the
+ pdf previewer, and it is actually viewing a pdf file, the pdf
+ file cannot be updated. Thus makes acroread a bad choice of
+ previewer if you use latexmk's previous-continuous mode (option
-pvc) under MS-windows. This problem does not occur if, for ex-
ample, SumatraPDF or gsview is used to view pdf files.
- Important note: Normally you will want to have a previewer run
+ Important note: Normally you will want to have a previewer run
detached, so that latexmk doesn't wait for the previewer to ter-
- minate before continuing its work. So normally you should pre-
- fix the command by "start ", which flags to latexmk that it
- should do the detaching of the previewer itself (by whatever
- method is appropriate to the operating system). But sometimes
+ minate before continuing its work. So normally you should pre-
+ fix the command by "start ", which flags to latexmk that it
+ should do the detaching of the previewer itself (by whatever
+ method is appropriate to the operating system). But sometimes
letting latexmk do the detaching is not appropriate (for a vari-
- ety of non-trivial reasons), so you should put the "start " bit
+ ety of non-trivial reasons), so you should put the "start " bit
in yourself, whenever it is needed.
$pdf_update_command [""]
- When the pdf previewer is set to be updated by running a com-
- mand, this is the command that is run. See the information for
+ When the pdf previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
the variable $pdf_update_method.
$pdf_update_method [1 under UNIX, 3 under MS-Windows]
- How the pdf viewer updates its display when the pdf file has
- changed. See the information on the variable $dvi_update_method
+ How the pdf viewer updates its display when the pdf file has
+ changed. See the information on the variable $dvi_update_method
for the codes. (Note that information needs be changed slightly
- so that for the value 4, to run a command to do the update, the
- command is specified by the variable $pdf_update_command, and
- for the value 2, to specify update by signal, the signal is
+ so that for the value 4, to run a command to do the update, the
+ command is specified by the variable $pdf_update_command, and
+ for the value 2, to specify update by signal, the signal is
specified by $pdf_update_signal.)
Note that acroread under MS-Windows (but not UNIX) locks the pdf
@@ -4137,59 +4146,59 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$pdf_update_method = 4;
$pdf_update_command = "xpdf -remote %R -reload";
- The first setting arranges for the xpdf program to be used in
- its "remote server mode", with the server name specified as the
- rootname of the TeX file. The second setting arranges for up-
- dating to be done in response to a command, and the third set-
- ting sets the update command.
+ The first setting arranges for the xpdf program to be used in
+ its "remote server mode", with the server name specified as the
+ rootname of the TeX file. The second setting arranges for up-
+ dating to be done in response to a command, and the third
- $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent
- value]
- The number of the signal that is sent to the pdf viewer when it
- is updated by sending a signal -- see the information on the
- variable $pdf_update_method. The default value is the one ap-
- propriate for gv on a UNIX system.
+ 27 December 2024 63
- 7 April 2024 63
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ setting sets the update command.
+ $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent
+ value]
+ The number of the signal that is sent to the pdf viewer when it
+ is updated by sending a signal -- see the information on the
+ variable $pdf_update_method. The default value is the one ap-
+ propriate for gv on a UNIX system.
$pid_position[1 under UNIX, -1 under MS-Windows]
- The variable $pid_position is used to specify which word in
- lines of the output from $pscmd corresponds to the process ID.
- The first word in the line is numbered 0. The default value of
+ The variable $pid_position is used to specify which word in
+ lines of the output from $pscmd corresponds to the process ID.
+ The first word in the line is numbered 0. The default value of
1 (2nd word in line) is correct for Solaris 2.6, Linux, and OS-X
with their default settings of $pscmd.
- Setting the variable to -1 is used to indicate that $pscmd is
+ Setting the variable to -1 is used to indicate that $pscmd is
not to be used.
$postscript_mode [0]
- If nonzero, generate a postscript version of the document.
+ If nonzero, generate a postscript version of the document.
Equivalent to the -ps option.
- If some other request is made for which a postscript file is
+ If some other request is made for which a postscript file is
needed, then $postscript_mode will be set to 1.
$pre_tex_code ['']
- Sets TeX code to be executed before inputting the source file.
- This works if the relevant one of $latex, etc contains a suit-
+ Sets TeX code to be executed before inputting the source file.
+ This works if the relevant one of $latex, etc contains a suit-
able command line with a %P or %U substitution. For example you
could do
$latex = 'latex %O %P';
$pre_tex_code = '\AtBeginDocument{An initial message\par}';
- To set all of $latex, $pdflatex, $lualatex, and $xelatex you
+ To set all of $latex, $pdflatex, $lualatex, and $xelatex you
could use the subroutine alt_tex_cmds:
&alt_tex_cmds;
@@ -4198,54 +4207,53 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$preview_continuous_mode [0]
- If nonzero, run a previewer to view the document, and continue
+ If nonzero, run a previewer to view the document, and continue
running latexmk to keep .dvi up-to-date. Equivalent to the -pvc
- option. Which previewer is run depends on the other settings,
+ option. Which previewer is run depends on the other settings,
see the command line options -view=, and the variable $view.
$preview_mode [0]
If nonzero, run a previewer to preview the document. Equivalent
- to the -pv option. Which previewer is run depends on the other
- settings, see the command line options -view=, and the variable
- $view.
-
- $printout_mode [0]
- If nonzero, print the document using the command specified in
- the $lpr variable. Equivalent to the -p option. This is recom-
- mended not to be set from an RC file, otherwise you could waste
- lots of paper.
+ to the -pv option. Which previewer is run depends on the other
+ settings, see the command line options -view=, and the variable
+ 27 December 2024 64
- 7 April 2024 64
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ $view.
+ $printout_mode [0]
+ If nonzero, print the document using the command specified in
+ the $lpr variable. Equivalent to the -p option. This is recom-
+ mended not to be set from an RC file, otherwise you could waste
+ lots of paper.
$print_type = ["auto"]
- Type of file to printout: possibilities are "auto", "dvi",
+ Type of file to printout: possibilities are "auto", "dvi",
"none", "pdf", or "ps". See the option -print= for the meaning
of the "auto" value.
$pscmd Command used to get all the processes currently run by the user.
- The -pvc option uses the command specified by the variable
- $pscmd to determine if there is an already running previewer,
- and to find the process ID (needed if latexmk needs to signal
+ The -pvc option uses the command specified by the variable
+ $pscmd to determine if there is an already running previewer,
+ and to find the process ID (needed if latexmk needs to signal
the previewer about file changes).
Each line of the output of this command is assumed to correspond
- to one process. See the $pid_position variable for how the
+ to one process. See the $pid_position variable for how the
process number is determined.
- The default for pscmd is "NONE" under MS-Windows and cygwin
- (i.e., the command is not used), "ps -ww -u $ENV{USER}" under
- OS-X, and "ps -f -u $ENV{USER}" under other operating systems
+ The default for pscmd is "NONE" under MS-Windows and cygwin
+ (i.e., the command is not used), "ps -ww -u $ENV{USER}" under
+ OS-X, and "ps -f -u $ENV{USER}" under other operating systems
(including Linux). In these specifications "$ENV{USER}" is sub-
stituted by the username.
@@ -4254,38 +4262,30 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
$ps_filter [empty]
The postscript file filter to be run on the newly produced post-
- script file before other processing. Equivalent to specifying
+ script file before other processing. Equivalent to specifying
the -pF option.
$ps_previewer ["start gv %O %S", but start %O %S under MS-Windows]
- The command to invoke a ps-previewer. (The default under MS-
+ The command to invoke a ps-previewer. (The default under MS-
Windows will cause to be run whatever command the system has as-
sociated with .ps files.)
- Note that gv could be used with the -watch option updates its
- display whenever the postscript file changes, whereas ghostview
- does not. However, different versions of gv have slightly dif-
- ferent ways of writing this option. You can configure this
+ Note that gv could be used with the -watch option updates its
+ display whenever the postscript file changes, whereas ghostview
+ does not. However, different versions of gv have slightly dif-
+ ferent ways of writing this option. You can configure this
variable appropriately.
WARNING: Linux systems may have installed one (or more) versions
- of gv under different names, e.g., ggv, kghostview, etc, but
+ of gv under different names, e.g., ggv, kghostview, etc, but
perhaps not one actually called gv.
- Important note: Normally you will want to have a previewer run
- detached, so that latexmk doesn't wait for the previewer to ter-
- minate before continuing its work. So normally you should pre-
- fix the command by "start ", which flags to latexmk that it
- should do the detaching of the previewer itself (by whatever
- method is appropriate to the operating system). But sometimes
- letting latexmk do the detaching is not appropriate (for a vari-
- ety of non-trivial reasons), so you should put the "start " bit
- in yourself, whenever it is needed.
-
+ Important note: Normally you will want to have a previewer run
+ detached, so that latexmk doesn't wait for the previewer to
- 7 April 2024 65
+ 27 December 2024 65
@@ -4294,6 +4294,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ terminate before continuing its work. So normally you should
+ prefix the command by "start ", which flags to latexmk that it
+ should do the detaching of the previewer itself (by whatever
+ method is appropriate to the operating system). But sometimes
+ letting latexmk do the detaching is not appropriate (for a vari-
+ ety of non-trivial reasons), so you should put the "start " bit
+ in yourself, whenever it is needed.
+
+
$ps_previewer_landscape ["start gv -swap %O %S", but start %O %S under
MS-Windows]
The command to invoke a ps-previewer in landscape mode.
@@ -4340,18 +4349,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
quotes. If this variable is 1 (or any other value Perl regards
as true), then quoting is done. Otherwise quoting is omitted.
- The quoting method used by latexmk is tested to work correctly
- under UNIX systems (including Linux and Mac OS-X) and under MS-
- Windows. It allows the use of filenames containing special
- characters, notably spaces. (But note that many versions of
- *latex cannot correctly deal with TeX files whose names contain
- spaces. Latexmk's quoting only ensures that such filenames are
- correctly treated by the operating system in passing arguments
- to programs.)
-
- 7 April 2024 66
+ 27 December 2024 66
@@ -4360,6 +4360,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
+ The quoting method used by latexmk is tested to work correctly
+ under UNIX systems (including Linux and Mac OS-X) and under MS-
+ Windows. It allows the use of filenames containing special
+ characters, notably spaces. (But note that many versions of
+ *latex cannot correctly deal with TeX files whose names contain
+ spaces. Latexmk's quoting only ensures that such filenames are
+ correctly treated by the operating system in passing arguments
+ to programs.)
+
$rc_report [1]
After initialization, whether to give a list of the RC files
read.
@@ -4405,27 +4414,27 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
software is running under an emulator for the other kind of op-
erating system; in that case you'll need to find out what is
needed, and set $search_path_separator explicitly. (The same
- goes, of course, for unusual operating systems that are not in
- the MSWin, Linux, OS-X, Unix collection.)
- $show_time [0]
- Whether to show time used, both the total and for individual
- steps.
- Note: On MS Windows, this is clock time. On other OSs it is the
- CPU time used (by latexmk and the child processes it invokes).
+ 27 December 2024 67
- 7 April 2024 67
+LATEXMK(1) General Commands Manual LATEXMK(1)
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ goes, of course, for unusual operating systems that are not in
+ the MSWin, Linux, OS-X, Unix collection.)
+ $show_time [0]
+ Whether to show time used, both the total and for individual
+ steps.
+ Note: On MS Windows, this is clock time. On other OSs it is the
+ CPU time used (by latexmk and the child processes it invokes).
The OS-dependence is because of a limitation of Windows. If you
wish to force the use of clock instead of CPU time, you can set
@@ -4473,17 +4482,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
compilation may take well under a second.
- $texfile_search [""]
- This is an obsolete variable, replaced by the @default_files
- variable.
-
- For backward compatibility, if you choose to set $tex-
- file_search, it is a string of space-separated filenames, and
- then latexmk replaces @default_files with the filenames in
-
-
- 7 April 2024 68
+ 27 December 2024 68
@@ -4492,64 +4492,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- $texfile_search to which is added "*.tex".
+ $texfile_search [""]
+ This is an obsolete variable, replaced by the @default_files
+ variable.
+
+ For backward compatibility, if you choose to set $tex-
+ file_search, it is a string of space-separated filenames, and
+ then latexmk replaces @default_files with the filenames in $tex-
+ file_search to which is added "*.tex".
$success_cmd [undefined]
See the documentation for $compiling_cmd.
$tmpdir [See below for default]
- Directory to store temporary files that latexmk may generate
+ Directory to store temporary files that latexmk may generate
while running.
- The default under MSWindows (including cygwin), is to set $tm-
- pdir to the value of the first of whichever of the system envi-
- ronment variables TMPDIR or TEMP exists, otherwise to the cur-
- rent directory. Under other operating systems (expected to be
- UNIX/Linux, including OS-X), the default is the value of the
- system environment variable TMPDIR if it exists, otherwise
+ The default under MSWindows (including cygwin), is to set $tm-
+ pdir to the value of the first of whichever of the system envi-
+ ronment variables TMPDIR or TEMP exists, otherwise to the cur-
+ rent directory. Under other operating systems (expected to be
+ UNIX/Linux, including OS-X), the default is the value of the
+ system environment variable TMPDIR if it exists, otherwise
"/tmp".
+
$use_make_for_missing_files [0]
Whether to use make to try and make files that are missing after
- a run of *latex, and for which a custom dependency has not been
- found. This is generally useful only when latexmk is used as
- part of a bigger project which is built by using the make pro-
+ a run of *latex, and for which a custom dependency has not been
+ found. This is generally useful only when latexmk is used as
+ part of a bigger project which is built by using the make pro-
gram.
Note that once a missing file has been made, no further calls to
- make will be made on a subsequent run of latexmk to update the
- file. Handling this problem is the job of a suitably defined
- Makefile. See the section "USING latexmk WITH make" for how to
- do this. The intent of calling make from latexmk is merely to
+ make will be made on a subsequent run of latexmk to update the
+ file. Handling this problem is the job of a suitably defined
+ Makefile. See the section "USING latexmk WITH make" for how to
+ do this. The intent of calling make from latexmk is merely to
detect dependencies.
- $view ["default"]
- Which kind of file is to be previewed if a previewer is used.
- The possible values are "default", "dvi", "ps", "pdf". The
- value of "default" means that the "highest" of the kinds of file
- generated is to be used (among .dvi, .ps and .pdf).
+ $user_deleted_file_treated_as_changed [0]
+ Whether when testing for changed files, a user file that changes
+ status from existing to non-existing should be regarded as
+ changed.
- $warnings_as_errors [0]
- Normally latexmk copies the behavior of latex in treating unde-
- fined references and citations and multiply defined references
- as conditions that give a warning but not an error. The vari-
- able $warnings_as_errors controls whether this behavior is modi-
- fied.
+ The default value is 0, which implies that if a user file (as
+ opposed to a generated file) has been deleted since the previous
+ run, then no recompilation should be done. The reasoning is
+ that a rerun would simply produce an error.
- When the variable is non-zero, latexmk at the end of its run
- will return a non-zero status code to the operating system if
- any of the files processed gives a warning about problems with
- citations or references (i.e., undefined citations or references
- or multiply defined references). This is after latexmk has com-
- pleted all the runs it needs to try and resolve references and
- citations. Thus $warnings_as_errors being nonzero causes la-
- texmk to treat such warnings as errors, but only when they occur
- on the last run of *latex and only after processing is complete.
+ If the value is 1, then disappearance of a user file is treated
+ as triggering a rerun, but only in non-preview-continuous mode.
+
+ If the value is 2, then disappearance of a user file is treated
- 7 April 2024 69
+ 27 December 2024 69
@@ -4558,105 +4558,145 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
LATEXMK(1) General Commands Manual LATEXMK(1)
- A non-zero value $warnings_as_errors can be set by the command-
+ as triggering a rerun, always.
+
+
+ $view ["default"]
+ Which kind of file is to be previewed if a previewer is used.
+ The possible values are "default", "dvi", "hnt", "ps", "pdf",
+ "none". The value of "default" means that the "highest" of the
+ kinds of file generated is to be used (among .dvi, .hnt, .ps and
+ .pdf).
+
+
+ $warnings_as_errors [0]
+ Normally latexmk copies the behavior of latex in treating unde-
+ fined references and citations and multiply defined references
+ as conditions that give a warning but not an error. The vari-
+ able $warnings_as_errors controls whether this behavior is modi-
+ fied.
+
+ When the variable is non-zero, latexmk at the end of its run
+ will return a non-zero status code to the operating system if
+ any of the files processed gives a warning about problems with
+ citations or references (i.e., undefined citations or references
+ or multiply defined references). This is after latexmk has com-
+ pleted all the runs it needs to try and resolve references and
+ citations. Thus $warnings_as_errors being nonzero causes la-
+ texmk to treat such warnings as errors, but only when they occur
+ on the last run of *latex and only after processing is complete.
+ A non-zero value $warnings_as_errors can be set by the command-
line option -Werror.
The default behavior is normally satisfactory in the usual edit-
- compile-edit cycle. But, for example, latexmk can also be used
- as part of a build process for some bigger project, e.g., for
- creating documentation in the build of a software application.
- Then it is often sensible to treat citation and reference warn-
- ings as errors that require the overall build process to be
+ compile-edit cycle. But, for example, latexmk can also be used
+ as part of a build process for some bigger project, e.g., for
+ creating documentation in the build of a software application.
+ Then it is often sensible to treat citation and reference warn-
+ ings as errors that require the overall build process to be
aborted. Of course, since multiple runs of *latex are generally
- needed to resolve references and citations, what matters is not
+ needed to resolve references and citations, what matters is not
the warnings on the first run, but the warnings on the last run;
latexmk takes this into account appropriately.
- In addition, when preview-continuous mode is used, a non-zero
- value for $warnings_as_errors changes the use of the commands
- $failure_cmd, $warning_cmd, and $success_cmd after a complia-
+ In addition, when preview-continuous mode is used, a non-zero
+ value for $warnings_as_errors changes the use of the commands
+ $failure_cmd, $warning_cmd, and $success_cmd after a complia-
tion. If there are citation or reference warnings, but no other
- errors, the behavior is as follows. If $warning_cmd is set, it
- is used. If it is not set, then then if $warnings_as_errors is
- non-zero and $failure_cmd is set, then $failure_cmd. Otherwise
- $success_cmd is used, if it is set. (The foregoing explanation
+ errors, the behavior is as follows. If $warning_cmd is set, it
+ is used. If it is not set, then then if $warnings_as_errors is
+ non-zero and $failure_cmd is set, then $failure_cmd. Otherwise
+ $success_cmd is used, if it is set. (The foregoing explanation
is rather complicated, because latexmk has to deal with the case
that one or more of the commands isn't set.)
+
+
+
+
+ 27 December 2024 70
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
$xdv_mode [0]
- If one, generate an xdv version of the document by use of xela-
+ If one, generate an xdv version of the document by use of xela-
tex.
$xdvipdfmx ["xdvipdfmx -E -o %D %O %S"]
- The program to make a pdf file from an xdv file (used in con-
+ The program to make a pdf file from an xdv file (used in con-
junction with xelatex when $pdf_mode=5).
$xdvipdfmx_silent_switch ["-q"]
Switch(es) for the xdvipdfmx program when silent mode is on.
$xelatex ["xelatex %O %S"]
- Specifies the command line for the LaTeX processing program of
- when the xelatex program is called for. See the documentation
- of the -xelatex option for some special properties of latexmk's
+ Specifies the command line for the LaTeX processing program of
+ when the xelatex program is called for. See the documentation
+ of the -xelatex option for some special properties of latexmk's
use of xelatex.
- Note about xelatex: latexmk uses xelatex to make an .xdv rather
- than .pdf file, with the .pdf file being created in a separate
+ Note about xelatex: latexmk uses xelatex to make an .xdv rather
+ than .pdf file, with the .pdf file being created in a separate
step. This is enforced by the use of the -no-pdf option. If %O
- is part of the command for invoking xelatex, then latexmk will
+ is part of the command for invoking xelatex, then latexmk will
insert the -no-pdf option automatically, otherwise you must pro-
- vide the option yourself. See the documentation for the -pdfxe
+ vide the option yourself. See the documentation for the -pdfxe
option for why latexmk makes a .xdv file rather than a .pdf file
when xelatex is used.
+ To do a coordinated setting of all of $dvilualatex, $hilatex,
+ $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad-
+ vanced Configuration".
+ %xelatex_input_extensions
+ This variable specifies the extensions tried by latexmk when it
+ finds that an xelatex run resulted in an error that a file has
+ not been found, and the file is given without an extension.
+ This typically happens when LaTeX commands of the form \in-
+ put{file} or \includegraphics{figure}, when the relevant source
+ file does not exist.
- 7 April 2024 70
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %xelatex_input_extensions. The de-
+ fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
+ See details of the %latex_input_extensions for other information
+ that equally applies to %xelatex_input_extensions.
+ $xelatex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the xelatex program (specified in the variable
+ $xelatex) when silent mode is on.
+ See details of the $latex_silent_switch for other information
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ 27 December 2024 71
- To do a coordinated setting of all of $dvilualatex, $hilatex,
- $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad-
- vanced Configuration".
- %xelatex_input_extensions
- This variable specifies the extensions tried by latexmk when it
- finds that an xelatex run resulted in an error that a file has
- not been found, and the file is given without an extension.
- This typically happens when LaTeX commands of the form \in-
- put{file} or \includegraphics{figure}, when the relevant source
- file does not exist.
- In this situation, latexmk searches for custom dependencies to
- make the missing file(s), but restricts it to the extensions
- specified by the variable %xelatex_input_extensions. The de-
- fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
- See details of the %latex_input_extensions for other information
- that equally applies to %xelatex_input_extensions.
+LATEXMK(1) General Commands Manual LATEXMK(1)
- $xelatex_silent_switch ["-interaction=batchmode"]
- Switch(es) for the xelatex program (specified in the variable
- $xelatex) when silent mode is on.
- See details of the $latex_silent_switch for other information
that equally applies to $xelatex_silent_switch.
CUSTOM DEPENDENCIES
- In any RC file a set of custom dependencies can be set up to convert a
+ In any RC file a set of custom dependencies can be set up to convert a
file with one extension to a file with another. An example use of this
would be to allow latexmk to convert a .fig file to .eps to be included
in the .tex file.
@@ -4664,9 +4704,9 @@ CUSTOM DEPENDENCIES
Defining a custom dependency:
The old method of configuring latexmk to use a custom dependency was to
- directly manipulate the @cus_dep_list array that contains information
- defining the custom dependencies. (See the section "Old Method of
- Defining Custom Dependencies" for details.) This method still works,
+ directly manipulate the @cus_dep_list array that contains information
+ defining the custom dependencies. (See the section "Old Method of
+ Defining Custom Dependencies" for details.) This method still works,
but is no longer preferred.
A better method is to use the subroutines that allow convenient manipu-
@@ -4678,245 +4718,246 @@ CUSTOM DEPENDENCIES
The arguments are as follows:
-
-
-
- 7 April 2024 71
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
from extension:
- The extension of the file we are converting from (e.g. "fig").
+ The extension of the file we are converting from (e.g. "fig").
It is specified without a period.
to extension:
The extension of the file we are converting to (e.g. "eps"). It
is specified without a period.
- must: If non-zero, the file from which we are converting must exist,
- if it doesn't exist latexmk will give an error message and exit
+ must: If non-zero, the file from which we are converting must exist,
+ if it doesn't exist latexmk will give an error message and exit
unless the -f option is specified. If must is zero and the file
- we are converting from doesn't exist, then no action is taken.
+ we are converting from doesn't exist, then no action is taken.
Generally, the appropriate value of must is zero.
function:
- The name of the subroutine that latexmk should call to perform
- the file conversion. The first argument to the subroutine is
+ The name of the subroutine that latexmk should call to perform
+ the file conversion. The first argument to the subroutine is
the base name of the file to be converted without any extension.
- The subroutines are declared in the syntax of Perl. The func-
- tion should return 0 if it was successful and a nonzero number
+ The subroutines are declared in the syntax of Perl. The func-
+ tion should return 0 if it was successful and a nonzero number
if it failed.
- Naturally add_cus_dep adds a custom dependency with the specified from
- and to extensions. If a custom dependency has been previously defined
- (e.g., in an rcfile that was read earlier), then it is replaced by the
+ Naturally add_cus_dep adds a custom dependency with the specified from
+ and to extensions. If a custom dependency has been previously defined
+ (e.g., in an rcfile that was read earlier), then it is replaced by the
+
+
+
+ 27 December 2024 72
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
new one.
- The subroutine remove_cus_dep removes the specified custom dependency.
+ The subroutine remove_cus_dep removes the specified custom dependency.
The subroutine show_cus_dep causes a list of the currently defined cus-
tom dependencies to be sent to the screen output.
How custom dependencies are used:
An instance of a custom dependency rule is created whenever latexmk de-
- tects that a run of *latex needs to read a file, like a graphics file,
- whose extension is the to-extension of a custom dependency. Then la-
- texmk examines whether a file exists with the same name, but with the
- corresponding from-extension, as specified in the custom-dependency.
- If it does, then a corresponding instance of the custom dependency is
- created, after which the rule is invoked whenever the destination file
+ tects that a run of *latex needs to read a file, like a graphics file,
+ whose extension is the to-extension of a custom dependency. Then la-
+ texmk examines whether a file exists with the same name, but with the
+ corresponding from-extension, as specified in the custom-dependency.
+ If it does, then a corresponding instance of the custom dependency is
+ created, after which the rule is invoked whenever the destination file
(the one with the to-extension) is out-of-date with respect to the cor-
responding source file.
- To make the new destination file, the Perl subroutine specified in the
+ To make the new destination file, the Perl subroutine specified in the
rule is invoked, with an argument that is the base name of the files in
- question. Simple cases just involve a subroutine invoking an external
- program; this can be done by following the templates below, even by
- those without knowledge of the Perl programming language. Of course,
+ question. Simple cases just involve a subroutine invoking an external
+ program; this can be done by following the templates below, even by
+ those without knowledge of the Perl programming language. Of course,
experts could do something much more elaborate.
- One item in the specification of each custom-dependency rule, labeled
- "must" above, specifies how the rule should be applied when the source
+ One item in the specification of each custom-dependency rule, labeled
+ "must" above, specifies how the rule should be applied when the source
file fails to exist.
-
-
- 7 April 2024 72
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
- When latex reports that an input file (e.g., a graphics file) does not
+ When latex reports that an input file (e.g., a graphics file) does not
exist, latexmk tries to find a source file and a custom dependency that
can be used to make it. If it succeeds, then it creates an instance of
- the custom dependency and invokes it to make the missing file, after
+ the custom dependency and invokes it to make the missing file, after
which the next pass of latex etc will be able to read the newly created
file.
- Note for advanced usage: The operating system's environment variable
+ Note for advanced usage: The operating system's environment variable
TEXINPUTS can be used to specify a search path for finding files by la-
- tex etc. Correspondingly, when a missing file is reported, latexmk
- looks in the directories specified in TEXINPUTS as well as in the cur-
- rent directory, to find a source file from which an instance of a cus-
+ tex etc. Correspondingly, when a missing file is reported, latexmk
+ looks in the directories specified in TEXINPUTS as well as in the cur-
+ rent directory, to find a source file from which an instance of a cus-
tom dependency can be used to make the missing file.
Function to implement custom dependency, traditional method:
- The function that implements a custom dependency gets the information
+ The function that implements a custom dependency gets the information
on the files to be processed in two ways. The first is through its one
- argument; the argument contains the base name of the source and desti-
+ argument; the argument contains the base name of the source and desti-
nation files. The second way is described later.
- A simple and typical example of code in an initialization rcfile using
+ A simple and typical example of code in an initialization rcfile using
the first method is:
add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
+
+
+
+ 27 December 2024 73
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
sub fig2eps {
system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" );
}
- The first line adds a custom dependency that converts a file with ex-
+ The first line adds a custom dependency that converts a file with ex-
tension "fig", as created by the xfig program, to an encapsulated post-
- script file, with extension "eps". The remaining lines define a sub-
- routine that carries out the conversion. If a rule for converting
- "fig" to "eps" files already exists (e.g., from a previously read-in
- initialization file), the latexmk will delete this rule before making
+ script file, with extension "eps". The remaining lines define a sub-
+ routine that carries out the conversion. If a rule for converting
+ "fig" to "eps" files already exists (e.g., from a previously read-in
+ initialization file), the latexmk will delete this rule before making
the new one.
- Suppose latexmk is using this rule to convert a file "figure.fig" to
- "figure.eps". Then it will invoke the fig2eps subroutine defined in
- the above code with a single argument "figure", which is the basename
- of each of the files (possibly with a path component). This argument
- is referred to by Perl as $_[0]. In the example above, the subroutine
+ Suppose latexmk is using this rule to convert a file "figure.fig" to
+ "figure.eps". Then it will invoke the fig2eps subroutine defined in
+ the above code with a single argument "figure", which is the basename
+ of each of the files (possibly with a path component). This argument
+ is referred to by Perl as $_[0]. In the example above, the subroutine
uses the Perl command system to invoke the program fig2dev. The double
quotes around the string are a Perl idiom that signify that each string
- of the form of a variable name, $_[0] in this case, is to be substi-
+ of the form of a variable name, $_[0] in this case, is to be substi-
tuted by its value.
- If the return value of the subroutine is non-zero, then latexmk will
- assume an error occurred during the execution of the subroutine. In
- the above example, no explicit return value is given, and instead the
- return value is the value returned by the last (and only) statement,
+ If the return value of the subroutine is non-zero, then latexmk will
+ assume an error occurred during the execution of the subroutine. In
+ the above example, no explicit return value is given, and instead the
+ return value is the value returned by the last (and only) statement,
i.e., the invocation of system, which returns the value 0 on success.
- If you use pdflatex, lualatex or xelatex instead of latex, then you
+ If you use pdflatex, lualatex or xelatex instead of latex, then you
+ will probably prefer to convert your graphics files to pdf format, in
+ which case you would replace the above code in an initialization file
+ by
+ add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
+ sub fig2pdf {
+ system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" );
+ }
+ Note 1: In the command lines given in the system commands in the above
+ examples, double quotes have been inserted around the file names (im-
+ plemented by '\"' in the Perl language). They immunize the running of
+ the program against special characters in filenames. Very often these
+ quotes are not necessary, i.e., they can be omitted. But it is nor-
+ mally safer to keep them in. Even though the rules for quoting vary
+ between operating systems, command shells and individual pieces of
+ software, the quotes in the above examples do not cause problems in the
+ cases I have tested.
- 7 April 2024 73
+ Note 2: One case in which the quotes are important is when the files
+ are in a subdirectory and your operating system is Microsoft Windows.
+ Then the separator character for directory components can be either a
+ forward slash '/' or Microsoft's more usual backward slash '\'. For-
+ ward slashes are generated by latexmk, to maintain its sanity from
+ software like MiKTeX that mixes both directory separators; but their
+ 27 December 2024 74
-LATEXMK(1) General Commands Manual LATEXMK(1)
- will probably prefer to convert your graphics files to pdf format, in
- which case you would replace the above code in an initialization file
- by
- add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
- sub fig2pdf {
- system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" );
- }
+LATEXMK(1) General Commands Manual LATEXMK(1)
- Note 1: In the command lines given in the system commands in the above
- examples, double quotes have been inserted around the file names (im-
- plemented by '\"' in the Perl language). They immunize the running of
- the program against special characters in filenames. Very often these
- quotes are not necessary, i.e., they can be omitted. But it is nor-
- mally safer to keep them in. Even though the rules for quoting vary
- between operating systems, command shells and individual pieces of
- software, the quotes in the above examples do not cause problems in the
- cases I have tested.
- Note 2: One case in which the quotes are important is when the files
- are in a subdirectory and your operating system is Microsoft Windows.
- Then the separator character for directory components can be either a
- forward slash '/' or Microsoft's more usual backward slash '\'. For-
- ward slashes are generated by latexmk, to maintain its sanity from
- software like MiKTeX that mixes both directory separators; but their
correct use normally requires quoted filenames. (See a log file from a
- run of MiKTeX (at least in v. 2.9) for an example of the use of both
+ run of MiKTeX (at least in v. 2.9) for an example of the use of both
directory separators.)
- Note 3: The subroutines implementing custom dependencies in the exam-
- ples given just have a single line invoking an external program.
- That's the usual situation. But since the subroutines are in the Perl
- language, you can implement much more complicated processing if you
+ Note 3: The subroutines implementing custom dependencies in the exam-
+ ples given just have a single line invoking an external program.
+ That's the usual situation. But since the subroutines are in the Perl
+ language, you can implement much more complicated processing if you
need it.
Removing custom dependencies, and when you might need to do this:
- If you have some general custom dependencies defined in the system or
- user initialization file, you may find that for a particular project
- they are undesirable. So you might want to delete the unneeded ones.
- A situation where this would be desirable is where there are multiple
- custom dependencies with the same from-extension or the same to-exten-
- sion. In that case, latexmk might choose a different one from the one
+ If you have some general custom dependencies defined in the system or
+ user initialization file, you may find that for a particular project
+ they are undesirable. So you might want to delete the unneeded ones.
+ A situation where this would be desirable is where there are multiple
+ custom dependencies with the same from-extension or the same to-exten-
+ sion. In that case, latexmk might choose a different one from the one
you want for a specific project. As an example, to remove any "fig" to
"eps" rule you would use:
remove_cus_dep( 'fig', 'eps' );
- If you have complicated sets of custom dependencies, you may want to
- get a listing of the custom dependencies. This is done by using the
+ If you have complicated sets of custom dependencies, you may want to
+ get a listing of the custom dependencies. This is done by using the
line
show_cus_dep();
-
-
-
- 7 April 2024 74
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
in an initialization file.
Function implementing custom dependency, alternative methods:
So far the examples for functions to implement custom dependencies have
used the argument of the function to specify the base name of converted
- file. This method has been available since very old versions of la-
+ file. This method has been available since very old versions of la-
texmk, and many examples can be found, e.g., on the web.
- However in later versions of latexmk the internal structure of the im-
+ However in later versions of latexmk the internal structure of the im-
plementation of its "rules" for the steps of processing, including cus-
tom dependencies, became much more powerful. The function implementing
a custom dependency is executed within a special context where a number
- of extra variables and subroutines are defined. Publicly documented
- ones, intended to be long-term stable, are listed below, under the
+ of extra variables and subroutines are defined. Publicly documented
+ ones, intended to be long-term stable, are listed below, under the
heading "Variables and subroutines for processing a rule".
- Examples of their use is given in the following examples, concerning
+ Examples of their use is given in the following examples, concerning
multiple index files and glossaries.
- The only index-file conversion built-in to latexmk is from an ".idx"
- file written on one run of *latex to an ".ind" file to be read in on a
- subsequent run. But with the index.sty package, for example, you can
- create extra indexes with extensions that you configure. Latexmk does
+ The only index-file conversion built-in to latexmk is from an ".idx"
+ file written on one run of *latex to an ".ind" file to be read in on a
+ subsequent run. But with the index.sty package, for example, you can
+ create extra indexes with extensions that you configure. Latexmk does
not know how to deduce the extensions from the information it has. But
- you can easily write a custom dependency. For example if your latex
+
+
+
+ 27 December 2024 75
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ you can easily write a custom dependency. For example if your latex
file uses the command "\newindex{special}{ndx}{nnd}{Special index}" you
- will need to get latexmk to convert files with the extension .ndx to
- .nnd. The most elementary method is to define a custom dependency as
+ will need to get latexmk to convert files with the extension .ndx to
+ .nnd. The most elementary method is to define a custom dependency as
follows:
add_cus_dep( 'ndx', 'nnd', 0, 'ndx2nnd' );
@@ -4925,14 +4966,14 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
}
push @generated_exts, 'ndx', 'nnd';
- Notice the added line compared with earlier examples. The extra line
+ Notice the added line compared with earlier examples. The extra line
gets the extensions "ndx" and "nnd" added to the list of extensions for
generated files; then the extra index files will be deleted by clean-up
operations
- But if you have yet more indexes with yet different extensions, e.g.,
- "adx" and "and", then you will need a separate function for each pair
- of extensions. This is quite annoying. You can use the Run_subst
+ But if you have yet more indexes with yet different extensions, e.g.,
+ "adx" and "and", then you will need a separate function for each pair
+ of extensions. This is quite annoying. You can use the Run_subst
function to simplify the definitions to use a single function:
add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
@@ -4942,18 +4983,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
}
push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
-
-
-
- 7 April 2024 75
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
You could also instead use
add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
@@ -4963,37 +4992,49 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
}
push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
- This last example uses the command specification in $makeindex, and so
- any customization you have made for the standard index also applies to
+ This last example uses the command specification in $makeindex, and so
+ any customization you have made for the standard index also applies to
your extra indexes.
Similar techniques can be applied for glossaries.
Those of you with experience with Makefiles, may get concerned that the
- .ndx file is written during a run of *latex and is always later than
+ .ndx file is written during a run of *latex and is always later than
the .nnd last read in. Thus the .nnd appears to be perpetually out-of-
- date. This situation, of circular dependencies, is endemic to latex,
- and is one of the issues that latexmk is programmed to overcome. It
- examines the contents of the files (by use of a checksum), and only
+ date. This situation, of circular dependencies, is endemic to latex,
+ and is one of the issues that latexmk is programmed to overcome. It
+ examines the contents of the files (by use of a checksum), and only
does a remake when the file contents have actually changed.
- Of course if you choose to write random data to the .nnd (or the .aux
- file, etc) that changes on each new run, then you will have a problem.
+ Of course if you choose to write random data to the .nnd (or the .aux
+ file, etc) that changes on each new run, then you will have a problem.
+
+
+
+ 27 December 2024 76
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
For real experts: See the %hash_calc_ignore_pattern if you have to deal
with such problems.
Old Method of Defining Custom Dependencies:
- In much older versions of latexmk, the only method of defining custom
- dependencies was to directly manipulate the table of custom dependen-
+ In much older versions of latexmk, the only method of defining custom
+ dependencies was to directly manipulate the table of custom dependen-
cies. This is contained in the @cus_dep_list array. It is an array of
- strings, and each string in the array has four items in it, each sepa-
- rated by a space, the from-extension, the to-extension, the "must"
- item, and the name of the subroutine for the custom dependency. These
+ strings, and each string in the array has four items in it, each sepa-
+ rated by a space, the from-extension, the to-extension, the "must"
+ item, and the name of the subroutine for the custom dependency. These
were all defined above.
An example of the old method of defining custom dependencies is as fol-
- lows. It is the code in an RC file to ensure automatic conversion of
+ lows. It is the code in an RC file to ensure automatic conversion of
.fig files to .eps files:
push @cus_dep_list, "fig eps 0 fig2eps";
@@ -5001,93 +5042,81 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
return system( "fig2dev -Lps \"$_[0].fig\" \"$_[0].eps\"" );
}
- This method still works, and is almost equivalent to the code given
- earlier that used the add_cus_dep subroutine. However, the old method
- doesn't delete any previous custom-dependency for the same conversion.
+ This method still works, and is almost equivalent to the code given
+ earlier that used the add_cus_dep subroutine. However, the old method
+ doesn't delete any previous custom-dependency for the same conversion.
So the new method is preferable.
+ADVANCED CONFIGURATION: SOME EXTRA RESOURCES AND ADVANCED TRICKS
+ For most purposes, simple configuration for latexmk along the lines of
+ the examples given is sufficient. But sometimes you need something
+ harder. In this section, I indicate some extra possibilities. Gener-
+ ally to use these, you need to be fluent in the Perl language, since
+ this is what is used in the rc files.
+ In this section, I include first, a description of a number of vari-
+ ables and subroutines that provide, among other things, access to la-
+ texmk's internal data structures for handling dependencies. Then I de-
+ scribe the hook mechanism whereby at certain points in the processing,
+ latexmk can call user-defined subroutines.
+ See also the section DEALING WITH ERRORS, PROBLEMS, ETC. See also the
+ examples in the directory example_rcfiles in the latexmk distributions.
+ Even if none of the examples apply to your case, they may give you use-
+ ful ideas
- 7 April 2024 76
+ Variables and subroutines for processing a rule
+ A step in the processing is called a rule. One possibility to implement
+ the processing of a rule is by a Perl subroutine. This is always the
+ case for custom dependencies. Also, for any other rule, you can use a
-LATEXMK(1) General Commands Manual LATEXMK(1)
+ 27 December 2024 77
-ADVANCED CONFIGURATION: SOME EXTRA RESOURCES AND ADVANCED TRICKS
- For most purposes, simple configuration for latexmk along the lines of
- the examples given is sufficient. But sometimes you need something
- harder. In this section, I indicate some extra possibilities. Gener-
- ally to use these, you need to be fluent in the Perl language, since
- this is what is used in the rc files.
- In this section, I include first, a description of a number of vari-
- ables and subroutines that provide, among other things, access to la-
- texmk's internal data structures for handling dependencies. Then I de-
- scribe the hook mechanism whereby at certain points in the processing,
- latexmk can call user-defined subroutines.
- See also the section DEALING WITH ERRORS, PROBLEMS, ETC. See also the
- examples in the directory example_rcfiles in the latexmk distributions.
- Even if none of the examples apply to your case, they may give you use-
- ful ideas
+LATEXMK(1) General Commands Manual LATEXMK(1)
- Variables and subroutines for processing a rule
- A step in the processing is called a rule. One possibility to implement
- the processing of a rule is by a Perl subroutine. This is always the
- case for custom dependencies. Also, for any other rule, you can use a
- subroutine by prefixing the command specification by the word "inter-
+ subroutine by prefixing the command specification by the word "inter-
nal" -- see the section FORMAT OF COMMAND SPECIFICATIONS.
- When you use a subroutine for processing a rule, all the possibilities
+ When you use a subroutine for processing a rule, all the possibilities
of Perl programming are available, of course. In addition, some of la-
- texmk's internal variables and subroutines are available. The ones
- listed below are intended to be available to (advanced) users, and
+ texmk's internal variables and subroutines are available. The ones
+ listed below are intended to be available to (advanced) users, and
their specifications will generally have stability under upgrades. Gen-
- erally, the variables should be treated as read-only: Changing their
- values can have bad consequences, since it is liable to mess up the
+ erally, the variables should be treated as read-only: Changing their
+ values can have bad consequences, since it is liable to mess up the
consistency of what latexmk is doing.
- $rule This variable has the name of the rule, as known to latexmk.
- Note that the exact contents of this variable for a given rule
+ $rule This variable has the name of the rule, as known to latexmk.
+ Note that the exact contents of this variable for a given rule
may be dependent on the version of latexmk
$$Pbase
- This gives the basename for the rule. Generally, it determines
- the names of generated files. E.g., for a run of *latex, the
+ This gives the basename for the rule. Generally, it determines
+ the names of generated files. E.g., for a run of *latex, the
name of the .log file is the aux directory concatenated with the
basename and then `.log'.
- For a *latex rule, the basename is without a directory compo-
- nent. For other rules, it includes the directory component (if
+ For a *latex rule, the basename is without a directory compo-
+ nent. For other rules, it includes the directory component (if
any is used).
This (annoying) difference is associated with the different ways
- in which the commands invoked by latexmk work when the command
+ in which the commands invoked by latexmk work when the command
line includes a name for a source file that includes a directory
-
-
-
- 7 April 2024 77
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
component. For the *latex commands, the directory of the source
- file is irrelevant to the directory component the generated
+ file is irrelevant to the directory component the generated
files, which instead is determined by the values in the -aux-di-
rectory and/or -output-directory options.
@@ -5096,21 +5125,33 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
with a changed extension.
Note the double dollar signs: In Perl terms, the variable $Pbase
- is a reference to a variable that contains the basename. The
- second dollar sign derefences the reference to give the actual
- value. (A reference is is used rather like a pointer, and the
- `P' (for `pointer') at the start of the variable name is a con-
- vention used in latexmk to indicate that the variable is a ref-
+ is a reference to a variable that contains the basename. The
+ second dollar sign derefences the reference to give the actual
+ value. (A reference is is used rather like a pointer, and the
+ `P' (for `pointer') at the start of the variable name is a con-
+ vention used in latexmk to indicate that the variable is a ref-
erence variable.)
$$Pdest
- This gives the name of the main output file if any. Note the
+ This gives the name of the main output file if any. Note the
double dollar signs.
$$Psource
This gives the name of the primary source file. Note the double
+
+
+
+ 27 December 2024 78
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
dollar signs.
@@ -5118,11 +5159,11 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
See the section `Hooks' for more details.
This adds the subroutine specified in the second argument to la-
- texmk's stack of hooks specified by the stack name. It returns
- 1 on sucess, and zero otherwise (e.g., if the specified hook
+ texmk's stack of hooks specified by the stack name. It returns
+ 1 on sucess, and zero otherwise (e.g., if the specified hook
stack doesn't exist).
- The subroutine can be specified by a reference to the subrou-
+ The subroutine can be specified by a reference to the subrou-
tine, as in
add_hook( 'after_xlatex_analysis', mmz_analyze )
@@ -5130,171 +5171,161 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Given that the subroutine mmz_analyze has been defined in the rc
file.
- The subroutine can be specified by a string whose value is the
+ The subroutine can be specified by a string whose value is the
name of the subroutine, e.g.,
add_hook( 'after_xlatex_analysis', 'mmz_analyze' )
- In simple cases, the subroutine can be an anonymous subroutine
+ In simple cases, the subroutine can be an anonymous subroutine
defined in the call to add_hooks,
- add_hook( 'after_main_pdf', sub{ print
+ add_hook( 'after_main_pdf', sub{ print "TEST\n"; return 0; }
+ );
+ Observe that on success, the subroutine should return 0 (like a
+ call to Perl's system subroutine), so normally this should be
+ coded explicitly. If a hook subroutine returns a non-zero
+ value, latexmk treats that as an error condition.
- 7 April 2024 78
+ ensure_path( var, values ...)
+ The first parameter is the name of one of the system's environ-
+ ment variables for search paths. The remaining parameters are
+ values that should be in the variable. For each of the value
+ parameters, if it isn't already in the variable, then it is
+ prepended to the variable; in that case the environment variable
+ is created if it doesn't already exist. For separating values,
+ the character appropriate the the operating system is used --
+ see the configuration variable $search_path_separator.
+ Example:
+ ensure_path( 'TEXINPUTS', './custom_cls_sty_files//' );
+ (In this example, the trailing '//' is documented by TeX systems
+ to mean that *latex search for files in the specified directory
-LATEXMK(1) General Commands Manual LATEXMK(1)
- Observe that on success, the subroutine should return 0 (like a
- call to Perl's system subroutine), so normally this should be
- coded explicitly. If a hook subroutine returns a non-zero
- value, latexmk treats that as an error condition.
+ 27 December 2024 79
- ensure_path( var, values ...)
- The first parameter is the name of one of the system's environ-
- ment variables for search paths. The remaining parameters are
- values that should be in the variable. For each of the value
- parameters, if it isn't already in the variable, then it is
- prepended to the variable; in that case the environment variable
- is created if it doesn't already exist. For separating values,
- the character appropriate the the operating system is used --
- see the configuration variable $search_path_separator.
- Example:
+LATEXMK(1) General Commands Manual LATEXMK(1)
- ensure_path( 'TEXINPUTS', './custom_cls_sty_files//' );
- (In this example, the trailing '//' is documented by TeX systems
- to mean that *latex search for files in the specified directory
and in all subdirectories.)
- Technically ensure_path works by setting Perl's variable
- $ENV{var}, where var is the name of the target variable. The
- changed value is then passed as an environment variable to any
+ Technically ensure_path works by setting Perl's variable
+ $ENV{var}, where var is the name of the target variable. The
+ changed value is then passed as an environment variable to any
invoked programs.
pushd( path ), popd()
- These subroutines are used when it is needed to temporarily
+ These subroutines are used when it is needed to temporarily
change the working directory, as in
pushd( 'some_directory' );
- ... Processing done with 'some_directory' as the working
+ ... Processing done with 'some_directory' as the working
directory
popd()
- They perform exactly the same function as the commands of the
+ They perform exactly the same function as the commands of the
same names in operating system command shells like bash on Unix,
and cmd.exe on the Windows.
rdb_add_generated( file, ... )
This subroutine is to be used in the context of a rule, that is,
- from within a subroutine that is carrying out processing of a
+ from within a subroutine that is carrying out processing of a
rule. Such is the case for the subroutine implementing a custom
- dependency, or the subroutine invoked by using the "internal"
- keyword in the command specification like that in the variable
+ dependency, or the subroutine invoked by using the "internal"
+ keyword in the command specification like that in the variable
$latex.
+ Its arguments are a sequence of filenames which are generated
+ during the running of the rule. The names might arise from an
+ analysis of the results of the run, e.g., in a log file, or from
+ knowledge of properties of the specific rule. Calling
+ rdb_add_generated with these filenames ensures that these files
+ are flagged as generated by the rule in latexmk's internal data
+ structures. Basically, no action is taken if the files have al-
+ ready been flagged as generated.
+ A main purpose of using this subroutine is for the situation
+ when a generated file is also the source file for some rule, so
+ that latexmk can correctly link the dependency information in
+ its network of rules.
+ Note: Unlike some other subroutines in this section, there is no
+ argument for a rule for rdb_add_generated. Instead, the subrou-
+ tine is to be invoked during the processing of a rule when la-
+ texmk has set up an appropriate context (i.e., appropriate vari-
+ ables). In contrast, subroutines with a rule argument can be
+ used also outside a rule context.
- 7 April 2024 79
+ rdb_ensure_file( $rule, file )
+ This subroutine ensures that the given file is among the source
+ 27 December 2024 80
-LATEXMK(1) General Commands Manual LATEXMK(1)
- Its arguments are a sequence of filenames which are generated
- during the running of the rule. The names might arise from an
- analysis of the results of the run, e.g., in a log file, or from
- knowledge of properties of the specific rule. Calling
- rdb_add_generated with these filenames ensures that these files
- are flagged as generated by the rule in latexmk's internal data
- structures. Basically, no action is taken if the files have al-
- ready been flagged as generated.
- A main purpose of using this subroutine is for the situation
- when a generated file is also the source file for some rule, so
- that latexmk can correctly link the dependency information in
- its network of rules.
- Note: Unlike some other subroutines in this section, there is no
- argument for a rule for rdb_add_generated. Instead, the subrou-
- tine is to be invoked during the processing of a rule when la-
- texmk has set up an appropriate context (i.e., appropriate vari-
- ables). In contrast, subroutines with a rule argument can be
- used also outside a rule context.
+LATEXMK(1) General Commands Manual LATEXMK(1)
- rdb_ensure_file( $rule, file )
- This subroutine ensures that the given file is among the source
files for the specified rule. It is typically used when, during
- the processing of a rule, it is known that a particular extra
+ the processing of a rule, it is known that a particular extra
file is among the dependencies that latexmk should know, but its
- default methods don't find the dependency. Almost always the
- first argument is the name of the rule currently being
+ default methods don't find the dependency. Almost always the
+ first argument is the name of the rule currently being
processed, so it is then appropriate to specify it by $rule.
- For examples of its use, see some of the files in the directory
- example_rcfiles of latexmk's distribution. Currently the cases
- that use this subroutine are bib2gls-latexmkrc, exceltex_la-
- texmkrc and texinfo-latexmkrc. These illustrate typical cases
- where latexmk's normal processing fails to detect certain extra
+ For examples of its use, see some of the files in the directory
+ example_rcfiles of latexmk's distribution. Currently the cases
+ that use this subroutine are bib2gls-latexmkrc, exceltex_la-
+ texmkrc and texinfo-latexmkrc. These illustrate typical cases
+ where latexmk's normal processing fails to detect certain extra
source files.
Note that rdb_ensure_file only has one filename argument, unlike
other subroutines in this section. If you want to apply its ac-
- tion to multiple files, you will need one call to rdb_en-
+ tion to multiple files, you will need one call to rdb_en-
sure_file for each file.
rdb_ensure_files_here( file, ... )
Like subroutine rdb_ensure_files, except that (a) it assumes the
- context is of a rule, and the files are to be added to the
+ context is of a rule, and the files are to be added to the
source list for that rule; (b) multiple files are allowed.
rdb_remove_files( $rule, file, ... )
- This subroutine removes one or more files from the dependency
+ This subroutine removes one or more files from the dependency
list for the given rule.
-
-
- 7 April 2024 80
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
rdb_remove_generated( file, ... )
This subroutine is to be used in the context of a rule, that is,
- from within a subroutine that is carrying out processing of a
- rule. It performs the opposite action to rdb_add_generated.
- Its effect is to ensure that the given filenames are not listed
- in latexmk's internal data structures as being generated by the
+ from within a subroutine that is carrying out processing of a
+ rule. It performs the opposite action to rdb_add_generated.
+ Its effect is to ensure that the given filenames are not listed
+ in latexmk's internal data structures as being generated by the
rule.
rdb_list_source( $rule )
- This subroutine returns the list of source files (i.e., the de-
+ This subroutine returns the list of source files (i.e., the de-
pendency list) for the given rule.
@@ -5302,12 +5333,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
rdb_set_source( $rule, @files )
- This subroutine sets the dependency list for the given rule to
+ This subroutine sets the dependency list for the given rule to
be the specified files. Files that are already in the list have
- unchanged information. Files that were not in the list are
+ unchanged information. Files that were not in the list are
added to it. Files in the previous dependency list that are not
- in the newly specified list of files are removed from the depen-
- dency list.
+ in the newly specified list of files are removed from the
+
+
+
+ 27 December 2024 81
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ dependency list.
Run_subst( command_spec )
@@ -5338,18 +5381,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
In addition, latexmk makes allowance for the possiblity that
files are hosted on a different computer than that running la-
texmk and that the system clock times on the two computers are
-
-
-
- 7 April 2024 81
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
mismatched. Latexmk automatically detects (and reports) any
significant mismatch and corrects for it.
@@ -5374,6 +5405,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
To be able to use the string provided by the -pretex option (if any),
you can use
+
+
+ 27 December 2024 82
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
&alt_tex_cmds;
This results in $latex = 'latex %O %P', etc. Again note the ampersand
@@ -5405,17 +5447,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
ment/pre-release versions of latex, etc, which have names, 'latex-dev',
'pdflatex-dev', etc, you could use
-
-
- 7 April 2024 82
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
set_tex_cmds( '%C-dev %O %S' );
This results in $latex = 'latex-dev %O %S', etc. (The pre-release pro-
@@ -5439,6 +5470,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Note that the hook mechanism is newly made public in v. 4.84 of la-
texmk. It is subject to change and improvement as experience is
+
+
+
+ 27 December 2024 83
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
gained.
The hooks are arranged in named hook stacks, and a hook subroutine is
@@ -5470,18 +5513,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
stack provide a useful way of adding items to the dependency infor-
mation
associated with particular packages and that latexmk doesn't
-
-
-
- 7 April 2024 83
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
automatically deal with.
@@ -5505,6 +5536,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
These subroutines are called before latexmk does any of its own
file
+
+
+
+ 27 December 2024 84
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
deletion; thus the hook subroutines have access to all the gener-
ated
files that give package-specific information.
@@ -5538,16 +5581,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
-
- 7 April 2024 84
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
Advanced configuration: Using latexmk with make
This section is targeted only at advanced users who use the make pro-
gram for complex projects, as for software development, with the depen-
@@ -5569,6 +5602,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
suitably configured. A standard configuration would be to define cus-
tom dependencies to make graphics files from their source files (e.g.,
as created by the xfig program). Custom dependencies are latexmk's
+
+
+
+ 27 December 2024 85
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
equivalent of pattern rules in Makefiles.
Nevertheless there are projects for which a Makefile is appropriate,
@@ -5602,18 +5647,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
The above example has a pattern rule for making a .pdf file from a .tex
file, and it is defined to use latexmk in the obvious way. There is a
-
-
-
- 7 April 2024 85
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
conventional default target named "all", with a prerequisite of
try.pdf. So when make is invoked, by default it makes try.pdf. The
only complication is that there may be many source files beyond
@@ -5635,6 +5668,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
TARGETS = document1.pdf document2.pdf
DEPS_DIR = .deps
+
+
+
+ 27 December 2024 86
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
LATEXMK = latexmk -recorder -use-make -deps \
-e 'warn qq(In Makefile, turn off custom dependencies\n);' \
-e '@cus_dep_list = ();' \
@@ -5668,18 +5713,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
tion, which improves its detection of files generated during a run of
pdflatex; such files should not be in the dependency list. The -e op-
tions are used to turn off all custom dependencies, and to document
-
-
-
- 7 April 2024 86
-
-
-
-
-
-LATEXMK(1) General Commands Manual LATEXMK(1)
-
-
this. Instead the -use-make is used to delegate the making of missing
files to make itself.
@@ -5700,24 +5733,36 @@ LATEXMK(1) General Commands Manual LATEXMK(1)
Generally, such special characters are best avoided.
By default, latexmk does no escaping of this kind, and the user will
- have to arrange to deal with the issue separately, if the relevant spe-
- cial characters are used. Note that the rules for escaping depend on
- which make program is used, and on its version.
+ have to arrange to deal with the issue separately, if the relevant
+
+
+
+ 27 December 2024 87
+
- One special case is of spaces, since those are particularly prevalent,
- notably in standard choices of name for a user's home directory. So
- latexmk does provide an option to escape spaces. See the option
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ special characters are used. Note that the rules for escaping depend
+ on which make program is used, and on its version.
+
+ One special case is of spaces, since those are particularly prevalent,
+ notably in standard choices of name for a user's home directory. So
+ latexmk does provide an option to escape spaces. See the option
-deps_escape=... and the variable $deps_escape for details.
NON_ASCII CHARACTERS IN FILENAMES, RC FILES, ETC
Modern operating systems and file systems allow non-ASCII characters in
- the names of files and directories that encompass the full Unicode
+ the names of files and directories that encompass the full Unicode
range. Mostly, latexmk deals with these correctly. However, there are
- some situations in which there are problems, notably on Microsoft Win-
+ some situations in which there are problems, notably on Microsoft Win-
dows. Prior to version 4.77, latexmk had problems with non-ASCII file-
- names on Windows, even though there were no corresponding problems on
+ names on Windows, even though there were no corresponding problems on
macOS and Linux. These problems are corrected in the present version.
DETAILS TO BE FILLED IN
@@ -5730,47 +5775,47 @@ SEE ALSO
BUGS (SELECTED)
Sometimes a viewer (gv) tries to read an updated .ps or .pdf file after
- its creation is started but before the file is complete. Work around:
+ its creation is started but before the file is complete. Work around:
manually refresh (or reopen) display. Or use one of the other preview-
ers and update methods.
+ (The following isn't really a bug, but concerns features of preview-
+ ers.) Preview continuous mode only works perfectly with certain pre-
+ viewers: Xdvi on UNIX/Linux works for dvi files. Gv on UNIX/Linux
+ works for both postscript and pdf. Ghostview on UNIX/Linux needs a
+ manual update (reopen); it views postscript and pdf. Gsview under MS-
+ Windows works for both postscript and pdf, but only reads the updated
+ file when its screen is refreshed. Acroread under UNIX/Linux views
+ pdf, but the file needs to be closed and reopened to view an updated
+ version. Under MS-Windows, acroread locks its input file and so the
+ pdf file cannot be updated. (Remedy: configure latexmk to use suma-
+ trapdf instead.)
+THANKS TO
+ Authors of previous versions. Many users with their feedback, and es-
+ pecially David Coppit (username david at node coppit.org) who made many
+ useful suggestions that contributed to version 3, and Herbert Schulz.
+ (Please note that the e-mail addresses are not written in their stan-
+ dard form to avoid being harvested too easily.)
+AUTHOR
+ Current version, by John Collins (Version 4.86a). Report bugs etc to
- 7 April 2024 87
+ 27 December 2024 88
-LATEXMK(1) General Commands Manual LATEXMK(1)
- (The following isn't really a bug, but concerns features of preview-
- ers.) Preview continuous mode only works perfectly with certain pre-
- viewers: Xdvi on UNIX/Linux works for dvi files. Gv on UNIX/Linux
- works for both postscript and pdf. Ghostview on UNIX/Linux needs a
- manual update (reopen); it views postscript and pdf. Gsview under MS-
- Windows works for both postscript and pdf, but only reads the updated
- file when its screen is refreshed. Acroread under UNIX/Linux views
- pdf, but the file needs to be closed and reopened to view an updated
- version. Under MS-Windows, acroread locks its input file and so the
- pdf file cannot be updated. (Remedy: configure latexmk to use suma-
- trapdf instead.)
+LATEXMK(1) General Commands Manual LATEXMK(1)
-THANKS TO
- Authors of previous versions. Many users with their feedback, and es-
- pecially David Coppit (username david at node coppit.org) who made many
- useful suggestions that contributed to version 3, and Herbert Schulz.
- (Please note that the e-mail addresses are not written in their stan-
- dard form to avoid being harvested too easily.)
-AUTHOR
- Current version, by John Collins (Version 4.85). Report bugs etc to
his e-mail (jcc8 at psu.edu).
- Released version can be obtained from CTAN:
- <http://www.ctan.org/pkg/latexmk/>, and from the author's website
+ Released version can be obtained from CTAN:
+ <http://www.ctan.org/pkg/latexmk/>, and from the author's website
<https://www.cantab.net/users/johncollins/latexmk/>.
Modifications and enhancements by Evan McLean (Version 2.0)
Original script called "go" by David J. Musliner (RCS Version 3.2)
@@ -5803,6 +5848,27 @@ AUTHOR
- 7 April 2024 88
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 27 December 2024 89
diff --git a/Master/texmf-dist/doc/support/luafindfont/CHANGELOG b/Master/texmf-dist/doc/support/luafindfont/CHANGELOG
index 783f804f294..a629f6617a8 100644
--- a/Master/texmf-dist/doc/support/luafindfont/CHANGELOG
+++ b/Master/texmf-dist/doc/support/luafindfont/CHANGELOG
@@ -1,3 +1,4 @@
+0.14 2024-08-25 - small changes to the output
0.13 2023-06-23 - add exrun:close() for every kpsewhich test
0.12 2023-06-21 - bugfix for undefined exrun (l. 251)
- check for empty font list and given font number
diff --git a/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.pdf b/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.pdf
index 65be6ced105..f51c3478b88 100644
--- a/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.pdf
+++ b/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.tex b/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.tex
index c10483ce5a2..818cd16fbb1 100644
--- a/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.tex
+++ b/Master/texmf-dist/doc/support/luafindfont/luafindfont-doc.tex
@@ -1,4 +1,4 @@
- %% $Id: luafindfont-doc.tex 648 2022-11-03 19:58:48Z herbert $
+ %% $Id: luafindfont-doc.tex 962 2024-08-25 16:50:54Z herbert $
%
\listfiles\setcounter{errorcontextlines}{100}
\documentclass[paper=a4,fontsize=11pt,DIV=14,parskip=half-,
@@ -81,7 +81,7 @@
\def\setVersion#1{\setVVersion#1!!}
\def\setVVersion#1=#2!!{\def\luafindfontVersion{#2}}
-\setVersion{version = 0.11}% can be automatically changed by perl
+\setVersion{version = 0.14}% can be automatically changed by perl
\setkeys{hv}{cleanup={},force}
diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README
index 561d6bd14dd..33ccdb5b815 100644
--- a/Master/texmf-dist/doc/support/make4ht/README
+++ b/Master/texmf-dist/doc/support/make4ht/README
@@ -1,4 +1,5 @@
% [![Build Status](https://travis-ci.org/michal-h21/make4ht.svg?branch=master)](https://travis-ci.org/michal-h21/make4ht)
+% HTML version of the documentation can be found [here](https://www.kodymirus.cz/make4ht/make4ht-doc.html)
# Introduction
@@ -8,11 +9,12 @@ customized conversion tools. An example of such a tool is
[tex4ebook](https://github.com/michal-h21/tex4ebook), a tool for conversion from \TeX\ to
ePub and other e-book formats.
-See section \ref{sec:htlatex} for some reasons why you should consider to use `make4ht` instead of `htlatex`,
-section \ref{sec:output} talks about supported output formats and extensions and section \ref{sec:buildfiles}
+See section \ref{sec:htlatex} for some reasons why you should consider to use `make4ht` instead
+of `htlatex`, section \ref{sec:output} talks about supported output formats and extensions and section \ref{sec:buildfiles}
describes build files, which can be used to execute additional commands or post-process the generated files.
+
# Usage
The basic conversion from \LaTeX\ to `HTML` using `make4ht` can be executed using the following command:
@@ -1162,12 +1164,23 @@ Example:
options
-: command line options for Dvisvgm. The default value is `-n --exact -c 1.15,1.15`.
+: command line options for Dvisvgm. The default value is `-n --exact -c ${scale},${scale}`.
cpu_cnt
: the number of processor cores used for the conversion. The extension tries to detect the available cores automatically by default.
+make_command
+
+: variant of the `make` command used for the parallel conversion of large
+number of pages. It receives tvo variables, `process_count` and `make_file`.
+Default value is "make -j ${process_count} -f ${make_file}".
+
+test_make_command
+
+: command that tests if the selected variant of the `make` command exists. Default value is `make -v`.
+
+
parallel_size
: the number of pages used in each Dvisvgm call. The extension detects changed
@@ -1176,7 +1189,7 @@ pages.
scale
-: SVG scaling.
+: amount of SVG scaling. The default value is 1.4.
## The `odttemplate` filter and extension
diff --git a/Master/texmf-dist/doc/support/make4ht/changelog.tex b/Master/texmf-dist/doc/support/make4ht/changelog.tex
index e17af6d5db3..d60bfc51c3c 100644
--- a/Master/texmf-dist/doc/support/make4ht/changelog.tex
+++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex
@@ -3,6 +3,136 @@
\begin{itemize}
\item
+ 2024/10/22
+
+ \begin{itemize}
+ \tightlist
+ \item
+ version \texttt{0.4b} released.
+ \item
+ test for the existence of the class atribute of tables before
+ performing string matches in the \texttt{tablerows} DOM filter.
+ \end{itemize}
+\item
+ 2024/10/21
+
+ \begin{itemize}
+ \tightlist
+ \item
+ version \texttt{0.4a} released.
+ \end{itemize}
+\item
+ 2024/09/30
+
+ \begin{itemize}
+ \tightlist
+ \item
+ remove last empty row in \texttt{longtable} environments.
+ \end{itemize}
+\item
+ 2024/09/25
+
+ \begin{itemize}
+ \tightlist
+ \item
+ added \texttt{make4ht-char-def} library to remove dependency on
+ \texttt{char-def} from ConTeXt. It is used by the \texttt{sectionid}
+ DOM filter. The library is automatically created from
+ UnicodeData.txt by \texttt{tools/make\_chardata.lua}.
+ https://tex.stackexchange.com/q/727202/2891
+ \end{itemize}
+\item
+ 2024/09/18
+
+ \begin{itemize}
+ \tightlist
+ \item
+ print error messages from the \texttt{log} file.
+ \end{itemize}
+\item
+ 2024/08/22
+
+ \begin{itemize}
+ \tightlist
+ \item
+ print debug message with XML parsing error context
+ \end{itemize}
+\item
+ 2024/08/21
+
+ \begin{itemize}
+ \tightlist
+ \item
+ try the HTML parser for DOM filters if XML parser fails.
+ \end{itemize}
+\item
+ 2024/06/18
+
+ \begin{itemize}
+ \tightlist
+ \item
+ changed default scaling in \texttt{dvisvgm\_hashes} to 1.4.
+ \end{itemize}
+\item
+ 2024/06/17
+
+ \begin{itemize}
+ \tightlist
+ \item
+ fixed support for index entries that are broken over several lines.
+ \end{itemize}
+\item
+ 2024/05/29
+
+ \begin{itemize}
+ \tightlist
+ \item
+ create temporary Lg file for Xtpipes.
+ https://github.com/michal-h21/make4ht/issues/148\#issuecomment-2136160818
+ \item
+ fixed handling of the generated ODT file, don't copy it
+ unnecessarily and handle build and output directories.
+ https://github.com/michal-h21/make4ht/issues/148\#issuecomment-2136160818
+ \end{itemize}
+\item
+ 2024/04/23
+
+ \begin{itemize}
+ \tightlist
+ \item
+ test if referenced files are contained in the \texttt{build-dir}
+ directory, use the current dir otherwise.
+ https://github.com/michal-h21/tex4ebook/issues/126
+ \end{itemize}
+\item
+ 2024/04/16
+
+ \begin{itemize}
+ \tightlist
+ \item
+ fixed bug in \texttt{dvisvgm\_hashes} log parsing. On Windows, it
+ didn't expect \texttt{\textbackslash{}r} characters at the line
+ ends, they then ended in new SVG filenames.
+ \end{itemize}
+\item
+ 2024/04/15
+
+ \begin{itemize}
+ \tightlist
+ \item
+ made the \texttt{make} command used in the \texttt{dvisvgm\_hashes}
+ extension configurable. https://tex.stackexchange.com/q/715633/2891
+ \end{itemize}
+\item
+ 2024/03/29
+
+ \begin{itemize}
+ \tightlist
+ \item
+ ignore numbers in braces in \texttt{make4ht-indexing} library.
+ https://tex.stackexchange.com/q/714247/2891
+ \end{itemize}
+\item
2024/02/22
\begin{itemize}
diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
index 7eacc7bd950..ed8effdfe99 100644
--- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
+++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex
index 9cff4cbeeae..d5392e53114 100644
--- a/Master/texmf-dist/doc/support/make4ht/readme.tex
+++ b/Master/texmf-dist/doc/support/make4ht/readme.tex
@@ -10,11 +10,10 @@ tools. An example of such a tool is
conversion from \TeX~to ePub and other e-book formats.
See section \ref{sec:htlatex} for some reasons why you should consider
-to use \texttt{make4ht} instead of \texttt{htlatex},\\
-section \ref{sec:output} talks about supported output formats and
-extensions and section \ref{sec:buildfiles} describes build files, which
-can be used to execute additional commands or post-process the generated
-files.
+to use \texttt{make4ht} instead of \texttt{htlatex}, section
+\ref{sec:output} talks about supported output formats and extensions and
+section \ref{sec:buildfiles} describes build files, which can be used to
+execute additional commands or post-process the generated files.
\hypertarget{usage}{%
\section{Usage}\label{usage}}
@@ -1279,16 +1278,24 @@ extension}{The dvisvgm\_hashes extension}}\label{the-dvisvgm_hashes-extension}}
\begin{description}
\item[options]
command line options for Dvisvgm. The default value is
-\texttt{-n\ -\/-exact\ -c\ 1.15,1.15}.
+\texttt{-n\ -\/-exact\ -c\ \$\{scale\},\$\{scale\}}.
\item[cpu\_cnt]
the number of processor cores used for the conversion. The extension
tries to detect the available cores automatically by default.
+\item[make\_command]
+variant of the \texttt{make} command used for the parallel conversion of
+large number of pages. It receives tvo variables,
+\texttt{process\_count} and \texttt{make\_file}. Default value is ``make
+-j \$\{process\_count\} -f \$\{make\_file\}''.
+\item[test\_make\_command]
+command that tests if the selected variant of the \texttt{make} command
+exists. Default value is \texttt{make\ -v}.
\item[parallel\_size]
the number of pages used in each Dvisvgm call. The extension detects
changed pages in the DVI file and constructs multiple calls to Dvisvgm
with only changed pages.
\item[scale]
-SVG scaling.
+amount of SVG scaling. The default value is 1.4.
\end{description}
\hypertarget{the-odttemplate-filter-and-extension}{%
diff --git a/Master/texmf-dist/doc/support/pdfjam/COPYING b/Master/texmf-dist/doc/support/pdfjam/COPYING
index d60c31a97a5..9efa6fbc962 100644
--- a/Master/texmf-dist/doc/support/pdfjam/COPYING
+++ b/Master/texmf-dist/doc/support/pdfjam/COPYING
@@ -1,12 +1,12 @@
- GNU GENERAL PUBLIC LICENSE
- Version 2, June 1991
+ GNU GENERAL PUBLIC LICENSE
+ Version 2, June 1991
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
- Preamble
+ Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
@@ -15,7 +15,7 @@ software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
+the GNU Lesser General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
@@ -55,8 +55,8 @@ patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
-
- GNU GENERAL PUBLIC LICENSE
+
+ GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains
@@ -110,7 +110,7 @@ above, provided that you also meet all of these conditions:
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
-
+
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
@@ -168,7 +168,7 @@ access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
-
+
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
@@ -225,7 +225,7 @@ impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
-
+
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
@@ -255,7 +255,7 @@ make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
- NO WARRANTY
+ NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
@@ -277,9 +277,9 @@ YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
- END OF TERMS AND CONDITIONS
-
- How to Apply These Terms to Your New Programs
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
@@ -303,17 +303,15 @@ the "copyright" line and a pointer to where the full notice is found.
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
+ You should have received a copy of the GNU General Public License along
+ with this program; if not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
- Gnomovision version 69, Copyright (C) year name of author
+ Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
@@ -330,11 +328,11 @@ necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
+ <signature of Moe Ghoul>, 1 April 1989
+ Moe Ghoul, President of Vice
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
+library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License.
diff --git a/Master/texmf-dist/doc/support/pdfjam/README.md b/Master/texmf-dist/doc/support/pdfjam/README.md
index 50c65255f24..347a4124020 100644
--- a/Master/texmf-dist/doc/support/pdfjam/README.md
+++ b/Master/texmf-dist/doc/support/pdfjam/README.md
@@ -1,11 +1,13 @@
-![GitHub CI](https://github.com/rrthomas/pdfjam/actions/workflows/ci.yml/badge.svg)
-# pdfjam
+![GitHub CI](https://github.com/pdfjam/pdfjam/actions/workflows/ci.yml/badge.svg)
-_Reuben Thomas_ <https://rrt.sc3d.org/>
+pdfjam
+===
-A snapshot of this page is included as _README.md_
-in the distributed package. The most up-to-date version is maintained online at
-<https://github.com/rrthomas/pdfjam>.
+_Reuben Thomas_ <https://rrt.sc3d.org>, _Markus Kurtz_ <_anything_ at mgkurtz.de>
+
+A snapshot of this page is included as _README.md_
+in the distributed package. The most up-to-date version is maintained online at
+<https://github.com/pdfjam/pdfjam>.
1. [Overview](#overview)
- [What is pdfjam?](#whatis)
@@ -20,24 +22,24 @@ in the distributed package. The most up-to-date version is maintained online at
9. [Version history](#history)
-# <a name="overview"> Overview
+# <a name="overview"> Overview
## <a name="whatis"> What is pdfjam?
-The **pdfjam** package makes available the `pdfjam` shell script that provides a
-simple interface to much of the functionality of the excellent
-[pdfpages](https://www.ctan.org/tex-archive/macros/latex/contrib/pdfpages)
-package (by Andreas Matthias) for _LaTeX_. The `pdfjam` script takes one
-or more PDF files (and/or JPG/PNG graphics files) as input, and produces
-one or more PDF files as output. It is useful for joining files together,
+The **pdfjam** package makes available the `pdfjam` shell script that provides a
+simple interface to much of the functionality of the excellent
+[pdfpages](https://www.ctan.org/tex-archive/macros/latex/contrib/pdfpages)
+package (by Andreas Matthias) for _LaTeX_. The `pdfjam` script takes one
+or more PDF files (and/or JPG/PNG graphics files) as input, and produces
+one or more PDF files as output. It is useful for joining files together,
selecting pages, reducing several source pages onto one output page, etc., etc.
-A potential drawback of `pdfjam` and other scripts based upon it is that any
-hyperlinks in the source PDF are lost.
+A potential drawback of `pdfjam` and other scripts based upon it is that any
+hyperlinks in the source PDF are lost.
-`pdfjam` is designed for Unix-like systems, including Linux and Mac OS X.
-It seems that it will work also on Windows computers with a suitable
-installation of [Cygwin](https://www.cygwin.com) (with TeX Live
+`pdfjam` is designed for Unix-like systems, including Linux and Mac OS X.
+It seems that it will work also on Windows computers with a suitable
+installation of [Cygwin](https://www.cygwin.com) (with TeX Live
installed), but this has not been thoroughly tested.
Alternatives to `pdfjam` which are widely packaged in GNU/Linux distributions and other free software collections include:
@@ -49,27 +51,27 @@ Alternatives to `pdfjam` which are widely packaged in GNU/Linux distributions an
Those alternatives do many of the same things as `pdfjam`, and maybe
quite a bit more too.
-The **pdfjam** software is made available free, under GPL version 2 (see the
-file named `COPYING` that is included with the package).
+The **pdfjam** software is made available free, under GPL version 2 (see the
+file named `COPYING` that is included with the package).
It comes with **ABSOLUTELY NO WARRANTY** of fitness for any purpose whatever.
## <a name="wrappers"> Wrapper scripts no longer included here
Previous versions of **pdfjam** (before 3.02) included some _other_ scripts too,
in addition to the `pdfjam` script iteslf.
-Those other scripts are simple wrappers for calls to `pdfjam`, designed to perform
-some common tasks such as joining or n-upping PDF files or to illustrate
-other features; they are not very elaborate, and nor are they extensively tested.
-They are probably best viewed as simple templates that can be used for
-constructing more elaborate wrapper scripts as required.
-
-Those 'wrapper' scripts are **no longer maintained**. I continue to make
-them available in a separate repository
-<https://github.com/rrthomas/pdfjam-extras>,
-in case anyone wants to see them, to use them, or to improve and maintain
+Those other scripts are simple wrappers for calls to `pdfjam`, designed to perform
+some common tasks such as joining or n-upping PDF files or to illustrate
+other features; they are not very elaborate, and nor are they extensively tested.
+They are probably best viewed as simple templates that can be used for
+constructing more elaborate wrapper scripts as required.
+
+Those 'wrapper' scripts are **no longer maintained**. I continue to make
+them available in a separate repository
+<https://github.com/pdfjam/pdfjam-extras>,
+in case anyone wants to see them, to use them, or to improve and maintain
them independently as a separate project.
-The specific wrapper scripts that were removed from the **pdfjam** package
+The specific wrapper scripts that were removed from the **pdfjam** package
at version 3.02 are:
- `pdfnup`, `pdfpun`
@@ -80,26 +82,26 @@ at version 3.02 are:
- `pdfjam-pocketmod`
- `pdfjam-slides3up`, `pdfjam-slides6up`
-For those scripts and for more information on them, please now see
-<https://github.com/rrthomas/pdfjam-extras>.
+For those scripts and for more information on them, please now see
+<https://github.com/pdfjam/pdfjam-extras>.
# <a name="prereq"> Pre-requisites
- A Unix-like operating system (Linux, Mac OS X, FreeBSD, etc.; possibly Cygwin)
-- A working, up-to-date installation of LaTeX (including at least one of
+- A working, up-to-date installation of LaTeX (including at least one of
`pdflatex`, `lualatex` or `xelatex`)
-- A working installation of the LaTeX package
+- A working installation of the LaTeX package
[**pdfpages**](https://www.ctan.org/tex-archive/macros/latex/contrib/pdfpages)
(version 0.4f or later)
and
[**geometry**](https://www.ctan.org/tex-archive/macros/latex/contrib/geometry).
-With [libpaper](https://github.com/rrthomas/libpaper) version 2 or later installed, `pdfjam` will be able to find your default paper size, which you can configure if desired.
+With [libpaper](https://github.com/rrthomas/libpaper) installed, `pdfjam` will be able to find your default paper size, which you can configure if desired.
-For some years now, **pdfjam** has been included in the _TeX Live_ distribution,
+For some years now, **pdfjam** has been included in the _TeX Live_ distribution,
which includes all the necessary programs and packages to make `pdfjam` run smoothly.
-If you have the necessary bandwidth and disk space for it, I do recommend installing
+If you have the necessary bandwidth and disk space for it, I do recommend installing
[_TeX Live_](https://tug.org/texlive/).
# <a name="documentation"></a> Documentation
@@ -111,16 +113,16 @@ via the command
pdfjam --help
```
-This gives information on the arguments to `pdfjam`, and the default settings
-that apply at your installation. In addition to the arguments that are explicitly
-documented there, `pdfjam` provides access to all of the options of the
-**pdfpages** package: that's a large number of options, and it's a set of options
-that might change, so users are referred to the current
+This gives information on the arguments to `pdfjam`, and the default settings
+that apply at your installation. In addition to the arguments that are explicitly
+documented there, `pdfjam` provides access to all of the options of the
+**pdfpages** package: that's a large number of options, and it's a set of options
+that might change, so users are referred to the current
[pdfpages manual (PDF)](https://www.ctan.org/tex-archive/macros/latex/contrib/pdfpages/pdfpages.pdf) to see what's available.
In case you want to look at the `pdfjam --help` text template online, for example
before you decide whether to install **pdfjam**, the source is available at
-<https://github.com/rrthomas/pdfjam/blob/master/pdfjam-help.txt>.
+<https://github.com/pdfjam/pdfjam/blob/master/pdfjam-help.txt>.
There is also a (very basic) `man` page, accessed in the usual way
(after installation) by
@@ -133,79 +135,79 @@ man pdfjam
There are two main ways:
-1. Install the [current _TeX Live_ distribution](https://tug.org/texlive/)
+1. Install the [current _TeX Live_ distribution](https://tug.org/texlive/)
(how you do this will depend on details of your operating system).
-_TeX Live_ will already contain a recent release of **pdfjam**.
+_TeX Live_ will already contain a recent release of **pdfjam**.
Many thanks to Karl Berry
-for setting up and maintaining **pdfjam** as a _CTAN_ package that is part of
+for setting up and maintaining **pdfjam** as a _CTAN_ package that is part of
_TeX Live_.
2. Install it yourself (e.g., if you don't want _TeX Live_, or if you want a later
-release of **pdfjam** than the one that's currently in _TeX Live_).
+release of **pdfjam** than the one that's currently in _TeX Live_).
Download the latest packaged release of **pdfjam** from
-<https://github.com/rrthomas/pdfjam/releases>.
+<https://github.com/pdfjam/pdfjam/releases>.
If for some reason you don't want the latest released version, or even a recently released version, you can still get older versions too: see <https://davidfirth.github.io/pdfjam>.
**The first way, via _TeX Live_, is recommended** as the easiest way for most users.
If you go the second way, then you will have a bit more to do:
-- The `pdfjam` shell script in the _bin_ sub-directory of the released package
+- The `pdfjam` shell script in the _bin_ sub-directory of the released package
should be placed on the `PATH` of anyone who needs to use it.
-- The `man` file in the _man1_ sub-directory should be installed on the `MANPATH`
+- The `man` file in the _man1_ sub-directory should be installed on the `MANPATH`
of all who might need to read it.
# <a name="config"></a> Configuration
-On many unix-like systems `pdfjam` should run without any further configuration,
-provided that the pre-requisite TeX installation (such as _TeX Live_) is present.
-If you want to check (e.g., prior to installation) that `pdfjam` will work on
-your system, then
+On many unix-like systems `pdfjam` should run without any further configuration,
+provided that the pre-requisite TeX installation (such as _TeX Live_) is present.
+If you want to check (e.g., prior to installation) that `pdfjam` will work on
+your system, then
- unzip the `tests.zip` archive (inside the package)
- `cd` to your newly made `tests` sub-directory and follow the instructions that appear there in `README_tests.md`.
-If configuration _is_ needed, this can be done through a site-wide or
-user-specific configuration file. This might be necessary if, for example, your
-site has a non-standard TeX installation, or a non-standard location for
-temporary files, or a specific paper size for output PDFs ---
+If configuration _is_ needed, this can be done through a site-wide or
+user-specific configuration file. This might be necessary if, for example, your
+site has a non-standard TeX installation, or a non-standard location for
+temporary files, or a specific paper size for output PDFs ---
or some other reason.
-The file
-[pdfjam.conf](https://github.com/rrthomas/pdfjam/raw/master/pdfjam.conf)
-is a sample configuration file which can be edited as needed. After editing,
-either install the file for site-wide use (at `/etc/pdfjam.conf`,
-`/usr/share/etc/pdfjam.conf`, `/usr/local/share/pdfjam.conf`, or
-`/usr/local/etc/pdfjam.conf`) or as a user-defaults file at `~/.pdfjam.conf`.
-User settings made at `~/.pdfjam.conf` override corresponding settings made
+The file
+[pdfjam.conf](https://github.com/pdfjam/pdfjam/raw/master/pdfjam.conf)
+is a sample configuration file which can be edited as needed. After editing,
+either install the file for site-wide use (at `/etc/pdfjam.conf`,
+`/usr/share/etc/pdfjam.conf`, `/usr/local/share/pdfjam.conf`, or
+`/usr/local/etc/pdfjam.conf`) or as a user-defaults file at `~/.pdfjam.conf`.
+User settings made at `~/.pdfjam.conf` override corresponding settings made
in a site-wide configuration file.
-For example, if you prefer to use `/usr/bin/xelatex` as your default LaTeX engine
+For example, if you prefer to use `/usr/bin/xelatex` as your default LaTeX engine
(in place of the standard `pdflatex`), and you want your output page size to be
-"US letter" size paper by default, you would simply include the lines
+"US letter" size paper by default, you would simply include the lines
```
latex=/usr/bin/xelatex
paper=letterpaper
```
-in a plain text file named '`.pdfjam.conf`' in your home directory.
+in a plain text file named '`.pdfjam.conf`' in your home directory.
The path `usr/bin/xelatex` specifies exactly _which_ LaTeX program will be
-used: it could be a path to any one of the `pdflatex`, `lualatex` or
-`xelatex` executables. (You can get the full path to an executable
+used: it could be a path to any one of the `pdflatex`, `lualatex` or
+`xelatex` executables. (You can get the full path to an executable
by, for example, the command `which xelatex`.)
The code word `letterpaper` is how LaTeX refers to that particular page size.
-For other available paper sizes, and all the many
+For other available paper sizes, and all the many
other options that could be set as defaults if you want, please see the output of
```
pdfjam --help
```
-On some systems it might even be necessary to change the list of places
-(i.e., `/etc/pdfjam.conf` and others as listed above) that is searched for
-site-wide configuration files. This can only be done by editing the
-`pdfjam` script itself. To see which directories on _your_ system are
+On some systems it might even be necessary to change the list of places
+(i.e., `/etc/pdfjam.conf` and others as listed above) that is searched for
+site-wide configuration files. This can only be done by editing the
+`pdfjam` script itself. To see which directories on _your_ system are
searched for a file named `pdfjam.conf`, look at the output of
```
@@ -214,23 +216,23 @@ pdfjam --configpath
# <a name="using"></a> Using pdfjam
-For a full overview of what `pdfjam` can do, the importance of the
-[pdfpages manual (PDF)](https://www.ctan.org/tex-archive/macros/latex/contrib/pdfpages/pdfpages.pdf)
-cannot be stressed enough!
+For a full overview of what `pdfjam` can do, the importance of the
+[pdfpages manual (PDF)](https://www.ctan.org/tex-archive/macros/latex/contrib/pdfpages/pdfpages.pdf)
+cannot be stressed enough!
The following examples merely serve as a brief introduction.
### Example 1: Batch 2-upping of documents
-Consider converting each of two documents to a side-by-side "2-up" format.
-Since we want the two documents to be processed separately, we'll use the
+Consider converting each of two documents to a side-by-side "2-up" format.
+Since we want the two documents to be processed separately, we'll use the
`--batch` option:
```
pdfjam --batch --nup 2x1 --suffix 2up --landscape file1.pdf file2.pdf
```
-This will produce new files `file1-2up.pdf` and `file2-2up.pdf` in the current
-working directory.
+This will produce new files `file1-2up.pdf` and `file2-2up.pdf` in the current
+working directory.
### Example 2: Merging pages from 2 documents
@@ -240,35 +242,35 @@ Suppose we want a single new document which puts together selected pages from tw
pdfjam file1.pdf '{},2-' file2.pdf '10,3-6' --outfile ../myNewFile.pdf
```
-The new file `myNewFile.pdf`, in the parent directory of the current one,
-contains an empty page, followed by all pages of `file1.pdf` except the first,
+The new file `myNewFile.pdf`, in the parent directory of the current one,
+contains an empty page, followed by all pages of `file1.pdf` except the first,
followed by pages 10, 3, 4, 5 and 6 from `file2.pdf`.
-The resulting PDF page size will be whatever is the default paper size for
-you at your site. If instead you want to preserve the page size of
+The resulting PDF page size will be whatever is the default paper size for
+you at your site. If instead you want to preserve the page size of
(the first included page from) `file1.pdf`, use the option `--fitpaper true`.
-**All pages in an output file from `pdfjam` will have the same size and
-orientation.** For joining together PDF files while preserving _different_ page
+**All pages in an output file from `pdfjam` will have the same size and
+orientation.** For joining together PDF files while preserving _different_ page
sizes and orientations, `pdfjam` is not the tool to use.
### Example 3: A 4-up document with frames
-To make a portrait-oriented 4-up file from the pages of three input files,
+To make a portrait-oriented 4-up file from the pages of three input files,
with a thin-line frame around the input pages:
```
pdfjam file1.pdf file2.pdf file3.pdf --no-landscape --frame true --nup 2x2 --suffix 4up --outfile ~/Documents
```
-Here a _directory_ was specified at `--outfile`: the resultant file in this
-case will be `~/Documents/file3-4up.pdf`.
-(Note that **if there's a writeable file with that name already, it will be
+Here a _directory_ was specified at `--outfile`: the resultant file in this
+case will be `~/Documents/file3-4up.pdf`.
+(Note that **if there's a writeable file with that name already, it will be
overwritten**: no check is made, and no warning given.)
### Example 4: Convert a 'US letter' document to A4
-Suppose we have a document made up of 'US letter' size pages,
+Suppose we have a document made up of 'US letter' size pages,
and we want to convert it to A4:
```
@@ -277,45 +279,45 @@ pdfjam 'my US letter file.pdf' --a4paper --outfile 'my A4 file.pdf'
### Example 5: Handouts from presentation slides
-A useful application of `pdfjam` is for producing a handout from a file of
-presentation slides. For slides made with the standard 4:3 aspect ratio a
+A useful application of `pdfjam` is for producing a handout from a file of
+presentation slides. For slides made with the standard 4:3 aspect ratio a
nice 6-up handout on A4 paper can be made by
```
pdfjam --nup 2x3 --frame true --noautoscale false --delta "0.2cm 0.3cm" --scale 0.95 myslides.pdf --outfile myhandout.pdf
```
-The `--delta` option here comes from the pdfpages package; the `--scale`
-option is passed to LaTeX's `\includegraphics` command.
+The `--delta` option here comes from the pdfpages package; the `--scale`
+option is passed to LaTeX's `\includegraphics` command.
-Slides made by LaTeX's _beamer_ package, using the `handout` class option,
+Slides made by LaTeX's _beamer_ package, using the `handout` class option,
work especially nicely with this! The example wrapper scripts `pdfjam-slides3up`
-and `pdfjam-slides6up`, in the
-[pdfjam-extras](https://github.com/rrthomas/pdfjam-extras) repository,
+and `pdfjam-slides6up`, in the
+[pdfjam-extras](https://github.com/pdfjam/pdfjam-extras) repository,
are for 3-up and 6-up handouts, respectively.
### Example 6: Trimming pages; and piped output
-Suppose we want to trim the pages of our input file prior to n-upping.
-This can be done by using a pipe:
+Suppose we want to trim the pages of our input file prior to n-upping.
+This can be done by using a pipe:
```
pdfjam myfile.pdf --trim '1cm 2cm 1cm 2cm' --clip true --outfile /dev/stdout | pdfjam --nup 2x1 --frame true --outfile myoutput.pdf
```
-The `--trim` option specifies an amount to trim from the left, bottom, right and
-top sides respectively; to work as intended here it needs also `--clip true`.
-These (i.e., `trim` and `clip`) are in fact options to LaTeX's
+The `--trim` option specifies an amount to trim from the left, bottom, right and
+top sides respectively; to work as intended here it needs also `--clip true`.
+These (i.e., `trim` and `clip`) are in fact options to LaTeX's
`\includegraphics` command (in the standard _graphics_ package).
-Thanks go to Christophe Lange and Christian Lohmaier for suggesting
+Thanks go to Christophe Lange and Christian Lohmaier for suggesting
an example on this.
### Example 7: Output pages suitable for binding
-To offset the content of double-sided printed pages so that they are
-suitable for binding with a
-[Heftstreifen](https://de.wikipedia.org/wiki/Heftstreifen), use
+To offset the content of double-sided printed pages so that they are
+suitable for binding with a
+[Heftstreifen](https://de.wikipedia.org/wiki/Heftstreifen), use
the `--twoside` option:
```
@@ -324,32 +326,32 @@ pdfjam --twoside myfile.pdf --offset '1cm 0cm' --suffix 'offset'
### Example 8: Input file with nonstandard name
-To use PDF input files whose names do not end in '`.pdf`', you will need to use
-the `--checkfiles` option. This depends on the availability of the `file`
+To use PDF input files whose names do not end in '`.pdf`', you will need to use
+the `--checkfiles` option. This depends on the availability of the `file`
utility, with support for the options `-Lb`; this can be checked by trying
```
file -Lb 'my PDF file'
```
-where `'my PDF file'` is the name of a PDF file on your system.
-The result should be something like '`PDF document, version 1.4`'
+where `'my PDF file'` is the name of a PDF file on your system.
+The result should be something like '`PDF document, version 1.4`'
(possibly with a different version number).
-With '`file -Lb`' available, we can use PDF files whose names lack the usual
-'`.pdf`' extension. For example,
+With '`file -Lb`' available, we can use PDF files whose names lack the usual
+'`.pdf`' extension. For example,
```
pdfjam --nup 2x1 --checkfiles 'my PDF file'
```
-will result in a file named '`my PDF file-2x1.pdf`'
+will result in a file named '`my PDF file-2x1.pdf`'
in the current working directory.
### Example 9: Rotate every 2nd page
-If you want to print a landscape-oriented PDF document on both sides of the paper,
-using a duplex printer that does not have 'tumble' capability, make a new version
+If you want to print a landscape-oriented PDF document on both sides of the paper,
+using a duplex printer that does not have 'tumble' capability, make a new version
with every second page rotated for printing:
```
@@ -362,46 +364,49 @@ pdfjam --landscape --doublepagestwistodd true my-landscape-document.pdf
**1. The script runs but the output doesn't look the way it should. Why?**
-Most likely either your pdfTeX or your pdfpages installation is an old version.
-You could check also that `pdftex.def`, typically to be found in
-`.../texmf/tex/latex/graphics/`,
-is up to date. If the problem persists even with up-to-date versions of pdfTeX,
-`pdftex.def` and pdfpages, then please do report it.
+Most likely either your pdfTeX or your pdfpages installation is an old version.
+You could check also that `pdftex.def`, typically to be found in
+`.../texmf/tex/latex/graphics/`,
+is up to date. If the problem persists even with up-to-date versions of pdfTeX,
+`pdftex.def` and pdfpages, then please do report it.
**2. What can I do to solve a 'Too many open files' error?**
-This error has been reported to occur sometimes, when dealing with large numbers of
-documents/pages. A suggested solution, if this happens,
+This error has been reported to occur sometimes, when dealing with large numbers of
+documents/pages. A suggested solution, if this happens,
is to include additionally (in the call to `pdfjam`):
```
- -- preamble '\let\mypdfximage\pdfximage \def\pdfximage{\immediate\mypdfximage}'
+--preamble '\let\mypdfximage\pdfximage \def\pdfximage{\immediate\mypdfximage}'
```
-See for example
+See for example
<https://stackoverflow.com/questions/1715677/error-too-many-open-files-in-pdflatex>
for this suggestion and links to more information.
# <a name="bugs"></a> Reporting bugs
-Please report any bugs found in `pdfjam`, either
+Please report any bugs found in `pdfjam` by reporting as an issue at GitHub:
+<https://github.com/pdfjam/pdfjam/issues>
+
+# Developing
-- by reporting as an issue at GitHub, <https://github.com/rrthomas/pdfjam/issues>
-- by email (see <https://warwick.ac.uk/dfirth> for my email address)
+This project uses [l3build](https://ctan.org/pkg/l3build). See the header of
+`build.lua` for more information.
### Some known problems:
-- Sometimes font information (such as ligatures) is lost from the output of
+- Sometimes font information (such as ligatures) is lost from the output of
`pdfjam`. It seems that a fairly simple fix when this happens is to add the
option `--preamble '\pdfinclusioncopyfonts=1'` in your call to `pdfjam`.
-- In _Cygwin_, using `pdfjam` in a pipeline does not seem to work.
- The problem seems to be with _Cygwin_'s handling of file descriptors
+- In _Cygwin_, using `pdfjam` in a pipeline does not seem to work.
+ The problem seems to be with _Cygwin_'s handling of file descriptors
within pipelines.
-- The `--preamble` option can sometimes clash with other elements of the LaTeX
+- The `--preamble` option can sometimes clash with other elements of the LaTeX
preamble. Some specific things to watch out for:
+ If the preamble needs to set further options to the _geometry_ package, be sure to use the `\geometry{}` command for that.
- + If options to the _color_ package are to be specified in the preamble,
- do not at the same time use the `--pagecolor` option to `pdfjam`.
+ + If options to the _color_ package are to be specified in the preamble,
+ do not at the same time use the `--pagecolor` option to `pdfjam`.
# <a name="history"> Version history
@@ -409,11 +414,11 @@ Please report any bugs found in `pdfjam`, either
### Overview of the history
This all grew originally from a script named `pdfnup`. That was later joined,
-in a published package called 'PDFjam', by two further scripts `pdfjoin` and
+in a published package called 'PDFjam', by two further scripts `pdfjoin` and
`pdf90`.
At version 2.00, everything was unified through a single script `pdfjam`, with
-many more options. Along with `pdfjam` various 'wrapper' scripts --- i.e.,
+many more options. Along with `pdfjam` various 'wrapper' scripts --- i.e.,
other scripts that use `pdfjam` in different ways --- were provided, mainly as
examples.
@@ -421,10 +426,10 @@ From version 3.02, the extra 'wrapper' scripts are removed from the package,
mainly because they are hard to maintain: different users want different
things, and `pdfjam` itself provides all the options in any case. So I have
broken out the wrapper scripts into a separate repository, _unsupported_ ---
-so that people can still see and use/adapt them if they want.
-And maybe even someone else will
+so that people can still see and use/adapt them if they want.
+And maybe even someone else will
want to take on the task of improving and maintaining some of them,
-who knows? The wrapper scripts (**no longer maintained**) can now be found at
-<https://github.com/rrthomas/pdfjam-extras>.
+who knows? The wrapper scripts (**no longer maintained**) can now be found at
+<https://github.com/pdfjam/pdfjam-extras>.
_Releases up to version 2.08 are still available at <https://davidfirth.github.io/pdfjam>._
diff --git a/Master/texmf-dist/doc/support/pdfjam/VERSION b/Master/texmf-dist/doc/support/pdfjam/VERSION
deleted file mode 100644
index cd7061f818c..00000000000
--- a/Master/texmf-dist/doc/support/pdfjam/VERSION
+++ /dev/null
@@ -1 +0,0 @@
-This is pdfjam 3.12
diff --git a/Master/texmf-dist/doc/support/pdfjam/VERSION-4.00 b/Master/texmf-dist/doc/support/pdfjam/VERSION-4.00
new file mode 100644
index 00000000000..806a3a3aba7
--- /dev/null
+++ b/Master/texmf-dist/doc/support/pdfjam/VERSION-4.00
@@ -0,0 +1 @@
+This is pdfjam 4.00
diff --git a/Master/texmf-dist/doc/support/pdfjam/pdfjam.conf b/Master/texmf-dist/doc/support/pdfjam/pdfjam.conf
index c1a14a1266e..e3468192d34 100644
--- a/Master/texmf-dist/doc/support/pdfjam/pdfjam.conf
+++ b/Master/texmf-dist/doc/support/pdfjam/pdfjam.conf
@@ -1,20 +1,20 @@
###############################################################
##
-## This is a _sample_ 'pdfjam.conf' file.
+## This is a _sample_ 'pdfjam.conf' file.
##
-## Edit lines below (and un-comment them as necessary) to
-## override settings made in the 'pdfjam' script itself.
+## Edit lines below (and un-comment them as necessary) to
+## override settings made in the 'pdfjam' script itself.
## (As distributed, the settings made in this file are the
## same as those made in the 'pdfjam' script.)
##
-## A file in this format can be used site-wide (as a file named
-## "pdfjam.conf", in an appropriate location), or for a specific
-## user (as "~/.pdfjam.conf"). User-specific settings override
-## site-wide settings.
+## A file in this format can be used site-wide (as a file named
+## "pdfjam.conf", in an appropriate location), or for a specific
+## user (as "~/.pdfjam.conf"). User-specific settings override
+## site-wide settings.
##
-## See 'pdfjam --help' for details, including where to put
+## See 'pdfjam --help' for details, including where to put
## your edited version of this file; or see the file README.md at
-## https://github.com/rrthomas/pdfjam
+## https://github.com/pdfjam/pdfjam
##
###############################################################
##
@@ -66,7 +66,7 @@ keepinfo='false' ## overridden by '--keepinfo' in the call
##
## Should the '--checkfiles' option be used by default?
checkfiles='false' ## overridden by '--checkfiles' in the call;
-# checkfiles='true' ## the alternative
+# checkfiles='true' ## the alternative
##
###############################################################
##
@@ -78,7 +78,7 @@ checkfiles='false' ## overridden by '--checkfiles' in the call;
##
###############################################################
##
-## DEFAULT PATH FOR THE --outfile OPTION
+## DEFAULT PATH FOR THE --outfile OPTION
##
outFile="$pwd" ## the obvious default
# outFile="$HOME/Documents" ## (another possibility, perhaps)
diff --git a/Master/texmf-dist/doc/support/pdfjam/tests.zip b/Master/texmf-dist/doc/support/pdfjam/tests.zip
deleted file mode 100644
index 0ff939f4b52..00000000000
--- a/Master/texmf-dist/doc/support/pdfjam/tests.zip
+++ /dev/null
Binary files differ
diff --git a/Master/texmf-dist/doc/support/pdflatexpicscale/README b/Master/texmf-dist/doc/support/pdflatexpicscale/README
index 56b00b6b36c..f95ecc2dd0b 100644
--- a/Master/texmf-dist/doc/support/pdflatexpicscale/README
+++ b/Master/texmf-dist/doc/support/pdflatexpicscale/README
@@ -3,11 +3,11 @@ to a target resolution before creating a PDF document
with PdfLaTeX.
*Version*
-2018-02-12 (version of bundle)
+2024-10-18 (version of bundle)
For version details check pdflatexpicscale.pdf.
*Requirements*
-Perl and ImageMagick have to be installed.
+Perl and some Perl modules have to be installed - see pdflatexpicscale.pdf.
*Basic usage*
pdflatex article
diff --git a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf
index 8e42d2a18ff..729034176fb 100644
--- a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf
+++ b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex
index e3b740a51a9..a54bf283ec7 100644
--- a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex
+++ b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex
@@ -5,7 +5,7 @@
\usepackage{url}
\title{pdflatexpicscale}
\author{Peter Willadt\footnote{willadt at t-online.de}}
-\date{2018-02-12} %version #version
+\date{2024-10-18} %version #version
\begin{document}
\maketitle
@@ -54,39 +54,50 @@ scale graphics according to the output intent.
\subsection{Prerequisites}
-You have to install ImageMagick and Perl. If you are using Linux, please use
-the tools of your distribution, if they are not already installed. As a
-windows user, you may probably use the official ImageMagick distribution at
-\url{http://www.imagemagick.org/script/download.php}. For Perl, you got more
-options. I have tested pdflatexpicscale with ActiveState ActivePerl, but other
-distributions should work too.
-You also need the following Perl modules: \texttt{File::Basename},
-\texttt{File::Spec}, \texttt{File::Copy}, and \texttt{Getopt::Long}. There are
-several ways to get these modules, if you have not got them already:
+You \label{section:requisites} have to install Perl version~5, if it is not
+installed already. If you are using Linux, I recommend to use the tools of
+your distribution. As a windows user, you may probably use Strawberry Perl.
+You also need the following Perl modules:
+\begin{itemize}
+\item \texttt{GD} (at least version 2.2),
+\item \texttt{Image::ExifTool},
+\item \texttt{File::Basename},
+\item \texttt{File::Spec},
+\texttt{File::Copy}, and
+\item \texttt{Getopt::Long}.
+\end{itemize}
+
+There are no further requirements for the versions of the software to install,
+but it may be wise to use recent releases.
+There are several ways to get these modules, if you have not got them
+already. The most popular are probably:
\begin{itemize}
\item use your Linux distribution's software manager
\item use the Perl CPAN module
-\item use ActiveState's \texttt{ppm} software, if you use ActivePerl.
+\item use ActiveState's \texttt{ppm} software, if you happen to use
+ ActivePerl.
\end{itemize}
-Detailled description of these procedures is beyond the scope of this
-document.
+Detailed description of these procedures is beyond the scope of this
+document.
-There are no special requirements for the versions of the software to install,
-but it may be wise to use recent versions, as there have been security flaws
-with ImageMagick.
+As of 2024, no further external software is needed, in contrast to earlier
+versions.
\subsection{Installation}
-If the prerequisites have been fulfilled (which is perhaps standard for a
-Linux computer), it is sufficient to move the file
-\texttt{pdflatexpicscale.pl} to a place that is included in your PATH and to
-make it executable. Of course, there are alternatives. You may perhaps
-prefer to type\\
+If pdflatexpicscale.pl is part of your \TeX\ distribution,
+chances are good that you only have to install missing Perl modules, if
+any. Otherwise the following should apply:
+
+Having installed Perl and the required modules, it is sufficient to move
+the file \texttt{pdflatexpicscale.pl} to a place that is included in your PATH
+and to make it executable. Of course, there are alternatives. You may perhaps
+prefer to type the following instead:
+
\texttt{perl /path/to/pdflatexpicscale.pl myarticle}\\
-instead.
\section{Basic usage}
@@ -127,7 +138,8 @@ Some other text...
You hopefully do not have distinct pictures with the same name in the listed
folders. With \verb|\graphicspath| you have to use double braces, even if you
-use only one directory.
+use only one directory. The best place for the \verb|\graphicspath| statement
+is probably near the beginning of your \LaTeX\ file.
\subsection{Preparing your \LaTeX\ file, Part~2}
@@ -172,7 +184,7 @@ again on \texttt{myarticle}. I have told you to use double braces with
\verb|\graphicspath|, haven't I? If you still are curious, you can again
check the size of \texttt{myarticle.pdf}.
-When it gets to preparing a print version, you create a directory for images
+When it is time to prepare a print version, you create a directory for images
with more detail, say \texttt{printpix}. You reset the \verb|\graphicspath|,
run Pdf\LaTeX, issue\\
\texttt{pdflatexpicscale --printdpi=300 --destdir=printpix myarticle}\\
@@ -180,11 +192,10 @@ and set \verb|\graphicspath{{printpix/}}| before the next Pdf\LaTeX\ run.
\section{Advanced usage}
-
\subsection{Excluding files from scaling}
You will probably exclude files from scaling when you think that scaling will
-do damage. You may achieve this by several means. Before you ask. Enumerating
+harm. You may achieve this by several means. Before you ask: Enumerating
files to exclude is not really cool, so this is not supported.
\begin{enumerate}
@@ -208,6 +219,19 @@ directories. Before the first \LaTeX\ run, you say\\
and after pdflatexpicscale is through, you change it to\\
\verb|\graphicspath{{hires/}{printimg/}}|
+\subsection{Monochrome Images}
+
+While \label{section:monochrome}Pdf\TeX\ supports JBIG2 files,
+pdflatexpicscale does not. Scaling JBIG2 files down looks like a bad idea,
+anyway.
+
+Scaling monochrome\footnote{\emph{Monochrome} in the technical sense of one
+ bit per pixel as opposed to grayscale or color images that use only one
+ color.} images may lead to bad results. I recommend converting them to
+grayscale before scaling, as blurred details are perhaps better than missing
+details. pdflatexpicsacle will scale B/W images only if their resolution is at
+least two times higher as requested.
+
\subsection{Gory details}
pdflatexpicscale reads the log file, not the \LaTeX\ source. So you have to
@@ -256,12 +280,16 @@ pictures remain unscaled because they are near the target resolution. Default
is 20, that means 20~percent. If target resolution is 300~dpi, files up to
320~dpi get accepted too. Change to 0 if you want no tolerance.
+\paragraph{draft/final} Setting one of these options will use reasonable
+defaults, if you do not want to use any of the further options.
+Please call \texttt{pdflatexpicscale.pl --help} to see concrete values.
+
\paragraph{verbose} entertains you by showing what the program is about to
do.
\paragraph{version} shows the software version.
-Calling pdflatexpicscale without any options and without a project name will
+Calling pdflatexpicscale.pl without any options and without a project name will
display a short usage text.
\subsection{Printer testing}
@@ -335,5 +363,23 @@ this document, the option \texttt{tolerance} had been listed as
As the TUGboat article corresponding to pdflatexpicscale is freely available
now, the link on page~\pageref{tugboatart} has been adjusted.
+\paragraph{2024-10-18}
+
+Added section~{section:monochrome} with hints for B/W images to
+documentation. Also did some minor edits, especially to accompany the
+following changes (see section~\ref{section:requisites}).
+
+As there have been issues with ImagMagick, pdflatexpicscale no longer uses
+external software; Perl's GD and Image::ExifTool modules are used instead.
+
+Added new shortcut options \texttt{--draft} and \texttt{--final}.
+
+Refactored pdflatexpicscale.pl, hopefully without bad side effects.
+
% for file version please see line 8
\end{document}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% End:
diff --git a/Master/texmf-dist/doc/support/pdflatexpicscale/testprinter.ps b/Master/texmf-dist/doc/support/pdflatexpicscale/testprinter.ps
index 900fe5dc8e9..71856a45e4a 100644
--- a/Master/texmf-dist/doc/support/pdflatexpicscale/testprinter.ps
+++ b/Master/texmf-dist/doc/support/pdflatexpicscale/testprinter.ps
@@ -4,7 +4,7 @@
% PostScript by Example.
% First printing, 1992, P. 544 ff
% Willadt 2016-07-27
-% version 2018-02-12 #version %version
+% version 2024-10-18 #version %version
% for information on usage and changes see pdflatexpicscale.pdf
/prozente 20 string def
diff --git a/Master/texmf-dist/doc/support/ppmcheckpdf/README.txt b/Master/texmf-dist/doc/support/ppmcheckpdf/README.txt
index daf87bd3d07..5cd108d1bba 100644
--- a/Master/texmf-dist/doc/support/ppmcheckpdf/README.txt
+++ b/Master/texmf-dist/doc/support/ppmcheckpdf/README.txt
@@ -1,4 +1,4 @@
-Package: Convert PDF to PNG and compare PNG files after l3build
+Package: Image-based regression testing for LaTeX packages
Author: Jianrui Lyu <tolvjr@163.com>
Repository: https://github.com/lvjr/ppmcheckpdf
License: The LaTeX Project Public License 1.3c
diff --git a/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.pdf b/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.pdf
index 6a893fa85b6..41f4cf1ed3d 100644
--- a/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.pdf
+++ b/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.tex b/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.tex
index 8b32a8259e1..05044f0ca48 100644
--- a/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.tex
+++ b/Master/texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.tex
@@ -2,7 +2,7 @@
\documentclass[oneside,12pt]{article}
\usepackage[a4paper,margin=2cm]{geometry}
-\newcommand*{\myversion}{2024B}
+\newcommand*{\myversion}{2024C}
\newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
@@ -10,6 +10,8 @@
\setlength{\parskip}{4pt plus 1pt minus 1pt}
\usepackage{codehigh}
+\usepackage{tabularray}
+\UseTblrLibrary{booktabs}
\usepackage{hyperref}
\hypersetup{
colorlinks=true,
@@ -27,7 +29,7 @@
\title{\sffamily
\textcolor{green3}{The \texttt{ppmcheckpdf} tool}\\
- {\large Convert PDF to PNG and compare PNG files after \texttt{l3build}}%
+ {\large Image-based regression testing for LaTeX packages}%
}
\author{%
Jianrui Lyu (tolvjr@163.com)%
@@ -48,10 +50,28 @@ to PNG files and compare PNG files after \mypkg{l3build} finishes its job.
\section{Installation}
-Normally your TeX distribution will copy \myfile{ppmcheckpdf.lua} file to the correct folder
-when you install this tool. If a manual installation is needed, you could download
-\href{https://ctan.org/pkg/ppmcheckpdf}{\myfile{ppmcheckpdf.lua}}
-from CTAN and install it to \myfile{TEXMF/scripts/ppmcheckpdf/ppmcheckpdf.lua}.
+Normally your TeX distribution will copy \mypkg{ppmcheckpdf} files and
+create a binary file \myfile{ppmcheckpdf} when you install this package.
+
+If a manual installation is needed, you could copy \mypkg{ppmcheckpdf} files to TEXMF tree as follows:
+
+\noindent\begin{tblr}{X[font=\ttfamily]X[2,font=\ttfamily]}
+\toprule
+ Package file & Where to install it \\
+\midrule
+ ppmcheckpdf.1 & TEXMF/doc/man/man1/ppmcheckpdf.1 \\
+ README.txt & TEXMF/doc/support/ppmcheckpdf/README.txt \\
+ ppmcheckpdf.lua & TEXMF/scripts/ppmcheckpdf/ppmcheckpdf.lua \\
+\bottomrule
+\end{tblr}
+
+Then create a symbolic link from \myfile{/usr/local/bin/ppmcheckpdf} to \myfile{path/to/ppmcheckpdf.lua} on Linux or MacOS,
+or create a batch file \myfile{ppmcheckpdf.bat} in binary folder of the TeX distribution with these lines on Windows:
+
+\begin{codehigh}
+@echo off
+texlua path\to\ppmcheckpdf.lua %*
+\end{codehigh}
The \mypkg{ppmcheckpdf} tool uses \myprg{pdftoppm} program for image converting.
This program is installed by default on MiKTeX. For TeX Live, you can install it by running
@@ -66,28 +86,24 @@ on Ubuntu/Debian Linux.
\section{Usages}
-First create a \myfile{buildend.lua} file with the following lines in the folder of your package
-(next to \myfile{build.lua} file for \mypkg{l3build}):
-\begin{codehigh}
-kpse.set_program_name("kpsewhich")
-dofile(kpse.lookup("ppmcheckpdf.lua"))
-\end{codehigh}
-Then you could run the folllowing commands
+You could call \myopt{check} action of \mypkg{ppmcheckpdf} with the folllowing commands
\begin{codehigh}
l3build check
-texlua buildend.lua
+ppmcheckpdf check
\end{codehigh}
The first run of \mypkg{ppmcheckpdf} will save image and md5 files to \myfile{testfiles} folder,
and the subsequent runs of it will compare new md5 values with existing md5 values.
-You could force \mypkg{ppmcheckpdf} to save new image and md5 files to \myfile{testfiles} folder
-by passing \myopt{save} option to it:
+You could force \mypkg{ppmcheckpdf} to save new image and md5 files of failed tests to
+\myfile{testfiles} folder by calling \myopt{save} option of it:
\begin{codehigh}
l3build check
-texlua buildend.lua save
+ppmcheckpdf save
\end{codehigh}
+Both \myopt{check} and \myopt{save} actions accept \myopt{-c} option, which sets the config to used.
+
\section{Customizations}
The \myprg{pdftoppm} program supports several types of image files.
diff --git a/Master/texmf-dist/doc/support/sqltex/SQLTeX.pdf b/Master/texmf-dist/doc/support/sqltex/SQLTeX.pdf
new file mode 100644
index 00000000000..050e48021df
--- /dev/null
+++ b/Master/texmf-dist/doc/support/sqltex/SQLTeX.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/sqltex/SQLTeX.tex b/Master/texmf-dist/doc/support/sqltex/SQLTeX.tex
new file mode 100644
index 00000000000..d3fbc8d6673
--- /dev/null
+++ b/Master/texmf-dist/doc/support/sqltex/SQLTeX.tex
@@ -0,0 +1,1050 @@
+\documentclass{article}
+\newcommand{\bs}{\ensuremath{\backslash}}
+\newcommand{\vs}{\vspace{3mm}}
+\newcommand{\sqltexversion}{3.0}
+\newcommand{\sqltexvmsversion}{3\_0}
+\usepackage{makeidx}
+\usepackage[pdftex
+ ,pagebackref=true
+ ,colorlinks=true
+ ,linkcolor=blue
+ ,unicode]{hyperref}
+\begin{document}
+\title{SQL\TeX\ v\sqltexversion}
+\date{Sep 20, 2024}
+\author{Oscar van Eijk}
+\maketitle
+\hrulefill
+\tableofcontents
+\hrulefill
+
+\section{Introduction}
+
+SQL\TeX\ is a preprocessor to enable the use of SQL statements in \LaTeX. It is a perl script that reads
+an input file containing the SQL commands, and writes a \LaTeX\ file that can be processed with your
+\LaTeX\ package.
+
+The SQL commands will be replaced by their values. It's possible to select a single field for substitution
+substitution in your \LaTeX\ document, or to be used as input in another SQL command.
+
+When an SQL command returns multiple fields and or rows, the values can only be used for substitution
+in the document.
+
+\subsection{Known limitations}
+
+\begin{itemize}
+\item The \LaTeX\ \texttt{\bs includeonly} directive is ignored; all documents included with \texttt{\bs include} will be parsed and written to the output file.
+\item Currently, only 9 command- line parameters (1-9), and 10 variables (0-9) can be used in SQL statements.
+\item Replace files can hold only 1,000 items.
+\end{itemize}
+
+\section{Installing SQL\TeX}
+
+Since v3.0, SQL\TeX\ is part of \TeX\ Live and doesn't need further installation. \\
+If you are using a different LaTeX distro, please follow the steps below for your OS.
+
+Before installing SQL\TeX, you need to have it. The latest version can always be found at
+\url{https://github.com/oveas/sqltex}.
+The download consists of this do\-cumentation, an installation script for Unix
+(\texttt{install}), and the Perl script \texttt{sqltex}, and a replace- file (\texttt{SQLTeX\_r.dat}) for manual installation
+on non- unix platforms\footnote{on Unix, this file will be generated by the install script}.
+
+\subsection{Requirements}
+
+SQL\TeX\ requires the following software:
+
+\begin{itemize}
+\item Perl v5.10 or higher (\url{http://perl.org/})
+\item Perl-DBI (\url{http://dbi.perl.org/})
+\item The DBI driver for your database\\(see: \url{http://search.cpan.org/search?query=DBD\%3A\%3A\&mode=module})
+\item Getopt::Long (\url{https://metacpan.org/pod/Getopt::Long})
+\item Term::ReadKey (\url{https://metacpan.org/pod/Term::ReadKey})
+\end{itemize}
+
+\subsection{Installation}
+
+If you are using a \TeX\ Live distribution, SQL\TeX\ is already available. For all other distros, follow the steps in this section.
+
+\vs
+
+First unpack the archive in a location of your choice and continue with one if the subsections below depending on you operating system.
+
+\subsubsection{Linux}
+
+Go to the top directory where the archive was unpacked (`\texttt{cd sqltex-\sqltexversion}') and execute the following commands:
+
+\vs
+
+\noindent\texttt{\$ ./configure \textit{[options]}\\
+\$ make \\
+\$ \textit{[sudo] }make install}
+
+\vs
+
+In the last command, \texttt{sudo} is only required if the install destination (\texttt{PREFIX}, see below) is outside the own user environment.
+
+\vs
+
+For \texttt{configure}, the following options are user buy SQL\TeX\ (type \texttt{./configure --help} for a full list):
+
+\begin{description}
+\item[\texttt{--prefix=PREFIX}] install architecture-independent files in PREFIX. Default is \texttt{/usr/local}.
+\item[\texttt{--exec-prefix=EPREFIX}] install architecture-dependent files in EPREFIX. Default is \texttt{PREFIX}.
+\end{description}
+
+The directives above are used by the ones below:
+
+\begin{description}
+\item[\texttt{--bindir=DIR}] Location of the SQL\TeX\ script. Default is \texttt{EPREFIX/bin}
+\item[\texttt{--sysconfdir=DIR}] Location of the Configuration- and replacefiles. Default is \texttt{PREFIX/etc}
+\item[\texttt{--datarootdir=DIR}] Data root, used by the directives below. Default is \texttt{PREFIX/share}
+\item[\texttt{--mandir=DIR}] Location of the SQL\TeX\ manpage. Default is \texttt{DATAROOTDIR/man}
+\item[\texttt{--docdir=DIR}] Documentation root, used by \texttt{pdfdir} below. Default is \texttt{DATAROOTDIR/doc/sqltex}
+\item[\texttt{--pdfdir=DIR}] Location of SQL\TeX.pdf. Default is \texttt{DOCDIR}
+\end{description}
+
+\vs
+
+After installation, the archive and unpack- directory can be removed.
+
+\subsubsection{Windows}
+
+\noindent\hspace{-3mm}\textit{\underline{Note:}}Since v3.0, the binary \texttt{SQLTEX.EXE} for Windows is not included in the distribution anymore\footnote{ It can be generated with any (portable) perl version for Windows, like Strawberry Perl (\url{https://strawberryperl.com/}\label{winexe}), with \texttt{PAR::Packer} (\url{https://metacpan.org/pod/PAR::Packer}) using the command:\\
+\texttt{pp -o sqltex.exe sqltex}}
+
+\vs
+
+The files \texttt{sqltex-\sqltexversion\ensuremath{\backslash}sqltex}, \texttt{sqltex-\sqltexversion\ensuremath{\backslash}src\ensuremath{\backslash}SQLTeX.cfg} and \\ \texttt{sqltex-\sqltexversion\ensuremath{\backslash}src\ensuremath{\backslash}SQLTeX\_r.dat} must be placed manually in the directory of your choice, all in the same direcrtory.
+
+
+\subsubsection{OpenVMS}
+
+On \textsc{OpenVMS} the files must be copied manually to the destination. All files must reside in the same location:\\
+\texttt{\$ COPY [.SQLTEX-\sqltexvmsversion.SRC]SQLTEX. SYS\$SYSTEM:SQLTEX.PL\\
+\$ COPY [.SQLTEX-\sqltexvmsversion.SRC]SQLTEX.CFG SYS\$SYSTEM:\\
+\$ COPY [.SQLTEX-\sqltexvmsversion.SRC]SQLTEX\_R.DAT SYS\$SYSTEM:\\
+\$ SET FILE/PROTECTION=(W:RE) SYS\$SYSTEM:SQLTEX.PL}
+
+\vs
+
+Next, define the command \texttt{SQLTEX} by setting a symbol,
+either in the \texttt{LOGIN.COM} for all users who need to execute this script, or in some group-- or
+system wide login procedure, with the command: \\
+\texttt{\$ SQLTEX :== "PERL SYS\$SYSTEM:SQLTEX.PL"}
+
+\subsection{Configuration}\label{config}
+
+The configuration file \texttt{SQLTeX.cfg} is located in \texttt{/usr/local/etc} (linux) or the same location where SQL\TeX\ is installed (all other operating systems and in \TeX\ Live distros)\footnote{ If a 1.x version of SQL\TeX\ is installed on your system, make sure you save the configuration section, which was inline in older versions}.
+Multiple configuration files can be created, the command line option \texttt{--configfile} can be used to
+select the requested configuration.
+
+\vs
+
+\noindent\hspace{-3mm}\textit{\underline{Note:}}\label{cfg:disable} Use of the \texttt{--configfile} commandfile option can be disabled on system wide installations. To do so, the script \texttt{sqltex} must be modified.\\
+At the top of the file (line 4), set the value for \texttt{\$main::ext\_cfgfile\_allowed} to \texttt{0}.
+
+\vs
+
+Some values can be overwritten using command line options (see section~\ref{cmdline}). When the command line options are omitted, the values from the requested configuration file will be used.
+
+\begin{description}
+
+\item[dbdriver] Database driver. The default is \texttt{mysql}.
+Other supported databases are \texttt{Pg}, \texttt{Sybase}, \texttt{Oracle}\footnote{ This requires the configuration setting \texttt{oracle\_sid}}, \texttt{Ingres}, \texttt{mSQL}, \texttt{PostgreSQL} and \texttt{ODBC}\footnote{ The actual driver can specified with the configuration setting \texttt{odbc\_driver}}, but also others might work without modification. \\
+
+\vs
+
+If your database driver is not support, look for the function
+\texttt{db\_connect} to add support (and please notify me :)
+
+\item[oracle\_sid] Oracle Site Identifier, required when the \texttt{Oracle} database driver is selected.
+
+\item[odbc\_driver] Specification of the ODBC driver. Default is ``\texttt{SQL Server}''
+
+
+\item[texex] The default file extension for \LaTeX\ file. When SQL\TeX\ is called, the first
+parameter should be the name of the input file. If this filename has no extension,
+SQL\TeX\ looks for one with the default extension.
+
+\item[stx] An output file can be given explicitly using the `\texttt{--output}' option. When omitted,
+SQL\TeX\ composes an output file name using this string.\\
+E.g, if your input file is called \texttt{db-doc.tex}, SQL\TeX\ will produce an
+outputfile with the name \texttt{db-docstx.tex}.
+
+\item[def\_out\_is\_in] By default, when no output file is specified or an output file without (relative) path is given, the output file will be generated in the current directory.\\
+This behaviour changed in version 2.1. In older version, the location of the output file always was the same as the input file location. To revert to the old behaviour, set \texttt{def\_out\_is\_in} to `\texttt{1}'\footnote{ Note the pre-v2.1 implementation also contained a bug: if the output file name contained an absolute or relative path, this path was always taken as relative from the input file location. In the new implementation, \texttt{def\_out\_is\_in} is ignored if the output file name contains a path.}.
+
+\item[multi\_rfile]If the commandline option \texttt{--replacementfile} is given, by default the given replacement file will be parsed and after that the default replacement file will be parsed as well.\\
+If only the given replacement file should be parsed skipping the default file, set this value to \texttt{0}.
+
+\item[rfile\_comment] The comment-sign used in replace files. If this is empty, comments are not allowed in
+the replace files.
+
+\item[rfile\_regexploc] This must be part of the value \texttt{rfile\_regexp} below.
+
+\item[rfile\_regexp] Explains how a regular expression is identified in the replace files (see section~\ref{regexp}).
+
+\item[cmd\_prefix]\label{prefix} SQL\TeX\ looks for SQL commands in the input file. Commands are specified in the
+same way all \LaTeX\ commands are specified: a backslash (\bs) followed by the
+name of the command.\\
+All SQL\TeX\ commands start with the same string. By default, this is the string
+\texttt{\textbf{sql}}. When user commands are defined that start with the same
+string, this can be changed here to prevent conflicts.
+
+\item[sql\_open] This string is appended to the \texttt{cmd\_prefix} to
+get the complete SQL\TeX\ command for opening a database.\\
+With the default configuration this command is ``\texttt{\bs sqldb}''.
+
+\item[sql\_field] This string is appended to the \texttt{cmd\_prefix} to
+get the complete SQL\TeX\ command to read a single field from the database.\\
+With the default configuration this command is ``\texttt{\bs sqlfield}''.
+
+\item[sql\_row] This string is appended to the \texttt{cmd\_prefix} to
+get the complete SQL\TeX\ command to read one or more rows from the database.\\
+With the default configuration this command is ``\texttt{\bs sqlrow}''.
+
+\item[sql\_params] This string is appended to the \texttt{cmd\_prefix} to get the complete SQL\TeX\ command to retrieve a list if fields that will be used as parameters (\texttt{\$PAR1}, see section~\ref{params}) in the multidocument environment (see section~\ref{multidoc}).\\
+With the default configuration this command is ``\texttt{\bs sqlparams}''.
+
+\item[sql\_update] This string is appended to the \texttt{cmd\_prefix}
+to get the complete SQL\TeX\ command to update one or more rows in the database.\\
+With the default configuration this command is ``\texttt{\bs sqlupdate}''.
+
+\item[sql\_start] This string is appended to the \texttt{cmd\_prefix} to get the complete SQL\TeX\ command start a section that will be repeated for every row from an array (see section~\ref{loops}).\\
+With the default configuration this command is ``\texttt{\bs sqlstart}''.
+
+\item[sql\_use] This string is appended to the \texttt{cmd\_prefix} to get the complete SQL\TeX\ command use a named variable from the array that is currently being processed in a loop context (see section~\ref{loops}).\\
+With the default configuration this command is ``\texttt{\bs sqluse}''.
+
+\item[sql\_end] This string is appended to the \texttt{cmd\_prefix} to get the complete SQL\TeX\ command to end a loop context (see section~\ref{loops}).\\
+With the default configuration this command is ``\texttt{\bs sqlend}''.
+
+\item[sqlsystem\_allowed] Set this to ``1'' to allow the use of the \texttt{\bs sqlsystem} command (see section~\ref{sqlsystem}).
+
+\item[repl\_step] Replacing strings (see section~\ref{replfiles} below) is done two steps, to prevent values from being replaced twice.
+This setting---followed by a three-digit integer - ``000'' to ``999''---is used in the first step and replaces values from the first column.
+In the second step, values from the second column replace the temporary value. \\
+If the first column in the replace file contains a character sequence that occurs in this temporary value, or if query results might contain the full string followed by three digits, this value might need to be changed in something unique.
+
+\item[alt\_cmd\_prefix] In loop context, this setting is used internally to differentiate between sql statements to process immediately and sql statements on stack.\\
+Normally, this setting should never change, but if the value for \texttt{cmd\_prefix} has been changed and a conflict is found, the message ``\texttt{Configuration item 'alt\_cmd\_prefix' cannot start with \textit{<conflicting value>}}'' indicates this setting should change as well.
+
+\end{description}
+
+\subsection{Create replace files}\label{replfiles}
+
+Replace files can be used to substitute values in the output of your SQL commands with a different value. This is especially useful when the database
+contains characters that are special characters in \LaTeX, like the percent sign (`\%'), underscore (`\_') etc.
+
+When SQL\TeX\ is installed, it comes with a standard file---\texttt{SQLTeX\_r.dat}---which is located in \texttt{/usr/local/etc}\footnote{ if a replace file with that name already exists, it will be stored there as \texttt{SQLTeX\_r.dat.new}} (linux) or the same location where SQL\TeX\ is installed (all other operating systems and in \TeX\ Live distros).
+
+\vspace{3mm}
+
+\noindent Example:
+\begin{verbatim}
+$ \$
+_ \_
+% \%
+& \&
+< \texttt{<}
+> \texttt{>}
+{ \{
+} \}
+# \#
+~ \~{}
+\ \ensuremath{\backslash}
+\end{verbatim}
+
+\vspace{3mm}
+
+These are all single character replacements, but you can add your own replacements that consist of a single character or a character sequence (or even regular expressions, see section~\ref{regexp}).
+
+\vs
+
+To do so, enter a new line with the character(string) that should be replaced, followed by one or more \texttt{TAB}-character(s) (\textit{not} blanks!) and the character(string) it should be replaced with.\\
+That last one can be empty if the input character(string) should be ignored, but the \texttt{TAB} after the input character(string) is mandatory!
+
+\vs
+
+If the first non-blank character is a semicolon (`;'), the line is considered a comment line\footnote{ in the default configuration. See the description for \texttt{rfile\_comment} in section~\ref{config} to change of disable comment lines.}. Blank lines are ignored.
+
+\vspace{3mm}
+
+The contents of the file are case sensitive, so of you add the line: \\
+\verb+LaTeX \LaTeX\+ \\
+the word ``LaTeX'' will be changed, but ``latex'' is untouched.
+
+\vspace{3mm}
+
+Different replace files can be created. To select a different replace file for a certain SQL\TeX\ source, use the commandline option
+`\texttt{--replacementfile \textit{filename}}'. To disable the use of replace files, use `\texttt{no-replacementfile}'.
+
+\subsubsection{Regular expressions}\label{regexp}
+
+The replace file can include regular expressions, which are recognized by a pattern given in the configuration setting \texttt{rfile\_regexp}. A part of the pattern, configurable as \texttt{rfile\_regexploc}, will be the actual regular expression.
+
+\vs
+
+By default, \texttt{rfile\_regexploc} is ``\texttt{...}'' and \texttt{rfile\_regexp} is ``\texttt{re(...)}''. If the sequence of three dots can appear anywhere else in the replace file, \texttt{rfile\_regexploc} can be changed to any other sequence of characters, e.g. ``\texttt{regexpHere}''.\\
+This also requires \texttt{rfile\_regexp} to be changed. Its new value has to be ``\texttt{re(regexpHere)}''
+
+\vs
+
+Both in the default configuration and with the modification example given above, the key for regular expressions is \texttt{re(<\textit{regular expression}>)}, e.g.:\\
+\hspace{3mm}\verb+re(<p.*?>) \paragraph*{}+ \\
+will replace all HTML \texttt{<}p\texttt{>} variants (\texttt{<}p style='font-size: normal'\texttt{>}, \texttt{<}p align='center'\texttt{>} etc)
+
+\vs
+
+An example replacement file using regular expressions to handle HTML codes could look like this:
+
+\noindent\begin{verbatim}
+&amp; \&
+<strong> \textbf{
+</strong> }
+<em> \textit{
+</em> }
+re(<br.*?/?>) \\
+re(<p.*?>) \paragraph*{}
+</p> \\[0pt]
+<sup> $^{
+</sup> }$
+re(<span.*?>) \textsl{
+</span> }
+re(<h1.*?>) \section{
+re(<h2.*?>) \subsection{
+re(<h3.*?>) \subsubsection{
+re(</h\d>) }
+\end{verbatim}
+
+\section{Write your SQL\TeX\ file}
+
+For SQL\TeX, you write your \LaTeX\ document just as you're used to. SQL\TeX\ provides you with
+some extra commands that you can include in your file.\\
+The basic format\footnote{in this document, in all examples will be assumed the default values in the
+configuration section as described in section~\ref{config}, have not been changed} of an SQL\TeX\ command is: \\
+\texttt{\bs sql\emph{cmd}[options]\{SQL statement\}}
+
+\vs
+
+All SQL\TeX\ commands can be specified anywhere in a line, and can span multiple lines.
+When SQL\TeX\ executes, the commands are read, executed, and their results---if they return
+any---are written to the output:
+
+\vs
+
+\begin{minipage}[t]{0.5\textwidth}\textsl{Input file:}\\\texttt{\footnotesize{\bs documentclass[article] \\
+\bs pagestyle\{empty\} \\
+\bs sqldb[oscar]\{mydb\} \\
+\bs begin\{document\} \\
+}}\end{minipage}\hfill\begin{minipage}[t]{0.5\textwidth}\textsl{Output file:}\\\texttt{\footnotesize{\bs documentclass[article] \\
+\bs pagestyle\{empty\} \\
+ \\
+\bs begin\{document\} \\
+}}\end{minipage}
+
+\vs
+
+Above you see the SQL\TeX\ command \texttt{\bs sqldb} was removed. Only the command was removed, not
+the \textsl{newline} character at the end of the line, so an empty line will be printed instead.
+The example below shows the output if an SQL\TeX\ command was found on a line with other \LaTeX\
+directives:
+
+\vs
+
+\begin{minipage}[t]{0.5\textwidth}\textsl{Input file:}\\\texttt{\footnotesize{\bs documentclass[article] \\
+\bs pagestyle\{empty\}\bs sqldb[oscar]\{mydb\} \\
+\bs begin\{document\} \\
+\hrulefill}}\end{minipage}\hfill\begin{minipage}[t]{0.5\textwidth}\textsl{Output file:}\\\texttt{\footnotesize{\bs documentclass[article] \\
+\bs pagestyle\{empty\} \\
+\bs begin\{document\} \\
+}}\end{minipage}
+
+\vs
+
+In these examples the SQL\TeX\ commands did not return a value. When commands actually read from
+the database, the returned value is written instead:
+
+\vs
+
+\begin{minipage}[t]{0.5\textwidth}\textsl{Input file:}\\\texttt{\footnotesize{This invoice has \bs sqlfield\{SELECT COUNT(*) FROM INVOICE\_LINE \\
+WHERE INVOICE\_NR = 20190062\} lines.\\
+\hrulefill}}\end{minipage}\hfill\begin{minipage}[t]{0.5\textwidth}\textsl{Output file:}\\\texttt{\footnotesize{This invoice has 3 lines \\
+}}\end{minipage}
+
+\subsection{SQL statements}\label{sqlstatements}
+
+This document assumes the reader is familiar with SQL commands. This section only tells something about
+implementing them in SQL\TeX\ files, especially with the use of command parameters and variables.
+Details about the SQL\TeX\ commands will be described in the next sections.
+
+\vs
+
+Let's look at a simple example. Suppose we want to retrieve all header information from the database
+for a specific invoice. The SQL statement could look something like this: \\
+\texttt{SELECT $\ast$ FROM INVOICE WHERE NR = 20190062;}\\
+To implement this statement in an SQL\TeX\ file, the \texttt{\bs sqlrow} command should be used (see
+section~\ref{sqlrow}):
+
+First, it is important to know that SQL statements should \textit{not} contain the ending semicolon (;) in
+any of the SQL\TeX\ commands. The command in SQL\TeX\ would be:\\
+\texttt{\bs sqlrow\{SELECT $\ast$ FROM INVOICE WHERE NR = 20190062\}}
+
+Next, SQL\TeX\ would be useless if you have to change your input file every time you want to generate
+the same document for another invoice.
+
+\vs
+
+Therefore, you parameters or variables can be used in your SQL statement. Parameters are given at the command
+line (see section~\ref{params}), variables can be defined using the \texttt{\bs sqlfield} command as
+described in section~\ref{vars}.
+
+Given the example above, the invoice number can be passed as a parameter by rewriting the command as: \\
+\texttt{\bs sqlrow\{SELECT $\ast$ FROM INVOICE WHERE NR = \$PAR1\}} \\
+or as a variable with the code line: \\
+\texttt{\bs sqlrow\{SELECT $\ast$ FROM INVOICE WHERE NR = \$VAR0\}}
+
+Note you have to know what datatype is expected by your database. In the example here the datatype is
+\textsc{integer}. If the field ``\textsc{invoice\_nr}'' contains a \textsc{varchar} type, the
+\texttt{\$PAR}ameter or \texttt{\$VAR}iable should be enclosed by quotes: \\
+\texttt{\bs sqlrow\{SELECT $\ast$ FROM INVOICE WHERE NR = '\$PAR1'\}}
+
+\subsection{Opening the database}\label{opendb}
+
+Before any information can be read from a database, this database should be opened.
+This is done with the \texttt{\textbf{\bs sqldb}} command.
+\texttt{\bs sqldb} requires the name of the dabatase. Optionally, a username, password and remote database host can be given. \\
+The format of the command is:\\
+\texttt{\bs sqldb[user=\textit{username},passwd=\textit{password},host=\textit{host}]\{database\}}
+
+The command can be used anywhere in your input file, but should occur before the first command that tries to
+read data from the database.
+
+\vs
+
+If the keywords \texttt{user}, \texttt{passwd} and \texttt{host} are omitted, SQL\TeX\ assumes the options are given in
+this order:\\
+\texttt{\bs sqldb[\textit{username},\textit{password},\textit{host}]\{database\}}
+
+Default host is localhost, the default user is the current user.
+
+\vs
+
+\noindent\hspace{-3mm}\textit{\underline{Note:}} The \texttt{\bs sqldb} command cannot span multiple lines!
+
+\subsubsection{Prompt for password and/or username}
+
+If a password is omitted, SQL\TeX\ will try connect to the database without a password, unless the commandline option \texttt{--password} is given (see section \ref{cmdline}).
+
+\vs
+
+Forcing a user to enter a database password when SQL\TeX\ runs can be achieved by specifying \texttt{?} as password:\\
+\texttt{\bs sqldb[user=dbUser,passwd=?]\{database\}}
+
+\vs
+
+When different database users should be able to use the same SQL\TeX\ file, the username can also be a question mark, forcing SQL\TeX
+to prompt for a username:\\
+\texttt{\bs sqldb[user=?,passwd=?]\{database\}}
+
+\subsection{Reading a single field}\label{sqlfield}
+
+When a single field of information is to be read from the database, the command \texttt{\textbf{\bs sqlfield}}
+is used. By default, the command in the input file is replaced by its result in the output file.\\
+The SQL command is enclosed by curly braces. Square brackets can optionally be used to enter some extra options.
+Currently, the only supported option is \texttt{setvar} (see section~\ref{vars}).
+
+The full syntax or the \texttt{\bs sqlfield} command is:\\
+\texttt{\bs sqlfield[\textit{options}]\{SELECT \textit{fieldname} FROM \textit{tablename} WHERE \textit{your where-clause}\}} \\
+By default, the SQL\TeX\ command is replaced with the value returned by the SQL query. This behaviour
+can be changed with options.
+
+
+\subsubsection{Define variables}\label{vars}
+
+The \texttt{\bs sqlfield} can also be used to set a variable. The value returned by the SQL query is not
+displayed in this case. Instead, a variable is created which can be used in any other SQL query later in
+the document (see also section~\ref{sqlstatements}).
+
+Therefore, the option \texttt{\textbf{[setvar=\textit{n}]}} is used, where \textit{n} is an integer between
+0 and 9.
+
+\vs
+
+Suppose you have an invoice in \LaTeX. SQL\TeX\ is executed to retrieve the invoice header information
+from the database for a specific customer. Next, the invoice lines are read from the database.
+
+You could pass the invoice number as a parameter to SQL\TeX\ for use in your queries, but that could
+change every month. It is easier to :\\
+\begin{itemize}
+\item pass the customer number as a parameter,
+\item retrieve the current date (assuming that is the invoice date as stored in
+the database by another program), and store it in a variable: \\
+\texttt{\bs sqlfield[setvar=0]\{SELECT DATE\_FORMAT(NOW(), "\%Y-\%m-\%d")\}} \\
+This creates a variable that can be used as \texttt{\$VAR0},
+\item retrieve the invoice number using the customer number (a command line parameter,
+see also section~\ref{params}) and the variable containing the invoice date.
+Store this invoice number in \texttt{\$VAR1}: \\
+\texttt{\bs sqlfield[setvar=1]\{SELECT NR FROM INVOICES \\
+WHERE CUST\_NR = '\$PAR1' AND INVOICE\_DATE = '\$VAR0'\}}
+\item use \texttt{\$VAR1} to retrieve all invoice information.
+\end{itemize}
+
+\vs
+
+The SQL queries used here do not display any output in your \LaTeX\ document.
+
+
+\subsection{Reading rows of data}\label{sqlrow}
+
+When an SQL query returns more information than one single field, the SQL\TeX\
+command \texttt{\textbf{\bs sqlrow}} should be used. As with the \texttt{\bs sqlfield},
+command, SQL\TeX\ replaces the command with the values it returns, but \texttt{\bs sqlrow}
+accepts different options for formatting the output.
+
+\vs
+
+By default, fields are separated by a comma and a blank (`\texttt{,~}'), and rows by
+a newline character (`\texttt{\bs\bs}'). To change this, the options ``\texttt{fldsep}''
+and ``\texttt{rowsep}'' can be used.
+
+e.g. In a \texttt{tabular} environment the fields should be separated by an ampersand (\texttt{\&}),
+perhaps a line should separate the rows of information. (\texttt{\bs\bs~\bs hline}).
+To do this, the options can be used with \texttt{\bs sqlrow} as shown here: \\
+\texttt{\bs sqlrow[fldsep=\&,rowsep=\bs\bs~\bs hline]\{SELECT I.NR, A.NR,
+A.PRICE, I.AMOUNT, (A.PRICE * I.AMOUNT) FROM ARTICLE A, INVOICE\_LINE I WHERE I.NR = \$VAR1
+AND I.ARTICLE\_NR = A.NR\}}
+
+\vs
+
+This will produce an output like: \\
+\texttt{1 \& 9712 \& 12 \& 1 \& 12 \bs\bs~\bs hline
+2 \& 4768 \& 9.75 \& 3 \& 29.25 \bs\bs~\bs hline
+3 \& 4363 \& 1.95 \& 10 \& 19.5 \bs\bs~\bs hline
+4 \& 8375 \& 12.5 \& 2 \& 25 \bs\bs~\bs hline}
+
+\subsubsection{Output rows on separate lines}
+
+Some \LaTeX\ packages require input on a separate line. If this output is to be
+read from a database, this can be set with the \texttt{rowsep} option using the
+fixed text ``\texttt{NEWLINE}''.
+
+Changing the example from section \ref{sqlrow} above to:\\
+\texttt{\bs sqlrow[fldsep=\&,rowsep=\bs\bs~\bs hline NEWLINE]\{SELECT I.NR, A.NR,
+A.PRICE, I.AMOUNT, (A.PRICE * I.AMOUNT) FROM ARTICLE A, INVOICE\_LINE I WHERE I.NR = \$VAR1
+AND I.ARTICLE\_NR = A.NR\}}
+
+\vs
+
+would produce the following result: \\
+\texttt{1 \& 9712 \& 12 \& 1 \& 12 \bs\bs~\bs hline \\
+2 \& 4768 \& 9.75 \& 3 \& 29.25 \bs\bs~\bs hline \\
+3 \& 4363 \& 1.95 \& 10 \& 19.5 \bs\bs~\bs hline \\
+4 \& 8375 \& 12.5 \& 2 \& 25 \bs\bs~\bs hline}
+
+
+
+\subsubsection{Store data in an array}
+
+
+The \texttt{\bs sqlrow} command can also be used to store the data in an array. The value returned by the SQL query is not displayed in this case. Instead, an array is created which can be used later in the document in a loop context (see section~\ref{loops}).
+
+Therefore, the option \texttt{\textbf{[setarr=\textit{n}]}} is used, where \textit{n} is an integer between
+0 and 9.
+
+\subsection{Loop context}\label{loops}
+
+In a loop context, an array is filled with data from the database using \texttt{\bs sqlrow}.\\
+Later in the document, the data can be used in a text block that will be written to the output file once for every record retrieved.
+
+\vs
+
+The text block is between the \texttt{\bs sqlstart\{\textit{n}\}} and \texttt{\bs sqlend\{\textit{n}\}} commands, where \textit{n} is the sequence number of the array to use\footnote{ in \texttt{\bs sqlend}, the sequence number is ignored, but required by syntax.}.
+
+Multiple text blocks can occur in the document, but they can \textit{not} be nested!
+
+\vs
+
+In the example below, data for unpaid invoices is stored in an array identified with sequence number 0:
+
+\texttt{\bs sqlrow[setarr=0]\{SELECT I.NR AS nr\\
+\hspace*{15mm}, I.DUE\_DATE AS date\\
+\hspace*{15mm}, I.TOTAL AS amount\\
+\hspace*{15mm}, C.NAME AS customer\\
+\hspace*{15mm}FROM INVOICE I\\
+\hspace*{15mm}LEFT OUTER JOIN CUSTOMER C\\
+\hspace*{20mm}ON C.NR = I.CUST\_NR\\
+\hspace*{15mm}WHERE I.PAY\_DATE IS NULL\}}
+
+\vs
+
+To use this data, a text block must start with: \texttt{\bs sqlstart\{0\}}\\
+Between this command and the first occurrence of \texttt{\bs sqlend\{\}}, an unlimited amount\footnote{ limited by your computer's memory only} of \LaTeX\ text can be written. Within this text, every occurrence of \texttt{\bs sqluse\{<\textit{field name}>\}} will be replaced with the matching field from the current row, e.g.:
+
+\noindent\begin{verbatim}
+\sqlstart{0}
+\begin{flushright}
+Regarding: invoicenumber \sqluse{nr}
+\end{flushright}
+
+Dear \sqluse{customer},
+
+On \today, the invoice with number \sqluse{nr}, payable before
+\sqluse{date}, was not yet received by us.
+
+We kindly request you to pay the amount of \texteuro\sqluse{amount}
+as soon as possible.
+
+\newpage
+\sqlend{}
+\end{verbatim}
+
+\subsubsection{If-endif control block}
+
+In the loop context, parts of the document can be enabled if certain conditions are met, using a control block with \texttt{\bs sqlif\{\textit{condition(s)}\}} and \texttt{\bs sqlendif\{\}}.
+
+\vs
+
+\textit{Conditions} can be up to 2 conditions separated by an \textit{and} (\texttt{\&\&}) or \textit{or} (\texttt{||}).
+
+The condition(s) consist of an left value and an right value seperated by 1 of the following comparisson operators: `\texttt{==}', `\texttt{!=}', `\texttt{<}',. `\texttt{>}', `\texttt{<=}' or `\texttt{>=}'.\\
+Numeric values will be used as is. When the value is text, it is expected to be the name of a field and `\texttt{\bs sqluse\{\}}` will be called to retrieve the value.
+\vs
+
+\noindent Example:\\
+\texttt{\bs sqlif\{article\_nr == 123 \&\& \bs stock < 5\}\\
+Stock is below threshold, please reorder.
+}\\
+\bs sqlendif\{\}
+
+\vs
+
+Note the conditions are very basic with the following limitations:
+\begin{itemize}
+\item A maximum of 2 conditions is supported per if-statement.
+\item Only numeric comparissons are supported.
+\item If-elsif blocks cannot be nested.
+\end{itemize}
+
+When checks are needed that are not supported by SQL\TeX, a workaround can be implemented in the SQL code.
+
+
+\subsection{Get input from external programs}\label{sqlsystem}
+
+The \texttt{\bs sqlsystem} command can be used to call commands at the operating system or external scripts and use their output in the location where the command was given. Any command arguments can be given in the command line.
+
+When used in a loop context (see section~\ref{loops}), \texttt{\bs sqluse} can also be used to provide data to the script. If command arguments must be given for database access, the following tags can be used:
+
+\begin{itemize}
+\item[\texttt{<SRV>}] Name of the database server.
+\item[\texttt{<USR>}] Username to connect to the database.
+\item[\texttt{<PWD>}] Password to connect to the database.
+\item[\texttt{<DB>}] Name of the database.
+\end{itemize}
+
+They will be replaced by the credentials for connecting to the database (see section~\ref{opendb}).
+
+
+\vs
+
+\noindent Example:\\
+\texttt{\bs sqlsystem\{./add\_vat --usr <USR> --db <DB> --pwd <PWD> $\hookleftarrow$ \\
+--inv \bs sqluse\{invoice\_nr\}\}}
+
+\vs
+
+By default, use of this command is disallowed. To enable it, set the value of \texttt{sqlsystem\_allowed} to ``1'' in the configuration file (see also section~\ref{config}.
+
+If the command is disabled, occurances of this command will be replaced by the fixed text ``\texttt{use of the \bs sqlsystem command is disallowed in the configuration}''.
+
+\vs
+
+\noindent\hspace{-3mm}\textit{\underline{Note:}} The \texttt{\bs sqlsystem} command cannot span multiple lines!
+
+
+\subsection{Output multiple documents}\label{multidoc}
+
+A single input file can be created to generate more output files using the \texttt{--multidoc-numbered} or \texttt{--multidoc-named} commandline option.
+
+The input document must contain the command \texttt{\bs sqlsetparams} without any options. The query that follows can return an unlimited number of rows: \\
+\texttt{\bs sqlsetparams\{SELECT NR, CUST\_NR FROM INVOICES WHERE REMINDERS = \$PAR1\}}
+
+\vs
+
+By processing this command, SQL\TeX\ builds a list with all values retrieved and
+processes the input file again for each row.\\
+In those runs, the queries are executed as described in the previous sections,
+using the returned fields to replace \texttt{\$MPAR\textit{n}} placeholders, where \textit{n} starts with 1 and represents the fields in the order as they have been retrieved:\\
+\texttt{\bs sqlrow\{SELECT * FROM INVOICES WHERE NR = \$MPAR1\}} \\
+\texttt{\bs sqlrow\{SELECT * FROM CUSTOMER WHERE CUST\_NR = \$MPAR2\}}
+
+\vs
+
+The options \texttt{--multidoc-numbered} or \texttt{--multidoc-named} cannot be used together.\\
+Without these options, a parameter can be given and a single output
+document will be created, ignoring the \texttt{\bs sqlsetparams} command.
+
+\vs
+
+With the \texttt{--multidoc-numbered} option, output filenames will be numbered \texttt{\emph{filename}\_1.tex} to \texttt{\emph{filename}\_\emph{n}.tex}.\\
+With the \texttt{--multidoc-named} option, output filenames will be numbered \\\texttt{\emph{filename}\_\emph{parameter}.tex}, where \emph{parameter} is the first value taken from the database (\texttt{\$MPAR1}, the invoice number \texttt{nr} in the example above). \\
+Note the parameter will not be formatted to be filename-friendly!\\
+
+
+\subsection{Update database records}
+
+Since version 1.5, SQL\TeX\ supports database updates as well: \\
+\texttt{\bs sqlupdate\{UPDATE INVOICE SET REMINDERS = REMINDERS + 1,
+LAST\_REMINDER = NOW() WHERE NR = \$VAR1\}}
+
+This command accepts no options.
+
+\vs
+
+By default, the update statements will be ignored. To actually process them, the commandline options \texttt{--updates} must be given!
+
+\section{Process your SQL\TeX\ file}
+
+To process your SQL\TeX\ file and create a \LaTeX\ file with all information read from
+the database, call SQL\TeX\ with the parameter(s) and (optional) command\-line options as
+described here.
+
+\subsection{Parameters}\label{params}
+
+SQL\TeX\ accepts more than one parameter. The first parameter is required; this should
+be the input file, pointing to your \LaTeX\ document containing the SQL\TeX\ commands.
+
+By default, SQL\TeX\ looks for a file with extension `\texttt{.tex}'.
+
+\vs
+
+All other parameters are used by the queries, if required. If an SQL query contains the
+string \texttt{\$PAR\textit{n}}\footnote{where \textit{n} is a number between 1 and 9. Note
+parameter `0' cannot be used, since that contains the filename!}, it is replaced by that parameter
+(see also section~\ref{sqlstatements}).
+
+\subsection{Command line options}\label{cmdline}
+
+SQL\TeX\ accepts the following command- line options:
+
+\begin{description}
+\item[\texttt{--configfile \textit{file}, -c \textit{file}}] SQL\TeX\ configuration file. Default is \texttt{SQLTeX.cfg} in the systems default location (see section \ref{config}).
+
+\item[\texttt{--file-extension \textit{string}, -E \textit{string}}] replace input file extension in outputfile:
+\texttt{input.tex} will be \texttt{input.\textit{string}}. \\
+For further notes, see option \texttt{--filename-extend} below.
+
+\item[\texttt{--filename-extend \textit{string}, -e \textit{string}}] add \textit{string} to the output filename:
+\texttt{input.tex} will be \texttt{input\textit{string}.tex}. This overwrites
+the configuration setting \texttt{stx}. \\
+In \textit{string}, the values between curly braces \{\} will be substituted:
+\begin{description}
+\item[P\textit{n}] parameter \textit{n}
+\item[M] current monthname (\textit{Mon})
+\item[W] current weekday (\textit{Wdy})
+\item[D] current date (\textit{yyyymmdd})
+\item[DT] current date and time (\textit{yyyymmddhhmmss})
+\item[T] current time (\textit{hhmmss})
+\end{description}
+e.g., the command\\
+\hspace*{1em}\texttt{sqltex --filename-extend \_\{P1\}\_\{W\} my\_file code}\\
+will read `\texttt{my\_file.tex}' and write `\texttt{myfile\_code\_Tue.tex}'.\\
+The same command, but with option \texttt{---file-extension} would create the outputfile \texttt{my\_file.\_code\_Tue}\\
+The options \texttt{--file-extension} and \texttt{--filename-extend} cannot be used together or with \texttt{--output}.
+
+\item[\texttt{--force, -f}] force overwrite of existing files. By default, SQL\TeX\ exits with a
+warning message it the outputfile already exists.
+
+\item[\texttt{--help, -h}] print this help message and exit.
+
+\item[\texttt{--multidoc-numbered, -m}] Multidocument mode; create one document for each parameter that is retrieved
+from the database in the input document (see section~\ref{multidoc}). This option cannot be used with \texttt{--output}.
+
+\item[\texttt{--multidoc-named, -M}] Same as \texttt{--multidoc-numbered}, but with the parameter in the filename instead of a serial number (see section~\ref{multidoc}).
+
+\item[\texttt{--null-allowed, -N}] \texttt{NULL} return values allowed. By default SQL\TeX\ exits if a
+query returns an empty set.
+
+\item[\texttt{--output \textit{file}, -o \textit{file}}] specify an output file. Cannot be used with \texttt{--file-extension},
+\texttt{--filename-extend} or the \texttt{--multidoc} options.
+
+\item[\texttt{--skip-empty-lines, -S}] All SQL\TeX\ commands will be removed from the input line or replaced by the corresponding value. The rest of the input line is written to the output file.
+This includes lines that only contain a SQL\TeX\ command (and a newline character). This will result in an empty line in the output file.\\
+By specifying this option, these empty lines will be skipped. Lines that were empty in the input will be written.
+
+\item[\texttt{--write-comments, -C}] \LaTeX\ comments in the input file will be skipped by default. With this option, comments will also be copied to the output file.
+
+\item[\texttt{--prefix \textit{prefix}, -p \textit{prefix}}] prefix used in the SQL\TeX\ file. Default is \texttt{sql} (see also section~\ref{config}
+on page~\pageref{prefix}. This overwrites the configurarion setting \texttt{cmd\_prefix}.
+
+\item[\texttt{--password \textit{[password]}, -P} \textit{[password]}] database password. The value is optional; if omitted, SQL\TeX\ will prompt for a password. This overwrites the password in the input file.
+
+\item[\texttt{--quiet, -q}] run in quiet mode.
+
+\item[\texttt{--replacementfile \textit{replace}, -r \textit{replace}}] Specify a file that contains the replace characters (see section~\ref{replfiles}). \\
+Default is \texttt{SQLTeX{\_}r.dat} in the systems default location (see section \ref{replfiles}). This default file will always be used after the given replacement file, unless \texttt{multi\_rfile} is set to \texttt{0} in the configuration (see secion \ref{config}).
+
+\item[\texttt{--no-replacementfile, -R}] Do not use a replace file. \texttt{--no-replacementfile} and \texttt{--replacementfile \textit{file}} are handled in the same order as
+they appear on the command line, overwriting each other.\\
+For backwards compatibility, \texttt{-rn} is also still supported.
+
+\item[\texttt{--sqlserver \textit{server}, -s \textit{server}}] SQL server to connect to. Default is \texttt{localhost}.
+
+\item[\texttt{--updates, -u}] if the input file contains updates, process them.
+
+\item[\texttt{--username \textit{user}, -U \textit{user}}] database username. This overwrites the username in the input file.
+
+\item[\texttt{--version, -V}] print version number and exit.
+\end{description}
+
+
+
+\section{SQL\TeX\ errors and warnings}
+
+\noindent\textbf{\texttt{no input file specified}}
+
+\vspace{1mm}
+
+\noindent SQL\TeX\ was called without any parameters.\\
+\textit{Action:} Specify at least one parameter at the commandline. This parameter should be
+the name of your input file.
+
+\vs
+
+\noindent\textbf{\texttt{File \textit{input filename} does not exist}}
+
+\vspace{1mm}
+
+\noindent The input file does not exist.\\
+\textit{Action:} Make sure the first parameter points to the input file.
+
+\vs
+
+\noindent\textbf{\texttt{outputfile \textit{output filename} already exists}}
+
+\vspace{1mm}
+
+\noindent The outputfile cannot be created because it already exists.\\
+\textit{Action:} Specify another output filename with command line option \texttt{-e},
+\texttt{-E} or \texttt{-o}, or force an overwrite with option \texttt{-f} (see also section\ref{cmdline}).
+
+\vs
+
+\noindent\textbf{\texttt{no database opened at line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent A query starts at line \textit{line nr}, but at that point no database was opened yet. \\
+\textit{Action:} Add an \texttt{\bs sqldb} command prior to the first query statement.
+
+\vs
+
+\noindent\textbf{\texttt{insufficient parameters to substitute variable on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent The query starting at line \textit{line nr} uses a parameter in a \textsc{where}- clause with
+\texttt{\$PAR\textit{n}}, where \textit{n} is a number bigger than the number of parameters
+passed to SQL\TeX\. \\
+\textit{Action:} Specify all required parameters at the command line.
+
+\vs
+
+\noindent\textbf{\texttt{trying to substitute with non existing on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent The query starting at line \textit{line nr} requires a variable \texttt{\$VAR\textit{n}} in its
+\textsc{where}- clause, where \textit{n} points to a variable that has not (yet) been set. \\
+\textit{Action:} Change the number or set the variable prior to this statement.
+
+\vs
+
+\noindent\textbf{\texttt{trying to overwrite an existing variable on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent At line \textit{line nr}, a \texttt{\bs sqlfield} query tries to set a variable \textit{n}
+using the option \texttt{[setvar=\textit{n}]}, but \texttt{\$VAR\textit{n}} already
+exists at that point. \\
+\textit{Action:} Change the number.
+
+\vs
+
+\noindent\textbf{\texttt{no result set found on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent The query starting at line \textit{line nr} returned a \texttt{NULL} value. If the
+option \texttt{-N} was specified at the commandline, this is just a warning message.
+Otherwise, SQL\TeX\ exits. \\
+\textit{Action:} None.
+
+\vs
+
+\noindent\textbf{\texttt{result set too big on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent The query starting at line \textit{line nr}, called with \texttt{\bs sqlfield} returned more than one field. \\
+\textit{Action:} Change your query or use \texttt{\bs sqlrow} instead.
+
+\vs
+
+\noindent\textbf{\texttt{no parameters for multidocument found on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent SQL\TeX\ is executed in multidocument mode, but the statement on line
+\textit{line nr} did not provide any parameters for the documents. \\
+\textit{Action:} Check your query.
+
+\vs
+
+\noindent\textbf{\texttt{too many fields returned in multidocument mode on \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent In multidocument mode, the lis of parameters retrieved on line
+\textit{line nr} returned more than one fields per row. \\
+\textit{Action:} Check your query.
+
+\vs
+
+\noindent\textbf{\texttt{start using a non-existing array on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent An \texttt{\bs sqlstart} command occurs, but refers to a non-existing array. \\
+\textit{Action:} Check the sequence number of the array filled with \texttt{\bs sqlrow[setarr=\textit{n}]} and retrieved with \texttt{\bs sqlstart\{\textit{n}\}} in your input file.
+
+\vs
+
+\noindent\textbf{\texttt{\bs sqluse command encountered outside loop context on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent Data from array is used, but the current input file position is not in the context where this data is available.\\
+\textit{Action:} Check the presence and positions of the \texttt{\bs sqlstart} and \texttt{\bs sqlend} commands in your input file.
+
+\vs
+
+\noindent\textbf{\texttt{unrecognized command on line \textit{line nr}}}
+
+\vspace{1mm}
+
+\noindent At line \textit{line nr}, a command was found that starts with ``\texttt{\bs sql}'',
+but this command was not recognized by SQL\TeX\. \\
+\textit{Action:} Check for typos. If the command is a user- defined command, it will
+conflict with default SQL\TeX\ commands. Change the SQL\TeX\ command prefix (see section~\ref{config}).
+
+\vs
+
+\noindent\textbf{\texttt{no sql statements found in \textit{input filename}}}
+
+\vspace{1mm}
+
+\noindent SQL\TeX\ did not find any valid SQL\TeX\ commands. \\
+\textit{Action:} Check your input file.
+
+
+\section{Copyright and disclaimer}
+
+\noindent\hrulefill \\
+The SQL\TeX\ project is available from GitHub: \url{https://github.com/oveas/sqltex}\\
+For bugs, questions and comments, please use the issue tracker available at \url{https://github.com/oveas/sqltex/issues}
+
+\vspace{3mm}
+
+\noindent Copyright\copyright\ 2001-2024 - Oscar van Eijk, Oveas Functionality Provider
+
+\noindent\hrulefill \\
+
+\noindent This software is subject to the terms of the LaTeX Project Public License;
+see \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html}.
+
+\section{History}
+
+\begin{description}
+\item[v3.0] \textit{released: Sep 20, 2024}
+\begin{itemize}
+\item Made it possible to run SQL\TeX\ directly from the distribution without \texttt{configure} and \texttt{make [install]} to make integration in \TeX\ Live possible.
+\item Renamed the script to \texttt{sqltex}. For backwards compatibility, during installation on linux a symbolic link \texttt{SQLTeX} is created.
+\item The \texttt{SQLTeX.exe} binary is no longer included in the distribution (see footnote \footref{winexe} on page \pageref{winexe}).
+\item Removed support for the \texttt{--use-local-config} commandline option. The options \texttt{--configfile} and \texttt{--replacementfile} can be used instead.
+\item Added an option to disable the \texttt{--configfile} command line option (see note on page \pageref{cfg:disable}).
+\item Added the \texttt{--skip-empty-lines} and \texttt{--write-comments} commandline options.
+\item Added support for multiple replacement files.
+\item Fix: ordering in the replacement file.
+\end{itemize}
+
+\item[v2.2] \textit{released: Jul 31, 2024}
+\begin{itemize}
+\item Extended the default replace file (see \ref{replfiles}) with more special characters (e.g. with diacritics) and HTML tags.
+\item Issue \#6 (\url{https://github.com/oveas/sqltex/issues/6}): added support for ODBC drivers
+\item Issue \#8 (\url{https://github.com/oveas/sqltex/issues/8}): added support for parameter-driven in \texttt{\bs sqlsetparams} statements (multi-document mode).\\
+\textit{\textbf{Note:}} This requires an update of your input files for multi-document mode that have been created before v2.2. Refer to section \ref{mdocupdates} for details.
+\item Added the \texttt{\bs sqlsystem} command.
+\item Added the \texttt{\bs sqlif}-\texttt{\bs sqlendif} control block.
+\end{itemize}
+
+\item[v2.1] \textit{released: Jan 21, 2022}
+\begin{itemize}
+\item Fix bug \#2 (\url{https://github.com/oveas/sqltex/issues/2}): standard path management for output files.\\
+See config item \texttt{def\_out\_is\_in} in section \ref{config} to revert to pre v2.1 behaviour.
+\item Fix: help was not displayed on Windows
+\item Implemented '?' as password in \texttt{dbopen}
+\item Implemented '?' as username in \texttt{dbopen}
+\item Implemented long options
+\item Allow overwriting variables in multidocument mode
+\item Added simple automated regression tests
+\item Added a man page for linux users
+\item Rewrote the installation procedure, now using \texttt{autotools} on linux.
+\item On linux, change the default installation directory to \texttt{/usr/bin} and store the configuration- and replacement files is \texttt{/etc}.
+\item Added option \texttt{--use-local-config}.
+\end{itemize}
+
+\item[v2.0] \textit{released: Jan 12, 2016}
+\begin{itemize}
+\item Fix: Oracle support using ORASID
+\item Fix: Ensure replacements are handled in the same order as they appear in the replacements file
+\item Separate configuration file(s)
+\item Added the options \texttt{-c} and \texttt{-M}
+\item Support for regular expressions in replace files
+\item Implemented support for the \LaTeX\ \texttt{\bs input} and \texttt{\bs include} directives
+\item Implemented loop context
+\item Skip commentlines
+\item Project moved from local CVS to GitHub
+\end{itemize}
+
+\item[v1.5] \textit{released: Nov 23, 2007}
+\begin{itemize}
+\item Support for multiple databases
+\item Implemented database updates (\texttt{sqlupdate})
+\item Implemented multiple output documents (option \texttt{-m})
+\end{itemize}
+
+\item[v1.4.1] \textit{released: Feb 15, 2005}\\
+Fix: removed leading whitespaces added to database results before replace
+
+\item[v1.4] \textit{released: May 2, 2002}\\
+Implemented replace files
+
+\item[v1.3] \textit{released: Mar 16, 2001}\\
+First public release
+
+\end{description}
+
+\subsection{Changes that require updates in your input files}
+
+\subsubsection{Multi-document mode since v2.2}\label{mdocupdates}
+
+Up until v2.1, the statement in \texttt{\bs sqlsetparams} could return only one field per row and the statement itself could not handle parameters. The placeholder \texttt{\$PAR1} was reserved for the subsequent statements.
+
+Since v2.2 it is possible to retrieve multiple values per row. They will replace the placeholders \texttt{\$MPAR\textit{n}} in the subsequent statements, while \texttt{\$PAR\textit{n}} placeholders can now also be used for regular parametes in the \texttt{\bs sqlsetparams} statement itself.
+
+\vs
+
+This means, in input documents created before v2.2, all ``\texttt{\$PAR1}'' placeholders must be replaced by ``\texttt{\$MPAR1}''.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/support/texfindpkg/README.md b/Master/texmf-dist/doc/support/texfindpkg/README.md
index 06c2d44bc24..53e40ede3d0 100644
--- a/Master/texmf-dist/doc/support/texfindpkg/README.md
+++ b/Master/texmf-dist/doc/support/texfindpkg/README.md
@@ -2,7 +2,7 @@
```
Description: Query or Install TeX packages and their dependencies
-Copyright: 2023 (c) Jianrui Lyu <tolvjr@163.com>
+Copyright: 2023-2024 (c) Jianrui Lyu <tolvjr@163.com>
Repository: https://github.com/lvjr/texfindpkg
License: GNU General Public License v3.0
```
@@ -23,7 +23,7 @@ If a manual installation is needed, you could copy TeXFindPkg files to TEXMF tre
| texfindpkg.1 | TEXMF/doc/man/man1/texfindpkg.1 |
| README.md | TEXMF/doc/support/texfindpkg/README.md |
| texfindpkg.lua | TEXMF/scripts/texfindpkg/texfindpkg.lua |
-| texfindpkg.json.gz | TEXMF/scripts/texfindpkg/texfindpkg.json.gz |
+| texfindpkg.json.gz | TEXMF/tex/latex/texfindpkg/texfindpkg.json.gz |
| tfpbuild.lua | TEXMF/source/texfindpkg/tfpbuild.lua |
Then you could create a symbolic link from `/usr/local/bin/texfindpkg` to `path/to/texfindpkg.lua` on Linux or MacOS,
@@ -45,13 +45,46 @@ texfindpkg <action> [<option>] [<name>]
The `<action>` could be `query`, `install`, `help` or `version`.
The leading dashes in any `<action>` will be removed first.
-For `query` action, you pass `-f`, `-c` or `-e` as `<option>`
-to indicate the following `<name>` is a file name, command name or environment name.
-For example,
-
-- `texfindpkg query -f array.sty` means querying package with file `array.sty`;
+For `query` action, you pass `-c`, `-e`, `-f` or `-p` as `<option>`
+to indicate the following `<name>` is a command name, environment name, file name or package name.
+For example (for `-f` option, you can omit file extension in the name if it is `.sty`),
- `texfindpkg query -c fakeverb` means querying package with command `\fakeverb`;
-- `texfindpkg query -e frame` means querying package with environment `{frame}`.
+- `texfindpkg query -e frame` means querying package with environment `{frame}`;
+- `texfindpkg query -f array.sty` means querying package with file `array.sty`;
+- `texfindpkg query -p caption` means querying LaTeX packages in TeXLive/MiKTeX package `caption`.
+
+You can query a lot of names in one go. For example,
+```
+texfindpkg query -c fakeverb -e verbatim tblr -f array longtable -p caption
+```
+
+When you have a lot of names to query, you may want to list them in a file and use `-i` option to insert them.
+For example, if you have a file `input.txt` of lines (comments starting with `#` characters are ignored in it)
+```
+-c
+fakeverb
+-e
+verbatim
+tblr
+-f
+array
+longtable
+-p
+caption
+```
+then the following command produces the same result as the previous one does:
+```
+texfindpkg query -i input.txt
+```
+
+Furthermore you can save total dependent list of packages to a file with `-o` option:
+```
+texfindpkg query -i input.txt -o output.txt
+```
+
+With `-i` and `-o` options, it is quite easy to install a minimal TeXLive distribution with all dependencies resolved,
+which is useful for you to run regression tests with GitHub Actions if you are a package writer.
+Please see `latex-package.txt` and `texlive-package.txt` in [tabularray](https://github.com/lvjr/tabularray/tree/main/.github/workflows) repository for a practical example.
The only difference between `query` and `install` actions is that
with `install` action TeXFindPkg will install missing TeXLive or MiKTeX packages at the end.
diff --git a/Master/texmf-dist/doc/support/texlogsieve/README.md b/Master/texmf-dist/doc/support/texlogsieve/README.md
index 23939d4388e..f227bce2f7d 100644
--- a/Master/texmf-dist/doc/support/texlogsieve/README.md
+++ b/Master/texmf-dist/doc/support/texlogsieve/README.md
@@ -9,6 +9,7 @@ report. It is a `texlua` script, similar in spirit to tools such as
[`textlog_extract`](https://ctan.org/pkg/texlog-extract),
[`texlogparser`](https://github.com/reitzig/texlogparser),
[`texlogfilter`](https://gricad-gitlab.univ-grenoble-alpes.fr/labbeju/latex-packages),
+[`pulp`](https://github.com/dmwit/pulp),
and others. Highlights:
* Two reports: the most important messages from the log file followed by
diff --git a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf
index a0e2ac061b1..7c404a20438 100644
--- a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf
+++ b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex
index 4bfe0b26768..e124ebb1b0c 100644
--- a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex
+++ b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex
@@ -98,12 +98,16 @@
\changes{1.4.1}{2024/01/15}{Look 5 lines ahead instead of 3}
\changes{1.4.1}{2024/01/15}{Reduce priority of harmless font substitutions}
\changes{1.4.1}{2024/01/15}{Recognize more messages}
+\changes{1.4.2}{2024/11/22}{Recognize more messages}
+\changes{1.4.2}{2024/11/22}{Correctly handle ``*full hbox while output\dots``}
+\changes{1.4.2}{2024/11/22}{Add mention to \texttt{pulp}}
+\changes{1.4.2}{2024/11/22}{Add messages from \texttt{comment} pkg}
\begin{document}
\title{\textsf{texlogsieve}:\thanks{This document
-corresponds to \textsf{texlogsieve}~1.4.1,
-dated~2024-01-15.}\\[.3\baselineskip]
+corresponds to \textsf{texlogsieve}~1.4.2,
+dated~2024-11-22.}\\[.3\baselineskip]
{\normalsize(yet another program to)\\[-.6\baselineskip]}
{\large filter and summarize \LaTeX\ log files}
}
@@ -150,7 +154,8 @@ spirit to tools such as \href{https://ctan.org/pkg/texfot}{\texttt{texfot}},
\href{https://ctan.org/pkg/texlog-extract}{\texttt{textlog\_extract}},
\href{https://github.com/reitzig/texlogparser}{\texttt{texlogparser}},
\href{https://gricad-gitlab.univ-grenoble-alpes.fr/labbeju/latex-packages}
-{\texttt{texlogfilter}}, and others.
+{\texttt{texlogfilter}}, \href{https://github.com/dmwit/pulp}
+{\texttt{pulp}}, and others.
Note that it does not try to do anything smart about error messages (but
it shows a warning in the summary if one is detected; check the ``Tips''
diff --git a/Master/texmf-dist/doc/support/tlaunch/Changes b/Master/texmf-dist/doc/support/tlaunch/Changes
index 148a5624669..4eddb17e6c4 100644
--- a/Master/texmf-dist/doc/support/tlaunch/Changes
+++ b/Master/texmf-dist/doc/support/tlaunch/Changes
@@ -1,3 +1,11 @@
+2024-10-07 Siep Kroonenberg <siepo@bitmuis.nl> Release 0.5.5
+
+ * Bug fixes
+
+2023-03-07 Siep Kroonenberg <siepo@bitmuis.nl> Release 0.5.4
+
+ * Transition to 64bit
+
2017-06-29 Siep Kroonenberg <siepo@cybercomm.nl> Release 0.5.3
* Remember command-line option: restores file associations on login