texworld / blacktex

:black_heart: Cleans up your LaTeX files.

Clean up your LaTeX files.

blacktex is a command-line tool that helps with article editing in LaTeX. It removes all comments from a given file and corrects some common anti-patterns.

Installation

Install blacktex from PyPI with

pip install blacktex

How to get a license

TeX World licenses for personal and academic use can be purchased here. You'll receive a confirmation email with a license key. Install the key with

slim install <your-license-file>

on your machine and you're good to go.

For commercial use, please contact [email protected].

Using blacktex

With

blacktex in.tex > out.tex

the input file

Because   of $$a+b=c$$ ({\it Pythogoras}),
% @johnny remember to insert name
and $y=2^ng$ with $n=1,...,10$, we have ${\Gamma \over 2}=8.$

is converted to

Because of
\[
a+b = c
\]
(\textit{Pythogoras}),
and \(y = 2^n g\) with \(n = 1,\dots,10\), we have \(\frac{\Gamma}{2} = 8\).

You can use

blacktex -i in0.tex in1.tex ...

to modify files in-place. See blacktex -h for all options.

blacktex's Issues

Do not change \def

I know that using plain TeX \def is an anti-pattern considered by your source, and normally LaTeX macros should be defined by \newcommand instead. However, it is not safe to blindly replace the former with the latter -- for starters, since you can't know whether \renewcommand should have been used instead. There are also legitimate uses of \def. Running blacktex on such a file will break it.

I would therefore strongly recommend removing this transformation (or at least put it behind a feature flag, default false, with a prominent warning).

In general, it would be good to make blacktex more configurable by being able to toggling every single transformation rule separately -- ideally using a toml file (stylua can serve as a guide here) -- although I am aware that this would be (too) much work.

List of issues addressed

As the code seems to be unavailable (which is your prerogative, of course), would it be possible to have a comprehensive list of which latex issues are addressed? Something like a checklist of issues noted by the l2tabu source, with those blacktex fixes marked off, would be very helpful; examples would be even better.

Is it possible to support support files in sub-folders?

Currently, it seems that only the main .tex file can be formatted. Is it also possible to support files imported with \input{folder/file.tex}?

Source code no longer available in git?

Could you explain your decision to remove tracking the source code in a public repository in 78c1483 and relicensing new code as "Other/Proprietary License" after v0.6.0?

The version published in PyPI (v0.8.6) only provides a wheel and no source code. Why should we trust it?

Adding backslash to keywords outside of math mode

This program adds a backslash to keywords such as min and max, however, this only works inside of math mode as \min is not valid outside of it. To fix this problem, it should be detected if the keyword is in math mode, and if it is, then do the same as it currently does, but if the keyword is not in math mode, then the characters to put the keyword into math mode should be inserted

Enter new license key for texworld

Hello,

I cannot use the blacktex today. I am asked to input the license key. Do you have any ideas what I should do? Thanks a lot for your help~!

Warning: Unable to find valid license in
- environment variable TEXWORLD_LICENSE_KEY (env var not found), or
- config file /home/l-----/.local/share/texworld/texworld.toml (file not found)
 
Enter enw license key for texworld:

connection with black formatter

Could you please let me know how does this implement the style as the python black formatter ❔

Just curious 😄

Replace in-place

I'm interestng to use blacktex across 200 TeX files.
Is it possible to have a replace in-place instead of using an explicit temp file like this way:

