X-Original-To: alpine-devel@lists.alpinelinux.org Received: from mail-wm0-f68.google.com (mail-wm0-f68.google.com [74.125.82.68]) by lists.alpinelinux.org (Postfix) with ESMTP id C94F05C5878 for ; Tue, 12 Dec 2017 22:59:54 +0000 (GMT) Received: by mail-wm0-f68.google.com with SMTP id t8so1634375wmc.3 for ; Tue, 12 Dec 2017 14:59:54 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=txtNYU7I6qy6hgN6NSZa2MMrqY/wNFK6hbCmR030OV0=; b=HHRqNg+sis57hcajBrnn8xad+kISKABOssj7j9AuDaQP30pz1415dcLfytSijRwn1E EEtVP3jtY49mSFJ3DURhCLM/NlNVFxmt+E5GqnRfHQWy126JhpoYK0WaGxIt63WT3N+L n9T5MlZnMFoa2I6QPpwQSy8vAtTQkOCuMyIpMydnqGUna68ZMAiYZI42YueMIWRaTZBv 58RAPg1t9QnTkl/EeAcGzKpwgCwfkbhBgLcNvwDQIrqdTTtV7OwSNnxKukW9fIrVkLuS VJk8mTsdZXX/p1rSasq0oS6xzoY6smi/jxjIKTdfYZXW1GDvka19qb2AS4RBitMvRdLj MrVQ== X-Gm-Message-State: AKGB3mK6M+YAed4ZND4ppqz2CVXXris8sFFb4Yd6y4BajiC7DmNNXL4j mofZDX4BQvCMa2bQYzuJoj2GvFlJ0IcnLCCUAx0= X-Google-Smtp-Source: ACJfBovjVDTThQOOPIN4REMumEOQHsFb3PQ6/LUV/Q4t+e6SpPzBUlcHjsY9frOihgprtA7uuvJ9dcHWxKlejGZ2ND4= X-Received: by 10.28.196.70 with SMTP id u67mr303244wmf.100.1513119593919; Tue, 12 Dec 2017 14:59:53 -0800 (PST) X-Mailinglist: alpine-devel Precedence: list List-Id: Alpine Development List-Unsubscribe: List-Post: List-Help: List-Subscribe: MIME-Version: 1.0 References: <20171212201302.GA9334@eddy> <20171212202301.GA26329@miku> <20171212223049.GA2084@homura> In-Reply-To: <20171212223049.GA2084@homura> From: Kiyoshi Aman Date: Tue, 12 Dec 2017 22:59:43 +0000 Message-ID: Subject: Re: [alpine-devel] Improving Alpine Linux documentation To: Drew DeVault Cc: William Pitcock , Consus , alpine-dev Content-Type: multipart/alternative; boundary="94eb2c19451ee5fc2b05602c9bac" --94eb2c19451ee5fc2b05602c9bac Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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=C3=A9lie 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 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@lists.alpinelinux.org > Help: alpine-devel+help@lists.alpinelinux.org > --- > > -- -- Kiyoshi Aman --94eb2c19451ee5fc2b05602c9bac Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi,

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

Please stop squabbling over manpage backend formats and f= ocus on the relevant issues. Namely, what to do about the wiki, what docume= ntation needs to be provided and where, and so on.

Thanks,
Kiyoshi

On Tue, Dec 12, 2017 at 4:31 PM Drew DeVault <sir@cmpwn.com> wrote:
On 2017-12-12=C2=A0 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<= br> forward. I don't think it's a very rational choice.

--
Drew DeVault


---
Unsubscribe:=C2=A0 alpine-devel+unsubscribe@lists.alpinelinux.or= g
Help:=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0alpine-devel+help@lists.alpineli= nux.org
---

--
-- Kiy= oshi Aman
--94eb2c19451ee5fc2b05602c9bac-- --- Unsubscribe: alpine-devel+unsubscribe@lists.alpinelinux.org Help: alpine-devel+help@lists.alpinelinux.org ---