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

[Gunnar Ritter]

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

> Note that .br/.nl, .ti, .ta, and .in are *not* in the portable set.
> These cannot be translated structurally by doclifter, and man-to-HTML
> translators tend to ignore them or give useless results as well.
> . . .
> I noted previously that \w is *not* portable.

I think you are right about the facts here, but I would
tend to give an adverse recommendation. Even when these
features are not translated, they can be very useful in
nroff visual markup as long as no structural information
hides behind them.

As I said in an earlier post, whether a request is safe
or not depends on the context in which is used. One can
safely use almost all requests if their context is pure
visual nroff markup which does not hurt when omitted.

> Fortunately. these can almost always be replaced by uses of .nf/.fi,
> .RS/.RE, and tbl markup (which doclifter handles).

Maybe you should simply handle pairing .in requests like
.RS/.RE?

> 1) Trim the groff manual pages so they use only the portable subset, plus
> the .SY and .OP macros that Werner and I have characterized.

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.

Since .de is in the list of portable request, there
is nothing to say against their use as local shorthand
notation in the groff manual pages, of course.

> 2) Any help in filling out the TODOs in the above draft would speed
> things up measurably.  Every hour I don't have to spend on research
> others could do will be spent on related things only I am presently
> qualified to work on, like doclifter internals.  Gunnar?  Anybody?

I can make no promises for the next weeks; I actually
should spend my time with other issues.

> 1)  Once we know what the portable set is, groff itself should issue
> warnings when a man page uses a non-portable feature.

I repeat, it should not do that since there are uses
of exotic requests which are completely harmless.

> 3) .SY/.OP/.EX/.EE/.DS/.DE will also be needed in Heirloom troff.  
> This one is pretty obviously Gunnar's baby.

I am willing to implement .EX/.EE/.DS/.DE but not .SY/.OP
for the reasons described before.

> In practice, this question comes down to whether we're going to bless
> Latin-1 as a portable character set and the groff glyphs mapping to
> Latin-1 as portable.  
>
> I favor setting a floor that includes Latin-1.

I am rather strongly against that. groff is one of the
few remaining programs that are stuck without UTF-8
support. Most Linux distributions I know have turned to
UTF-8 as the default encoding for German locales years
ago. Latin-1 is already a legacy encoding as far as use
on Unix terminals is concerned. We should thus not base
our manual page recommendations on it.

I think we should recommend not to use anything except
US-ASCII and traditional troff special characters (minus
those that are found to be non-translatable) in English
language manual pages. One does not really need Latin-1
for these anyway.

Non-English manual pages are a platform-dependent and
evolving issue and should not be described in the guide
for the time being.

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

> I think two years from when we ship 1.20 seems reasonable.  That would give
> groff-1.20, (hypothetical) KDE help-browser patches, and an update of
> heiroom troff time to propagate.

Ultimately, this does not depend on our wishes, but
on the actions of vendors and on the intentions of the
maintainers of the manual pages and the respective
software.

        Gunnar