Don't panic:
- The warning applies only when running black from the command line.
- The warning apples only when running black on files created by @file.
- Leo's blacken-* command are completely safe. As noted previously, they
can fail in rare cases, but failures are clearly reported and leave
outlines unchanged.
There is, *in principle*, no way for *Leo *to avoid the danger...
*Blackening external files with Leo sentinels is inherently dangerous*
The reason is shocking. After many hours of investigation, I finally
realized that Leo's read code *already* recognizes *blackened sentinels*,
sentinels with a blank between the opening comment delimiter and the '@'
sign that starts all sentinels. No change is necessary (or possible!) to
Leo's read code.
The problem lies entirely outside of Leo's read code. After blackening,
*formerly
innocent comments* can become sentinel lines. There is no way, *in
principle*, for the read code to know that these *apparent* sentinels
should be ignored. Honoring these *newly active sentinels* can destroy an
@file tree.
The problem is really a case of *missing @verbatim sentinels*. For example,
leoTangle.py contains the following comment:
# if you're not going to use { } for pascal comments, use
# @comment (* *)
# to specify the alternative
Yikes! After blackening outside Leo, the second comment becomes a real
@comment sentinel. It passes the corresponding regex used by the read code!
So we're stuck:
- Leo creates @verbatim sentinels only for python comments that start with
"#@".
- To avoid missing @verbatim sentinels, Leo would have to create @verbatim
sentinels for *newly dangerous comments*. These are comments that:
a) are preceded only by whitespace,
b) start with "# @", (notice the blank)
c) actually look like a valid Leo sentinel comment.
Alas, generating @verbatim sentinels for newly-dangerous comments would
change the format of Leo's file format.
I know from experience that this kind of change can have subtle, rare (and
therefore all the more dangerous) unintended consequences. Old versions of
Leo might not handle these new @verbatim sentinels properly. The potential
for misery is real. There is *no way* I shall allow Leo to create more
@verbatim sentinels!
*Workarounds*
There are several workarounds, none of them perfect.
1. Poor: A script might warn about newly dangerous comments. You would have
to remember to run the script before blackening external files, and then
you would have to change the comments.
2. Fair: Convert @file trees to @clean before blackening, and convert them
back to @file afterwards.
3. Good: Use Leo's tangle-tree and tangle-node commands. They usually work
just fine.
4. Possible: Modify black so it doesn't insert a blank between # and @.
Last night I discovered how! In def make_comment, change:
if content and content[0] not in " !:#'%":
content = " " + content
to:
if content and content[0] not in " @!:#'%": # EKR: This string should be an
option.
content = " " + content
Imo, this is an urgently needed option. We'll see what the black devs say.
*Summary*
Leo's read code in fast_at.scan_lines *already* recognizes blackened
sentinels. That's very bad news.
Blacking an external file can turn *formerly innocent comments* into *newly
dangerous sentinels*. scan_lines can not, in principle, tell which sentinel
lines should be ignored. The needed @verbatim sentinels that do not exist.
I shall reject any proposal to write new @verbatim sentinels. The worst
quality disasters in Leo's history have arisen from similar "small" changes.
There are several workarounds. Using Leo's blacken-tree command will
usually be the best.
I'll ask the black devs to create an option that would allow Leonistas to
use black safely.
Edward
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/leo-editor/7a2d6f0b-077d-4e4c-aea1-62a62819164a%40googlegroups.com.
