Re: [Groff] Mission statement, second draft

[Ingo Schwarze]

Hi Peter,

Peter Schaffter wrote on Tue, Mar 18, 2014 at 09:23:19PM -0400:
> On Tue, Mar 18, 2014, Kristaps Dzonsons wrote:

>> 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.
[...]
> 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)".

To do that, i first have to try and rehash Eric's plan,
hoping this will be an adequate summary:

 (1) narrowing and simplifying the man markup language, decoupling it
     from groff peculiarities (without going into much detail yet
     which idioms exactly to discourage, and what in partiular to
     replace them with - probably idioms from (2) in most cases)

 (2) maybe introduce a small number of additional semantic macros
     to man(7), or maybe (likely?) what's in man_ext now may be
     enough extension already (without going into much detail yet
     what might or might not still be missing)

 (3) scan existing packages for usage conflicting with (1),
     contacting maintainers and politely explaining to them
     what is problematic about it, what the downsides for their
     users are, and how they can improve user experience by
     modernizing documentation markup, sometimes even providing
     patches (note that (3) lies outside the scope of groff
     development)

My "plan" (grand word, not quite fitting...) is really largely
parallel, except that:

 (1) doesn't really require any substantial work because real-world 
     mdoc(7) manuals, even sloppily written ones, typically do not
     contain any substantial amount of low-lewel roff markup, and
     even if they do, it's almost always trivial to replace with
     standard macros; what remains is largely a documentation task,
     saying which features are discouraged for use (e.g. predefined
     strings, .Bf, .Bt, .Fr, .Hf, .Ot, .Tn, .Ud to name some
     examples, but most such stuff is already used rarely now).

 (2) is more like an ongoing maintenance task for mdoc(7).
     As far as changing the language specification is concerned,
     it's mostly a documentation task, for example, more
     rigourously defining the difference between .Cm and .Ic.
     There may be some code or syntax polishing needed here or
     there, but nothing complex enough to warrant drafting a plan.

 (3) "encouraging and actively supporting" mostly implies
     providing documentation, answering questions, and working
     on bug reports.  Providing tools may also help, but part
     of that work is already done.  For example, the mandoc -Tman
     mode is available such that projects having mdoc(7)
     documentation can run it in their "make dist" target to
     autogenerate man(7) versions for legacy operating systems
     not having mdoc(7) support (like Solaris clones).
     Contacting projects is optional and in any case outside
     the scope of groff development.  I don't see a need for
     a crusade to bully everybody into using mdoc(7), least
     of all projects that don't care.  There is no big cost
     associated with some legacy man(7) documentation remaining
     around, both groff and mandoc deal with it all right.

Basically, each of these three points requires less work within
the groff project than the respective point in Eric's plan,
which may also explain why it could seem a bit fuzzy on first,
superficial sight:  If a tool is already mature and widely
deployed, it *is* harder to say what needs to be done about it,
except: "less".  :-)

Yours,
  Ingo