From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9798 invoked by alias); 8 Aug 2013 21:56:41 -0000 Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org Received: (qmail 9788 invoked by uid 89); 8 Aug 2013 21:56:40 -0000 X-Spam-SWARE-Status: No, score=-3.7 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,RDNS_NONE,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from Unknown (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Thu, 08 Aug 2013 21:56:39 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MR800E00FDYND00@a-mtaout20.012.net.il> for gdb@sourceware.org; Fri, 09 Aug 2013 00:55:20 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MR800EUQFK8BK80@a-mtaout20.012.net.il>; Fri, 09 Aug 2013 00:55:20 +0300 (IDT) Date: Thu, 08 Aug 2013 21:56:00 -0000 From: Eli Zaretskii Subject: Re: A new strategy for internals documentation In-reply-to: To: Doug Evans Cc: stanshebs@earthlink.net, gdb@sourceware.org Reply-to: Eli Zaretskii Message-id: <8361vfu9t4.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> <83li4ct7ot.fsf@gnu.org> X-SW-Source: 2013-08/txt/msg00032.txt.bz2 > Date: Thu, 8 Aug 2013 14:07:51 -0700 > From: Doug Evans > Cc: Stan Shebs , gdb > > On Thu, Aug 8, 2013 at 10:26 AM, Eli Zaretskii wrote: > >> Date: Wed, 07 Aug 2013 12:58:14 -0700 > >> From: Stan Shebs > >> CC: gdb@sourceware.org > >> > >> > So how just declaring gdbint.texinfo dead and deleting it altogether? > >> > >> Isn't that going to be the end state of what I'm proposing? :-) I just > >> added a path to conserve any bits that seem useful. > > > > My way is faster and easier. > > Possibly alright, but what final result do we want? The same as now: the internals manual is useless. > > The grumbles come from people other than those who can provide the > > documentation. And the latter don't think we have a problem in the > > first place. > > If the latter includes me I disagree. Disagree with what, and why? > > Again, if we don't care about the documentation, then of course we > > shouldn't care about poor information. If we do care, then wiki is a > > way to waste resources at best. > > I disagree (that the wiki is a way to waste resources at best). It is a waste because nothing good will ever come out of it. It will be a heap of notes various people at various times thought it would be a good idea to share. You cannot create a coherent document that way. > > Why do you need development for comments? > > He's referring to development of the comment->doc generator. Why do we need that developed, if it already does the job? > > The net result will be that the documentation will be unreadable. Not > > everybody who writes good code can write good documentation. > > OTOH, It's easier to improve documentation over time. Who will do that, and why? Again, the core developers think that what we have in the comments is enough, and if it is not enough, the comments should be improved/expanded. Why would someone invest efforts in another resource?