X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=6549e94f2cd0c7c5651b35fc283fc3c8055d0388;hb=3fa740d165a0c2ef7c03b11633f65c421f07f0a2;hp=bca15ea53dac8fe0702ff2fb4041241f825257d7;hpb=facb4a1ad3c9e8b2cdf55824680eed2afb91aebe;p=pspp

diff --git a/doc/utilities.texi b/doc/utilities.texi
index bca15ea53d..6549e94f2c 100644
--- a/doc/utilities.texi
+++ b/doc/utilities.texi
@@ -90,18 +90,25 @@ CD 'new directory' .
 @vindex *
 
 @display
-Two possibles syntaxes:
-        COMMENT comment text @dots{} .
-        *comment text @dots{} .
+Comment commands:
+    COMMENT comment text @dots{} .
+    *comment text @dots{} .
+
+Comments within a line of syntax:
+    FREQUENCIES /VARIABLES=v0 v1 v2.  /* All our categorical variables.
 @end display
 
 @cmd{COMMENT} is ignored.  It is used to provide information to
 the author and other readers of the @pspp{} syntax file.
 
-@cmd{COMMENT} can extend over any number of lines.  Don't forget to
-terminate it with a dot or a blank line.
-
+@cmd{COMMENT} can extend over any number of lines.  It ends at a dot
+at the end of a line or a blank line.  The comment may contain any
+characters.
 
+PSPP also supports comments within a line of syntax, introduced with
+@samp{/*}.  These comments end at the first @samp{*/} or at the end of
+the line, whichever comes first.  A line that contains just this kind
+of comment is considered blank and ends the current command.
 
 @node DOCUMENT
 @section DOCUMENT
@@ -229,21 +236,51 @@ control to the operating system.
 @section HOST
 @vindex HOST
 
+In the syntax below, the square brackets must be included in the
+command syntax and do not indicate that that their contents are
+optional.
+
 @display
-HOST.
-HOST COMMAND=['@var{command}'...].
+HOST COMMAND=['@var{command}'...]
+     TIMELIMIT=@var{secs}.
 @end display
 
-@cmd{HOST} suspends the current @pspp{} session and temporarily returns control
-to the operating system.
-This command cannot be used if the SAFER (@pxref{SET}) setting is active.
+@cmd{HOST} executes one or more commands, each provided as a string in
+the required @subcmd{COMMAND} subcommand, in the shell of the
+underlying operating system.  PSPP runs each command in a separate
+shell process and waits for it to finish before running the next one.
+If a command fails (with a nonzero exit status, or because it is
+killed by a signal), then PSPP does not run any remaining commands.
+
+PSPP provides @file{/dev/null} as the shell's standard input.  If a
+process needs to read from stdin, redirect from a file or device, or
+use a pipe.
+
+PSPP displays the shell's standard output and standard error as PSPP
+output.  Redirect to a file or @code{/dev/null} or another device if
+this is not desired.
+
+The following example runs @code{rsync} to copy a file from a remote
+server to the local file @file{data.txt}, writing @code{rsync}'s own
+output to @file{rsync-log.txt}.  PSPP displays the command's error
+output, if any.  If @code{rsync} needs to prompt the user (e.g.@: to
+obtain a password), the command fails.  Only if the @code{rsync}
+succeeds, PSPP then runs the @code{sha512sum} command.
+
+@example
+HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt'
+              'sha512sum -c data.txt.sha512sum].
+@end example
+
+By default, PSPP waits as long as necessary for the series of commands
+to complete.  Use the optional @subcmd{TIMELIMIT} subcommand to limit
+the execution time to the specified number of seconds.
 
-If the @subcmd{COMMAND} subcommand is specified, as a sequence of shell
-commands as quoted strings within square brackets, then @pspp{} executes
-them together in a single subshell.
+PSPP built for mingw does not support all the features of
+@subcmd{HOST}.
 
-If no subcommands are specified, then @pspp{} invokes an interactive
-subshell.
+PSPP rejects this command if the SAFER (@pxref{SET}) setting is
+active.
 
 @node INCLUDE
 @section INCLUDE