tests: Add test of the sort function.

[goals.git] / docs / goals.pod

diff --git a/docs/goals.pod b/docs/goals.pod
index eca8876..e2b1af1 100644 (file)
--- a/docs/goals.pod
+++ b/docs/goals.pod
@@ -2,13 +2,13 @@
 
 =head1 NAME
 
-goals - an experimental tool that generalizes "make"
+goals - an experimental tool that generalizes “make”
 
 =head1 SUMMARY
 
  goals ['TARGET'] ['VAR=VALUE']
        [-C|--directory DIRECTORY] [-d] [-f|--file Goalfile]
-       [-I|--include DIRECTORY] [--no-prelude]
+       [-I|--include DIRECTORY] [-j|--jobs JOBS] [--no-prelude]
 
  goals --help
 
@@ -16,7 +16,19 @@ goals - an experimental tool that generalizes "make"
 
 =head1 DESCRIPTION
 
+Goals is a command line tool similar in concept to L<make(1)> — a way
+to express dependencies between tasks that need to be done.  Goals
+generalizes make so it can express dependencies between not just files
+but anything such as URLs, remote files, remote builds and more.  It
+is also very extensible using only shell scripting, and it fixes many
+problems that make suffers from.
 
+This manual page documents the command line tool and options.
+
+There is an introduction and tutorial on writing goal files:
+L<Goalfile(5)>.
+
+There is also a reference manual: L<goals-reference(5)>.
 
 =head1 OPTIONS
 
@@ -64,6 +76,15 @@ Note that if a relative path is given here, it is relative to the
 directory specified with the I<-C> option, or to the current directory
 if I<-C> was not used.
 
+=item B<-j> JOBS
+
+=item B<--jobs> JOBS
+
+Set the maximum number of commands that can run at the same time.
+Unlike make, goals defaults to running in parallel, setting the
+default to the number of cores on the machine.  To disable parallel
+jobs, you must use S<I<-j 1>>.
+
 =item B<--no-prelude>
 
 Do not load F<prelude.gl> from C<%stdlib>.  The default is that the