gitlatexdiff-original 0.2.0__tar.gz

gitlatexdiff_original-0.2.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: gitlatexdiff-original
+Version: 0.2.0
+Summary: Make diff of two versions of a LaTeX document in a Git repo
+Author-email: bjhend <developer@bjhend.de>
+Maintainer-email: bjhend <developer@bjhend.de>
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/bjhend/gitlatexdiff
+Project-URL: Issues, https://github.com/bjhend/gitlatexdiff/issues
+Project-URL: Changelog, https://github.com/bjhend/gitlatexdiff/blob/main/CHANGELOG.md
+Keywords: git,latex,diff,tool
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: beartype
+Requires-Dist: mkdocs
+Requires-Dist: mkdocstrings[python]
+Requires-Dist: pymdown-extensions
+Requires-Dist: icecream
+
+# Git-LaTeX-Diff Original
+
+Make a rendered diff of two versions of a LaTeX document.
+
+
+### License
+
+See [License](LICENSE.md)
+
+
+### Changelog
+
+See [Changelog](CHANGELOG.md)
+
+
+## Purpose
+
+[*latexdiff*](https://www.ctan.org/pkg/latexdiff) is a LaTeX tool to create a diff of two LaTeX documents, which shows deletions and additions as red strike-through text and additions as blue underlined text when compiled to PDF. However, *latexdiff* has some major limitations.
+
+To overcome the limitations, this Python script extends *latexdiff* in several ways:
+
+* It works with a Git repo such that it compares the current state or a given commit with an earlier commit
+* It resolves `\include` and `\input` commands like LaTeX does
+* It calls `pdflatex` to render the final PDF
+
+In addition the `\include` and `\input` resolving itself can be called as standalone script.
+
+
+
+## Caveats
+
+* While `\include` and `\input` are resolved from the respective git revisions, other includes like figures are resolved when compiling the diff. This is done in the new revision. So if the old version includes figures that are missing or renamed in the new revision they will be missing in the diff PDF as well.
+* There is no diff of the bibliography and other generated parts.
+* When using uncommitted changes as new version the rendering has to take place in the documents work directory. This may leave temporary files and have other unexpected side effects. However, if everything is committed or dedicated Git revisions are compared all processing is done in temporary directories that are cleaned up.
+
+
+
+### Prerequesites
+
+* LaTeX must be installed including the tools
+    * `pdflatex`
+    * `latexdiff`
+* Python3 is available with at least the version set in `pyproject.toml`
+
+
+
+## Usage
+
+The easiest way is to apply the Python tool `uv`, which we describe here. Likely `poetry` will work as well.
+
+Change to the directory where you cloned the gitlatexdiff project and call
+
+```bash
+uv sync
+```
+
+to install all dependencies and create a virtual environment.
+
+To run the script call
+
+```bash
+uv run gitlatexdiff <options>
+```
+
+To run the script to flatten a LeTeX file standalone call
+
+```bash
+uv run flattenlatex <options>
+```
+
+
+#### Tips
+
+If the diff sources cannot be compiled check the log file for problems with `\DIF...` commands and see which original LaTeX command caused it. Then you may exclude that command from the diff with for example:
+
+`-l 'append-textcmd=hint.*,todo' 'exclude-textcmd=title,.*section,chapter'`
+
+Here, LaTeX commands `\title`, `\chapter`, and all ending in `section` are excluded, so diffs in these commands are not marked in the output.
+
+Note, that in this case the `'append-textcmd=hint.*,todo'` is the default for option `-l`, which needs to be set explicitely if `-l` is given.
+
+
+### Options
+
+Call `gitlatexdiff` with option `--help` to get the current list of command line options and their defaults if applicable.
+
+#### Mandatory options
+
+* `-m`, `--main`: Name of the main LaTeX file whose versions should be compared. It has to reside in the respective Git repository containing the versions to compare. May be given with path if `gitlatexdiff` is called from outside the LaTeX project directory.
+
+#### Optional
+
+All other command line options are optional.
+
+Call `gitlatexdiff --help` to see the defaults of the following options.
+
+* `-n`, `--new-rev`: Newer revision to compare with. If not given the current state of the work files is used, which will be the HEAD revision if all files are committed or else the work files.
+* `-o`, `--old-rev`: Older revision to compare with. If not given either the revision before `--new-rev` is used or the HEAD revision if `--new-rev` is also not given and there are uncommitted changes.
+* `--old-main`: Name of the old main LaTeX file which should be compared. Defaults to `--main`.
+* `-d`, `--diff-name`: Name of the final diff file. '`.pdf`' will be appended if necessary. The log file of the last `pdflatex` call will be stored beside this file.
+* `-w`, `--overwrite`: If not given `gitlatexdiff` refuses to overwite an existing diff file.
+* `--num-rounds`: Number of calls to `pdflatex` when compiling the diff.
+
+The following options are passed to `latexdiff` or `pdflatex` respectively. For technical reasons values have to be given without leading dashes. Dashes are prepended as required by the respective command.
+
+* `-l`, `--latexdiff-options`: Arbitrary number of options passed to `latexdiff` call. Pass without any value to turn off the default.
+* `-p`, `--pdflatex-options`: Arbitrary number of options passed to `pdflatex` call. Pass without any value to turn off the default.
+
+
+### `flattenlatex`
+
+Python module to recusively resolve `\include` and `\input` commands in a LaTeX document. `gitlatexdiff` uses it on both versions of the input file.
+
+Call `uv run flattenlatex --help` to see its options to set input and output file. The input file is mandatory, because included files are drawn from its directory. The output file is optional, if omitted, `stdout` will be used.
+
+
+
+## Documentation
+
+Documentation is created with [MkDocs](https://www.mkdocs.org).
+
+The following commands called from the base directory create the documentation:
+
+* `uv run mkdocs serve` - Start the docs server.
+* `uv run mkdocs build` - Build static documentation in subfolder `site/`
+* `uv run mkdocs --help` - Print help message and exit.
+
+
+
+## Contributing
+
+Create issues or a pull requests to point out bugs or improvements.
+
+
+## A note on the name
+
+This project is called *Git-LaTeX-Diff Original* or `gitlatexdiff-original`, because the project name *gitlatexdiff* is already in use on [PyPI](https://pypi.org) for a similar [package](https://pypi.org/project/gitlatexdiff/) that was independently developed. It is called *original* due to the fact that the first publication of this project on GitHub is older.
+

gitlatexdiff_original-0.2.0/README.md

@@ -0,0 +1,138 @@
+# Git-LaTeX-Diff Original
+
+Make a rendered diff of two versions of a LaTeX document.
+
+
+### License
+
+See [License](LICENSE.md)
+
+
+### Changelog
+
+See [Changelog](CHANGELOG.md)
+
+
+## Purpose
+
+[*latexdiff*](https://www.ctan.org/pkg/latexdiff) is a LaTeX tool to create a diff of two LaTeX documents, which shows deletions and additions as red strike-through text and additions as blue underlined text when compiled to PDF. However, *latexdiff* has some major limitations.
+
+To overcome the limitations, this Python script extends *latexdiff* in several ways:
+
+* It works with a Git repo such that it compares the current state or a given commit with an earlier commit
+* It resolves `\include` and `\input` commands like LaTeX does
+* It calls `pdflatex` to render the final PDF
+
+In addition the `\include` and `\input` resolving itself can be called as standalone script.
+
+
+
+## Caveats
+
+* While `\include` and `\input` are resolved from the respective git revisions, other includes like figures are resolved when compiling the diff. This is done in the new revision. So if the old version includes figures that are missing or renamed in the new revision they will be missing in the diff PDF as well.
+* There is no diff of the bibliography and other generated parts.
+* When using uncommitted changes as new version the rendering has to take place in the documents work directory. This may leave temporary files and have other unexpected side effects. However, if everything is committed or dedicated Git revisions are compared all processing is done in temporary directories that are cleaned up.
+
+
+
+### Prerequesites
+
+* LaTeX must be installed including the tools
+    * `pdflatex`
+    * `latexdiff`
+* Python3 is available with at least the version set in `pyproject.toml`
+
+
+
+## Usage
+
+The easiest way is to apply the Python tool `uv`, which we describe here. Likely `poetry` will work as well.
+
+Change to the directory where you cloned the gitlatexdiff project and call
+
+```bash
+uv sync
+```
+
+to install all dependencies and create a virtual environment.
+
+To run the script call
+
+```bash
+uv run gitlatexdiff <options>
+```
+
+To run the script to flatten a LeTeX file standalone call
+
+```bash
+uv run flattenlatex <options>
+```
+
+
+#### Tips
+
+If the diff sources cannot be compiled check the log file for problems with `\DIF...` commands and see which original LaTeX command caused it. Then you may exclude that command from the diff with for example:
+
+`-l 'append-textcmd=hint.*,todo' 'exclude-textcmd=title,.*section,chapter'`
+
+Here, LaTeX commands `\title`, `\chapter`, and all ending in `section` are excluded, so diffs in these commands are not marked in the output.
+
+Note, that in this case the `'append-textcmd=hint.*,todo'` is the default for option `-l`, which needs to be set explicitely if `-l` is given.
+
+
+### Options
+
+Call `gitlatexdiff` with option `--help` to get the current list of command line options and their defaults if applicable.
+
+#### Mandatory options
+
+* `-m`, `--main`: Name of the main LaTeX file whose versions should be compared. It has to reside in the respective Git repository containing the versions to compare. May be given with path if `gitlatexdiff` is called from outside the LaTeX project directory.
+
+#### Optional
+
+All other command line options are optional.
+
+Call `gitlatexdiff --help` to see the defaults of the following options.
+
+* `-n`, `--new-rev`: Newer revision to compare with. If not given the current state of the work files is used, which will be the HEAD revision if all files are committed or else the work files.
+* `-o`, `--old-rev`: Older revision to compare with. If not given either the revision before `--new-rev` is used or the HEAD revision if `--new-rev` is also not given and there are uncommitted changes.
+* `--old-main`: Name of the old main LaTeX file which should be compared. Defaults to `--main`.
+* `-d`, `--diff-name`: Name of the final diff file. '`.pdf`' will be appended if necessary. The log file of the last `pdflatex` call will be stored beside this file.
+* `-w`, `--overwrite`: If not given `gitlatexdiff` refuses to overwite an existing diff file.
+* `--num-rounds`: Number of calls to `pdflatex` when compiling the diff.
+
+The following options are passed to `latexdiff` or `pdflatex` respectively. For technical reasons values have to be given without leading dashes. Dashes are prepended as required by the respective command.
+
+* `-l`, `--latexdiff-options`: Arbitrary number of options passed to `latexdiff` call. Pass without any value to turn off the default.
+* `-p`, `--pdflatex-options`: Arbitrary number of options passed to `pdflatex` call. Pass without any value to turn off the default.
+
+
+### `flattenlatex`
+
+Python module to recusively resolve `\include` and `\input` commands in a LaTeX document. `gitlatexdiff` uses it on both versions of the input file.
+
+Call `uv run flattenlatex --help` to see its options to set input and output file. The input file is mandatory, because included files are drawn from its directory. The output file is optional, if omitted, `stdout` will be used.
+
+
+
+## Documentation
+
+Documentation is created with [MkDocs](https://www.mkdocs.org).
+
+The following commands called from the base directory create the documentation:
+
+* `uv run mkdocs serve` - Start the docs server.
+* `uv run mkdocs build` - Build static documentation in subfolder `site/`
+* `uv run mkdocs --help` - Print help message and exit.
+
+
+
+## Contributing
+
+Create issues or a pull requests to point out bugs or improvements.
+
+
+## A note on the name
+
+This project is called *Git-LaTeX-Diff Original* or `gitlatexdiff-original`, because the project name *gitlatexdiff* is already in use on [PyPI](https://pypi.org) for a similar [package](https://pypi.org/project/gitlatexdiff/) that was independently developed. It is called *original* due to the fact that the first publication of this project on GitHub is older.
+

gitlatexdiff_original-0.2.0/pyproject.toml

@@ -0,0 +1,61 @@
+
+
+# Copyright 2019,2026 Björn Hendriks
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+[project]
+name = "gitlatexdiff-original"
+version = "0.2.0"
+description = "Make diff of two versions of a LaTeX document in a Git repo"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = [ "LICENSE" ]
+keywords = [ "git", "latex", "diff", "tool" ]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+]
+authors = [
+    {name = "bjhend", email = "developer@bjhend.de"},
+]
+maintainers = [
+    {name = "bjhend", email = "developer@bjhend.de"},
+]
+
+requires-python = ">=3.12"
+dependencies = [
+    "beartype",
+    "mkdocs",
+    "mkdocstrings[python]",
+    "pymdown-extensions",
+    "icecream",
+]
+
+
+[project.urls]
+Repository = "https://github.com/bjhend/gitlatexdiff"
+Issues = "https://github.com/bjhend/gitlatexdiff/issues"
+Changelog = "https://github.com/bjhend/gitlatexdiff/blob/main/CHANGELOG.md"
+
+
+[project.scripts]
+gitlatexdiff = "gitlatexdiff:main"
+flattenlatex = "gitlatexdiff:flattenCommand"
+
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+

gitlatexdiff_original-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gitlatexdiff_original-0.2.0/src/gitlatexdiff/__init__.py

@@ -0,0 +1,25 @@
+
+
+# Copyright 2019,2026 Björn Hendriks
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Dynamic type checking with beartype
+from beartype.claw import beartype_this_package
+beartype_this_package()
+
+
+from .make_diff import main
+from .flatten_latex import flattenCommand
+

gitlatexdiff_original-0.2.0/src/gitlatexdiff/flatten_latex.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# Recursively replace LaTeX input and include commands by the respective files
+#
+# Can be used either as module providing the parseFile function or directly
+# called with LaTeX code provided on stdin and the result written to stdout.
+
+
+# Copyright 2019,2026 Björn Hendriks
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import sys
+import os
+import re
+import typing
+import argparse
+import pathlib as pl
+import contextlib
+from icecream import ic
+
+
+
+class _Config():
+    """Configuration values"""
+
+    texExtension = '.tex'
+
+    # Regular expression template to find LaTeX commands which are not commented out
+    # the first part only allows '%' with an odd number of leading backslashes
+    _commandPattern = r"^(?P<before>(?:[^%\\]|\\.)*)\\{cmd}{{(?P<filename>.*?)}}(?P<after>.*)"
+    inputRe = re.compile(_commandPattern.format(cmd='input'))
+    includeRe = re.compile(_commandPattern.format(cmd='include'))
+    includeOnlyRe = re.compile(_commandPattern.format(cmd='includeonly'))
+
+
+def _flattenRecursion(inFile:typing.TextIO, outFile:typing.TextIO,
+                     includeOnly:list[str]|None=None, isResolveInclude:bool=True) -> None:
+    """Copy inFile to outFile recursively inserting inputs and includes
+
+    According to LaTeX `\\input` is always inserted but `\\include` is more special.
+    `\\include` cannot be nested and if `\\includeonly` is given in the preamble
+    includes are limited to those files. In addition `\\include` is surrounded by
+    `\\clearpage`.
+
+    Args:
+        inFile:           readable text file object to parse
+        outFile:          writable text file object to write result into
+        includeOnly:      list of filenames to include found in `\\includeonly` command
+        isResolveInclude: True if `\\include` should be resolved to avoid nested inclusion
+    """
+    config = _Config()
+
+    def getFilename(match:re.Match) -> str:
+        """Get filename argument from command match"""
+        return match.group('filename').strip()
+
+    def insertFile(match:re.Match, isInclude:bool) -> None:
+        """Open filename in match and insert its content"""
+
+        if isInclude:
+            label = 'include'
+            surround = "\\clearpage  % inserted due to resolved include\n"
+            newIsResolveInclude = False
+        else:
+            label = 'input'
+            surround = ''
+            newIsResolveInclude = isResolveInclude
+
+        fileName = getFilename(match)
+        if not fileName.endswith(config.texExtension):
+            fileName += config.texExtension
+        before = match.group('before')
+        after = match.group('after')
+
+        outFile.write(before)
+        outFile.write(f"% ========= begin {label} of {fileName} ==========\n")
+        outFile.write(surround)
+        with open(fileName) as file:
+            _flattenRecursion(file, outFile, includeOnly=includeOnly,
+                             isResolveInclude=newIsResolveInclude)
+        outFile.write(surround)
+        outFile.write(f"% ========= end {label} of {fileName} ==========\n")
+        outFile.write(after)
+
+    for line in inFile:
+        # Handle \includeonly
+        matchIncludeOnly = config.includeOnlyRe.search(line)
+        if matchIncludeOnly:
+            filenames = getFilename(matchIncludeOnly).split(sep=',')
+            includeOnly = [ f.strip() for f in filenames ]
+
+        # Handle \input
+        matchInput = config.inputRe.search(line)
+        if matchInput:
+            insertFile(match=matchInput, isInclude=False)
+            continue
+
+        # Handle \include
+        if isResolveInclude:
+            matchInclude = config.includeRe.search(line)
+            if matchInclude:
+                if (not includeOnly) or (getFilename(matchInclude) in includeOnly):
+                    insertFile(match=matchInclude, isInclude=True)
+                    continue
+
+        # Copy line
+        outFile.write(line)
+
+
+def flatten(inFile:typing.TextIO, outFile:typing.TextIO) -> None:
+    """Start recursively resolving inputs/includes
+
+    Args:
+        inFile:  An open read text file object to read input LaTeX code from
+        OutFile: An open write text file object to write flattened LaTeX code to
+    """
+    _flattenRecursion(inFile, outFile)
+
+
+def flattenFiles(inPath:pl.Path, outPath:pl.Path|None=None) -> None:
+    """Open files and call flatten() with them
+
+    Both files can be given as pathlib.Path or string.
+
+    We require inPath instead of defaulting to stdin, because we need
+    its directory to resolve relative input/include paths in the LaTeX code
+
+    Args:
+        inPath:  path of input file
+        outPath: optional name of output file, if omitted stdout is used instead
+
+    Raises:
+        OSError: if a file cannot be opened.
+    """
+    cwd = pl.Path.cwd()
+    try:
+        inPath = pl.Path(inPath)
+        assert inPath.is_file()
+
+        inPathAbs = inPath.absolute()
+        if outPath:
+            outPath = pl.Path(outPath)
+            output:contextlib.AbstractContextManager[typing.TextIO] = contextlib.closing(outPath.absolute().open('w'))
+        else:
+            output = contextlib.nullcontext(sys.stdout)
+
+        # Change dir to resolve relative inputs/includes
+        os.chdir(inPathAbs.parent)
+
+        with inPathAbs.open() as inFile:
+            with output as outFile:
+                flatten(inFile, outFile)
+    finally:
+        os.chdir(cwd)
+
+
+def flattenCommand() -> None:
+    """Call flatten from command line
+
+    Parses command line for input and output and calls flattenFiles with them.
+
+    If output exists an additional command line flag is required to overwrite it.
+    """
+    parser = argparse.ArgumentParser(description="Flatten a LaTeX file to a single file with all input/include resolved")
+
+    # See flattenFiles documentation, why --input is required
+    parser.add_argument('-i', '--input', required=True, type=pl.Path, help="Main LaTeX file to flatten")
+    parser.add_argument('-o', '--output', type=pl.Path, help="Output file, default is stdout")
+    parser.add_argument('-w', '--overwrite', action='store_true', help="Silently overwrite existing diff? (default: %(default)s)")
+    args = parser.parse_args()
+
+    if args.output and (not args.overwrite) and args.output.exists():
+        print(f"Output {args.output} exists. Delete it or set option --overwrite (-w) to overwrite it.")
+        exit(1)
+
+    try:
+        flattenFiles(args.input, args.output)
+    except OSError as ex:
+        print(f"Cannot open input or output file: {ex}")
+        exit(1)
+
+
+if __name__ == "__main__":
+    flattenCommand()
+

gitlatexdiff_original-0.2.0/src/gitlatexdiff/make_diff.py

@@ -0,0 +1,375 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# Make a diff of a LaTeX file to another Git revision with latexdiff
+#
+# Call it with option --help for more info
+
+# Copyright 2019,2026 Björn Hendriks
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+
+import os
+import argparse
+import subprocess
+import tempfile
+import pathlib as pl
+import contextlib
+import typing
+from collections.abc import Generator
+import shutil
+from icecream import ic
+from . import flatten_latex
+
+
+latexExtension = '.tex'
+pdfExtension = '.pdf'
+logExtension = '.log'
+messagePrefix = "------ "
+
+# Command line option defaults
+defaultNumRounds = 3
+defaultDiffName = 'diff'
+defaultLatexdiffOptions = ['append-textcmd=hint.*,todo']
+defaultPdflatexOptions = ['interaction=batchmode']
+
+
+def callCommand(args:list[str], cwd:pl.Path|None=None) -> str:
+    """Call args as shell command and return its stdout (NOT stderr)
+
+    Args:
+        cwd: optional working directory
+
+    Raises:
+        subprocess.CalledProcessError: if the command returns with non-zero
+                                       exit code
+
+    Returns:
+        stdout of the command
+    """
+    result = subprocess.run(args, cwd=cwd, stdout=subprocess.PIPE, check=True)
+    return result.stdout.decode().strip()
+
+
+class Configuration():
+    """Configuration values either from parsing command line or hard coded"""
+
+    def __init__(self):
+        """Get and preprocess command line arguments"""
+        args = self._parseArgs()
+
+        # Options given to latexdiff
+        self.latexdiffOptions = self._prependPrefix('--', args.latexdiff_options)
+        # Options given to pdflatex
+        self.pdflatexOptions = self._prependPrefix('-', args.pdflatex_options)
+        # Number of successive calls of pdflatex to achieve the final result
+        self.numTexRounds = args.num_rounds
+        if self.numTexRounds < 1:
+            print(f"--num-rounds set to {self.numTexRounds}, but must be at least 1")
+            exit(1)
+
+        self.mainFileAbs = args.main.resolve().with_suffix(latexExtension)
+        self.oldMainFileAbs = args.old_main.resolve().with_suffix(latexExtension) if args.old_main else self.mainFileAbs
+        self.diffNameAbs = args.diff_name.resolve().with_suffix(pdfExtension)
+        self.logNameAbs = args.diff_name.resolve().with_suffix(logExtension)
+
+        # Bail out if diffNameAbs exists and no --overwrite given
+        if (not args.overwrite) and self.diffNameAbs.exists():
+            print(f"Destination file {self.diffNameAbs} exists. Delete it or set --overwrite to overwrite it.")
+            exit(1)
+
+        self.newRevision = args.new_rev
+        self.oldRevision = args.old_rev
+
+    def _prependPrefix(self, prefix:str, options:list[str]) -> list[str]:
+        """Prepend prefix to all elements of options tuple
+
+        Args:
+            prefix:  string to prepend to all elements of options
+            options: iterable of strings to prepend prefix to
+
+        Returns:
+            options with prefix prepended
+        """
+        return [ prefix + opt for opt in options ]
+
+    def _parseArgs(self) -> argparse.Namespace:
+        """Parse command line arguments
+
+        Returns:
+            result of argparse.ArgumentParser.parse_args()
+        """
+        parser = argparse.ArgumentParser(description='Make a LaTeX diff for two Git revisions of a LaTeX project')
+
+        parser.add_argument('-m', '--main', type=pl.Path, required=True, help='Main LaTeX file (required)')
+        parser.add_argument('-n', '--new-rev', help='Ref to new revision for diff (default: current state of the repo)')
+        parser.add_argument('-o', '--old-rev', help='Ref to old revision for diff (default depends on --new-rev: If --new-rev is given'
+                                                    ' one revision before --new-rev. If --new-rev is omitted but everything is committed'
+                                                    ' then one before HEAD. Else HEAD itself.)')
+        parser.add_argument('--old-main', type=pl.Path, help='Main LaTeX file of old revision (defaults to --main)')
+        parser.add_argument('-d', '--diff-name', type=pl.Path, default=defaultDiffName, help='Name for final diff file (default: %(default)s)')
+        parser.add_argument('-w', '--overwrite', action='store_true', help='Silently overwrite existing diff (default: %(default)s)')
+        parser.add_argument('--num-rounds', type=int, default=defaultNumRounds, help='Number of pdflatexcalls to compile the diff (default: %(default)s)')
+        parser.add_argument('-l', '--latexdiff-options', nargs='*', default=defaultLatexdiffOptions,
+                            help='Options passed to latexdiff without leading dashes (default: %(default)s)')
+        parser.add_argument('-p', '--pdflatex-options', nargs='*', default=defaultPdflatexOptions,
+                            help='Options passed to pdflatex without leading dashes (default: %(default)s)')
+
+        return parser.parse_args()
+
+
+class GitRepo():
+    """Wrapper for all Git commands
+
+    We do not apply GitPython or other third party packages to be as portable
+    as possible. Instead we call the Git commands directly.
+    """
+
+    def __init__(self, config:Configuration):
+        """Init GitRepo with given config
+
+        Args:
+            config: configuration with main file path
+        """
+        self.repoDir = pl.Path(self._callGit(['rev-parse', '--show-toplevel'], config.mainFileAbs.parent))
+
+    def getSha1(self, committish:str) -> str:
+        """Return SHA1 of committish
+
+        Args:
+            committish: any string that Git recognizes as a commit reference: HEAD,
+                        branch, tag, or their parents
+
+        Returns:
+            SHA1 of the referenced commit or `None` if it cannot be resolved
+        """
+
+        try:
+            return self._callGit(['rev-parse', committish])
+        except subprocess.CalledProcessError:
+            return None
+
+    def isDirty(self) -> bool:
+        """Check if uncommitted changes or new non-ignored files are present
+
+        Returns:
+            `True` if there are uncommitted files
+        """
+        try:
+            # Returns with non-zero exitcode if a committed file is altered
+            self._callGit(['diff-index', '--quiet', 'HEAD', '--'])
+        except subprocess.CalledProcessError:
+            return True
+
+        # Returns list of non-ignored untracked files
+        untrackedFiles = self._callGit(['ls-files', '--exclude-standard', '--others'])
+        return bool(untrackedFiles)
+
+    @contextlib.contextmanager
+    def worktree(self, sha1:str|None=None) -> Generator[pl.Path]:
+        """Check out sha1 in a temporary worktree and finally cleanup or return repo dir
+
+        This is a contextmanager, so call it in a `with` statement.
+
+        If `sha1` is given check it out in a temporary worktree and remove the
+        worktree on exit of the context. If `sha1` is `None` return the repo dir
+        itself.
+
+        Args:
+            sha1: SHA1 of the commit to check out in the worktree, if `None` return
+                  the repo dir itself
+
+        Returns:
+            path to the work files
+        """
+
+        if not sha1:
+            yield self.repoDir
+            return
+
+        with tempfile.TemporaryDirectory(prefix='gitlatexdiff_worktree_') as workDir:
+            workDirPath = pl.Path(workDir)
+            self._callGit(['worktree', 'add', '--force', str(workDirPath), sha1])
+            try:
+                yield workDirPath
+            finally:
+                self._callGit(['worktree', 'remove', str(workDirPath)])
+
+    def _callGit(self, args:list[str], workingDir:pl.Path|None=None) -> str:
+        """Call a Git command in the repo or workingDir if given
+
+        Prepends `git` to the given args and calls callCommand() with them.
+
+        Args:
+            args:       command line arguments for the Git command (without `git` itself)
+            workingDir: optional dir to execute the command in, if ommitted use
+                        the repo dir
+
+        Return:
+            stdout of the command
+
+        Raises:
+            see callCommand()
+        """
+        if workingDir is None:
+            workingDir = self.repoDir
+        return callCommand(['git'] + args, cwd=workingDir)
+
+
+
+class Diff():
+    """Class to create the diff"""
+
+    def __init__(self, config:Configuration, gitRepo:GitRepo):
+        """Init
+
+        Args:
+            config:  configuration
+            gitRepo: Git repo
+        """
+
+        self.config = config
+        self.gitRepo = gitRepo
+        self.mainFileRelative = self.config.mainFileAbs.relative_to(self.gitRepo.repoDir)
+        self.oldMainFileRelative = self.config.oldMainFileAbs.relative_to(self.gitRepo.repoDir)
+
+        # Determine new sha1
+        if config.newRevision:
+            self.newSha1:str|None = self.gitRepo.getSha1(config.newRevision)
+        else:
+            if self.gitRepo.isDirty():
+                self.newSha1 = None
+            else:
+                self.newSha1 = self.gitRepo.getSha1('HEAD')
+
+        # Determine old sha1
+        if config.oldRevision:
+            self.oldSha1 = self.gitRepo.getSha1(config.oldRevision)
+        else:
+            if self.newSha1:
+                # Use one revision before new sha1
+                self.oldSha1 = self.gitRepo.getSha1(self.newSha1 + '~')
+            else:
+                # Compare work files with HEAD revision
+                self.oldSha1 = self.gitRepo.getSha1('HEAD')
+
+    @contextlib.contextmanager
+    def _flatFile(self, sha1:str|None, mainFileRelative:pl.Path) -> Generator[pl.Path]:
+        """Flatten mainFileRelative in the given sha1 revision and return its path
+
+        This method is a contextmanager. So it needs to be called in a
+        with-statement. On leaving the context the returned file and the worktree
+        will be removed.
+
+        Flatten resolves all include/input commands.
+
+        If sha1 is not None flattening is done in an exclusive worktree to avoid
+        interfering with the repo.
+
+        Args:
+            sha1:             revision to check out, if None use the repo itself
+            mainFileRelative: relative path to the main file in the repo
+
+        Returns:
+            name of the temporary file
+        """
+        version = f"version {sha1}" if sha1 else "current version"
+        print(f"{messagePrefix}Flattening {mainFileRelative} in {version}")
+        with self.gitRepo.worktree(sha1) as workDir:
+            mainFileDir = workDir / mainFileRelative.parent
+            os.chdir(mainFileDir)
+            with tempfile.NamedTemporaryFile(mode='w',
+                                        prefix='flattened_',
+                                        suffix=latexExtension,
+                                        dir=mainFileDir,
+                                        delete_on_close=False) as texFile:
+                with (workDir / mainFileRelative).open() as mainFile:
+                    flatten_latex.flatten(mainFile, typing.cast(typing.TextIO, texFile.file))
+                texFile.close()
+                yield pl.Path(texFile.name)
+
+    def makeDiff(self) -> None:
+        """Create the diff PDF file in the directory this script was called from"""
+
+        # Make LaTeX diff
+        with (self._flatFile(self.oldSha1, self.oldMainFileRelative) as oldFlatInput,
+              self._flatFile(self.newSha1, self.mainFileRelative) as newFlatInput):
+            print(f"{messagePrefix}Create diff")
+            diffTex = callCommand(['latexdiff'] + self.config.latexdiffOptions
+                                  + [str(oldFlatInput), str(newFlatInput)])
+
+        # Compile diff in a worktree and move it to its configure final path.
+        # Note that workDir is the repo itself if self.newSha1 is None.
+        with self.gitRepo.worktree(self.newSha1) as workDir:
+            mainFileDir = workDir / self.mainFileRelative.parent
+
+            # TeX commands need to be executed in their repo to have correct access
+            # to all temporary TeX files
+            os.chdir(mainFileDir)
+
+            with tempfile.NamedTemporaryFile(mode='w',
+                                        prefix='diff_',
+                                        suffix=latexExtension,
+                                        dir=mainFileDir,
+                                        delete_on_close=False) as diffTexFile:
+                diffTexFile.write(diffTex)
+                diffTexFile.close()
+                diffTexFilePath = pl.Path(diffTexFile.name)
+
+                # Call pdflatex sufficiently often on diff
+                for i in range(self.config.numTexRounds):
+                    print(f"{messagePrefix}Compiling diff round {i+1}")
+                    try:
+                        callCommand(['pdflatex'] + self.config.pdflatexOptions + [str(diffTexFilePath)], cwd=mainFileDir)
+                    except subprocess.CalledProcessError as ex:
+                        # Sometimes a pdfltex call returns an error but still works
+                        print(f"Warning: pdflatex returned an error, which we ignore: {ex}")
+                        print(f"See pdflatex log for possible causes: {self.config.logNameAbs}")
+
+                # Move resulting PDF and log to initial dir
+                diffPdfPathname = diffTexFilePath.with_suffix(pdfExtension)
+                diffLogPathname = diffTexFilePath.with_suffix(logExtension)
+                shutil.move(diffLogPathname, self.config.logNameAbs)
+                try:
+                    shutil.move(diffPdfPathname, self.config.diffNameAbs)
+                except FileNotFoundError:
+                    print(f"No diff created. See log files for possible cause: {self.config.logNameAbs}")
+                    print("Hint: It may help exclude LaTeX commands with for example \"-l 'exclude-textcmd=title,.*section,chapter'\"")
+
+        # Remove all temporary pdflatex files
+        # This is only relevant if a diff with current dirty work files was made,
+        # so it was compiled in the repo itself instead of a temp worktree.
+        for path in diffTexFilePath.parent.glob(f'{diffTexFilePath.stem}*'):
+            path.unlink()
+
+        print(f"{messagePrefix}Successfully created diff {self.config.diffNameAbs}")
+
+
+def main() -> None:
+    """Entry point"""
+
+    try:
+        config = Configuration()
+        gitRepo = GitRepo(config)
+        diff = Diff(config, gitRepo)
+        diff.makeDiff()
+    except Exception as ex:
+        print(f"An error occurred: {ex}")
+        exit(1)
+
+
+if __name__ == "__main__":
+    main()
+

gitlatexdiff_original-0.2.0/src/gitlatexdiff_original.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: gitlatexdiff-original
+Version: 0.2.0
+Summary: Make diff of two versions of a LaTeX document in a Git repo
+Author-email: bjhend <developer@bjhend.de>
+Maintainer-email: bjhend <developer@bjhend.de>
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/bjhend/gitlatexdiff
+Project-URL: Issues, https://github.com/bjhend/gitlatexdiff/issues
+Project-URL: Changelog, https://github.com/bjhend/gitlatexdiff/blob/main/CHANGELOG.md
+Keywords: git,latex,diff,tool
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: beartype
+Requires-Dist: mkdocs
+Requires-Dist: mkdocstrings[python]
+Requires-Dist: pymdown-extensions
+Requires-Dist: icecream
+
+# Git-LaTeX-Diff Original
+
+Make a rendered diff of two versions of a LaTeX document.
+
+
+### License
+
+See [License](LICENSE.md)
+
+
+### Changelog
+
+See [Changelog](CHANGELOG.md)
+
+
+## Purpose
+
+[*latexdiff*](https://www.ctan.org/pkg/latexdiff) is a LaTeX tool to create a diff of two LaTeX documents, which shows deletions and additions as red strike-through text and additions as blue underlined text when compiled to PDF. However, *latexdiff* has some major limitations.
+
+To overcome the limitations, this Python script extends *latexdiff* in several ways:
+
+* It works with a Git repo such that it compares the current state or a given commit with an earlier commit
+* It resolves `\include` and `\input` commands like LaTeX does
+* It calls `pdflatex` to render the final PDF
+
+In addition the `\include` and `\input` resolving itself can be called as standalone script.
+
+
+
+## Caveats
+
+* While `\include` and `\input` are resolved from the respective git revisions, other includes like figures are resolved when compiling the diff. This is done in the new revision. So if the old version includes figures that are missing or renamed in the new revision they will be missing in the diff PDF as well.
+* There is no diff of the bibliography and other generated parts.
+* When using uncommitted changes as new version the rendering has to take place in the documents work directory. This may leave temporary files and have other unexpected side effects. However, if everything is committed or dedicated Git revisions are compared all processing is done in temporary directories that are cleaned up.
+
+
+
+### Prerequesites
+
+* LaTeX must be installed including the tools
+    * `pdflatex`
+    * `latexdiff`
+* Python3 is available with at least the version set in `pyproject.toml`
+
+
+
+## Usage
+
+The easiest way is to apply the Python tool `uv`, which we describe here. Likely `poetry` will work as well.
+
+Change to the directory where you cloned the gitlatexdiff project and call
+
+```bash
+uv sync
+```
+
+to install all dependencies and create a virtual environment.
+
+To run the script call
+
+```bash
+uv run gitlatexdiff <options>
+```
+
+To run the script to flatten a LeTeX file standalone call
+
+```bash
+uv run flattenlatex <options>
+```
+
+
+#### Tips
+
+If the diff sources cannot be compiled check the log file for problems with `\DIF...` commands and see which original LaTeX command caused it. Then you may exclude that command from the diff with for example:
+
+`-l 'append-textcmd=hint.*,todo' 'exclude-textcmd=title,.*section,chapter'`
+
+Here, LaTeX commands `\title`, `\chapter`, and all ending in `section` are excluded, so diffs in these commands are not marked in the output.
+
+Note, that in this case the `'append-textcmd=hint.*,todo'` is the default for option `-l`, which needs to be set explicitely if `-l` is given.
+
+
+### Options
+
+Call `gitlatexdiff` with option `--help` to get the current list of command line options and their defaults if applicable.
+
+#### Mandatory options
+
+* `-m`, `--main`: Name of the main LaTeX file whose versions should be compared. It has to reside in the respective Git repository containing the versions to compare. May be given with path if `gitlatexdiff` is called from outside the LaTeX project directory.
+
+#### Optional
+
+All other command line options are optional.
+
+Call `gitlatexdiff --help` to see the defaults of the following options.
+
+* `-n`, `--new-rev`: Newer revision to compare with. If not given the current state of the work files is used, which will be the HEAD revision if all files are committed or else the work files.
+* `-o`, `--old-rev`: Older revision to compare with. If not given either the revision before `--new-rev` is used or the HEAD revision if `--new-rev` is also not given and there are uncommitted changes.
+* `--old-main`: Name of the old main LaTeX file which should be compared. Defaults to `--main`.
+* `-d`, `--diff-name`: Name of the final diff file. '`.pdf`' will be appended if necessary. The log file of the last `pdflatex` call will be stored beside this file.
+* `-w`, `--overwrite`: If not given `gitlatexdiff` refuses to overwite an existing diff file.
+* `--num-rounds`: Number of calls to `pdflatex` when compiling the diff.
+
+The following options are passed to `latexdiff` or `pdflatex` respectively. For technical reasons values have to be given without leading dashes. Dashes are prepended as required by the respective command.
+
+* `-l`, `--latexdiff-options`: Arbitrary number of options passed to `latexdiff` call. Pass without any value to turn off the default.
+* `-p`, `--pdflatex-options`: Arbitrary number of options passed to `pdflatex` call. Pass without any value to turn off the default.
+
+
+### `flattenlatex`
+
+Python module to recusively resolve `\include` and `\input` commands in a LaTeX document. `gitlatexdiff` uses it on both versions of the input file.
+
+Call `uv run flattenlatex --help` to see its options to set input and output file. The input file is mandatory, because included files are drawn from its directory. The output file is optional, if omitted, `stdout` will be used.
+
+
+
+## Documentation
+
+Documentation is created with [MkDocs](https://www.mkdocs.org).
+
+The following commands called from the base directory create the documentation:
+
+* `uv run mkdocs serve` - Start the docs server.
+* `uv run mkdocs build` - Build static documentation in subfolder `site/`
+* `uv run mkdocs --help` - Print help message and exit.
+
+
+
+## Contributing
+
+Create issues or a pull requests to point out bugs or improvements.
+
+
+## A note on the name
+
+This project is called *Git-LaTeX-Diff Original* or `gitlatexdiff-original`, because the project name *gitlatexdiff* is already in use on [PyPI](https://pypi.org) for a similar [package](https://pypi.org/project/gitlatexdiff/) that was independently developed. It is called *original* due to the fact that the first publication of this project on GitHub is older.
+

gitlatexdiff_original-0.2.0/src/gitlatexdiff_original.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/gitlatexdiff/__init__.py
+src/gitlatexdiff/flatten_latex.py
+src/gitlatexdiff/make_diff.py
+src/gitlatexdiff_original.egg-info/PKG-INFO
+src/gitlatexdiff_original.egg-info/SOURCES.txt
+src/gitlatexdiff_original.egg-info/dependency_links.txt
+src/gitlatexdiff_original.egg-info/entry_points.txt
+src/gitlatexdiff_original.egg-info/requires.txt
+src/gitlatexdiff_original.egg-info/top_level.txt

gitlatexdiff_original-0.2.0/src/gitlatexdiff_original.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gitlatexdiff_original-0.2.0/src/gitlatexdiff_original.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+flattenlatex = gitlatexdiff:flattenCommand
+gitlatexdiff = gitlatexdiff:main

gitlatexdiff_original-0.2.0/src/gitlatexdiff_original.egg-info/requires.txt

@@ -0,0 +1,5 @@
+beartype
+mkdocs
+mkdocstrings[python]
+pymdown-extensions
+icecream

gitlatexdiff_original-0.2.0/src/gitlatexdiff_original.egg-info/top_level.txt

@@ -0,0 +1 @@
+gitlatexdiff