From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 31165 invoked by alias); 4 Mar 2014 19:51:08 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 31115 invoked by uid 89); 4 Mar 2014 19:51:08 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: elasmtp-banded.atl.sa.earthlink.net Received: from elasmtp-banded.atl.sa.earthlink.net (HELO elasmtp-banded.atl.sa.earthlink.net) (209.86.89.70) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 04 Mar 2014 19:51:06 +0000 Received: from [68.96.200.16] (helo=macbook2.local) by elasmtp-banded.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1WKvMl-00073T-NB; Tue, 04 Mar 2014 14:51:03 -0500 Message-ID: <53162EA7.9090804@earthlink.net> Date: Tue, 04 Mar 2014 19:51:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:24.0) Gecko/20100101 Thunderbird/24.3.0 MIME-Version: 1.0 To: Eli Zaretskii CC: gdb-patches@sourceware.org Subject: Re: [PATCH] Doxygenate gdbtypes.h References: <53151B5D.5000309@earthlink.net> <201403040039.s240db0w008027@glazunov.sibelius.xs4all.nl> <531529D4.3050309@earthlink.net> <8761ntoogy.fsf@gnu.org> <53162394.3030604@earthlink.net> <83txbdrd10.fsf@gnu.org> In-Reply-To: <83txbdrd10.fsf@gnu.org> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da9406976bdf17fa1d8583bb5dea1dc25f7b1350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-IsSubscribed: yes X-SW-Source: 2014-03/txt/msg00095.txt.bz2 On 3/4/14 11:15 AM, Eli Zaretskii wrote: >> Date: Tue, 04 Mar 2014 11:03:48 -0800 >> From: Stan Shebs >> >>> Just because some GNU packages use Doxygen (or CMake, or...) doesn’t >>> mean it’s a good idea; and it remains a GCS violation. >> >> Paragraph and sentence, please? > >>>From the "GNU Manuals" node: > > The preferred document format for the GNU system is the Texinfo > formatting language. Every GNU package should (ideally) have > documentation in Texinfo both for reference and for learners. Texinfo > makes it possible to produce a good quality formatted book, using TeX, > and to generate an Info file. It is also possible to generate HTML > output from Texinfo source. See the Texinfo manual, either the > hardcopy, or the on-line version available through `info' or the Emacs > Info subsystem (`C-h i'). > > Nowadays some other formats such as Docbook and Sgmltexi can be > converted automatically into Texinfo. It is ok to produce the Texinfo > documentation by conversion this way, as long as it gives good results. In this context, it's important that the standard says "preferred", not "required". As we've been discussing since last August, writing internals documentation as a separate manual in Texinfo has not worked out for GDB. Fortunately, the general coding standards do allow projects to set their own additional practices, where such changes do not contradict any explicit requirements set down by the FSF. Stan stan@codesourcery.com