[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Sat, 8 Sep 2012 12:44:33 +0100
From: Justin Cormack <justin@...cialbusservice.com>
To: musl@...ts.openwall.com
Subject: Re: documenting musl
On Sat, Sep 8, 2012 at 3:40 AM, Rich Felker <dalias@...ifal.cx> wrote:
> Hi all,
>
> One item that's been on my todo list for a while, but didn't really
> make it into the last email, is creating some kind of documentation
> for musl.
>
> One document, which I would call simply the "manual", should cover
> everything you need to know if you're writing applications against
> musl or building existing applications against musl. It should contain
> introductory materials on the standards and extensions musl aims to
> support, feature test macros, etc. It should also document musl's
> locale behavior, quality of implementation guarantees, and anything
> ISO C or POSIX requires an implementation to document (i.e.
> implementation-defined behavior). In some cases, the documentation may
> defer to that for the compiler being used. The manual should further
> document any additional behavior guarantees for functions beyond
> what's required in the standard, as well as behavior for all supported
> non-standard functions.
>
> A second possible document would be oriented towards people wanting to
> learn from the source, port musl to new platforms, add features or
> customize it for unusual usage cases, reuse parts of musl in other
> software, etc. This document would explain the source tree layout and
> build system, use of weak symbols and object file dependency graph
> issues, stdio and pthread internal interfaces including thread
> cancellation architecture, porting requirements, and so on.
>
> For getting the documentation done, and ideal situation would be for a
> FOSS documentation guru with an interest in musl to show up and
> volunteer to organize the documentation effort, write major portions,
> and maintain it. In the absence of such a miracle, perhaps we could
> turn the above ramblings into a sort of outline for the proposed
> documentation, and use the wiki to draft unofficial documents that
> cover some of the same topics. I think the wiki would be especially
> appropriate for the developer/hacking documentation, since it's less
> official in nature and more community-oriented.
>
> Ideas? Volunteers?
Sounds good. Happy to help. Have you got a model for what form it
might end up in? I find that it helps to know how it might end up
looking in order to get an idea of how much to write, and who the
audience is.
For example, do we want to produce a set of man pages for a
distribution that uses Musl at some point? Should we aim to produce
everything as an online reference first?
Maybe some examples will help to discuss what we want.
I think for the comprehensive documentation the wiki might be a pain.
Justin
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
