Date: Tue, 12 Dec 2017 17:30:49 -0500
From: Drew DeVault <sir@cmpwn.com>
To: William Pitcock <nenolod@dereferenced.org>
Cc: Consus <consus@ftml.net>,
	alpine-dev <alpine-devel@lists.alpinelinux.org>
Subject: Re: [alpine-devel] Improving Alpine Linux documentation
Message-ID: <20171212223049.GA2084@homura>
References: <20171212201302.GA9334@eddy>
 <20171212202301.GA26329@miku>
 <CA+T2pCG0f6S9R70kca3GMX03g886ZsiJ8rRb4AoUt4hjCmsL4g@mail.gmail.com>
Precedence: list
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CA+T2pCG0f6S9R70kca3GMX03g886ZsiJ8rRb4AoUt4hjCmsL4g@mail.gmail.com>

On 2017-12-12  4:05 PM, William Pitcock wrote:
> We prefer to have apk's documentation in mdoc, since it does not
> require any preprocessing, but maybe your tool can be useful for other
> Alpine projects.

Summarizing the discussion from IRC on the ML:

mdoc requires either preprocessing or an extra runtime dependency.
Saying mdoc doesn't require preprocessing is like saying JVM bytecode
doesn't require compilation.

scdoc is a very light compile-time dependency and is extremely portable.
The syntax is much friendlier than mdoc (which is unavoidable as long as
mdoc is based on roff), which makes it easier for more people to
contribute. mdoc/roff syntax _has_ been a significant barrier for people
to contribute to projects that use them in the past.

It seems like it's been set in some of your minds that mdoc is the way
forward. I don't think it's a very rational choice.

--
Drew DeVault


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---