Mail archive
alpine-devel

Re: [alpine-devel] Improving Alpine Linux documentation

From: Kiyoshi Aman <aphrael_at_alpinelinux.org>
Date: Tue, 12 Dec 2017 22:59:43 +0000

Hi,

As an end user, I really couldn't care less how the documentation is
generated. It needs to be complete, thorough, readable for plebes such as
myself, and available. (It also needs to be compatible with enduser
toolchains like mandb and mdoc, since those are the man providers used by
Adélie and Alpine, respectively.)

Please stop squabbling over manpage backend formats and focus on the
relevant issues. Namely, what to do about the wiki, what documentation
needs to be provided and where, and so on.

Thanks,
Kiyoshi

On Tue, Dec 12, 2017 at 4:31 PM Drew DeVault <sir_at_cmpwn.com> wrote:

> 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_at_lists.alpinelinux.org
> Help: alpine-devel+help_at_lists.alpinelinux.org
> ---
>
> --
-- Kiyoshi Aman



---
Unsubscribe:  alpine-devel+unsubscribe_at_lists.alpinelinux.org
Help:         alpine-devel+help_at_lists.alpinelinux.org
---
Received on Tue Dec 12 2017 - 22:59:43 GMT