Re: [Groff] ESR in manpages versus the WEB

[Eric S. Raymond]

Larry Kollar <address@hidden>:
> 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

You're defining a new set of aliases and pseudo-structural macros in
order to convey the information raw troff doesn't carry.  Doesn't
this tend to prove the point you thought you were refuting?

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

Actually, man-page markup does contain 'enough' information, or would
with the addition of .EX/.EE.  If this weren't so, doclifter's job
would be impossible rather than merely difficult.
 
> 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).

Speaking as someone who has wrestled at length with the problem, a new
'structural' macro set would be far less useful (if only because less
likely to be widely adopted) than an extension or two and some
good-practice guidelines.

I've described the two extensions I think would be merited.  The sort
of good-practice guidelines I nean are things like "don't use troff
requests outside the safe set" and "don't put running-text notes in a
synopsis section" and "don't write multiple description lines".
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>