groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Ingo Schwarze
Subject: Re: [Groff] [PATCH] Expand portable escape section of groff_man(7).
Date: Wed, 25 Oct 2017 14:06:24 +0200
User-agent: Mutt/1.8.0 (2017-02-23)

Hi Branden,

G. Branden Robinson wrote on Sun, Oct 15, 2017 at 12:33:06PM -0400:

>     Expand portable escape section of groff_man(7).

Most of this seems acceptable to me, with some exceptions, see
below.  I think you should put it in, taking my comments into account
or dismissing them at your discretion.

>     * 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.

> +.\" 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.

> +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.

> +and others may be known to your system.

I don't see how that adds value to the example, it is just
extra varbiage.

> +Without
> +.BR \e& ,
> +the above renders as:
> +.RS
> +.IP
> +The
> +.B
> +.gcolor
> +request supports several color names, e.g.
> +'green', by default,
> +and others may be known to your system.
> +.RE
> +.
> +.IP
> +Note the undesired inter-sentence spacing after \[lq]e.g.\[rq], among
> +more obvious defects.

I consider that completely useless verbiage, it should be deleted.
It is important to keep manual pages concise and not intersperse
them with low-utility talk.  For one thing, it is never useful to
show how something renders.  Users can easily try for themselves.
In this particular case, it isn't even useful to know how it renders,
and it is completely obvious what is wrong with an apostroph at the
beginning of an input line.  Besides, it was already explained above
what the purpose is, so this is useless duplication of information,
too.

>  .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.

> +.
>  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"?

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.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]