Re: [groff] Release Candidate 1.22.4.rc3

[Ingo Schwarze]

Hi Larry,

Larry Kollar wrote on Thu, Nov 29, 2018 at 11:02:32PM -0500:

> Cool. Believe it or not, that's the first time I've seen mdoc options
> done that way.  Most everyone seems to run them together on a single line,

That's surprising, given that Cynthia developed mdoc(7) long before
Werner lifted the eight-argument-limit - so BSD manuals certainly have
a long-standing tradition of using short macro lines.

I started sometimes using long macro lines about 2010/2011 - but only
in cases where that is easier to read for humans.


[...]
> I'll give mdoc another shot.  If it works out this time, I'll
> rewrite the Tines manpages in mdoc.

Let me know if you run into any trouble.  Feedback from an experienced
writer with little mdoc(7) experience seems quite valuable, in particular
for improving documentation of the language (both in groff and mandoc),
and maybe even for fixing issues with the implementations themselves.

Note that in addition to groff_mdoc(7),

  https://man.openbsd.org/mdoc.7

may occasionally be more concise and more precise as a reference, and

  http://mandoc.bsd.lv/mdoc/

provides additional information for advanced users, for example
regarding best practices in some respects.


[...]
> But yeah, converting anything to anything isn't going to be
> seamless.

That is probably true in many cases, but not in all.

For example, converting mdoc(7) to man(7) with "mandoc -Tman" is
almost perfect.  It is intended to be run in "make dist" maintainer
targets of build systems, such that you can ship the results in
release tarballs without ever looking at them, and some maintainers
use it that way.  If there were anything wrong with the generated
man(7) code that would require manual postprocessing, i'd consider
that a bug.  Currently, i'm not aware of any such bugs.

Yours,
  Ingo