mac_do.4: Update separator between <from> and <to> parts of a rule

[olce]

Summary

That new separator is '>'. ':' is still accepted for backwards
compatibility in -CURRENT but only for a transition period, so we
willingly remove all references to it.

[ziaee]

share/man/man4/mac_do.4

79

Quotes don't do what people think they do in Roff, so I think having them just confuses people.

[bapt]

with @ziaee changes incorporated

[olce]

share/man/man4/mac_do.4

79

What do you mean exactly?

I expressly want literal characters between single quotes (or possibly other signs) throughout the manual page, especially for formal rule lines, to make them stand out as being verbatim text.

What would be the proper way to do that?

[ziaee]

Would you be willing to squash this commit with the feature commit when you merge?

share/man/man4/mac_do.4

79

Ql means "Quoted literal", so it does enclose the rest of the line in single quotes.

The " characters there actually produce no change in the rendered output, thus I think their inclusion promotes misconception for future people who look at whatever manual they've been recently using which they think is well formatted to study how they did it.

People sometimes use quotes to try and escape characters, but you should prefix the character with \& if the linter (mandoc -Tlint) complains.

[olce]

In D49627#1131504, @ziaee wrote:

Would you be willing to squash this commit with the feature commit when you merge?

Sure.

share/man/man4/mac_do.4

78–80

Found by another proofreading, and fixed in my local commit as well.

79

Yes, sorry for the confusion in the above comment where I forgot about Ql and briefly wrongly thought that " was outputting the single quotes.

" is just a roff escape indeed. It *was* necessary before the change here because : is considered a closing delimiter and thus is treated specially, which would be wrong here (the : would appear outside of the quotes). With >, I agree quoting isn't necessary, but I don't think it's wrong to overquote precisely because that avoids worrying about whether a character is considered as an opening or closing delimiter with special treatment.

I'd rather have people learn about what " is about, which is easier to remember than a list of special characters, but I certainly understand your point of view as well (and my mistake above kind of supports it).

I've removed the double-quotes around > in my local commit.

[ziaee]

With quotes removed from the Ql and squash with the commit that that changes the behavior, LGTM from manpages.

Overquoting to escape the character will render correctly, but it won't pass the linter, because the correct escape sequence in Roff is \&. Perhaps we should use stronger language in mandoc_char(7)? Generally I prefer that we don't because if the manual seems unweildly people won't read it.

[olce]

In D49627#1131552, @ziaee wrote:

Overquoting to escape the character will render correctly, but it won't pass the linter, because the correct escape sequence in Roff is \&. Perhaps we should use stronger language in mandoc_char(7)? Generally I prefer that we don't because if the manual seems unweildly people won't read it.

I do not see any quote error reported by mandoc -Tlint even with the quotes around >. Which error do you get?

[ziaee]

Sorry for the confusion, it errors when used to escape a character considered a closing delimiter.