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

[John Gardner]

>
> *It relies on DocBook, which has by far the lowest quality man(7) code
> generator on the planet.*


I'd say second-lowest... you should see marked(1)'s output:

https://github.com/markedjs/marked/blob/master/man/marked.1

On 6 March 2018 at 03:50, Ralph Corderoy <address@hidden> wrote:

> Hi Ingo,
>
> > > 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.
>
> I agree DocBook is awful.  The world seems to have cottoned on and it's
> being allowed to rot.  I was talking more about the asciidoc input file
> format than a method of production from it;  that's why I deleted the
> reference to man pages when I was complaining about the various Markdown
> input formats.  AIUI though, asciidoc the program, rather than the file
> format, has the original `run everything through DocBook' route to a man
> page that produces
>
>     http://www.methods.co.nz/asciidoc/asciidoc.1
>     .PP
>     \fB\-o, \-\-out\-file\fR=\fIOUT_FILE\fR
>     .RS 4
>     Write output to file
>     \fIOUT_FILE\fR\&. Defaults to the base name of input file with
>     \fIbackend\fR
>     extension\&. If the input is stdin then the outfile defaults to
> stdout\&. If
>     \fIOUT_FILE\fR
>     is
>     \fI\-\fR
>     then the standard output is used\&.
>     .RE
>
> yes, it does `\&. ' rather than `.  ', but also two straight-to-roff
> backends, the first of which uses CSS,
>
>     http://www.methods.co.nz/asciidoc/asciidoc.1.css-embedded.html
>     <dt class="hdlist1">
>     <strong>-o, --out-file</strong>=<em>OUT_FILE</em>
>     </dt>
>     <dd>
>     <p>
>         Write output to file <em>OUT_FILE</em>. Defaults to the base name
> of
>         input file with <em>backend</em> extension. If the input is stdin
> then
>         the outfile defaults to stdout. If <em>OUT_FILE</em> is <em>-</em>
> then the
>         standard output is used.
>     </p>
>     </dd>
>
> and the second doesn't.
>
>     http://www.methods.co.nz/asciidoc/asciidoc.1.html
>     <dt>
>     <strong>-o, --out-file</strong>=<b>OUT_FILE</b>
>     </dt>
>     <dd>
>     <p>
>         Write output to file <b>OUT_FILE</b>. Defaults to the base name of
>         input file with <b>backend</b> extension. If the input is stdin
> then
>         the outfile defaults to stdout. If <b>OUT_FILE</b> is <b>-</b>
> then the
>         standard output is used.
>     </p>
>     </dd>
>
> Neither are great, but... no Docbook.
>
> > 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.
>
> That's because Larry Wall was well used to writing roff for man pages by
> the time he concocted POD to replace his Perl man pages.  He didn't
> shoehorn some format designed for a different backend to make a man page
> instead.  :-)
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>