[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] Macros in their own package ...
From: |
John Gardner |
Subject: |
Re: [groff] Macros in their own package ... |
Date: |
Tue, 6 Mar 2018 18:01:05 +1100 |
>
> *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
>
>