Re: [Groff] Status of the portability work, and plans for the future

[Gunnar Ritter]

"Eric S. Raymond" <address@hidden> wrote:

> But now you say "One can safely use almost all requests if their context
> is pure visual nroff markup which does not hurt when omitted."  You
> reverse the thrust of your earlier argument, and you do it in a way
> that makes no sense to me!  

It is actually quite simple. For example, when a synopsis
is at risk of spanning multiple output lines, I write code
like

.SH SYNOPSIS
.HP
.ad l
.nh
\fBcommand\fR . . . options . . .
.br
.hy 1
.ad b

This results in nice formatting with nroff. However, there
is no structural information within the additional requests.
A viewer can omit them, resulting in less beautiful output,
or it can use the actual text and format the synopsis
according to its own principles, which is I suppose what
a DocBook conversion process would ultimately do.

Actually, the proposed code for .SY does something very
similar, so it is not even foreign to our discussion.

> Because, in general, we *cannot know* in advance what markup will "not hurt
> when omitted".

No, but the manual page author can. The most basic rule
is not to hide any actual text behind a non-safe macro
or request call. For example, setting up a .tr mapping
would violate that principle. Another rule is to only
add visual markup to structural markup, not to use it
standalone. For example, it is perfectly acceptable to
use a .sp to further separate a following .PP from the
preceding text.

> So what criterion for "portable" are you actually groping for here?

I consider a manual page portable when it can be
formatted in all viewers without flaws. But this does
not forbid further careful optimization for a certain
viewer (i.e. nroff) as long as it does not cause the
output of other viewers to get worse.

> > I can only repeat: Do not codify .SY and .OP in their
> > current form. They are completely insufficient even for
> > pure POSIX synopsis markup, so they can only lead to a
> > weird mix of structural and visual information within
> > the synopsis section.
>
> I think your complaint is justified with regard to .OP but not with
> regard to .SY.  It can be read as a purely structural "command synopsis
> begins here" tag,

The proposed definition did contain visual markup. If it
remained the only synopsis macro, manual page authors would
certainly add matching visual markup to the other parts of
their synopsis lines. The effect would be the same: a mix
of structural and visual markup. This will happen with any
incomplete synopsis macro set.

> > > 2) When, in the portable-subset description, can we say that .EX/.EE,
> > > .SY/.OP, and .DS/.DE should be considered portable and no longer 
> > > need local definitions?
> > 
> > When they are implemented in AIX, HP-UX, Solaris, and
> > all other systems about which software maintainers care.
> > We should not "consider" something portable when know
> > that it actually is not.
>
> But here I think you are setting too high a hurdle.  I will be very surprised 
> if AIX or HP-UX are relevant to *anything* other than a handful of aging
> legacy systems in two years' time.

We will see; this is certainly possible. But as I said,
we are not the ones who make the decision here. We can
only observe what happens and write our recommendations
accordingly.

        Gunnar