From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4546 invoked by alias); 6 Jan 2015 17:31:40 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 4535 invoked by uid 89); 6 Jan 2015 17:31:39 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=2.2 required=5.0 tests=AWL,BAYES_50,MEDICAL_SUBJECT,RCVD_IN_DNSWL_NONE,SPF_PASS autolearn=no version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 06 Jan 2015 17:31:38 +0000 Received: from svr-orw-fem-05.mgc.mentorg.com ([147.34.97.43]) by relay1.mentorg.com with esmtp id 1Y8Xyf-0003Nt-GF from Sandra_Loosemore@mentor.com ; Tue, 06 Jan 2015 09:31:33 -0800 Received: from [IPv6:::1] (147.34.91.1) by svr-orw-fem-05.mgc.mentorg.com (147.34.97.43) with Microsoft SMTP Server id 14.3.224.2; Tue, 6 Jan 2015 09:31:33 -0800 Message-ID: <54AC1BEF.70603@codesourcery.com> Date: Tue, 06 Jan 2015 17:31:00 -0000 From: Sandra Loosemore User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130329 Thunderbird/17.0.5 MIME-Version: 1.0 To: James Greenhalgh CC: Joseph Myers , GCC Patches , Gerald Pfeifer Subject: Re: Re: [Patch docs 0/5] Update some of md.texi References: <1420543302-11008-1-git-send-email-james.greenhalgh@arm.com> <20150106152620.GA24397@arm.com> In-Reply-To: <20150106152620.GA24397@arm.com> Content-Type: text/plain; charset="windows-1252"; format=flowed Content-Transfer-Encoding: 7bit X-SW-Source: 2015-01/txt/msg00249.txt.bz2 On Tue, 6 Jan 2015, James Greenhalgh wrote: > On Tue, Jan 06, 2015 at 02:56:58PM +0000, Joseph Myers wrote: >> On Tue, 6 Jan 2015, James Greenhalgh wrote: >> >>> I was aiming to: >>> >>> * Remove outdated details of the compiler. >>> * Remove long or obscure words that, while accurate, only served to >>> obfuscate a simple idea. >>> * Refer to similar things in a consistent fashion - in particular >>> trying to keep consistent use of "insn" and "pattern". >>> * Remove superflous examples, or waffling. >>> * Update some K&R C and make it use GNU-style. >>> >>> I've split the patch to a 5-patch series, roughly covering one section >>> in each. >> >> It would be much more reviewable if the patches were split logically - >> each addressing only one of the five issues you mention above - rather >> than physically. > > That is rather difficult to tease out of a documentation patch without > ending up with a very deep patch stack. Of course such a request is > possible, but often the partial change makes little sense or improvement > without rewriting an entire section, and the burden of making the > intermediary changes read well makes the process of rewriting documentation > exceedingly laborious. Splitting to this granularity essentially requires > a per-paragraph justification. > > In reality, a per-paragraph justification of my changes will be easier > for me to provide than a deep patch set. I'll try to find some time one > evening this week to "review" my patches to give this context, if that > would be acceptable. > > Hopefully I'll find a few more areas where the text can be improved > along the way! FWIW, I've had the same dilemma with edits to the GCC user documentation -- it's too easy to spend a few hours going through the document and end up with a gigantic patch that is totally unreviewable (because nobody really wants to take the time to go through tedious mechanical changes and nobody can identify the substantive changes mixed in with them or reconstruct your logic for making them). I've concluded that the best way is *not* to try to maintain a big patch stack, but just to make multiple passes through the document to fix different types of problems incrementally. E.g. address markup and grammar issues separately from rewrites of a whole section, in particular. I have a notepad where I've jotted down some things I've identified that are in need of fixing while I've been working on other things in invoke.texi, but no patches beyond the ones I've already posted and committed. From time to time I've wondered if we might not be better off moving towards something like the Wikipedia model for maintaining the GNU documentation (where everyone can make or revert changes and editors are encouraged to make changes boldly), but WP's tools are better suited for that model than Texinfo, patches, and SVN. I do think that taking a more lenient view of "obvious fixes" for documentation than for code changes is appropriate, though, since bad doc changes can simply be reverted and are unlikely to break GCC or hold up other developers' work meanwhile. It also sometimes (often?) takes months to get code patches reviewed and such a heavyweight process for documentation changes would only discourage volunteers from undertaking such work as they have time. -Sandra