From owner-freebsd-doc@freebsd.org Sun Feb 7 16:24:35 2021 Return-Path: Delivered-To: freebsd-doc@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id A3EBF530F97 for ; Sun, 7 Feb 2021 16:24:35 +0000 (UTC) (envelope-from lev@FreeBSD.org) Received: from smtp.freebsd.org (smtp.freebsd.org [96.47.72.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DYZHR3twbz4nZt; Sun, 7 Feb 2021 16:24:35 +0000 (UTC) (envelope-from lev@FreeBSD.org) Received: from onlyone.not-for.work (onlyone.not-for.work [IPv6:2a01:4f8:201:6350::2]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) (Authenticated sender: lev/mail) by smtp.freebsd.org (Postfix) with ESMTPSA id 5E321B630; Sun, 7 Feb 2021 16:24:35 +0000 (UTC) (envelope-from lev@FreeBSD.org) Received: from [IPv6:2001:470:923f:1:e899:143e:f56f:67ea] (unknown [IPv6:2001:470:923f:1:e899:143e:f56f:67ea]) (Authenticated sender: lev@serebryakov.spb.ru) by onlyone.not-for.work (Postfix) with ESMTPSA id B0482B550; Sun, 7 Feb 2021 19:24:31 +0300 (MSK) Reply-To: lev@FreeBSD.org Subject: Re: Is here common source format to produce mdoc and MarkDown? To: Mateusz Piotrowski <0mp@FreeBSD.org>, Brooks Davis Cc: freebsd-doc@freebsd.org References: <1c54f0c2-c5fd-b266-a760-ae4c374a7e84@FreeBSD.org> <20210205225508.GA56641@spindle.one-eyed-alien.net> From: Lev Serebryakov Organization: FreeBSD Message-ID: <50b2f43a-a8e0-7995-6ad3-5bed3a17698b@FreeBSD.org> Date: Sun, 7 Feb 2021 19:24:30 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.7.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 07 Feb 2021 16:24:35 -0000 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