groff
[Top][All Lists]
Advanced

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

Re: [Groff] Mission statement, second draft


From: Kristaps Dzonsons
Subject: Re: [Groff] Mission statement, second draft
Date: Tue, 18 Mar 2014 15:01:13 +0100
User-agent: Mozilla/5.0 (X11; OpenBSD i386; rv:17.0) Gecko/20130722 Thunderbird/17.0.7

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



reply via email to

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