The section dealing with manpages had me hemming and hawing for
days. The original wording wasn't vague; it stated the matter
clearly--the intention to improve the semantic usefulness of
manpage markup. Details of strategy/implementation were omitted
because the issue is a minefield, and part of our mission will be
to navigate through it gracefully. Whether, as Eric proposes, we
tinker with man(7) so it plays nice with DocLifter, or, as Ingo
proposes, we advocate a migration to mdoc, the goal remains the
same: semantically clearer manpage markup for easier conversion to
xml. (Ingo spotted the reason for my general wording right off that
bat, as did a few others.)
Nevertheless, I've rewritten that section of the mission statement
outlining Eric's strategy for dealing with the manpage-markup=>xml
challenge. I don't expect it to be final, but here are my reasons.
(I'm non-partisan, merely trying to clear things up for a mission
statement.)
Hi Peter,
In the spirit of debate, I thought I'd dwell a bit more on the mdoc(7)
question. I think it's worth it!
My agenda is just to have good manpages. To me, good means portable
across systems and media, adhering to a common style, and having
human-readable source. Good on GNU systems, BSD, HTML, PS... "good".
We agree that man(7) doesn't cover that, I think. There's no standard
way of formatting non-trivial pages, resulting in a mix of roff(7) and
man(7) to compensate. The results are messy. What's worse is that the
community doesn't have a reliable, standard way of documenting works.
Everybody suffers. In other words, man(7) is *already* dead from the
perspective of good manpages. The proposal to extend it would be a new
macro package that shares some existing macros. But any non-trivial
manpage would effectively need to be re-written to take advantage of
these extensions.
Here are a few salient points in favour of mdoc(7), instead:
- mdoc(7) is the language for thousands upon thousands of manpages.
On my OpenBSD machine alone, the base system consists of >5000
semantically-searchable, HTML-renderable mdoc(7) manuals.
- mdoc(7) has been around for over twenty years, with continuous
attention to macros, behaviour, rendering, and so on. Twenty years of
real-world usage.
- It has considerable semantic power. Function names, variables,
standards compliance, and so on. I can search for variable types in all
manpages, or manpages adhering to a given standard. (What I'd give for
mdoc(7) versions of LAPACK's manuals...)
- It has mature tools for rendering and analysis, from the reference
implementation in groff(1) to full semantic search in mandocdb(8). (I
can't speak for other troffs... did Heirloom put out an mdoc package?)
- It has a thriving community of authors. Developers and users on
OpenBSD and NetBSD's misc@ lists use the languages on a daily basis.
Yes, mdoc(7) has cons. The macros themselves can be confusing. This
boils down to documentation: we've done a sucky job of documenting the
language itself. I've put a bit of effort into solving this with
http://manpages.bsd.lv, but there needs to be more to make it easy for
new manpage writers to get down to business.
And if some macros are hopeless, well that too, is a problem that can be
solved. First by careful documentation, then slowly, if absolutely
necessary, by way of deprecation. mdoc(7) isn't set in stone: its tools
are actively maintained and can be updated.
Peter, you'd mentioned that a new man(7) would give specific tasks to
developers. But you don't mention that mdoc(7) would require developers
to do nothing at all! The tools already exist and are mature. There's
no need for more work, unless to fit the underlying roff(7) in
groff(1)'s macro definition file to be more www-friendly. That would
need to happen anyway with a new man(7).
You also mention that Ingo's strategy, versus Eric's, involves social
engineering. How would this not apply to a new man(7)? Either way,
manpage authors will need to be educated, or re-educated, for the new
format.
I hear bits and pieces about how doclifter could help. Why can't
doclifter be taught to emit mdoc(7) instead of DocBook or this new
format? Wouldn't this solve everybody's problem? And if it can't, why
should those failings be relevant to a choice of manpage language?
Most significantly, the proposed format just doesn't exist. And there's
a lot of speculation on what it could be or wants to be with little tos
how for it. ("Semantics" has been thrown around a lot, but has been
left undefined.) Why not focus on mdoc(7), then consider a new man(7)
when it has had a few years in the field? A little competition is a
good thing, but at this point, you're stacking a known, stable product
against an idea. Especially since this idea could end up having the
same cons as mdoc(7)--maybe more. We just don't know.
1. No matter how successfully mdoc/mandoc have replaced man/groff
in BSDs, groff remains a GNU project. Ingo's strategy comes
awfully close to touching on GNU policy itself, which doesn't
belong in a groff mission statement.
2. Ingo's strategy entails social engineering ("...actively
supporting the transition from man(7) to mdoc(7)"). So does
Eric's, however Eric has already done a lot of work on that
front with respect to man(7), getting package maintainers and
developers to clean up their markup.
This doesn't seem fair... Ingo, as with all OpenBSD developers, has put
a tremendous amount of effort in making sure the downstream and upstream
developers put out conformant, quality manpages. More significantly,
he's taken over mandoc(1)--needing to deal with my spaghetti alone
deserves an award! :) He's actively contributed mdoc(7) work back into
groff(1) and continues, daily, to push the field of quality presentation
and documentation.
Best,
Kristaps
