manuals: Fix escaping for (some) backslashes

[gperciva]

No description provided.

[gperciva]

@mhorne

I'm in the odd situation of submitting a PR which I hope we don't accept.

The rendered output (in ascii and html) is not affected by this commit.

According to mandoc_char(7), we should use '\e' rather than '\'.
@concussious recently reminded me: #1523 (comment)

In particular, mandoc_char(7) says:

Backslashes

To include a literal backslash (‘\’) into the output, use the (‘\e’)
escape sequence.

Note that doubling it (‘\’) is not the right way to output a backslash.
Because mandoc(1) does not implement full roff(7) functionality, it may
work with mandoc(1), but it may have weird effects on complete roff(7)
implementations.

Based on that, I find it hard to argue that we shouldn't make this change.

On the other hand, it makes the document source harder to read, and thus harder to maintain.

shrug

If we want these changes, I have the script ready. There's around 100 files; this PR fixes 30 of them. Happy to split up the changes as requested (all 100 at once? batches of 20, or 30, or 50?)

OTOH, if you decide that mandoc_char's concerns are not worth the extra maintenance burden, I'm happy to drop the matter.

[gperciva]

FWIW, main currently has 528 instances of \\, and 827 instances of \e.

[gperciva]

Just to elaborate on the "maintainability" thing... anybody looking at the source code for echo.1 will recognize the previous text. "Ok, it says \\tworld, which is clearly a \t tab, but with the backslashes escaped."

Whereas the "correct" source is \etworld. Which to my eyes, looks like "some kind of special \e command, followed by tworld. What on earth does tworld mean? That must be a typo, surely!"

[emaste]

FWIW, main currently has 528 instances of \\, and 827 instances of \e.

Even if \e is less clear the fact that it is both correct and more common is an argument for making this change.

I suspect "complete roff(7) implementations" that we care about actually handle \\ just fine though; if that can be confirmed (and documented) we could update mandoc_char with that information.

[emaste]

We can't update mandoc_char because OpenBSD has a full time manuals maintainer

That doesn't follow -- we can make changes to mandoc_char in FreeBSD, if we are so inclined. There may be several reasons such a change is a bad idea, but there's no hard requirement that Ingo approves of it.

[bsdimp]

I think \ is clearer than \e. It's a sane extension. It's limited. It's not full roff(7). It doesn't have to be either or. It can be just one thing. I think this change isn't such a great idea since \ works.

[emaste]

Interesting discovery: apparently \e is not a backslash per se, but is an escape that represents the current escape. Apparently \(rs or \[rs] is the escape sequence specifically for a backslash.

[concussious]

When I get home, I'm happy to check it in groff and heirloom-doctools. What other roff compilers are there?

[gperciva]

Bad news for \\ fans (including myself): it only works within certain portions of mdoc files.

I tested replacing \e with \\ everywhere, and was unpleasantly surprised to find many differences in the rendered output. For example, consider lines 333-334 of bin/date/date.1:

A newline
.Pq Ql \en

That currently renders as

A newline (‘\n’)

However, if we change \e to \\, then we get:

A newline (‘’)

If we remove the .Pq and .Ql and use \\, then the rendered output is as expected:

A newline \n

Out of curiosity, I tried adding more \\ in case it needed something like \\\\n. No dice with any number of backslashes from 1 to 12.

... I suppose we could allow \\ where it works (which probably means "not inside any enclosures"), and require \e where it's necessary. But I suspect that would increase the maintainability burden more than requiring \e everywhere.