From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7575 invoked by alias); 8 Aug 2013 21:08:00 -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 7548 invoked by uid 89); 8 Aug 2013 21:07:59 -0000 X-Spam-SWARE-Status: No, score=-3.5 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_LOW,RCVD_IN_HOSTKARMA_YE,RDNS_NONE,SPF_PASS autolearn=ham version=3.3.1 Received: from Unknown (HELO mail-ie0-f178.google.com) (209.85.223.178) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Thu, 08 Aug 2013 21:07:58 +0000 Received: by mail-ie0-f178.google.com with SMTP id f4so2901333iea.9 for ; Thu, 08 Aug 2013 14:07:51 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc:content-type; bh=B0P9QP7U63w9tR0S3LE0hPRxNamGxx/D88Sp0O8Aw0s=; b=UONWhaglnOFXVWMKDOEW/ZoRZGONAJN92m9FO/7tmJ8igRTEnx3ZQZF6NF05c2Rcie FHXhangJQPEBJoEuUgpKW6LvKPW2uluXnXKnSCwApYFhvMDadVO8BHXR5H6wonvUQp9/ qlTizajKC0Kk7O335FKJiNjo2evavYqPUrFXdVj089J+D7swxsWanpXdXFNJ1XtlP+xu MwNTw+wiuJ7TDIVGonk1r4U2jpdS/VuyXIMm8Iogp1emwYPwaFOmHsbaOIdOggq5zKQQ swfkBKchFKEXzQDze5t6jkqB1AhTrp7MDe1gOarh9kAN0h6NF1bn0CMZmR2p6tAQuDDo +/Xg== X-Gm-Message-State: ALoCoQnt8BbYqYKa7QsP7bMwU0rp0mwWhrn0bkhdPelRbTupU4yCfDT4T25b7UzdyKlK6JXeUbknGb5Soel0P7LI2SXAVNiANG/9SvJrq8klnGiqXj8wx9s12NolIGNitMDVDHdtt8xu3BSosM2yAELpAkdSSFw+xV0rEYhmRU8oKclOk/fazRov4bsZKszflgmkfYkkozlo MIME-Version: 1.0 X-Received: by 10.50.7.101 with SMTP id i5mr462207iga.48.1375996071455; Thu, 08 Aug 2013 14:07:51 -0700 (PDT) Received: by 10.64.239.148 with HTTP; Thu, 8 Aug 2013 14:07:51 -0700 (PDT) In-Reply-To: <83li4ct7ot.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> <83li4ct7ot.fsf@gnu.org> Date: Thu, 08 Aug 2013 21:08:00 -0000 Message-ID: Subject: Re: A new strategy for internals documentation From: Doug Evans To: Eli Zaretskii Cc: Stan Shebs , gdb Content-Type: text/plain; charset=ISO-8859-1 X-SW-Source: 2013-08/txt/msg00030.txt.bz2 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? [What are we working towards?] >> People do want internals documentation, we hear grumbles about it on a >> weekly basis. > > 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. [I think the latter includes me, IIUC, but I could be wrong.] >> >> *** Migration of gdbint.texinfo to wiki >> > >> > Wiki is a bad idea, because there's virtually no control on the >> > quality of the information there. >> >> That's true now, but I don't think I've heard of anybody being misled by >> poor information on the GDB wiki. > > 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). >> > AFAIK, Doxygen cannot generate an Info manual, only HTML. If so, this >> > would be a serious downside that you don't mention. >> >> Hmm, I'm perhaps prejudiced since I haven't looked at any info file in >> probably a decade. Are many people using them still? > > I do, quite a lot. Besides, Info is the official format of GNU > documentation, you will have hard time convincing the FSF to demote an > existing manual. > >> > If we want to keep the documentation in the sources, why not use the >> > same system as libiberty? >> >> It's plausible, but idiosyncratic. How much development does it get, >> vs Doxygen? > > Why do you need development for comments? He's referring to development of the comment->doc generator. [right?] >> > Not having a review process for documentation is an "upside" >> > because?... >> >> I think it's time-consuming overkill for tutorials and howtos. An >> underlying implicit goal here is to encourage contribution, not think of >> ways to chase people away. > > 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. [it's more important to get code right sooner than later]