@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
@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 (@i{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
@item @subcmd{LOCALE}
The encoding used by the system locale, or as overridden by the
@cmd{SET} command (@pxref{SET}). On GNU/Linux and other Unix-like systems,
-environment variables, e.g.@: @env{LANG} or @env{LC_ALL}, determine the
+environment variables, @i{e.g.}@: @env{LANG} or @env{LC_ALL}, determine the
system locale.
@item @var{charset_name}