groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Back to the future


From: Ingo Schwarze
Subject: Re: [Groff] Back to the future
Date: Thu, 6 Mar 2014 15:07:08 +0100
User-agent: Mutt/1.5.21 (2010-09-15)

Hi Eric,

Eric S. Raymond wrote on Tue, Mar 04, 2014 at 12:57:20AM -0500:

> 4. Identify 'semantic' macro packages,

I fully agree with that.

> including man markup

Sorry, but you are completely wrong here.

The classical man(7) language is a purely presentational language
and contains exactly three semantic macros as exceptions: TH, SH, SS.
So basically, nothing except titles is semantic in there.

For proof, here is the complete list of macros, according to both
the man(7) and the groff_man(7) manuals:

 * vertical spacing control: LP P PD PP
 * horizontal spacing control: RE RS
 * list formatting: HP IP TP
 * font control: B BI BR I IB IR R RB RI SB SM

That's it.  Period.

For most formatting needs, even well-written man(7) documents
rely on low-level roff requests and escape sequences, because
the man(7) language is far from complete even as presentational
language.

> and possibly mom.

Certainly.  And mdoc(7), of course.  Even if it may have weaknesses,
it is certainly a semantic language.  Well-written mdoc(7) documents
do not contain *any* low-level groff requests.

> Work towards systematically isolating those macro sets from groff-specific 
> back end details, with the general direction of making them more semantic
> and enabling simpler non-groff rendering engines for terminal and web use.

Sure.

> 5. Improve the semantic expressiveness of man markup.

Hell, **NO**!

I'm aware that you have started doing that with man-ext.  But if
you think it through, you have to abolish *all* existing man(7)
macros except TH SH SS and invent everything else from scratch.
That will not be man(7) any longer, not in any sense.  Heirloom
roff or Plan 9 roff will be completely helpless with such documents,
unless you tell authors to copy the complete implementation of the
language into each document they write, which is indeed what you
do now.  It would be more honest to choose a new name if you want
to invent a new language.

Now, which requests *did* you invent so far:

 * semantical:
    - semantic display: EE EX SY YS
    - command line elements: OP
    - hyperlinks: ME MT UE UR
 * presentational:
    - list formatting: TQ

So, are you saying that the following list of elements is what
needs semantic markup in a manual page?  Or even what could
get us started?

 - title, section, date
 - subtitles
 - synopsis and examples
 - optional command line elements
 - hyperlinks

While all elements in this list are relevant, their choice is
completely arbitrary and so incomplete that it cannot really be
taken seriously, not even as a starting point for a design.

The man(7) language as we know it today was a great thing for one
decade, from 1979 to 1989.  But it has become obsolete since then,
and we should merely support it for backward compatibilty by now.

> I'm willing to work on these things, not just talk about them.
> To be more concrete, I'm willing to own the cluster of design
> and implementation problems around man macros.  

Absolutely nothing to do there, please move on.

I think we have come to a point where we can *very* carefully start
improving modc(7), even at the price of slight backward compatibility
sacrifices, as long as we move groff_mdoc(7) and mandoc(1) in
lock-step: Heirloom and Plan 9 do not support it, anyway, so
we control all relevant implementations and are not going to break
anything.

But regarding man(7) - just forget it.  Don't touch that, ever
again.  Its only remaining function is supporting legacy
*presentationally formatted* manuals, and processing output
from autogenerators like pod2man(1).  Both can only take hurt
from messing with it.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]