X-Original-To: alpine-devel@lists.alpinelinux.org Received: from mail-qt0-f175.google.com (mail-qt0-f175.google.com [209.85.216.175]) by lists.alpinelinux.org (Postfix) with ESMTP id 57ED65C58F7 for ; Tue, 12 Dec 2017 23:00:02 +0000 (GMT) Received: by mail-qt0-f175.google.com with SMTP id g10so1283377qtj.12 for ; Tue, 12 Dec 2017 15:00:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=dereferenced-org.20150623.gappssmtp.com; s=20150623; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=EruY6L+kdKOFwGHjTPpvO2U/m+m7D0BKW/8yp2FAi4U=; b=sUQN8kN+/kW8G1D6J13UjSmXsXBujBTPw+WeAx5YV/sWEtgh6Nv6AuEgVaNdxE1pEI JMkweYXNOHYGRzSARiELRewF+cK/TujBCTM/en1rQ+G1elc/nYmSWe0b40juH3qe7SP8 2OmB/pF2MUtyF65THirmGxVZQM3uBwNr9PddaPt6ihP891VY45B+egCHIfDUAUC10a55 jYakJrBaHWA/EimpZoAPk+xvaflXJJ+Jvx/sGuLXQXHeVJXmQHn3U0psQbaaWiEebAF9 zYKwpLG+49KbRXyZfsw3kVgazLc0Pb7rSFnscBVW0vy/esV4q+r7hqxA4yZqhxzdAK03 io9A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=EruY6L+kdKOFwGHjTPpvO2U/m+m7D0BKW/8yp2FAi4U=; b=iI7pSb4iJpELus8Y4C7ienerOzr+3q6KYUhuaY1jijO4Et5Vmn/C5X1EDksib19fH7 ZyvqOCHxpwzZknd9zN9Zua2vZtLP6nU7SsXHl0nRfMjzdSaM/2VGUC4WqFfXGeYGnV/q VF7Cn7OvSyMhKzniEYR+YmyJppYArN+ci9CmT+oiC+cIfs0NTLA5a/1GMPc7He2G10c8 bNIalkbV0p/KKj6NUlTXzwsecdRxlJFixSoKRYF4tVuNqExqo+VFfnki0LSQ7L/eiAET SLMVFb4mlelQZnmwg/S9zbjUr5WWbjRMYoW7gUtEpsbeUq2jmA1G52zSqMo1Z/PqLCZd FQuw== X-Gm-Message-State: AKGB3mJcJ/4ULeDsjN9AvtIR/0rubbOYYdzqfpYHLeQVo3Yvc04vs+A3 4o4/B374bNodGbtJHNCckENhyCcFfiPwpIW+6F3JnQ== X-Google-Smtp-Source: ACJfBosQmhAO2WXquq12ImLvuXwi3sj9+9PeMryd0KDOGvW9+GJrZpmzL7uLJAbrnCHVJimGRudHTnEJLdWnPXKMKa0= X-Received: by 10.55.43.15 with SMTP id r15mr8239455qkh.42.1513119601591; Tue, 12 Dec 2017 15:00:01 -0800 (PST) X-Mailinglist: alpine-devel Precedence: list List-Id: Alpine Development List-Unsubscribe: List-Post: List-Help: List-Subscribe: MIME-Version: 1.0 Received: by 10.237.38.162 with HTTP; Tue, 12 Dec 2017 15:00:01 -0800 (PST) In-Reply-To: <20171212223049.GA2084@homura> References: <20171212201302.GA9334@eddy> <20171212202301.GA26329@miku> <20171212223049.GA2084@homura> From: William Pitcock Date: Tue, 12 Dec 2017 17:00:01 -0600 Message-ID: Subject: Re: [alpine-devel] Improving Alpine Linux documentation To: Drew DeVault Cc: Consus , alpine-dev Content-Type: text/plain; charset="UTF-8" Hello, On Tue, Dec 12, 2017 at 4:30 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. That is not an accurate summarization. Alpine's man command includes the mdoc macro package. > 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. In the case of apk and probably also abuild, it makes most sense that the documentation be written by the maintainers of that software. Accordingly, it makes sense that they should use the tools they wish to use, which in the case of apk, would be mdoc. > 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. Finally, as somebody who is involved in maintenance of apk, I am stating that I intend to write a manpage for apk at some point during the 3.8 development cycle. I just need to get pkgconf 1.4 out the door first, which ironically, is also blocking on docs right now. William --- Unsubscribe: alpine-devel+unsubscribe@lists.alpinelinux.org Help: alpine-devel+help@lists.alpinelinux.org ---