From: Ingo Schwarze <schwarze@usta.de>
To: discuss@mdocml.bsd.lv, David Holland <dholland@netbsd.org>
Subject: Re: Extension for more general documents
Date: Sat, 14 Jun 2014 14:27:39 +0200 [thread overview]
Message-ID: <20140614122739.GB27521@iris.usta.de> (raw)
In-Reply-To: <20140613140402.GA4354@crux>
Hi,
Svyatoslav Mishyn wrote on Fri, Jun 13, 2014 at 05:04:03PM +0300:
> just notice
> maybe AsciiDoc will be interesting..
No, it will not.
Never use AsciiDoc or DocBook for anything related to manuals.
The man(7) code generated from the AsciiDoc/DocBook toolchain
is by far the worst quality autogenerated man(7) code you can
find from any autogeneration tool chain i'm aware of. It is
the worst by such a large margin that DocBook alone is responsible
for the overwhelming majority of bogus bug reports for mandoc, that
is reports that something is presumably broken in mandoc which turn
out to be merely broken mandoc *input* generated from some buggy
autogenerator.
Besides, the AsciiDoc toolchain is incredibly slow. Generating man(7)
code from AsciiDoc typically takes about hundred (!) times the CPU time
required to format that man(7) code for terminal output with mandoc(1).
If you must autogenerate man(7) code for some reason, even the Perl
"plain old documentation" (POD) format is a much better starting
point than AsciiDoc. But i wouldn't recomment that, or generating
man(7) code at all, either. Just use mdoc(7), Thomas is right in
that respect.
Yours,
Ingo
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
next prev parent reply other threads:[~2014-06-14 12:27 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-06-13 8:35 Thomas Klausner
2014-06-13 8:46 ` Kristaps Dzonsons
2014-06-13 10:05 ` Ingo Schwarze
2014-06-13 11:06 ` Thomas Klausner
2014-06-13 11:44 ` Thomas Klausner
2014-06-13 14:04 ` Svyatoslav Mishyn
2014-06-13 22:18 ` Thomas Klausner
2014-06-14 12:27 ` Ingo Schwarze [this message]
2014-06-14 12:16 ` Ingo Schwarze
[not found] ` <20140705205008.GA8289@netbsd.org>
2014-08-09 1:05 ` Ingo Schwarze
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20140614122739.GB27521@iris.usta.de \
--to=schwarze@usta.de \
--cc=dholland@netbsd.org \
--cc=discuss@mdocml.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).