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

[Werner LEMBERG]

> Werner Lemberg wanted to know the status of \~.  I found 17 uses
> within the groff documentation and 4 outside it.  Of those 4, two
> were errors.  So it's not much needed for manual pages, which is a
> good thing as it is not portable.  In particular, I was unable to
> discover any corresponding ISO entity or Unicode character.

Both `\<SP>' and `\~' (and \0) are equivalent to &nbsp;

In many cases the use of `\<SP>' meaning exactly `one space' is
incorrect -- what is `one space' in a variable-width font?  Here the
meaning is reduced to `insert normal whitespace and don't break the
line here', nothing else.

> I think we can declare Latin-1 and the intersection of groff glyphs
> with HTML entities portable as well, [...]

I think this is something beyond us.  Restricting man pages to latin-1
encoding is bad.  Instead, I suggest the route which is outlined in
preconv.man (part of the CVS).

  1. If the input encoding has been explicitly specified, use it.

  2. Otherwise, check whether the input starts with a Byte Order Mark.
     If found, use it.

  3. Finally, check whether there is a known coding tag in either the
     first or second input line.  If found, use it.

  4. If everything fails, use a default encoding as given by the
     current locale, or `latin1' if the locale is set to `C', `POSIX',
     or empty.

Instead of using the groff's `uXXXX' glyphs, doclifter would directly
map to HTML entities.

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

While I fully support .SY and .OP I wonder whether we need another
macro to better separate content from formatting issues.  Gunnar, any
suggestions here?

> Yes, I know, Bernd Warken is in love with the hyperextended macros
> on groffer.1 and elsewhere, and will go ballistic.  Too bad for him;
> we've established that they break too much software to live.

Well, I won't change groffer.man -- this is his contribution.  It
seems that grohtml does a quite decent job for this man page: What
about putting it into an exception list (even if it is the only
member) so that it is converted with `groff -Thtml' instead of
doclifter?

> 1) Once we know what the portable set is, groff itself should issue
> warnings when a man page uses a non-portable feature.  This should
> be taken on by somebody who understands groff internals better than
> I do.

Hmm.  To do that within troff macros, you actually need the CVS
version of groff bundle.  For example, older versions can't reliably
replace

  'foo

with a macro because you don't know whether it has been called with
. or with ' -- the CVS offers \n[.br] for that purpose.  I rather
favour a simple external script for checking.

BTW, some man pages documenting groff itself will never be conformant.
It would be completely ridiculous to modify, say, groff_char.man so
that groff specific extensions would be avoided.  We need an Orwellian
approach here: All man pages are equal, but some are more equal than
others. :-)

> 2) Patches for .SY/.OP/.EX/.EE/.DS/.DE support should be developed
> for the KDE help browser and shipped as soon as possible.

What I consider even more important is that all man pagers (which
don't use groff internally) emit a warning if they can't display the
man page correctly.  Ideally, they should use groff for formatting
(opening a TTY window showing `man' output would be sufficient IMHO)
if the number of problems exceeds a certain threshold.

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

I really don't know.  Just remember that Debian (and thus probably
Ubuntu as well) still uses the groff 1.18 series, for example.


    Werner