[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] [PATCH] Expand portable escape section of groff_man(7).
From: |
G. Branden Robinson |
Subject: |
Re: [Groff] [PATCH] Expand portable escape section of groff_man(7). |
Date: |
Thu, 26 Oct 2017 02:48:11 -0400 |
User-agent: |
NeoMutt/20170113 (1.7.2) |
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