Re: [Groff] Mission statement

[Eric S. Raymond]

Ingo Schwarze <address@hidden>:
> > - Increased use of browsers
> 
> That's overstated.  It is not just use of browsers that makes
> semantic markup desirable, it's also useful in its own right, for
> example to support semantic searching.

Nobody would be happier than me if semantic search were more than a
wish and a maybe-someday and an occasional toy demonstration.  It
isn't yet - not close enough to real to belong in a plan like this.

> >   shifts the commonest use cases
> 
> I contest that.  The commonest use case for man pages is, and
> remains, man(1) -Tascii or -Tutf8 terminal output.
> 
> >   for man pages in a direction that rewards structural rather than
> >   presentational markup.  
> >   The future direction for the man macros

I think you are overinterpreting. The phrase "shifts in a direction"
does not mean that browser usage has already overtaken man(1).  There
is nothing here you need to contest.
 
> Here, as is well known by now, we strongly disagree.  That may be
> a future direction for manual markup (though even that is imprecise,
> in BSD, this has already been archieved nearly twenty-five years
> ago), but not with the man(7) macros.  There is no consensus whether
> or not the man(7) macros should have any future at all.

"Consensus" will have about as much affect on the future of man(7) 
as a gnat hitting a boulder. The corpus is just too freaking large 
for anything short of fully automated translation tools to kill it off,
and even with those it will take years yet.  And careful battlespace
preparation (which in fact I am doing).

> If i were to make it more specific, i would say something like:
> 
>  - improve the semantic usefulness of manpage markup by encouraging
>    and actively supporting the transition from man(7) to mdoc(7),
>    and carefully evolve and improve mdoc(7), while at the same
>    time continuing full support for the traditional man(7) macros,
>    completely unchanged, to support historic and autogenerated
>    documentation.

"Actively supporting" is empty verbiage unless you have a mechanical
translator from man(7) markup to semantically enriched mdoc(7). You
don't, and I know exactly why you don't, because I wrote the pattern
analyzer you would need and don't have.

> Probably, you wouldn't be happy with that variant.

No. Until you write said mechanical translator to mdoc(7) that variant
points to nowhere. From my experience, it will take you a minimum of
2.5 man-years of effort if you start now.  Do be sure to come back and
re-propose this change when you're done, eh?
 
> I don't buy your claim that mdoc(7) is complicated, i consider that
> a myth.  But i do claim that DocBook is bloated and complicated
> and hence a direction to be avoided.

You are free to believe and disbelieve anything you like, but here is
the most important ground truth: 93% of man(7) users can get to
semantic markup in DocBook automatically via doclifter (98.5% with
minor patching), while getting to semantic markup via mdoc(7) requires
a by-hand rewrite of each page.

That means that mdoc(7)'s prospects of being the universal manual
markup of the future are already *gone*.  Sunk.  Kaput.  It isn't
going to happen - the least-effort path out of presentationville
bypasses mdoc(7), and you don't have any compelling feature story to
make it worth going to more effort than running doclifter.

Yes, DocBook markup is bulky and ugly; this is not breaking news.  So
is mdoc(7) markup.  About equivalently, to anyone not in love with
either one. That's not the feature story you're looking for.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>