On 2023/01/03 05:22, Ask Bjørn Hansen via nsd-users wrote: > > > > On Jan 2, 2023, at 14:19, Jan Stary via nsd-users > > <nsd-users@lists.nlnetlabs.nl> wrote: > > > > For example, the entirety of manpages.debian.org is done with that. > > For comparison here’s one of the bind9 man pages — I for one much prefer the > resulting output. > > https://bind9.readthedocs.io/en/v9_18_10/manpages.html#delv-dns-lookup-and-validation-utility
If you're comparing the same manual between bind9.readthedocs.io (rst straight to html) and manpages.debian.org (first rst is converted to man, and that is then converted to html) it's obvious which is going to look best, simply because it has more information available (semantic markup rather than basic formatting information). A better comparison would be between html pages generated from a "proper" mdoc conversion and from the rst source, e.g. https://bind9.readthedocs.io/en/v9_18_10/manpages.html#dig-dns-lookup-utility https://man.openbsd.org/dig - the content is a bit different between the two as the version of dig in openbsd is from an old fork and cut-down compared to current ISC releases, but ignoring that, you get a better picture of what high quality output looks like from each of the source formats. Both look pretty much ok to me; the semantic information in mdoc is pretty good for searches, and mandoc's linter can be helpful to maintain quality, on the other hand rst has a slightly lower barrier for users to edit at the expense of heavier dependencies. The key thing is to use something that whoever does most work to maintain the documentation is happy with really imho. _______________________________________________ nsd-users mailing list nsd-users@lists.nlnetlabs.nl https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users
