From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22781 invoked by alias); 16 Aug 2010 05:46:55 -0000 Received: (qmail 22768 invoked by uid 22791); 16 Aug 2010 05:46:51 -0000 X-SWARE-Spam-Status: No, hits=-2.1 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from lo.gmane.org (HELO lo.gmane.org) (80.91.229.12) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 16 Aug 2010 05:46:28 +0000 Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1OksWf-0002W2-FW for gcc@gcc.gnu.org; Mon, 16 Aug 2010 07:46:25 +0200 Received: from fencepost.gnu.org ([140.186.70.10]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 16 Aug 2010 07:46:25 +0200 Received: from miles by fencepost.gnu.org with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 16 Aug 2010 07:46:25 +0200 To: gcc@gcc.gnu.org From: Miles Bader Subject: Re: GFDL/GPL issues Date: Mon, 16 Aug 2010 12:10:00 -0000 Message-ID: References: <4BFC6EF0.4090908@codesourcery.com> <20100727180738.GU17485@synopsys.com> <4C4F20E8.5050206@codesourcery.com> <4C509E54.6090401@codesourcery.com> <11007291247.AA02219@vlsi1.ultra.nyu.edu> <4C5195FA.2060208@codesourcery.com> <4C52B176.7040807@adacore.com> <4C52E1C0.6090400@codesourcery.com> <4C53696B.7030801@adacore.com> <4C536B50.4010402@codesourcery.com> <11008022335.AA09107@vlsi1.ultra.nyu.edu> <4C575891.1000106@codesourcery.com> <4C5863D6.5090808@adacore.com> <4C67A8CD.70205@adacore.com> <8739ugs0na.fsf@mid.deneb.enyo.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii System-Type: x86_64-unknown-linux-gnu Blat: Foop X-IsSubscribed: yes Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org X-SW-Source: 2010-08/txt/msg00252.txt.bz2 Florian Weimer writes: >>> Duplication is how other GNU projects handle this. For instance, many >>> Emacs Lisp functions are documented twice: once as a docstring in the >>> source code (which is roughly equivalent to the comment-in-spec >>> approach), and once in the Elisp reference (which is GFDLed). >> >> Well probably we can all agree that such duplication is undesirable, >> unless it is automated, since documentation can get out of sync. > > There's a school of thought that claims that things need to be > described at least twice, both formally and informally. I don't think > these people mean "code and documentation", but rather "two forms of > documentation". With elisp, I've found that in practice I usually start by copying the docstring (the "in code doc") to the manual (the "doc doc"), but almost always end up largely rewriting to fit the context in the manual better, and to explain things in more detail (modern docstrings tend to be rather verbose compared to docstrings-of-old, but they're still generally more terse than the manual). What this says, I dunno; it'd be nice to have the freedom to just do whatever's best, of course... -Miles -- Neighbor, n. One whom we are commanded to love as ourselves, and who does all he knows how to make us disobedient.