From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/1897 Path: news.gmane.org!not-for-mail From: nwmcsween@gmail.com Newsgroups: gmane.linux.lib.musl.general Subject: Re: documenting musl Date: Sat, 8 Sep 2012 20:09:51 -0700 Message-ID: <1CAEF50B-DAB5-4B88-9B74-0334D628B0AF@gmail.com> References: <20120908024006.GA5937@brightrain.aerifal.cx> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 (1.0) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1347160215 20299 80.91.229.3 (9 Sep 2012 03:10:15 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 9 Sep 2012 03:10:15 +0000 (UTC) To: "musl@lists.openwall.com" Original-X-From: musl-return-1898-gllmg-musl=m.gmane.org@lists.openwall.com Sun Sep 09 05:10:18 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 1TAXuZ-0007Ho-8n for gllmg-musl@plane.gmane.org; Sun, 09 Sep 2012 05:10:15 +0200 Original-Received: (qmail 24381 invoked by uid 550); 9 Sep 2012 03:10:11 -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 24373 invoked from network); 9 Sep 2012 03:10:11 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=subject:references:from:content-type:x-mailer:in-reply-to :message-id:date:to:content-transfer-encoding:mime-version; bh=AEDIgqW/wKpMCVAn4l4NyNyVK854qbSqARBitJljSPw=; b=K0PW+OpMtzgPi/0lhJ0VZtqu37t52RjFT8+J4HxfLqE77cdx4+ZUMWjBbjAuJIhwLH eqOqKSXWEcMNNoxppDYfpEoA8yay+Bxued2OwYQoh9txEiU4XM2YKorBRQdSjPJpn7eO y/E28s3pEkxyUZiKQ8vaSqwAUXf0k8X5Zopj00ZaxvhHDgWLFKM33QZ7hSwxZu0F5tUC RRh5gKI03AxnNL0ZkLNqQvtL7ZDRVONxSsBb1NcdmCnOjfofOpjfMaUSzOHr8VDP6mvY K6bSwnO0btuuCrxaVKZKatDOT3oO912B3vgDgjnz4i3wbbkbij8m+dyNNKt+BA34lT9o rdBg== X-Mailer: iPhone Mail (9A405) In-Reply-To: <20120908024006.GA5937@brightrain.aerifal.cx> Xref: news.gmane.org gmane.linux.lib.musl.general:1897 Archived-At: IMO documentation should be inline with code, I've banged my head on the wal= l countless times reading musl source wrt linuxisms, etc. a good inline doc s= tyle is Rocco style literate inline documentation / Donald Knuth style liter= ate documentation. I also doubt any normal inline documentation has any meas= urable compiler overhead. On Sep 7, 2012, at 7:40 PM, Rich Felker wrote: > Hi all, >=20 > 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.=20 >=20 > 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. >=20 > 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. >=20 > 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. >=20 > Ideas? Volunteers? >=20 > Rich