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
