Subject: Re: [alpine-devel] Improving Alpine Linux documentation
To: alpine-devel@lists.alpinelinux.org
References: <20171212201302.GA9334@eddy>
 <20171215091236.324b290c@ncopa-desktop.copa.dup.pw>
From: "A. Wilcox" <awilfox@adelielinux.org>
Organization: =?UTF-8?Q?Ad=c3=a9lie_Linux?=
Message-ID: <5A345AC2.6060003@adelielinux.org>
Date: Fri, 15 Dec 2017 17:29:06 -0600
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.5.0
Precedence: list
MIME-Version: 1.0
In-Reply-To: <20171215091236.324b290c@ncopa-desktop.copa.dup.pw>
Content-Type: text/plain; charset="windows-1252"
Content-Transfer-Encoding: quoted-printable

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 15/12/17 02:12, Natanael Copa wrote:
> We need to keep in mind that there are different kinds of=20
> documentation. For example:
>=20
> install doc: how to do the install administrator doc: the overview
> doc on how to do basic things in alpine manpages: technical docs
> and specifications for individual tools contributor doc: how to get
> involved in the project developer doc: how to get started with
> development infra doc: documentation of our infra structure=20
> community docs: how to set up some specific hard/software


I agree this is a good split of the docs.


> Those docs can link to the manpages, which are more in-depth docs
> for each tool. I don't have strong opinion on the format of the man
> pages. Personally I would prefer write things in markdown or
> asciidoc, but I don't mind writing directly in mdoc. (would be nice
> to have a filter for cgit to parse mdoc)


This may already be true.  It depends on what syntax highlighter
Alpine cgit is using:

https://wiki.archlinux.org/index.php/Cgit#Syntax_highlighting

Unfortunately `highlight` does not support man (or asciidoc!), but
`pygments` does support both:

http://pygments.org/docs/lexers/#lexers-for-non-html-markup-languages


> I think that manpages should be kept in the project it belongs to
> (eg apk man pages should be stored in the apk-tools git repo,
> etc).


Yes, definitely.


> Other thing I think we should do is to make sure that every git
> repo has a README, which includes: - what is the purpose of the
> software project - how do you get started (how to build) - where to
> find info on how to report bugs and get involved (links)


Would rST format be okay for this?  I could use the templates we have
in Ad=E9lie for README / CONTRIBUTING files and write some for apk-tools
and abuild if you like.  Here is an example:

https://code.foxkit.us/adelie/shimmy/raw/master/README.rst
https://code.foxkit.us/adelie/shimmy/raw/master/CONTRIBUTING.rst


Best to you and yours,
- --arw

- --=20
A. Wilcox (awilfox)
Project Lead, Ad=E9lie Linux
http://adelielinux.org
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJaNFq/AAoJEMspy1GSK50UGjQQAKtj8W5dnWK7PtwUS/rdsSs3
pIDAFE+XFxXs1nyugvOaIHIQ+qXBehp+ryq2kNP8DZOVr5GiYUZmU+iFWbZ6HucV
Q4XtWnSKJFBSQ3isDp1HHTMPlZB1SBFHE+R60Xptdv8wdKsWqA2LUmI2HminO0nB
U2Mo0oMm9ojEXBHY/CBoFsN28GTub1FmgU4EZs5MNORUPlMo6N6pKe5E976Qr9Sp
bJj5agyQk0h7eTBYJQBGTLDFvb+KZCxhmsCLyoYP+74A1XSoJkUYQ2TNMvvDrID/
YlvEwvhm6BOL7Ck9E/nbU1VJRxOtxNc2fBWqBjtXH28sA3tK3XOFnkmzpD3f5XnK
ZFszcoA8u5FWyIb358WIASk+2eBTSa7o9dwoPoCR3qHHuyAid8n1exNNWlO8EAW/
w8SYOuc385M805iCFRYn/opP3+jyHEVJwgcFS1ea8e7hMItQmv2DgzyyEWjRwgQ1
ZR/mIHfuNPxTmdknNxYW81WbzTFPEFwc2/n7v4sd9NPctDkmDi/Lve2qAPQ2inrr
2UdveVw1YfYDbKF11+VnpMcdWarS2x1tqIakGrSwPsBISxaz6ZKYvdtal8dg+C4t
yQuyZU96NsB5AYNeXMNJljxGcfVzw7bCQ1F1hACrqla24p06Lvb4vB/gffONexTi
+joyzbluEL/KaEt9jYAv
=3DgInG
-----END PGP SIGNATURE-----


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---