Date: Sun, 7 Feb 2021 19:24:30 +0300 From: Lev Serebryakov <lev@FreeBSD.org> To: Mateusz Piotrowski <0mp@FreeBSD.org>, Brooks Davis <brooks@freebsd.org> Cc: freebsd-doc@freebsd.org Subject: Re: Is here common source format to produce mdoc and MarkDown? Message-ID: <50b2f43a-a8e0-7995-6ad3-5bed3a17698b@FreeBSD.org> In-Reply-To: <fc546a32-bd52-e33e-ac71-f894068c1ede@FreeBSD.org> References: <1c54f0c2-c5fd-b266-a760-ae4c374a7e84@FreeBSD.org> <20210205225508.GA56641@spindle.one-eyed-alien.net> <fc546a32-bd52-e33e-ac71-f894068c1ede@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 07.02.2021 15:30, Mateusz Piotrowski wrote: >>> Maybe, mdoc to MarkDown converter? It is not best way, as mdoc is very tedious to edit, but better than nothing. >> See mandoc(1) and -T markdown. No idea if it's any good. > > It is pretty good. It is awful. Good MarkDown should be readable as simple txt, without any render at all. And output of `mandoc -T markdown` is complete mess. It is rendered my MarkDown parser semi-right (IMHO, it is still ugly, but tolerable), but it is unreadable as-is. For me, MarkDown is format to be used both with fancy renderer (i.e GitHub presentation of README.md) and without one (`more README.md` at local console). Output of `mandoc` is not any good for second use case, and for first one only (effectively reading in browser) it us better to render HTML directly, without MarkDown as intermediate format. > There is also Pandoc, which as far as I remember allows you to convert Markdown documents into manual pages. I'll look at it, but I don't have high hopes, as mdoc is semantic format and MarkDown is (almost) not. There is no notion of "option with optional argument" in MarkDown. -- // Lev Serebryakov
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?50b2f43a-a8e0-7995-6ad3-5bed3a17698b>