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

[Eric S. Raymond]

Gunnar Ritter <address@hidden>:
> > 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.

I see.  OK, on that basis I might be prepared to grant that
.hy/.nh/.ad are safe, though the thought makes me uneasy.

But definitely not .br; there are contexts in which failure to render .br 
would matter a lot, by (for example) running .br-separated lines together
in an HTML viewer.  The .ti and .in requests are out for similar reasons,
though like .br they're safely ignored in the specific context of a
command synopsis.

What requests would you say are "visually safe" in the way you are defining 
that are not on the portable list?  (It is presently .de .ds .fi .ft .ie .if
.ig .nf .nr .rm .rn .so .sp).  You make a case for .hy/.nh/.ad; what others
would you add?

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

Yes, you're right about that.
 
> > 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.

I see what you are driving at, but there is a practical problem with
this style of rule; it's too complicated.  It probably can't be
mechanically checked, and it's going to make people who aren't troff
experts crazy trying to apply it, and they'll get it wrong, and before
too long they will give up trying.

To be viable, the portability rules need to be dead simple --
specifying a list of portable requests with the absolute minimum of
codicils of the form "can be used here but not there".

My opinion is that a certain amount of loss of fine control over
vusual output is an acceptable tradeoff for getting a set of rules
that non-experts can apply and will be willing to apply -- especially
since I think the future belongs to browsers, where you can't get
precise visual control anyway without heroic measures that are a
bad idea for other reasons.

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

This is fundamentally reasonable, I think.  A difficult criterion to
actually apply, though -- you're begging for a lot of acrimonious
arguments about edge cases.  I'd prefer to avoid that, even if the
cost is that the portable set is somewhat less expressive.

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

That is true.  However, because man-page markup is doomed to be such a
mix of visual-structural markup anyway, I have to consider an
addition like .SY with the effect of decreasing the number of troff
cliches uttered to be a net win, even if it's not theoretically
complete.

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

What sort of trigger point would you fin acceptble?  When proprietary-Unix
market share falls below 10%?  5%?  1%?
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>