Re: [groff] 05/05: groff_man.5.man: Make editorial fixes.

[Ingo Schwarze]

Hi Dave,

Dave Kemper wrote on Sat, Jun 29, 2019 at 12:46:35PM -0500:
> On 6/29/19, Ingo Schwarze <address@hidden> wrote:

>> As far as i understand, it is true that "\&" has value to suppress
>> end-of-sentence recognition only at the end of an input line.

> "Value" is subjective, but it does function that way in the middle of
> an input line (best seen by making sentence spacing very large):
> 
> .ss 12 48
> Bogus Inc.  sells snake oil at very competitive prices.
> .br
> Bogus Inc.\&  sells snake oil at very competitive prices.
> 
> I wouldn't argue that the above construction is useful,

Quite obviously, it is not.  :-)

However, technically, it appears eos recognition is not just done
at the end of input lines, but also before double space characters
in the input stream.

I never noticed because in OpenBSD, we very strictly follow
the rule "new sentence, new line" and never allow double spaces
characters in roff(7) source code except in no-fill mode.

> but the man page should document the way groff works,

The groff(7) man page, yes.

But here we are talking about the groff_man(7) manual page,
and specifically the section explaining that most escape
sequences are not useful in manual pages, and listing the
few that can be employed safely for a specific purpose.

Trying to completely describe all theoretically possible uses
of \& would be counter-productive in this contect.  We should
really restrict *this* text to what we actually recommend
in manual pages.

> regardless of a particular construction's usefulness.

Well, if we can, we should still word instructions such that users
aren't mislead into writing useless macros and escapes but also
learn clean style from each manual page in the groff package, and
even more so for a page like groff_man(7) aiming at users who are
not necessarily interested in typesetting, but more likely just
want to get their documentation written.

I still consider "Bogus Inc.\& sells" poor style
and "Bogus Inc.\&  sells" even more so, so i think we should avoid
wording the manual in a way that might mislead users into thinking
something like that might make sense.

Yours,
  Ingo