From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14573 invoked by alias); 8 Aug 2013 03:45:53 -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 14542 invoked by uid 89); 8 Aug 2013 03:45:53 -0000 X-Spam-SWARE-Status: No, score=-4.2 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,KHOP_THREADED,RCVD_IN_HOSTKARMA_W,RCVD_IN_HOSTKARMA_WL,RDNS_NONE autolearn=no version=3.3.1 Received: from Unknown (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Thu, 08 Aug 2013 03:45:52 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1V7HAV-0007WZ-WF from Yao_Qi@mentor.com ; Wed, 07 Aug 2013 20:45:44 -0700 Received: from SVR-ORW-FEM-03.mgc.mentorg.com ([147.34.97.39]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Wed, 7 Aug 2013 20:45:44 -0700 Received: from qiyao.dyndns.org (147.34.91.1) by svr-orw-fem-03.mgc.mentorg.com (147.34.97.39) with Microsoft SMTP Server id 14.2.247.3; Wed, 7 Aug 2013 20:45:42 -0700 Message-ID: <52031434.2080005@codesourcery.com> Date: Thu, 08 Aug 2013 03:45:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130110 Thunderbird/17.0.2 MIME-Version: 1.0 To: Eli Zaretskii CC: Stan Shebs , Subject: Re: A new strategy for internals documentation References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> In-Reply-To: <83k3jyunt8.fsf@gnu.org> Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-SW-Source: 2013-08/txt/msg00019.txt.bz2 On 08/07/2013 12:28 PM, Eli Zaretskii wrote: > internals manual, and the result was always the same: people are > generally happy with the commentary in the code and don't feel any > need to go any further. My personal feeling is that it is harder to edit the internal manual than to change the .c code. I feel competent to edit c files to fix a bug or add a new feature, with some comments in the code and rationale description in the mail. However, when it comes to the internal doc, I don't know how/where to edit because I don't have a global view on both the internal doc and the source code. Unfortunately, only few contributors has such global view. That may be the reason why some contributors complain about the internal manual, but fail to post patches to improve it. I like the idea that using wiki, which is not very formal, to encourage contributions on the internal doc, tutorials, howtos, etc. I had slides "Port GDB To A New Processor Architecture: TI C6X" on the GNU Cauldron this year, and John Gilmore suggests that "It would be lovely if you could improve the Internals manual in the spots where you learned things that were not well documented." [1]. It is a very good idea, and I checked the internal manual, and tried to improve it. Finally, I gave up, because I can see something is missing here and something is unclear there, but I was unable to extract some necessary bits from my slides, and add them to the internal doc, it is too hard for me. Then I'd like to convert my slides to several blog posts or wiki pages, which is informal, and people also can get benefits from them. The current Internals is like a book, most of people can't write a book or revise a book, but people can write a lot of useful blog or wiki pages. LLVM is famous for its documentation, go through its web site http://llvm.org/docs/, most of them are tutorials and howtos. Probably there is a "LLVM Programmer’s Manual" [2], which is equivalent to GDB Internals. It is quite general, doesn't include much details. Contributors and developers can read tutorials and howtos which are related to their tasks, and get their works started. Experienced hackers are too familiar with the code to rely much on the internal doc, but newbie contributors need them. Usually, documentation from newbie contributors usually fits the needs of other contributors. We need the contributions to the internal doc, and wiki is a good way to go, IMO. -- Yao (齐尧) [1] http://sourceware.org/ml/gdb/2013-07/msg00095.html [2] http://llvm.org/docs/ProgrammersManual.html