[document-jobserver-fds]: Reword the manual page

While the wording included in the manual page was not verbatim copying
from the source material, it was perhaps not distinct enough. The
manual page is not a copy/edit of the source material anymore, being
rewritten using different words and flow.

Signed-off-by: Manoj Srivastava <srivasta@debian.org>

1 files changed, 45 insertions, 45 deletions

diff --git a/make.1 b/make.1
index b61a5ad9..4192f247 100644
--- a/make.1
+++ b/make.1
@@ -373,67 +373,67 @@ programs are properly installed at your site, the command
 .PP
 should give you access to the complete manual.
 .SH "PARALLEL MAKE AND THE JOBSERVER"
-GNU make can invoke multiple commands, or
-.I jobs,
-in parallel.
+Using the
+.I -j
+option, the user can instruct
 .BR make
-may be told to run at most
-.B N
-jobs in parallel, where it will invoke between
-1 and
-.B N
-jobs, but never more than
-.B N.
+to execute tasks in parallel. By specifying a numeric argument to
+.I -j
+the user may specify an upper limit of the number of parallel tasks to
+be run.
 .PP
-In a recursive build environment, no one instance of
+When the build environment is such that a top level
 .BR make
-has enough information, enough
-.I global vision,
-to be able to know how many jobs are being run at any given moment across all the
-other instances of
-.BR make.
-.PP
-Rather than using complex schemes such as a central server, shared
-memory, sockets, etc. for synchronizing the various instances of make,
+invokes
+.BR sub-makes
+(for instance, a style in which each sub-directory contains its own
+.I Makefile
+), no individual instance of
+.BR make
+knows how many tasks are running in parallel, so keeping the number of
+tasks under the upper limit would be impossible without communication
+between all the
 .BR make
-uses a simple  pipe. The initial, top-level
+instances running. While solutions like having the top level
 .BR make
-creates a pipe and writes
+serve as a central controller are feasible, or using other
+synchronization mechanisms like shared memory or sockets can be
+created, the current implementation uses a simple shared pipe.
+.PP
+This pipe is created by the top-level
+.BR make
+process, and passed on to all the
+.BR sub-makes.
+The top level
+.BR make process writes
 .B N-1
 one-byte tokens into the pipe (The top level
 .BR make
-is assumed to reserve one token for iitself). That pipe is shared
-between that
+is assumed to reserve one token for itself). Whenever any of the
+.BR make
+processes (including the top-level
+.BR make
+) needs to run a new task, it reads a byte from the shared pipe. If
+there are no tokens left, it must wait for a token to be written back
+to the pipe. Once the task is completed, the
 .BR make
-and all
-.BR submakes,
-and any time any
+process writes a token back to the pipe (and thus, if the tokens had
+been exhausted, unblocking the first
 .BR make
-wants to run
-a job it first has to read a token from the pipe. Once the job is
-complete, it writes the token back to the pipe. Since there are only
+process that was waiting to read a token).  Since only
 .B N-1
-tokens, you know that you will never invoke more than
+tokens were written into the pipe, no more than
 .B N
-jobs.
+tasks can be running at any given time.
 .PP
 If the job to be run is not a
 .BR sub-make
-(determined the same way GNU
-make has always done so: by the absence of both the
-.B MAKE
-variable in the command script and the special prefix
-.B +
-before a line in the
-command script), then
+then
 .BR make
-will close the jobserver pipe file
-descriptors before invoking the commands. This ensures that no other
-commands will interrupt the jobserver processing, and it also ensures
-that commands that expect certain file
-descriptors to be available will not be disappointed. More details are
-available at
-.IR http://make.mad-scientist.net/papers/jobserver-implementation/
+will close the jobserver pipe file descriptors before invoking the
+commands, so that the command can not interfere with the
+.I jobserver,
+and the command does not find any unusual file descriptors.
 .SH BUGS
 See the chapter ``Problems and Bugs'' in
 .IR "The GNU Make Manual" .