From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23741 invoked by alias); 8 Aug 2013 17:28:23 -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 23716 invoked by uid 89); 8 Aug 2013 17:28:22 -0000 X-Spam-SWARE-Status: No, score=-2.4 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,RDNS_NONE,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from Unknown (HELO mtaout21.012.net.il) (80.179.55.169) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Thu, 08 Aug 2013 17:28:21 +0000 Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0MR800F002VSF300@a-mtaout21.012.net.il> for gdb@sourceware.org; Thu, 08 Aug 2013 20:26:27 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MR800FBB343DT40@a-mtaout21.012.net.il>; Thu, 08 Aug 2013 20:26:27 +0300 (IDT) Date: Thu, 08 Aug 2013 17:28:00 -0000 From: Eli Zaretskii Subject: Re: A new strategy for internals documentation In-reply-to: <5202A6D6.8090908@earthlink.net> To: Stan Shebs Cc: gdb@sourceware.org Reply-to: Eli Zaretskii Message-id: <83li4ct7ot.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> X-SW-Source: 2013-08/txt/msg00023.txt.bz2 > 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. > 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. > >> *** 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. > > What exactly makes it hard to keep this part up to date now? > > If nothing else, ensuring that "make info" doesn't break because > you forgot an @-sign. :-) How is this different from a typo in the code? > >> proposals to auto-generate any of [internal API docs] from the (GPLed) > >> sources run afoul of the incompatible GFDL that governs the wiki and > >> the manuals. > > > > That's not correct. Generation of a Texinfo manual from program > > sources is well established, and used in libiberty, binutils, and > > elsewhere. The licensing issue is AFAIU a red herring. > > True, if you're not mixing anything. In the discussion that started > with http://www.sourceware.org/ml/gdb/2009-10/msg00208.html , there > seemed to be valid concerns about how things could be intermixed, and I > note that the libg++ documentation has a specific disclaimer that the > auto-generated parts of its docs are GPL and separate from the GFDL parts. Red herring. I asked RMS about this once, and the answer was there was no problem. > > 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? > > 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. > >> The licensing requires us to be careful about migrating pieces of > >> text; material from gdbint.texinfo can be copied to the wiki, but not > >> into the sources. This is not purely hypothetical, as for instance > >> the gdbint.texinfo description of i386_insert_watchpoint is more > >> detailed than the comments currently in the source code. > > > > Because the author for some strange reason believed that the > > documentation should be in the manual rather than in the sources. But > > that author is still among us, so you could ask him politely whether > > he would like to consider relicensing the stuff. > > Yes, in theory I could re-contribute my bits, but I really really don't > want to spend hours of debate on whether the licenses, or FSF ownership, > even allow for that, or if there if some obscure obstacle. Another red herring, AFAIK. I can decide to distribute the text that I wrote under any license I want, as long as I don't preclude the FSF to distribute that text in the GNU manuals under GFDL. The fact that I assigned the copyright to the FSF for the manual just means that the FSF is free to distribute that text in that manual. But it doesn't in any way preclude me to distribute the same text in other ways. IOW, assignment of copyright doesn't mean the FSF now owns the text.