From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by sourceware.org (Postfix) with ESMTP id 4EF943844000 for ; Wed, 10 Mar 2021 13:52:22 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 4EF943844000 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-159-cqyoLogSPQG0megE17OR4w-1; Wed, 10 Mar 2021 08:52:20 -0500 X-MC-Unique: cqyoLogSPQG0megE17OR4w-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id C452357; Wed, 10 Mar 2021 13:52:18 +0000 (UTC) Received: from t14s.localdomain (ovpn-114-98.phx2.redhat.com [10.3.114.98]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1B1D160C13; Wed, 10 Mar 2021 13:52:17 +0000 (UTC) Message-ID: Subject: Re: [PATCH] docs: add interactive vs batch distinction to UX guidelines From: David Malcolm To: David Brown , Jonathan Wakely Cc: Florian Weimer , Jonathan Wakely via Gcc , Thanos Makatos Date: Wed, 10 Mar 2021 08:52:17 -0500 In-Reply-To: <20210223022615.1986132-1-dmalcolm@redhat.com> References: <37e4a606-cb4a-85f8-00fa-dbbf14339dc5@westcontrol.com> <20210223022615.1986132-1-dmalcolm@redhat.com> User-Agent: Evolution 3.38.3 (3.38.3-1.fc33) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-12.2 required=5.0 tests=BAYES_00, BODY_8BITS, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 10 Mar 2021 13:52:23 -0000 On Mon, 2021-02-22 at 21:26 -0500, David Malcolm wrote: > On Sat, 2021-02-20 at 17:49 +0100, David Brown wrote: > > > > > > On 20/02/2021 16:46, David Malcolm wrote: > > > On Sat, 2021-02-20 at 15:25 +0100, David Brown wrote: > > > > > > > > > > I think we need to think about both of these use-cases e.g. as we > > > implement our diagnostics, and that we should mention this > > > distinction > > > in our UX guidelines... > > > > > > > Is it possible to distinguish these uses, and then have > > > > different > > > > default flags?  Perhaps something as simple as looking at the > > > > name > > > > used > > > > to call the compiler - "cc" or "gcc" ? > > > > > > > > > > ...but I'm wary of having an actual distinction between them in > > > the > > > code; it seems like a way to complicate things and lead to > > > "weird" > > > build failures. > > > > > > > Fair enough. > > [...snip...] > > How about the following addition to the User Experience Guidelines? I've gone ahead and pushed this to trunk (as c4a36bb1e1be0b826e71f4723c9f66266aa86b6f), after checking it bootstrapped. Dave > gcc/ChangeLog: >         * doc/ux.texi: Add subsection contrasting interactive versus >         batch usage of GCC. > --- >  gcc/doc/ux.texi | 25 +++++++++++++++++++++++++ >  1 file changed, 25 insertions(+) > > diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi > index fdba5da1598..28d5994d10f 100644 > --- a/gcc/doc/ux.texi > +++ b/gcc/doc/ux.texi > @@ -86,6 +86,31 @@ information to allow the user to make an informed > choice about whether >  they should care (and how to fix it), but a balance must be drawn > against >  overloading the user with irrelevant data. >   > +@subsection Sometimes the user didn't write the code > + > +GCC is typically used in two different ways: > + > +@itemize @bullet > +@item > +Semi-interactive usage: GCC is used as a development tool when the > user > +is writing code, as the ``compile'' part of the ``edit-compile- > debug'' > +cycle.  The user is actively hacking on the code themself (perhaps a > +project they wrote, or someone else's), where they just made a > change > +to the code and want to see what happens, and to be warned about > +mistakes. > + > +@item > +Batch rebuilds: where the user is recompiling one or more existing > +packages, and GCC is a detail that's being invoked by various build > +scripts.  Examples include a user trying to bring up an operating > system > +consisting of hundreds of packages on a new CPU architecture, where > the > +packages were written by many different people, or simply rebuilding > +packages after a dependency changed, where the user is hoping > +``nothing breaks'', since they are unfamiliar with the code. > +@end itemize > + > +Keep both of these styles of usage in mind when implementing > diagnostics. > + >  @subsection Precision of Wording >   >  Provide the user with details that allow them to identify what the