[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Message-ID: <20120908024006.GA5937@brightrain.aerifal.cx>
Date: Fri, 7 Sep 2012 22:40:06 -0400
From: Rich Felker <dalias@...ifal.cx>
To: musl@...ts.openwall.com
Subject: documenting musl
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?
Rich
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.
