From: Ben Pfaff Date: Fri, 9 May 2025 00:07:42 +0000 (-0700) Subject: work on manual X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=63a7a82298c3d178a63512cfbea87c2c33933182;p=pspp work on manual --- diff --git a/rust/doc/src/SUMMARY.md b/rust/doc/src/SUMMARY.md index 1654d2ebca..13814f6179 100644 --- a/rust/doc/src/SUMMARY.md +++ b/rust/doc/src/SUMMARY.md @@ -143,6 +143,23 @@ - [MATRIX DATA](commands/matrix/matrix-data.md) - [MCONVERT](commands/matrix/mconvert.md) - [MATRIX](commands/matrix/matrix.md) +- [Utilities](commands/utilities/index.md) + - [ADD DOCUMENT](commands/utilities/add-document.md) + - [CACHE](commands/utilities/cache.md) + - [CD](commands/utilities/cd.md) + - [COMMENT](commands/utilities/comment.md) + - [DOCUMENT](commands/utilities/document.md) + - [DISPLAY DOCUMENTS](commands/utilities/display-documents.md) + - [DISPLAY FILE LABEL](commands/utilities/display-file-label.md) + - [DROP DOCUMENTS](commands/utilities/drop-documents.md) + - [ECHO](commands/utilities/echo.md) + - [ERASE](commands/utilities/erase.md) + - [EXECUTE](commands/utilities/execute.md) + - [FILE LABEL](commands/utilities/file-label.md) + - [FINISH](commands/utilities/finish.md) + - [HOST](commands/utilities/host.md) + - [INCLUDE](commands/utilities/include.md) + - [INSERT](commands/utilities/insert.md) # Developer Documentation diff --git a/rust/doc/src/commands/utilities/add-document.md b/rust/doc/src/commands/utilities/add-document.md new file mode 100644 index 0000000000..a931ae21d5 --- /dev/null +++ b/rust/doc/src/commands/utilities/add-document.md @@ -0,0 +1,16 @@ +# ADD DOCUMENT + +``` +ADD DOCUMENT + 'line one' 'line two' ... 'last line' . +``` + +`ADD DOCUMENT` adds one or more lines of descriptive commentary to +the active dataset. Documents added in this way are saved to system +files. They can be viewed using `SYSFILE INFO` or `DISPLAY DOCUMENTS`. +They can be removed from the active dataset with `DROP DOCUMENTS`. + +Each line of documentary text must be enclosed in quotation marks, and +may not be more than 80 bytes long. See also +[`DOCUMENT`](document.md). + diff --git a/rust/doc/src/commands/utilities/cache.md b/rust/doc/src/commands/utilities/cache.md new file mode 100644 index 0000000000..acd61c9435 --- /dev/null +++ b/rust/doc/src/commands/utilities/cache.md @@ -0,0 +1,8 @@ +# CACHE + +``` +CACHE. +``` + +This command is accepted, for compatibility, but it has no effect. + diff --git a/rust/doc/src/commands/utilities/cd.md b/rust/doc/src/commands/utilities/cd.md new file mode 100644 index 0000000000..74bf3ade93 --- /dev/null +++ b/rust/doc/src/commands/utilities/cd.md @@ -0,0 +1,9 @@ +# CD + +``` +CD 'new directory' . +``` + +`CD` changes the current directory. The new directory becomes that +specified by the command. + diff --git a/rust/doc/src/commands/utilities/comment.md b/rust/doc/src/commands/utilities/comment.md new file mode 100644 index 0000000000..00b3322b12 --- /dev/null +++ b/rust/doc/src/commands/utilities/comment.md @@ -0,0 +1,23 @@ +# COMMENT + +``` +Comment commands: + COMMENT comment text ... . + *comment text ... . + +Comments within a line of syntax: + FREQUENCIES /VARIABLES=v0 v1 v2. /* All our categorical variables. +``` + +`COMMENT` is ignored. It is used to provide information to the +author and other readers of the PSPP syntax file. + +`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 +`/*`. These comments end at the first `*/` 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. + diff --git a/rust/doc/src/commands/utilities/display-documents.md b/rust/doc/src/commands/utilities/display-documents.md new file mode 100644 index 0000000000..0f679447cb --- /dev/null +++ b/rust/doc/src/commands/utilities/display-documents.md @@ -0,0 +1,10 @@ +# DISPLAY DOCUMENTS + +``` +DISPLAY DOCUMENTS. +``` + +`DISPLAY DOCUMENTS` displays the documents in the active dataset. +Each document is preceded by a line giving the time and date that it +was added. See also [`DOCUMENT`](document.md). + diff --git a/rust/doc/src/commands/utilities/display-file-label.md b/rust/doc/src/commands/utilities/display-file-label.md new file mode 100644 index 0000000000..7eb51cccab --- /dev/null +++ b/rust/doc/src/commands/utilities/display-file-label.md @@ -0,0 +1,11 @@ +# DISPLAY FILE LABEL + +``` +DISPLAY FILE LABEL. +``` + +`DISPLAY FILE LABEL` displays the file label contained in the active +dataset, if any. See also [`FILE LABEL`](file-label.md). + +This command is a PSPP extension. + diff --git a/rust/doc/src/commands/utilities/document.md b/rust/doc/src/commands/utilities/document.md new file mode 100644 index 0000000000..58a74a02a2 --- /dev/null +++ b/rust/doc/src/commands/utilities/document.md @@ -0,0 +1,20 @@ +# DOCUMENT + +``` +DOCUMENT DOCUMENTARY_TEXT. +``` + +`DOCUMENT` adds one or more lines of descriptive commentary to the +active dataset. Documents added in this way are saved to system +files. They can be viewed using `SYSFILE INFO` or [`DISPLAY +DOCUMENTS`](display-documents.md). They can be removed from the +active dataset with [`DROP DOCUMENTS`](drop-documents.md). + +Specify the text of the document following the `DOCUMENT` keyword. It +is interpreted literally—any quotes or other punctuation marks are +included in the file. You can extend the documentary text over as +many lines as necessary, including blank lines to separate paragraphs. +Lines are truncated at 80 bytes. Don't forget to terminate the +command with a dot at the end of a line. See also [ADD +DOCUMENT](add-document.md). + diff --git a/rust/doc/src/commands/utilities/drop-documents.md b/rust/doc/src/commands/utilities/drop-documents.md new file mode 100644 index 0000000000..b5dd7608bd --- /dev/null +++ b/rust/doc/src/commands/utilities/drop-documents.md @@ -0,0 +1,12 @@ +# DROP DOCUMENTS + +``` +DROP DOCUMENTS. +``` + +`DROP DOCUMENTS` removes all documents from the active dataset. New +documents can be added with [`DOCUMENT`](document.md). + +`DROP DOCUMENTS` changes only the active dataset. It does not modify +any system files stored on disk. + diff --git a/rust/doc/src/commands/utilities/echo.md b/rust/doc/src/commands/utilities/echo.md new file mode 100644 index 0000000000..d868940d4e --- /dev/null +++ b/rust/doc/src/commands/utilities/echo.md @@ -0,0 +1,10 @@ +# ECHO + +``` +ECHO 'arbitrary text' . +``` + +Use `ECHO` to write arbitrary text to the output stream. The text +should be enclosed in quotation marks following the normal rules for +[string tokens](../../language/basics/tokens.md#strings). + diff --git a/rust/doc/src/commands/utilities/erase.md b/rust/doc/src/commands/utilities/erase.md new file mode 100644 index 0000000000..0e2f6cc16c --- /dev/null +++ b/rust/doc/src/commands/utilities/erase.md @@ -0,0 +1,10 @@ +# ERASE + +``` +ERASE FILE "FILE_NAME". +``` + +`ERASE FILE` deletes a file from the local file system. The file's +name must be quoted. This command cannot be used if the SAFER (*note +SET::) setting is active. + diff --git a/rust/doc/src/commands/utilities/execute.md b/rust/doc/src/commands/utilities/execute.md new file mode 100644 index 0000000000..b269ef63bb --- /dev/null +++ b/rust/doc/src/commands/utilities/execute.md @@ -0,0 +1,9 @@ +# EXECUTE + +``` +EXECUTE. +``` + +`EXECUTE` causes the active dataset to be read and all pending +transformations to be executed. + diff --git a/rust/doc/src/commands/utilities/file-label.md b/rust/doc/src/commands/utilities/file-label.md new file mode 100644 index 0000000000..9aa87a6c58 --- /dev/null +++ b/rust/doc/src/commands/utilities/file-label.md @@ -0,0 +1,13 @@ +# FILE LABEL + +``` +FILE LABEL file label. +``` + +`FILE LABEL` provides a title for the active dataset. This title is +saved into system files and portable files that are created during +this PSPP run. + +The file label should not be quoted. If quotes are included, they are +become part of the file label. + diff --git a/rust/doc/src/commands/utilities/finish.md b/rust/doc/src/commands/utilities/finish.md new file mode 100644 index 0000000000..702e755992 --- /dev/null +++ b/rust/doc/src/commands/utilities/finish.md @@ -0,0 +1,9 @@ +# FINISH + +``` +FINISH. +``` + +`FINISH` terminates the current PSPP session and returns control to +the operating system. + diff --git a/rust/doc/src/commands/utilities/host.md b/rust/doc/src/commands/utilities/host.md new file mode 100644 index 0000000000..bdc6e5e176 --- /dev/null +++ b/rust/doc/src/commands/utilities/host.md @@ -0,0 +1,48 @@ +# 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. + +``` +HOST COMMAND=['COMMAND'...] + TIMELIMIT=SECS. +``` + +`HOST` executes one or more commands, each provided as a string in +the required `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 `/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 `/dev/null` or another device if this is +not desired. + +By default, PSPP waits as long as necessary for the series of +commands to complete. Use the optional `TIMELIMIT` subcommand to limit +the execution time to the specified number of seconds. + +PSPP built for mingw does not support all the features of `HOST`. + +PSPP rejects this command if the SAFER (*note SET::) setting is +active. + +## Example + +The following example runs `rsync` to copy a file from a remote +server to the local file `data.txt`, writing `rsync`'s own output to +`rsync-log.txt`. PSPP displays the command's error output, if any. If +`rsync` needs to prompt the user (e.g. to obtain a password), the +command fails. Only if the `rsync` succeeds, PSPP then runs the +`sha512sum` command. + +``` +HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt' + 'sha512sum -c data.txt.sha512sum]. +``` + diff --git a/rust/doc/src/commands/utilities/include.md b/rust/doc/src/commands/utilities/include.md new file mode 100644 index 0000000000..5de38ada66 --- /dev/null +++ b/rust/doc/src/commands/utilities/include.md @@ -0,0 +1,19 @@ +# INCLUDE + +``` +INCLUDE [FILE=]'FILE_NAME' [ENCODING='ENCODING']. +``` + +`INCLUDE` causes the PSPP command processor to read an additional +command file as if it were included bodily in the current command file. +If errors are encountered in the included file, then command processing +stops and no more commands are processed. Include files may be nested +to any depth, up to the limit of available memory. + +The [`INSERT`](insert.md) command is a more flexible alternative to +`INCLUDE`. An `INCLUDE` command acts the same as `INSERT` with +`ERROR=STOP CD=NO SYNTAX=BATCH` specified. + +The optional `ENCODING` subcommand has the same meaning as with +`INSERT`. + diff --git a/rust/doc/src/commands/utilities/index.md b/rust/doc/src/commands/utilities/index.md new file mode 100644 index 0000000000..08ddbfcbd5 --- /dev/null +++ b/rust/doc/src/commands/utilities/index.md @@ -0,0 +1,7 @@ +# Utility Commands + +This chapter describes commands that don't fit in other categories. + +Most of these commands are not affected by commands like `IF` and +`LOOP`: they take effect only once, unconditionally, at the time that +they are encountered in the input. diff --git a/rust/doc/src/commands/utilities/insert.md b/rust/doc/src/commands/utilities/insert.md new file mode 100644 index 0000000000..efe132cfa9 --- /dev/null +++ b/rust/doc/src/commands/utilities/insert.md @@ -0,0 +1,69 @@ +# INSERT + +``` +INSERT [FILE=]'FILE_NAME' + [CD={NO,YES}] + [ERROR={CONTINUE,STOP}] + [SYNTAX={BATCH,INTERACTIVE}] + [ENCODING={LOCALE, 'CHARSET_NAME'}]. +``` + +`INSERT` is similar to [`INCLUDE`](include.md) but more flexible. It +causes the command processor to read a file as if it were embedded in +the current command file. + +If `CD=YES` is specified, then before including the file, the current +directory becomes the directory of the included file. The default +setting is `CD=NO`. Note that this directory remains current until it +is changed explicitly (with the `CD` command, or a subsequent `INSERT` +command with the `CD=YES` option). It does not revert to its original +setting even after the included file is finished processing. + +If `ERROR=STOP` is specified, errors encountered in the inserted file +causes processing to immediately cease. Otherwise processing continues +at the next command. The default setting is `ERROR=CONTINUE`. + +If `SYNTAX=INTERACTIVE` is specified then the syntax contained in the +included file must conform to [interactive syntax +conventions](../../language/basics/syntax-variants.md). The default +setting is `SYNTAX=BATCH`. + +`ENCODING` optionally specifies the character set used by the +included file. Its argument, which is not case-sensitive, must be in +one of the following forms: + +* `LOCALE` + The encoding used by the system locale, or as overridden by the + `SET` command (*note SET::). On GNU/Linux and other Unix-like + systems, environment variables, e.g. `LANG` or `LC_ALL`, determine + the system locale. + +* `'CHARSET_NAME'` + An [IANA character set + name](http://www.iana.org/assignments/character-sets). Some + examples are `ASCII` (United States), `ISO-8859-1` (western Europe), + `EUC-JP` (Japan), and `windows-1252` (Windows). Not all systems + support all character sets. + +* `Auto,ENCODING` + Automatically detects whether a syntax file is encoded in a Unicode + encoding such as UTF-8, UTF-16, or UTF-32. If it is not, then PSPP + generally assumes that the file is encoded in `ENCODING` (an IANA + character set name). However, if `ENCODING` is UTF-8, and the + syntax file is not valid UTF-8, PSPP instead assumes that the file + is encoded in `windows-1252`. + + For best results, `ENCODING` should be an ASCII-compatible encoding + (the most common locale encodings are all ASCII-compatible), + because encodings that are not ASCII compatible cannot be + automatically distinguished from UTF-8. + +* `Auto` + `Auto,Locale` + Automatic detection, as above, with the default encoding taken from + the system locale or the setting on `SET LOCALE`. + +When `ENCODING` is not specified, the default is taken from the +`--syntax-encoding` command option, if it was specified, and otherwise +it is `Auto`. +