From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16774 invoked by alias); 2 Aug 2010 23:34:39 -0000 Received: (qmail 16765 invoked by uid 22791); 2 Aug 2010 23:34:38 -0000 X-SWARE-Spam-Status: No, hits=-2.1 required=5.0 tests=AWL,BAYES_00,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from VLSI1.ULTRA.NYU.EDU (HELO vlsi1.ultra.nyu.edu) (128.122.140.213) by sourceware.org (qpsmtpd/0.43rc1) with SMTP; Mon, 02 Aug 2010 23:34:33 +0000 Received: by vlsi1.ultra.nyu.edu (4.1/1.34) id AA09107; Mon, 2 Aug 10 19:35:40 EDT From: kenner@vlsi1.ultra.nyu.edu (Richard Kenner) Message-Id: <11008022335.AA09107@vlsi1.ultra.nyu.edu> Date: Mon, 02 Aug 2010 23:34:00 -0000 To: stevenb.gcc@gmail.com Subject: Re: GFDL/GPL issues Cc: Joe.Buck@synopsys.com, ams@gnu.org, bkoz@redhat.com, dewar@adacore.com, dnovillo@google.com, gcc@gcc.gnu.org, iant@google.com, mark@codesourcery.com, richard.guenther@gmail.com In-Reply-To: References: <4BFC6EF0.4090908@codesourcery.com> <20100714172307.3687a9c4@shotwell> <4C48D2C4.5000103@codesourcery.com> <4C48D60E.3000604@codesourcery.com> <20100726175013.20b12428@shotwell> <4C4E35B8.6010301@codesourcery.com> <4C4E37FC.1060208@adacore.com> <4C4F010C.5060401@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> 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/msg00017.txt.bz2 > That is true, but very often the documentation is needed in two > places: in the code and in the manual. Especially for things like > machine constraints, flags and options. Yes, but the audiences are different between users who read the manual and developers who read the code. For the best quality, the two descriptions may well be quite different, in emphasis, tone and other areas. If the emphasis is on finding text that's acceptable for BOTH purposes, you create documentation that's not ideal for EITHER. > And even if the documentation isn't needed in two places to, well, > document something, it may still be useful to automatically generate > parts of manual to avoid divergence between the manual and the compiler. That's indeed a worthwhile goal, but doing it at the expense of the quality of the documentation is a very bad idea, in my opinion. The quality of documentation in the industry, and even in the Free Software community is pretty poor. GCC is known for a very high standard of documentation. Let's not lower it by substiting automated tools for quality handwritten documentation. I believe that tools have their purpose for such things as functions lists and detailed ABI documentation, but not in things like user manuals.