Mail archive
alpine-devel

Re: [alpine-devel] Improving Alpine Linux documentation

From: A. Wilcox <awilfox_at_adelielinux.org>
Date: Fri, 15 Dec 2017 17:29:06 -0600

-----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
> documentation. For example:
>
> 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
> 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élie 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

- --
A. Wilcox (awilfox)
Project Lead, Adélie 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
=gInG
-----END PGP SIGNATURE-----


---
Unsubscribe:  alpine-devel+unsubscribe_at_lists.alpinelinux.org
Help:         alpine-devel+help_at_lists.alpinelinux.org
---
Received on Fri Dec 15 2017 - 17:29:06 GMT