Mail archive
alpine-devel

Re: [alpine-devel] Improving Alpine Linux documentation

From: William Pitcock <nenolod_at_dereferenced.org>
Date: Tue, 12 Dec 2017 17:00:01 -0600

Hello,

On Tue, Dec 12, 2017 at 4:30 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.

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_at_lists.alpinelinux.org
Help:         alpine-devel+help_at_lists.alpinelinux.org
---
Received on Tue Dec 12 2017 - 17:00:01 GMT