Bugfix/manual nits

[nbuwe]

This series of commits tries to address minor but annoying inconsistencies about the manual appearance. Hopefully its not too controversial. It mostly focuses on problems that have multiple instances. One problem I didn't have time to address is \(+- that has the very low minus part ram into the stem of the following italic letter, it needs a bit more thought.

[reffort]

Merged #106 into master.

Really?

I haven't made it through the entire list yet, but I find many of these changes to be unnecessary/redundant, or introduce potential reader communication issues because the changes are based on a flawed premise, or are just a different way of doing the same thing. Some of them do not actually fix the underlying document flaw, but do add more typing to implement the same flaw.

There is a lot in the document that needs some attention, and I'm glad someone is looking into it and offering suggestions. However, the document was written primarily by Ossanna, Kernighan, and Ritter, and (since it is still sometimes called "Heirloom" troff) I think their authoring is worth preserving unless there is an actual error or some other necessary change.

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Tuesday, April 6, 2021 7:07 AM, n-t-roff @.***> wrote:

Merged #106 into master.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[nbuwe]

Can you be more specific? The use of environments in 5fdeb11 is probably the most controversial if i have to second-guess... I am happy to revert those bits if that's what's right.

Other than that the changes just try to bring some consistency. The old code had e.g. both

\fB&bp\fI|\(+-N\fR  \fIN\(eq\fR1    \(en    B   Begin page.
...
\fB&pn\fI|\(+-N\fR  \fIN\fR\(eq1    ignored \(en    Page number.

right next to each other, one with = inside \fI and the other outside. I highly doubt there's any ancient wisdom behind that specific variation.

Or

The function \A'e_H'\fB\eH\fI\'\(+-N'\fR
...
The function \A'e_b'\fB\eb\'\fIstring\fB\|\'\fR may be used to pile

again, one with bold (literal) quotes, one with italic (variable).

The few instances that used \(aq were all late additions as far as I can tell and are converted to be consistent with \' used in the rest of the text.

Consistent "no-break" spelling of e293058 follows the version of the manual I grabbed off Bell Labs site ages ago. Unfortunately I only have the pdf handy, i can't find the sources locally, they should still be out there, probably.

The fe0c466 .tr fix was clearly an overlooked glitch.

So, as I said, I was mostly aiming for consistency. The current state may not be much better visually (though I humbly posit it is a bit better), but it now should be much easier to find them and change them in bulk.

PS: My troff is nowhere near fluent as my formatter of choice has always been Lout. Sorry if my inept but well-meant attempts caused any offense.

[n-t-roff]

@reffort I have reverted it. I have added you as contributor, you normally should have full access rights to the repo (push, merging pull requests, reverting them etc.), at least when you have confirmed to contribute request.

[reffort]

Some of the things I alluded to previously are:

• Numerous brute-forced italic corrections: Unless I missed some, these are all handled by .kernpair requests near the beginning of the document. There is no need to hard-code italic corrections for every instance in the document source, as is required by groff.

• Inline request delimiters: The delimiters are not literals--they are user-defined--and should not be treated as literals except in an example where it is appropriate to do so. The character used as the delimiter in the text is not the ASCII apostrophe/singlequote for that reason--it can be anything--although the singlequote is used in specific examples because it is the most common form. I made the usage consistent on the pages I touched and in many other places were it was obviously wrong, but there are undoubtedly still a lot of cases that need attention. Every instance in the inline request reference in the front of the document is correct, though, as best I recall.

• \(aq is the ASCII quote, \' is the acute accent--they are not arbitrarily interchangeable.

• Defined strings .ds TR: \fItroff:\fP, .ds NR, \fInroff,\fP, etc., that include trailing punctuation: The typographical treatment is wrong, but the definition works just fine in the document; changing the definition to use an inline environment doesn't really accomplish anything. So, if we are going take the trouble to change things, I suggest we obtain the right result. (Trailing punctuation that belongs to the surrounding text is not a part of the italicized text and should not be italicized, although that style was common for a long time.)

The correct typography can be accomplished:

1) By defining the string as .ds TR \fItroff\fP (without including the trailing punctuation) and then modifying the document source from \*[TR:] or \*[NR,] to \*[TR]: or \*[NR], or \*[TR]'s or whatever the punctuation is. Having a single string (minus the punctuation) reduces the number of variants to keep up with, but would require a change at every place it is used in the document. This is my preference, but that means making a lot of edits throughout the document, which carries along the likelihood of introducing new errors. So,...

2) To keep the existing document coding intact, the font change would need to be incorporated as part of the string, as in .ds TR; \fItroff\fP; (the punctuation occurs after the font reverts); or if using an inline environment, after the environment is closed: \@{\fItroff\@};. This version would be assumed correct most of the time, depending on usage.

I still haven't made it through the rest of the list.

but it now should be much easier to find them and change them in bulk.

Changing things in bulk is a really, really bad idea for the nroff/troff user manual.

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, April 7, 2021 2:44 PM, Valery Ushakov @.***> wrote:

Can you be more specific? The use of environments in 5fdeb11 is probably the most controversial if i have to second-guess... I am happy to revert those bits if that's what's right.

Other than that the changes just try to bring some consistency. The old code had e.g. both

\fB&bp\fI|(+-N\fR \fIN(eq\fR1 (en B Begin page. ... \fB&pn\fI|(+-N\fR \fIN\fR(eq1 ignored (en Page number.

right next to each other, one with = inside \fI and the other outside. I highly doubt there's any ancient wisdom behind that specific variation.

Or

The function \A'e_H'\fB\eH\fI\'(+-N'\fR ... The function \A'e_b'\fB\eb\'\fIstring\fB|\'\fR may be used to pile

again, one with bold (literal) quotes, one with italic (variable).

The few instances that used (aq were all late additions as far as I can tell and are converted to be consistent with \' used in the rest of the text.

Consistent "no-break" spelling of e293058 follows the version of the manual I grabbed off Bell Labs site ages ago. Unfortunately I only have the pdf handy, i can't find the sources locally, they should still be out there, probably.

The fe0c466 .tr fix was clearly an overlooked glitch.

So, as I said, I was mostly aiming for consistency. The current state may not be much better visually (though I humbly posit it is a bit better), but it now should be much easier to find them and change them in bulk.

PS: My troff is nowhere near fluent as my formatter of choice has always been Lout. Sorry if my inept but well-meant attempts caused any offense.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[nbuwe]

• \(aq is the ASCII quote, \' is the acute accent--they are not arbitrarily interchangeable.

Right. Have you actually looked at the change?

The manual has e.g. in the list of escapes:

\fB\eT\fI\'string\'\fR

and then elsewhere both \'

e.g.: \fB\eT\fI\'string\'text of link\fB\eT\fR.

and \(aq

generated by the \fB\eT\(aq\fIid\fB\(aq\fR request

So if you copy paste the \T ́ from the PDF to search for it in that same PDF, you won't find the latter occurrence.

[Alhadis]

Defined strings .ds TR: \fItroff:\fP, .ds NR, \fInroff,\fP, etc., that include trailing punctuation

Shouldn't trailing punctuation appear after \fP, so that only nroff and troff are italicised?

[reffort]

Shouldn't trailing punctuation appear after \fP, so that only nroff and troff are italicised?

That's why I included the explanation in that same paragraph: "(Trailing punctuation that belongs to the surrounding text is not a part of the italicized text and should not be italicized, although that style was common for a long time.)"

And continued with: "The correct typography can be accomplished:", where both items 1) and 2) do just that.

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, April 8, 2021 9:05 PM, John Gardner @.***> wrote:

Defined strings .ds TR: \fItroff:\fP, .ds NR, \fInroff,\fP, etc., that include trailing punctuation

Shouldn't trailing punctuation appear after \fP, so that only nroff and troff are italicised?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[reffort]

Have you actually looked at the change?

Can you mark up the document to show the changes in context? That would reduce the ambiguity of trying to associate a raw diff list of isolated roff code with its formatted output in a typeset document. For an example, please see the attached PDF and the external document 2 it references..

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, April 8, 2021 8:43 PM, Valery Ushakov @.***> wrote:

• (aq is the ASCII quote, \' is the acute accent--they are not arbitrarily interchangeable.

Right. Have you actually looked at the change?

The manual has e.g. in the list of escapes:

\fB\eT\fI\'string\'\fR

and then elsewhere both \'

e.g.: \fB\eT\fI\'string\'text of link\fB\eT\fR.

and (aq

generated by the \fB\eT(aq\fIid\fB(aq\fR request

So if you copy paste the \T ́ from the PDF to search for it in that same PDF, you won't find the latter occurrence.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[nbuwe]

For an example, please see the attached PDF and the external document 2 it references.

I don't see any attachments.