Re: [Groff] ESR in manpages versus the WEB

[Larry Kollar]

Gunnar Ritter wrote:

> > D.E. Evans asked about an improved grohtml, or even a replacement.
> > Perhaps grohtml can be improved.
>
> grohtml is broken by concept. It is thus impossible that
> it will ever reach a satisfying state.

This is a little off the subject, but I disagree. I'm already using
grohtml to generate useful HTML. True, you can't do it with bog-
standard macros, but using -mwww (which I know Heirloom
doesn't support) and some customization, helps a lot.

But even if you aren't interested in generating (or converting to)
HTML, whether markup is structured or presentational basically
depends on what you call it. :-) For example, emphasis and
citations might both be rendered as italic, but that doesn't mean
you *have* to use .I for both of them:

        .als CITE I
        .als EM I

If you're using grohtml to create HTML, you can still preserve
structural meaning with the "class" attribute. For example
(assuming -ms here):

        .de CITE
        .  ie '\\*[.T]'html' .HTML \\$3<i class=citation>\\$1</i>\\$2
        .  el .I "\\$1" "\\$2" "\\$3"
        ..

You can cut & paste for the EM tag, replacing "class=citation"
with "class=emphasis" and so forth. Run the HTML through
Tidy (which you can do in the pipeline) and the result is
surprisingly useful.


Getting back to the topic at hand, converting manpages to
some kind of structural markup, one *could* do similar things
with -man if people were so inclined. Probably the most
obvious idiom is the use of the .IR macro to mark a reference
to another manpage. It would be simple to define an alias:

        .als REF IR

If you wanted grohtml to do something useful with it, you
could define a macro in the same way as I've shown above:

        .\" usage: .REF name section#
        .de REF
        . ie '\\*[.T]'html' .URL "../man\\$2/\\$1.html" "\\$1" "(\\$2)"
        . el .IR "\\$1" (\\$2)
        ..

Either way, doclifter could recognize .REF as a cross-reference
and easily do the right thing with it.


At this point, we could draw a line in time at "now" and
separate manpages into two groups: existing and future.
I'm going to assume that converting the entire corpus
(i.e. both groups) to DocBook is a worthwhile effort, since
ESR obviously feels strongly enough about it to dedicate
a huge amount of effort to writing doclifter. So...

1) Existing manpages are overwhelmingly the majority,
and may continue to be the majority of manpages for... ever.
Converting them requires a pretty clever hack (doclifter)
because the existing vocabulary doesn't contain enough
structural information.

2) Future manpages *could* be written using structurally-
aware macros and converted using either doclifter (which
would have to do less work) or an XSLT script that works
with grohtml output (containing embedded class attributes
to make the structure more obvious). However, you can't
*force* people to use new macros, and Werner seems
reluctant to expand the vocabulary. But I'd be glad to
write a patch if we could agree on what should be added.


> But this can only work for manual pages that do not have
> too much raw troff code in them. Otherwise, the job of
> doclifter quickly becomes as impossible as that of grohtml.

I agree with this. It's always best to minimize or eliminate
raw *roff requests, and not just in manpages. Repeated use
of raw requests probably indicate the need for a macro.

--
Larry Kollar     k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: "UTP Revival"
http://unixtext.org/