Re: [Groff] Mission statement, second draft

[Peter Schaffter]

On Tue, Mar 18, 2014, Kristaps Dzonsons wrote:
> 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".

That puts us on the same page. :)

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

Agreed.

> The proposal to extend it would be a new macro package that
> shares some existing macros.

Or "an existing macro package with additional macros."

> But any non-trivial manpage would effectively need to be
> re-written to take advantage of these extensions.

As would converting man(7) formatted manpages to mdoc(7).

As I see it, there are three strata of manpages:

- legacy manpages  =>those without a maintainer
- current manpages =>those with an active maintainer
- future manpages  =>those yet to be written

Legacy:
  Unless someone undertakes rewriting legacy manpages, they stay
  man(7) formatted forever and need DocLifter to output xml-ized
  versions.  Think of DocLifter in this case as a kind of -Txml.
  (Eric was quite right when he accused us of "not being old-school
  enough.")

Current:
  If maintainers re-write current manpages, they use whatever
  solution we come up with for "good manpages".  If they don't
  re-write, we have a legacy condition.

Future:
  Future manpages use mdoc(7) or the revamped man(7).

If we subtract "current", we have a relatively straightforward
situation (though not one free of debate): use DocLifter to get
xml-ized versions of legacy manpages, and institute a policy shift
toward a better markup system, whatever form that may take.  In this
scenario, your arguments in favour of mdoc would probably carry the
day.

However we do have current to deal with, and it's the crux of the
debate.  Which of "fix man(7)" or "switch to mdoc" puts the least
burden of re-write on current manpages, and is therefore the most
likely to receive community-wide acceptance?

Let's imagine, for a moment, that man(7) is modified in such a
way that backward compatibility with existing documents is fully
supported, no presentational richness is lost, and extensions to the
macro set permit clearer semantic structuring.

With this imaginary man(7), authors who wished to make their
manpages conformant wouldn't have much re-writing to do at all.
Mostly it would involve replacing presentational clichés with
semantic tags; in cases where there's a compelling need for
presentational markup, groff would handle it as it always has.
Hold-outs on rewrites wouldn't present much of a problem since their
documents would render to -Tascii/-Tps/-Tpdf the same as always, and
given the percentages Eric's provided about DocLifter, xml from the
same documents would be >90% clean.

Contrast that with converting manpages using man(7) to mdoc(7).  I
foresee considerable resistance and a very long slog ahead.  While
groff and mdoc are one place where a fruitful alliance exists
between BSD and GNU, partisanship is factor that can't be ignored,
however much I personally wish it could.

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

Ah.  I didn't express myself clearly.  I consider it an *advantage*
to have a project for developers to work together on right now.  I
truly believe groff is at a turning point, and honing our ability to
function as a team is crucial.

> 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 mentioned that Eric's strategy involved social engineering, too.
My point was that he has a lot of experience with this.  He knows
the players and they know him.  A substantial percentage have been
responsive to his suggestions.  His success rate is good.  He can be
very persuasive. :) These are x-factorish qualities we need in the
quest for "good manpages."

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

Not following you here.  DocLifter takes man(7) and mdoc(7) as
input and spits out DocBook xml.  It wouldn't be emitting the "new
format"; that would be its input.  Or are you suggesting using
DocLifter as a man(7)=>mdoc(7) converter?  (I can see the blood
draining from Eric's face.)

> Most significantly, the proposed format just doesn't exist...
> you're stacking a known, stable product against an idea.

I'm aware.  Just to be clear, I'm still working on clarifying goals
for a mission statement, not committing to one course of action or
the other, at least not while the debate continues.

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

I do apologize if my terseness came across as trivializing
Ingo's considerable work, and the work done in this regard by the
other BSD developers.  Definitely not my intention.

Kristaps, can you or Ingo present the list with a concise plan for
mdoc(7) adoption, modelled after Eric's?  Something more concrete
than "...encouraging and actively supporting the transition from
man(7) to mdoc(7)".

Cheers.

-- 
Peter Schaffter
http://www.schaffter.ca