From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/1871 Path: news.gmane.org!not-for-mail From: Rich Felker Newsgroups: gmane.linux.lib.musl.general Subject: documenting musl Date: Fri, 7 Sep 2012 22:40:06 -0400 Message-ID: <20120908024006.GA5937@brightrain.aerifal.cx> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1347071856 18042 80.91.229.3 (8 Sep 2012 02:37:36 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 8 Sep 2012 02:37:36 +0000 (UTC) To: musl@lists.openwall.com Original-X-From: musl-return-1872-gllmg-musl=m.gmane.org@lists.openwall.com Sat Sep 08 04:37:39 2012 Return-path: Envelope-to: gllmg-musl@plane.gmane.org Original-Received: from mother.openwall.net ([195.42.179.200]) by plane.gmane.org with smtp (Exim 4.69) (envelope-from ) id 1TAAvR-0001j3-WE for gllmg-musl@plane.gmane.org; Sat, 08 Sep 2012 04:37:38 +0200 Original-Received: (qmail 5650 invoked by uid 550); 8 Sep 2012 02:37:34 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Original-Received: (qmail 5642 invoked from network); 8 Sep 2012 02:37:34 -0000 Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:1871 Archived-At: 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