Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

Sidenote: I recently refactored Node.js's manpage
<https://github.com/nodejs/node/pull/18559> to use mdoc macros, advising
the project maintainers to stick to to mdoc whenever possible. I linked to
OpenBSD's mdoc reference and explained that mandoc itself isn't a
full-featured roff interpreter, so roff syntax should be avoided.

I'm glad they took notice of my utterly-inhuman justification abilities:
https://github.com/nodejs/node/pull/18559#issuecomment-364778689

Does anybody else here manage to line-wrap their commit messages at
*precisely* 72-characters without the aide of hyphenation or justification?
;-) Or is it just me?

On 16 April 2018 at 22:52, Ingo Schwarze <address@hidden> wrote:

> Hi Ralph,
>
> Ralph Corderoy wrote on Mon, Apr 16, 2018 at 12:43:19PM +0100:
> > Ingo Schwarze wrote:
>
> >> Debian, Ubuntu, Arch, Gentoo, Slackware, Homebrew, MacPorts, and
> >> pkgsrc provide packages that you can install.
>
> > Arch Linux's user repository, AUR, has
> > https://aur.archlinux.org/packages/mandoc/ but it seems the maintainer
> > has decided to have it conflict with groff:
>
> That is bad.  Thanks for noticing!
>
> There is more than one reason why i use both all the time:
> mandoc cannot do real typesetting; even for manual pages,
> i often do routine output comparisons; some manual pages -
> about 0.25% in the wild - still don't work with mandoc and
> require groff; ...
>
> > `...this package now
> > outright conflicts with groff.  mandoc provides the functionality of
> > both groff and man-db combined; as such, I consider it a full
> > replacement'.
>
> Uh oh.  They got that wrong.  :/
>
> > I've added a comment pointing out that groff might remain
> > useful.  :-)
>
> Thanks, absolutely!
>
> >>     https://www.bsdcan.org/2018/schedule/events/958.en.html
>
> > That says
> >
> >      Both Debian and Arch Linux now also use the mandoc formatter for
> >      their official online manuals.
> >
> > but I had trouble finding Arch's.
> > https://wiki.archlinux.org/index.php/Man_page#Online_man_pages points to
> > https://manned.org/
> >
> > I guess you're referring to https://jlk.fjfi.cvut.cz/arch/manpages/about
> > that they use for wiki links, e.g.
> > https://jlk.fjfi.cvut.cz/arch/manpages/man/utf-8.7
>
> Yes, that's what i'm linking to from below "Documentation and help /
> online manual page portals" on http://mandoc.bsd.lv/ .
>
> > Odd that they don't explicitly reference it AFAICS.
>
> I have no idea what's going on there.  :-)
>
> Yours,
>   Ingo
>
>