for i in *.tex; do (blacktex "$i" out.tex && mv out.tex "$i"; done

Thanks

Blacktex dangerously reformats commented-out code even with `--keep-comments` option

Consider the following commented-out latex snippet:

% Because   of $$a+b=c$$ ({\it Pythogoras}),
% % @johnny remember to insert name
% and $y=2^ng$ with $n=1,...,10$, we have ${\Gamma \over 2}=8.$

When we run blacktex on this file with the --keep-comments option, the text is modified to:

% Because of
\[
a+b = c
\]
(\textit{Pythogoras}),
% % @johnny remember to insert name
% and \(y = 2^n g\) with \(n = 1,\dots,10\), we have \(\frac{\Gamma}{2} = 8\).

Note that the equation a+b=c will get typeset in the PDF output, despite the user's intention to keep it commented out. This is dangerous, and such silent side effects can be impossible to detect in a large document.

Exit code

Playing around with blacktex, am I right in thinking that it returns an error code if anything was changed? It's definitely helpful to have a way of checking whether a document is valid, but it's also useful to be able to tell the difference between a successful pass of the formatter and a failed pass of the formatter without having to dig into the error code itself. Would you consider an exit code of 0 for formats which succeeded but changed things, but a --check flag which would raise an error code if anything needed changing?

Line Breaking

When I write latex, I find it enjoyable to have the tex file have line breaks at a certain horizontal limit:

How hard would it be to implement an option into the formatter which can enforce a line width?

I would be able to help implement this if you can direct me where to go.

blacktex produces error on spacing before $

Running blacktex on

$\alpha\,.$

gives the output

lib/python3.6/site-packages/blacktex/main.py", line 72, in _replace_dollar
    assert len(locations) % 2 == 0
               └ [1997, 2029, 2037, 2039, 2056, 2060, 2097, 2105, 2108, 2142, 2213, 2220, 2223, 2230, 2235, 2242, 2256, 2290, 2294, 2316, 2382, 2...
AssertionError: assert len(locations) % 2 == 0

replace $ ... $ with \( .... \)

It is better to use \( ... \) than $....$.
https://tex.stackexchange.com/questions/510/are-and-preferable-to-dollar-signs-for-math-mode
Maybe we can make it an optional rule?

Add a `conda` install option to `blacktex`

A conda install option as an alternative to pip installing from PyPI could be useful. I have already added blacktex to conda-forge (PR: conda-forge/staged-recipes#17224).

I will send a PR to add the following to the readme.

conda install -c conda-forge blacktex

spacing command \, switches opening and closing parentheses

The string $a$\,$b$ is converted into \)a\(\,\)b\( instead of\(a\)\,\(b\).

Removes spaces in \text environment

If someone uses spaces (trailing at the start or end) in \text{ ... } environment, they are removed. Is this the intended functionality (this actually changes the output of the latex file as it changes the spacing)

IndexError

Running blacktex 0.8.3 on Python 3.9.12, the following error is produced:

(base) PS C:\Users> blacktex -i -c '.\in.tex'
Traceback (most recent call last):
  File "C:\Users\user\Anaconda3\lib\runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Users\user\Anaconda3\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "C:\Users\user\Anaconda3\Scripts\blacktex.exe\__main__.py", line 7, in <module>
  File "<string>", line 23, in _traverse_tree
  File "<string>", line 90, in _replace_obsolete_text_mods
IndexError: list index out of range

Spaces sometimes inserted two characters after underscore in label

A small working example:

\documentclass{standalone}
\begin{document}
\section{One} \label{one_one}
\section{Two} \label{_two}
\section{Three} \label{three_t}
\subsection{Four} \label{__}
\end{document}

blacktex produces the following:

\documentclass{standalone}
\begin{document}
\section{One}\label{one_o ne}
\section{Two}\label{_t wo}
\section{Three}\label{three_t}
\subsection{Four}\label{__}
\end{document}

Notice that the first two labels are changed while the last two are not.

The output of blacktex -v is blacktex 0.2.1, Python 3.8.2.

Integration with texmaker or texstudio

Is there any way one could integrate it with Texstudio or texmaker?

log is changed to \log in text mode

The example file:

\documentclass[]{article}

\begin{document}

log

\end{document}

becomes

$ blacktex blacktex_log.tex 
\documentclass[]{article}

\begin{document}

\log

\end{document}

Obviously, it won't compile:
Missing $ inserted. \log

Comments should not be removed

Comments are a critical part of TeX code.

• Even a simple class or style file usually requires explanation of the various lengths, macros, and commands it defines.
• TikZ code gets very complicated and I heavily comment mine, including descriptions of arguments.
• The equation and align environments from amsmath don't allow empty lines. An empty line can be added for ease of reading by commenting the end of the line.
• Many TeX and LaTeX commands are sensitive to line breaks in and between arguments and the standard way to deal with this is by commenting the end of the line. I've included an excerpt from amsmath.sty as an example below.

\DeclareOption{alignedleftspaceyesifneg}{%
\def\alignedspace@left{%
  \edef\@tempa{\expandafter\@car\the\lastskip\@nil}%
  \if-\@tempa\null\,%
  \else
    \edef\@tempa{\expandafter\@car\the\lastkern\@nil}%
    \if-\@tempa\null\,%
    \else\null
    \fi
  \fi}%
}

missing braces inside braces

\rightline{\bf a} becomes \rightline\textbf{a} instead of \rightline{\textbf{a}}