> > *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 <ra...@inputplus.co.uk> 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 > >
