Re: [bug #33138] .PARLLELSYNC enhancement with patch

[David Boyce]

On Sun, Apr 28, 2013 at 1:34 AM, Paul Smith <address@hidden> wrote:
> I'm not excited about that term ("job"); it's kind of accurate, but in
> the documentation for example we're really mushy about exactly what a
> "job" is, vs. a "recipe" or a "command line" etc.  I'd like to pick some
> terms for this, define them in a solid way, then clean up the
> references.  It would be best to do this before the release to avoid
> changing things later.
>
> For example, we currently use "target" as the name; maybe "recipe" is
> better?
>
> If anyone has opinions I'm listening.

This seems quite wrong to me. I think it's inherent from the existence
of the --jobs option that "job" must be synonymous with "recipe", even
if that's not what was intended at the time. Therefore my HO is that
not only does this one need a new name but "-O target" would be better
renamed "-O job".

What's wrong with "line" for the line-by-line case? It's exactly the
way make is documented, that each line of the recipe is fed to the
shell in turn, and the documentation you just wrote for the new
argument is all about lines; I see the word "line" 4 times in 2
sentences. The whole thing seems clear and well written to me, but
would be even more clear if the new option was called "-O line".

So I'd argue for:

-O line (new)
-O job (current -O target)
-O make

And document the notion that "job" and "recipe" are equivalent terms
(more precisely, one is the instantiation of the other: "job" is to
"recipe" what "process" is to "program").

I also think it wouldn't hurt for the documentation of the default to
contain a forward reference. Pending potential rename:

--- a/doc/make.texi
+++ b/doc/make.texi
@@ -4136,7 +4136,7 @@ specified by giving an argument to the option
(e.g.,  @samp{-Ojob} or
 @table @code
 @item none
 The is the default: all output is sent directly as it is generated and
-no synchronization is performed.
+no synchronization is performed. It is identical to @samp{--output-sync=target}

 @item job
 Output from each individual line of the recipe is grouped and printed

David