[PATCH] docs: add interactive vs batch distinction to UX guidelines

[David Malcolm]

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