Re: [Groff] [PATCH] Expand portable escape section of groff_man(7).

[G. Branden Robinson]

At 2017-10-25T14:06:24+0200, Ingo Schwarze wrote:
> Hi Branden,

Hi Ingo!  Thanks for your feedback.

> >     * Document \~ escape, with example.
> 
> I would prefer to not add that one.  The purpose of the list is to
> document escape sequences that are both *required*, in the sense
> that manual pages cannot be properly written without them, and are
> also *safe* regarding portability.  As far as i know, \~ is a GNU
> extension, and even though mandoc(1) does support it, i'm not
> convinced that it is portable.  Are you sure that it is?  In any
> case, it is not required.

No, you're right.  I hand-made a list of things I wanted to add, checked
them against groff_diff(7), and apparently failed to note that this one
appeared there.  It's out.

> > +.\" TODO: Find a use case for this.  Please let it not be ersatz table
> > +.\" layout in fixed-width character cells.
> 
> To answer that question: The point of using "\ " is that is is
> portable.  I don't think an example is needed.  It is obvious
> what a non-breaking space can be used for.  Besides, it is rarely
> needed, and you shouldn't waste readers' time on things that are
> rare and relatively unimportant.

Well, I think it _has_ a use case if we don't have \~ as an alternative
because we're describing a portability diet to the reader.

> > +There are 2.54\e\[ti]cm in an inch, 1,024\e\[ti]bytes in 1\e\[ti]kiB.
> 
> I clearly advise against that.  It may render as "2.54cm" on some
> formatters and as "2.54 cm" on others.  Either way, it is very
> unimportant for manual pages and giving an example is clearly
> excessive.  At best, this belongs into an advanced typesetting
> discussion, but not into instructions for writing manual pages.

There may be other cases where a writer wants a non-breaking space.

> > +and others may be known to your system.
> 
> I don't see how that adds value to the example, it is just
> extra varbiage.

The idea was that "green" isn't the only color one can specify, but in
any case I agree with you.  The whole .gcolor example can go, and I
realize it probably grates because that example itself is of a
non-portable request.  :)  What do you think?

> >  .B \ec
> > +(Mnemonic: \[lq]continue\[rq] next input line on output.)
> 
> That mnemonic is not helpful, but rather confusing.  Nothing is
> continued here, and in particular not the next input line.
> Maybe you want to say that the current logical input line is
> continued on the next physical input line, but that would be
> an outright lie - that's what \<newline> does, not \c.
> 
> What this does is suppress spacing, not continue anything -
> but that's already properly explained in the following text.

Well, thinking about it this way helped me get _my_ head around it, but
I may be an unusual case.  ;-)

> >  If this escape sequence occurs at the end of an input line, no
> > -white space is inserted between the last glyph resulting from this
> > -and the first glyph resulting from the next input line.
> > +white space or is inserted between the last glyph resulting from this
> > +and the first glyph resulting from the next input line, as would
> > +normally be done.
> 
> The change in the first line makes no sense: "white space or is"?

This was just a plain old error, noted earlier in the thread.  

> The last five words are redundant.  It goes without saying that
> spacing is inserted between input lines, and even if somebody
> wouldn't know that, it becomes even more obvious once we say that
> it is suppressed - why would we say that if there was be no spacing
> in the first place?  Also, the wording sounds awkward.

Okay.  I will get rid of 'em.

Thanks again!

-- 
Regards,
Branden

signature.asc
Description: PGP signature