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

[Ralph Corderoy]

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