Re: [groff] Macros in their own package ...

[Ingo Schwarze]

Hi,

Ralph Corderoy wrote on Mon, Mar 05, 2018 at 03:43:43PM +0000:

> It's good a Markdown is working for you, but it and its ilk need to die
> out.  Others did a better job, e.g. http://www.methods.co.nz/asciidoc/

That may or may not be adequate for books, i don't know, but keep
in mind that AsciiDoc must never, under any circumstances, be used
for software documentation.  It relies on DocBook, which has by far
the lowest quality man(7) code generator on the planet.  Besides
being notoriously buggy and producing contorted, ugly, and highly
non-portable code, that code generator is virtually unmaintained.
Besides being the worst, it is also the most heavyweight documentation
formatting system i'm aware of, and by far the slowest - on the order
of 20 times slower than groff itself the last time i measured a few
years ago.

If you feel like you absolutely must auto-generate man(7) code for
some reason rather than writing it properly by hand (or even better,
writing mdoc(7) instead and converting that to man(7) for the handful
of systems that still don't ship it), use perlpod(1) and pod2man(1).
That's not perfect, but has always been very stable for a very long
time without serious bugs that would be worth mentioning, and the
generated code is not too messy.  It's also reasonably simple and
fast.

Yours,
  Ingo

P.S.
I know this is drifting off-topic with respect to the OP,
but an AsciiDoc advertisement on this list is too dangerous
without a clarification, it might cause people to misunderstand
and screw up the documentation of their project, even if it 
likely wasn't intended that way.