From 42af8d7afa39c0277071aac1fb90d59235465fa8 Mon Sep 17 00:00:00 2001 From: John Darrington Date: Wed, 28 Mar 2012 22:36:55 +0200 Subject: [PATCH] Documentation: New markup for subcommands --- doc/combining.texi | 62 ++++++------- doc/data-io.texi | 80 ++++++++--------- doc/files.texi | 154 ++++++++++++++++---------------- doc/flow-control.texi | 33 +++---- doc/pspp.texinfo | 10 ++- doc/regression.texi | 12 +-- doc/statistics.texi | 192 ++++++++++++++++++++-------------------- doc/transformation.texi | 8 +- doc/utilities.texi | 6 +- doc/variables.texi | 26 +++--- 10 files changed, 297 insertions(+), 286 deletions(-) diff --git a/doc/combining.texi b/doc/combining.texi index 1f31ff64aa..3e2fa3c22d 100644 --- a/doc/combining.texi +++ b/doc/combining.texi @@ -66,14 +66,14 @@ The syntax of each command begins with a specification of the files to be read as input. For each input file, specify FILE with a system file or portable file's name as a string, a dataset (@pxref{Datasets}) or file handle name, (@pxref{File Handles}), or an asterisk (@samp{*}) -to use the active dataset as input. Use of portable files on FILE is a +to use the active dataset as input. Use of portable files on @subcmd{FILE} is a @pspp{} extension. -At least two FILE subcommands must be specified. If the active dataset +At least two @subcmd{FILE} subcommands must be specified. If the active dataset is used as an input source, then @cmd{TEMPORARY} must not be in effect. -Each FILE subcommand may be followed by any number of RENAME +Each @subcmd{FILE} subcommand may be followed by any number of @subcmd{RENAME} subcommands that specify a parenthesized group or groups of variable names as they appear in the input file, followed by those variables' new names, separated by an equals sign (@samp{=}), @@ -83,17 +83,17 @@ Within a parenthesized group, variables are renamed simultaneously, so that @samp{/RENAME=(A B=B A)} exchanges the names of variables A and B. Otherwise, renaming occurs in left-to-right order. -Each FILE subcommand may optionally be followed by a single IN +Each @subcmd{FILE} subcommand may optionally be followed by a single @subcmd{IN} subcommand, which creates a numeric variable with the specified name and format F1.0. The IN variable takes value 1 in an output case if the given input file contributed to that output case, and 0 otherwise. -The DROP, KEEP, and RENAME subcommands have no effect on IN variables. +The @subcmd{DROP}, @subcmd{KEEP}, and @subcmd{RENAME} subcommands have no effect on IN variables. If BY is used (see below), the SORT keyword must be specified after a -FILE if that input file is not already sorted on the BY variables. -When SORT is specified, @pspp{} sorts the input file's data on the BY +@subcmd{FILE} if that input file is not already sorted on the BY variables. +When @subcmd{SORT} is specified, @pspp{} sorts the input file's data on the BY variables before it applies it to the command. When SORT is used, BY -is required. SORT is a @pspp{} extension. +is required. @subcmd{SORT} is a @pspp{} extension. @pspp{} merges the dictionaries of all of the input files to form the dictionary of the new active dataset, like so: @@ -106,8 +106,8 @@ contains a variable with a given name, the output file will contain exactly that variable. When more than one input file contains a variable with a given name, those variables must all have the same type (numeric or string) and, for string variables, the same width. -Variables are matched after renaming with the RENAME subcommand. -Thus, RENAME can be used to resolve conflicts. +Variables are matched after renaming with the @subcmd{RENAME} subcommand. +Thus, @subcmd{RENAME} can be used to resolve conflicts. @item The variable label for each output variable is taken from the first @@ -121,7 +121,7 @@ first specified FILE that has a file label. @item The documents in the new active dataset (@pxref{DOCUMENT}) are the concatenation of all the input files' documents, in the order in which -the FILE subcommands are specified. +the @subcmd{FILE} subcommands are specified. @item If all of the input files are weighted on the same variable, then the @@ -141,26 +141,26 @@ variables, then SORT must be specified for those input files. The variables listed on BY may include (A) or (D) annotations to specify ascending or descending sort order. @xref{SORT CASES}, for -more details on this notation. Adding (A) or (D) to the BY subcommand +more details on this notation. Adding (A) or (D) to the @subcmd{BY} subcommand specification is a @pspp{} extension. -The DROP subcommand can be used to specify a list of variables to -exclude from the output. By contrast, the KEEP subcommand can be used +The @subcmd{DROP} subcommand can be used to specify a list of variables to +exclude from the output. By contrast, the @subcmd{KEEP} subcommand can be used to specify variables to include in the output; all variables not listed are dropped. DROP and KEEP are executed in left-to-right order and may be repeated any number of times. DROP and KEEP do not affect -variables created by the IN, FIRST, and LAST subcommands, which are +variables created by the IN, FIRST, and @subcmd{LAST} subcommands, which are always included in the new active dataset, but they can be used to drop BY variables. -The FIRST and LAST subcommands are optional. They may only be +The @subcmd{FIRST} and @subcmd{LAST} subcommands are optional. They may only be specified on @cmd{MATCH FILES} and @cmd{ADD FILES}, and only when BY -is used. FIRST and LIST each adds a numeric variable to the new +is used. @subcmd{FIRST} and @subcmd{LIST} each adds a numeric variable to the new active dataset, with the name given as the subcommand's argument and F1.0 -print and write formats. The value of the FIRST variable is 1 in the +print and write formats. The value of the @subcmd{FIRST} variable is 1 in the first output case with a given set of values for the BY variables, and -0 in other cases. Similarly, the LAST variable is 1 in the last case -with a given of BY values, and 0 in other cases. +0 in other cases. Similarly, the @subcmd{LAST} variable is 1 in the last case +with a given of @subcmd{BY} values, and 0 in other cases. When any of these commands creates an output case, variables that are only in files that are not present for the current case are set to the @@ -193,16 +193,16 @@ Once per command: which replaces the active dataset, consists all of the cases in all of the input files. -ADD FILES shares the bulk of its syntax with other @pspp{} commands for +@subcmd{ADD FILES} shares the bulk of its syntax with other @pspp{} commands for combining multiple data files. @xref{Combining Files Common Syntax}, above, for an explanation of this common syntax. -When BY is not used, the output of ADD FILES consists of all the cases +When @subcmd{BY} is not used, the output of @subcmd{ADD FILES} consists of all the cases from the first input file specified, followed by all the cases from the second file specified, and so on. When BY is used, the output is additionally sorted on the BY variables. -When ADD FILES creates an output case, variables that are not part of +When @subcmd{ADD FILES} creates an output case, variables that are not part of the input file from which the case was drawn are set to the system-missing value for numeric variables or spaces for string variables. @@ -251,13 +251,13 @@ to cases output after their input has been exhausted. If BY is used, MATCH FILES combines cases from each input file that have identical values for the BY variables. -When BY is used, TABLE subcommands may be used to introduce @dfn{table -lookup file}. TABLE has same syntax as FILE, and the RENAME, IN, and -SORT subcommands may follow a TABLE in the same way as a FILE. +When BY is used, @subcmd{TABLE} subcommands may be used to introduce @dfn{table +lookup file}. @subcmd{TABLE} has same syntax as @subcmd{FILE}, and the @subcmd{RENAME}, @subcmd{IN}, and +@subcmd{SORT} subcommands may follow a TABLE in the same way as a FILE. Regardless of the number of TABLEs, at least one FILE must specified. Table lookup files are treated in the same way as other input files for most purposes and, in particular, table lookup files must be -sorted on the BY variables or the SORT subcommand must be specified +sorted on the BY variables or the @subcmd{SORT} subcommand must be specified for that TABLE. Cases in table lookup files are not consumed after they have been used @@ -297,17 +297,17 @@ Once per command: @cmd{UPDATE} updates a @dfn{master file} by applying modifications from one or more @dfn{transaction files}. -UPDATE shares the bulk of its syntax with other @pspp{} commands for +@cmd{UPDATE} shares the bulk of its syntax with other @pspp{} commands for combining multiple data files. @xref{Combining Files Common Syntax}, above, for an explanation of this common syntax. -At least two FILE subcommands must be specified. The first FILE +At least two @subcmd{FILE} subcommands must be specified. The first @subcmd{FILE} subcommand names the master file, and the rest name transaction files. Every input file must either be sorted on the variables named on the -BY subcommand, or the SORT subcommand must be used just after the FILE +@subcmd{BY} subcommand, or the @subcmd{SORT} subcommand must be used just after the @subcmd{FILE} subcommand for that input file. -UPDATE uses the variables specified on the BY subcommand, which is +@cmd{UPDATE} uses the variables specified on the @subcmd{BY} subcommand, which is required, to attempt to match each case in a transaction file with a case in the master file: diff --git a/doc/data-io.texi b/doc/data-io.texi index dc916424a8..2fffbb71fe 100644 --- a/doc/data-io.texi +++ b/doc/data-io.texi @@ -102,7 +102,7 @@ attributes associated with the active dataset. Custom data file attributes are not interpreted by @pspp{}, but they are saved as part of system files and may be used by other software that reads them. -Use the ATTRIBUTE subcommand to add or modify a custom data file +Use the @subcmd{ATTRIBUTE} subcommand to add or modify a custom data file attribute. Specify the name of the attribute as an identifier (@pxref{Tokens}), followed by the desired value, in parentheses, as a quoted string. Attribute names that begin with @code{$} are reserved @@ -116,7 +116,7 @@ element, add an integer array index enclosed in square brackets indexes start at 1, not 0. An attribute array that has a single element (number 1) is not distinguished from a non-array attribute. -Use the DELETE subcommand to delete an attribute. Specify an +Use the @subcmd{DELETE} subcommand to delete an attribute. Specify an attribute name by itself to delete an entire attribute, including all array elements for attribute arrays. Specify an attribute name followed by an array index in square brackets to delete a single @@ -187,9 +187,9 @@ all datasets except for the active dataset, which becomes unnamed. @vindex DATASET DISPLAY The DATASET DISPLAY command lists all the currently defined datasets. -Many DATASET commands accept an optional WINDOW subcommand. In the +Many DATASET commands accept an optional @subcmd{WINDOW} subcommand. In the @pspp{}IRE GUI, the value given for this subcommand influences how the -dataset's window is displayed. Outside the GUI, the WINDOW subcommand +dataset's window is displayed. Outside the GUI, the @subcmd{WINDOW} subcommand has no effect. The valid values are: @table @asis @@ -267,28 +267,28 @@ where each var_spec takes one of the forms positions on each line of single-line or multiline records. The keyword FIXED is optional. -The FILE subcommand must be used if input is to be taken from an +The @subcmd{FILE} subcommand must be used if input is to be taken from an external file. It may be used to specify a file name as a string or a -file handle (@pxref{File Handles}). If the FILE subcommand is not used, +file handle (@pxref{File Handles}). If the @subcmd{FILE} subcommand is not used, then input is assumed to be specified within the command file using @cmd{BEGIN DATA}@dots{}@cmd{END DATA} (@pxref{BEGIN DATA}). -The ENCODING subcommand may only be used if the FILE subcommand is also used. +The @subcmd{ENCODING} subcommand may only be used if the @subcmd{FILE} subcommand is also used. It specifies the character encoding of the file. -The optional RECORDS subcommand, which takes a single integer as an +The optional @subcmd{RECORDS} subcommand, which takes a single integer as an argument, is used to specify the number of lines per record. If RECORDS is not specified, then the number of lines per record is calculated from the list of variable specifications later in @cmd{DATA LIST}. -The END subcommand is only useful in conjunction with @cmd{INPUT +The @subcmd{END} subcommand is only useful in conjunction with @cmd{INPUT PROGRAM}. @xref{INPUT PROGRAM}, for details. -The optional SKIP subcommand specifies a number of records to skip at +The optional @subcmd{SKIP} subcommand specifies a number of records to skip at the beginning of an input file. It can be used to skip over a row that contains variable names, for example. @cmd{DATA LIST} can optionally output a table describing how the data file -will be read. The TABLE subcommand enables this output, and NOTABLE +will be read. The @subcmd{TABLE} subcommand enables this output, and @subcmd{NOTABLE} disables it. The default is to output the table. The list of variables to be read from the data list must come last. @@ -494,10 +494,10 @@ fields. Furthermore, leading spaces at the beginnings of fields are not trimmed, consecutive delimiters define empty fields, and no form of quoting is allowed. -The NOTABLE and TABLE subcommands are as in @cmd{DATA LIST FIXED} above. -NOTABLE is the default. +The @subcmd{NOTABLE} and @subcmd{TABLE} subcommands are as in @cmd{DATA LIST FIXED} above. +@subcmd{NOTABLE} is the default. -The FILE and SKIP subcommands are as in @cmd{DATA LIST FIXED} above. +The @subcmd{FILE} and @subcmd{SKIP} subcommands are as in @cmd{DATA LIST FIXED} above. The variables to be parsed are given as a single list of variable names. This list must be introduced by a single slash (@samp{/}). The set of @@ -648,7 +648,7 @@ input or output, using an ASCII/EBCDIC translation that is one-to-one, so that a ``round trip'' from ASCII to EBCDIC back to ASCII, or vice versa, always yields exactly the original data. -The RECFORM subcommand is required in mode 360. The precise file +The @subcmd{RECFORM} subcommand is required in mode 360. The precise file format depends on its setting: @table @asis @@ -716,7 +716,7 @@ these fields are effectively padded with character @code{X'80'}. This wart is implemented for compatibility. @end itemize -The NAME subcommand specifies the name of the file associated with the +The @subcmd{NAME} subcommand specifies the name of the file associated with the handle. It is required in all modes but SCRATCH mode, in which its use is forbidden. @@ -748,7 +748,7 @@ stop when end of file is reached on any of the data files. To prevent @cmd{INPUT PROGRAM} from terminating at the first end of file, use -the END subcommand on @cmd{DATA LIST}. This subcommand takes a +the @subcmd{END} subcommand on @cmd{DATA LIST}. This subcommand takes a variable name, which should be a numeric scratch variable (@pxref{Scratch Variables}). (It need not be a scratch variable but otherwise the results can be @@ -762,7 +762,7 @@ structure produces one case. @cmd{END CASE} controls exactly when cases are output. When @cmd{END CASE} is used, looping from the end of @cmd{INPUT PROGRAM} to the beginning does not cause a case to be output. -@cmd{END FILE} is the second. When the END subcommand is used on @cmd{DATA +@cmd{END FILE} is the second. When the @subcmd{END} subcommand is used on @cmd{DATA LIST}, there is no way for the @cmd{INPUT PROGRAM} construct to stop looping, so an infinite loop results. @cmd{END FILE}, when executed, @@ -895,17 +895,17 @@ LIST The @cmd{LIST} procedure prints the values of specified variables to the listing file. -The VARIABLES subcommand specifies the variables whose values are to be -printed. Keyword VARIABLES is optional. If VARIABLES subcommand is not +The @subcmd{VARIABLES} subcommand specifies the variables whose values are to be +printed. Keyword VARIABLES is optional. If @subcmd{VARIABLES} subcommand is not specified then all variables in the active dataset are printed. -The CASES subcommand can be used to specify a subset of cases to be +The @subcmd{CASES} subcommand can be used to specify a subset of cases to be printed. Specify FROM and the case number of the first case to print, TO and the case number of the last case to print, and BY and the number of cases to advance between printing cases, or any subset of those settings. If CASES is not specified then all cases are printed. -The FORMAT subcommand can be used to change the output format. NUMBERED +The @subcmd{FORMAT} subcommand can be used to change the output format. NUMBERED will print case numbers along with each case; UNNUMBERED, the default, causes the case numbers to be omitted. The WRAP and SINGLE settings are currently not used. @@ -956,18 +956,18 @@ print variable data without invoking a procedure (@pxref{EXECUTE}). All @cmd{PRINT} subcommands are optional. If no strings or variables are specified, PRINT outputs a single blank line. -The OUTFILE subcommand specifies the file to receive the output. The +The @subcmd{OUTFILE} subcommand specifies the file to receive the output. The file may be a file name as a string or a file handle (@pxref{File Handles}). If OUTFILE is not present then output will be sent to @pspp{}'s output listing file. When OUTFILE is present, a space is inserted at beginning of each output line, even lines that otherwise would be blank. -The RECORDS subcommand specifies the number of lines to be output. The +The @subcmd{RECORDS} subcommand specifies the number of lines to be output. The number of lines may optionally be surrounded by parentheses. -TABLE will cause the PRINT command to output a table to the listing file -that describes what it will print to the output file. NOTABLE, the +@subcmd{TABLE} will cause the @cmd{PRINT} command to output a table to the listing file +that describes what it will print to the output file. @subcmd{NOTABLE}, the default, suppresses this output table. Introduce the strings and variables to be printed with a slash @@ -1020,10 +1020,10 @@ way as @cmd{PRINT}. All @cmd{PRINT EJECT} subcommands are optional. -Without OUTFILE, PRINT EJECT ejects the current page in +Without @subcmd{OUTFILE}, @cmd{PRINT EJECT} ejects the current page in the listing file, then it produces other output, if any is specified. -With OUTFILE, PRINT EJECT writes its output to the specified file. +With @subcmd{OUTFILE}, @cmd{PRINT EJECT} writes its output to the specified file. The first line of output is written with @samp{1} inserted in the first column. Commonly, this is the only line of output. If additional lines of output are specified, these additional lines are @@ -1041,7 +1041,7 @@ PRINT SPACE OUTFILE='file-name' n_lines. @cmd{PRINT SPACE} prints one or more blank lines to an output file. -The OUTFILE subcommand is optional. It may be used to direct output to +The @subcmd{OUTFILE} subcommand is optional. It may be used to direct output to a file specified by file name as a string or file handle (@pxref{File Handles}). If OUTFILE is not specified then output will be directed to the listing file. @@ -1063,14 +1063,14 @@ data file already processed by @cmd{DATA LIST} or another input command to be re-read for further processing. -The FILE subcommand, which is optional, is used to specify the file to +The @subcmd{FILE} subcommand, which is optional, is used to specify the file to have its line re-read. The file must be specified as the name of a file handle (@pxref{File Handles}). If FILE is not specified then the last file specified on @cmd{DATA LIST} will be assumed (last file specified lexically, not in terms of flow-of-control). By default, the line re-read is re-read in its entirety. With the -COLUMN subcommand, a prefix of the line can be exempted from +@subcmd{COLUMN} subcommand, a prefix of the line can be exempted from re-reading. Specify an expression (@pxref{Expressions}) evaluating to the first column that should be included in the re-read line. Columns are numbered from 1 at the left margin. @@ -1106,7 +1106,7 @@ When used with @cmd{DATA LIST}, it can be used to parse groups of cases that share a subset of variables but differ in their other data. -The STARTS subcommand is required. Specify a range of columns, using +The @subcmd{STARTS} subcommand is required. Specify a range of columns, using literal numbers or numeric variable names. This range specifies the columns on the first line that are used to contain groups of data. The ending column is optional. If it is not specified, then the record @@ -1114,11 +1114,11 @@ width of the input file is used. For the inline file (@pxref{BEGIN DATA}) this is 80 columns; for a file with fixed record widths it is the record width; for other files it is 1024 characters by default. -The OCCURS subcommand is required. It must be a number or the name of a +The @subcmd{OCCURS} subcommand is required. It must be a number or the name of a numeric variable. Its value is the number of groups present in the current record. -The DATA subcommand is required. It must be the last subcommand +The @subcmd{DATA} subcommand is required. It must be the last subcommand specified. It is used to specify the data present within each repeating group. Column numbers are specified relative to the beginning of a group at column 1. Data is specified in the same way as with @cmd{DATA LIST @@ -1132,23 +1132,23 @@ default is the last file handle used on @cmd{DATA LIST} (lexically, not in terms of flow of control). By default @cmd{REPEATING DATA} will output a table describing how it will -parse the input data. Specifying NOTABLE will disable this behavior; +parse the input data. Specifying @subcmd{NOTABLE} will disable this behavior; specifying TABLE will explicitly enable it. -The LENGTH subcommand specifies the length in characters of each group. -If it is not present then length is inferred from the DATA subcommand. +The @subcmd{LENGTH} subcommand specifies the length in characters of each group. +If it is not present then length is inferred from the @subcmd{DATA} subcommand. LENGTH can be a number or a variable name. Normally all the data groups are expected to be present on a single -line. Use the CONTINUED command to indicate that data can be continued +line. Use the @subcmd{CONTINUED} command to indicate that data can be continued onto additional lines. If data on continuation lines starts at the left margin and continues through the entire field width, no column -specifications are necessary on CONTINUED. Otherwise, specify the +specifications are necessary on @subcmd{CONTINUED}. Otherwise, specify the possible range of columns in the same way as on STARTS. When data groups are continued from line to line, it is easy for cases to get out of sync through careless hand editing. The -ID subcommand allows a case identifier to be present on each line of +@subcmd{ID} subcommand allows a case identifier to be present on each line of repeating data groups. @cmd{REPEATING DATA} will check for the same identifier on each line and report mismatches. Specify the range of columns that the identifier will occupy, followed by an equals sign diff --git a/doc/files.texi b/doc/files.texi index a68e0031d7..3f8a31a1dc 100644 --- a/doc/files.texi +++ b/doc/files.texi @@ -103,7 +103,7 @@ The @cmd{EXPORT} procedure writes the active dataset's dictionary and data to a specified portable file. By default, cases excluded with FILTER are written to the -file. These can be excluded by specifying DELETE on the UNSELECTED +file. These can be excluded by specifying DELETE on the @subcmd{UNSELECTED} subcommand. Specifying RETAIN makes the default explicit. Portable files express real numbers in base 30. Integers are always @@ -111,21 +111,21 @@ expressed to the maximum precision needed to make them exact. Non-integers are, by default, expressed to the machine's maximum natural precision (approximately 15 decimal digits on many machines). If many numbers require this many digits, the portable file may -significantly increase in size. As an alternative, the DIGITS +significantly increase in size. As an alternative, the @subcmd{DIGITS} subcommand may be used to specify the number of decimal digits of precision to write. DIGITS applies only to non-integers. -The OUTFILE subcommand, which is the only required subcommand, specifies +The @subcmd{OUTFILE} subcommand, which is the only required subcommand, specifies the portable file to be written as a file name string or a file handle (@pxref{File Handles}). -DROP, KEEP, and RENAME follow the same format as the SAVE procedure -(@pxref{SAVE}). +@subcmd{DROP}, @subcmd{KEEP}, and @subcmd{RENAME} follow the same format as the +@subcmd{SAVE} procedure (@pxref{SAVE}). -The TYPE subcommand specifies the character set for use in the +The @subcmd{TYPE} subcommand specifies the character set for use in the portable file. Its value is currently not used. -The MAP subcommand is currently ignored. +The @subcmd{MAP} subcommand is currently ignored. @cmd{EXPORT} is a procedure. It causes the active dataset to be read. @@ -145,29 +145,29 @@ GET @cmd{GET} clears the current dictionary and active dataset and replaces them with the dictionary and data from a specified file. -The FILE subcommand is the only required subcommand. Specify the system +The @subcmd{FILE} subcommand is the only required subcommand. Specify the system file or portable file to be read as a string file name or a file handle (@pxref{File Handles}). By default, all the variables in a file are read. The DROP subcommand can be used to specify a list of variables that are not to be -read. By contrast, the KEEP subcommand can be used to specify variable +read. By contrast, the @subcmd{KEEP} subcommand can be used to specify variable that are to be read, with all other variables not read. Normally variables in a file retain the names that they were -saved under. Use the RENAME subcommand to change these names. Specify, +saved under. Use the @subcmd{RENAME} subcommand to change these names. Specify, within parentheses, a list of variable names followed by an equals sign (@samp{=}) and the names that they should be renamed to. Multiple parenthesized groups of variable names can be included on a single -RENAME subcommand. Variables' names may be swapped using a RENAME +@subcmd{RENAME} subcommand. Variables' names may be swapped using a @subcmd{RENAME} subcommand of the form @samp{/RENAME=(A B=B A)}. -Alternate syntax for the RENAME subcommand allows the parentheses to be +Alternate syntax for the @subcmd{RENAME} subcommand allows the parentheses to be eliminated. When this is done, only a single variable may be renamed at once. For instance, @samp{/RENAME=A=B}. This alternate syntax is deprecated. -DROP, KEEP, and RENAME are executed in left-to-right order. +@subcmd{DROP}, @subcmd{KEEP}, and @subcmd{RENAME} are executed in left-to-right order. Each may be present any number of times. @cmd{GET} never modifies a file on disk. Only the active dataset read from the file is affected by these subcommands. @@ -175,8 +175,8 @@ is affected by these subcommands. @pspp{} tries to automatically detect the encoding of string data in the file. Sometimes, however, this does not work well encoding, especially for files written by old versions of SPSS or @pspp{}. Specify -the ENCODING subcommand with an IANA character set name as its string -argument to override the default. The ENCODING subcommand is a @pspp{} +the @subcmd{ENCODING} subcommand with an IANA character set name as its string +argument to override the default. The @subcmd{ENCODING} subcommand is a @pspp{} extension. @cmd{GET} does not cause the data to be read, only the dictionary. The data @@ -199,7 +199,7 @@ sources created by other applications. When this command is executed, the current dictionary and active dataset are replaced with variables and data read from the specified source. -The TYPE subcommand is mandatory and must be the first subcommand +The @subcmd{TYPE} subcommand is mandatory and must be the first subcommand specified. It determines the type of the file or source to read. @pspp{} currently supports the following file types: @@ -246,10 +246,10 @@ Gnumeric spreadsheets (@url{http://gnumeric.org}), and spreadsheets in OpenDocument format (@url{http://libreplanet.org/wiki/Group:OpenDocument/Software}) can be read using the GET DATA command. -Use the TYPE subcommand to indicate the file's format. +Use the @subcmd{TYPE} subcommand to indicate the file's format. /TYPE=GNM indicates Gnumeric files, /TYPE=ODS indicates OpenDocument. -The FILE subcommand is mandatory. +The @subcmd{FILE} subcommand is mandatory. Use it to specify the name file to be read. All other subcommands are optional. @@ -257,27 +257,27 @@ The format of each variable is determined by the format of the spreadsheet cell containing the first datum for the variable. If this cell is of string (text) format, then the width of the variable is determined from the length of the string it contains, unless the -ASSUMEDVARWIDTH subcommand is given. +@subcmd{ASSUMEDVARWIDTH} subcommand is given. -The SHEET subcommand specifies the sheet within the spreadsheet file to read. -There are two forms of the SHEET subcommand. +The @subcmd{SHEET} subcommand specifies the sheet within the spreadsheet file to read. +There are two forms of the @subcmd{SHEET} subcommand. In the first form, @samp{/SHEET=name @var{sheet-name}}, the string @var{sheet-name} is the name of the sheet to read. In the second form, @samp{/SHEET=index @var{idx}}, @var{idx} is a integer which is the index of the sheet to read. The first sheet has the index 1. -If the SHEET subcommand is omitted, then the command will read the +If the @subcmd{SHEET} subcommand is omitted, then the command will read the first sheet in the file. -The CELLRANGE subcommand specifies the range of cells within the sheet to read. +The @subcmd{CELLRANGE} subcommand specifies the range of cells within the sheet to read. If the subcommand is given as @samp{/CELLRANGE=FULL}, then the entire sheet is read. To read only part of a sheet, use the form @samp{/CELLRANGE=range '@var{top-left-cell}:@var{bottom-right-cell}'}. For example, the subcommand @samp{/CELLRANGE=range 'C3:P19'} reads columns C--P, and rows 3--19 inclusive. -If no CELLRANGE subcommand is given, then the entire sheet is read. +If no @subcmd{CELLRANGE} subcommand is given, then the entire sheet is read. If @samp{/READNAMES=ON} is specified, then the contents of cells of the first row are used as the names of the variables in which to store @@ -285,7 +285,7 @@ the data from subsequent rows. This is the default. If @samp{/READNAMES=OFF} is used, then the variables receive automatically assigned names. -The ASSUMEDVARWIDTH subcommand specifies the maximum width of string +The @subcmd{ASSUMEDVARWIDTH} subcommand specifies the maximum width of string variables read from the file. If omitted, the default value is determined from the length of the string in the first spreadsheet cell for each variable. @@ -316,29 +316,29 @@ Not all the postgres data types are able to be represented in @pspp{}. If a datum cannot be represented a warning will be issued and that datum will be set to SYSMIS. -The CONNECT subcommand is mandatory. +The @subcmd{CONNECT} subcommand is mandatory. It is a string specifying the parameters of the database server from which the data should be fetched. The format of the string is given in the postgres manual @url{http://www.postgresql.org/docs/8.0/static/libpq.html#LIBPQ-CONNECT}. -The SQL subcommand is mandatory. +The @subcmd{SQL} subcommand is mandatory. It must be a valid SQL string to retrieve data from the database. -The ASSUMEDVARWIDTH subcommand specifies the maximum width of string +The @subcmd{ASSUMEDVARWIDTH} subcommand specifies the maximum width of string variables read from the database. If omitted, the default value is determined from the length of the string in the first value read for each variable. -The UNENCRYPTED subcommand allows data to be retrieved over an insecure +The @subcmd{UNENCRYPTED} subcommand allows data to be retrieved over an insecure connection. -If the connection is not encrypted, and the UNENCRYPTED subcommand is not +If the connection is not encrypted, and the @subcmd{UNENCRYPTED} subcommand is not given, then an error will occur. Whether or not the connection is encrypted depends upon the underlying psql library and the capabilities of the database server. -The BSIZE subcommand serves only to optimise the speed of data transfer. +The @subcmd{BSIZE} subcommand serves only to optimise the speed of data transfer. It specifies an upper limit on number of cases to fetch from the database at once. The default value is 4096. @@ -374,22 +374,22 @@ GET DATA /TYPE=TXT When TYPE=TXT is specified, GET DATA reads data in a delimited or fixed columnar format, much like DATA LIST (@pxref{DATA LIST}). -The FILE subcommand is mandatory. Specify the file to be read as +The @subcmd{FILE} subcommand is mandatory. Specify the file to be read as a string file name or (for textual data only) a file handle (@pxref{File Handles}). -The ARRANGEMENT subcommand determines the file's basic format. +The @subcmd{ARRANGEMENT} subcommand determines the file's basic format. DELIMITED, the default setting, specifies that fields in the input data are separated by spaces, tabs, or other user-specified delimiters. FIXED specifies that fields in the input data appear at particular fixed column positions within records of a case. By default, cases are read from the input file starting from the first -line. To skip lines at the beginning of an input file, set FIRSTCASE +line. To skip lines at the beginning of an input file, set @subcmd{FIRSTCASE} to the number of the first line to read: 2 to skip the first line, 3 to skip the first two lines, and so on. -IMPORTCASE can be used to limit the number of cases read from the +@subcmd{IMPORTCASE} can be used to limit the number of cases read from the input file. With the default setting, ALL, all cases in the file are read. Specify FIRST @i{max_cases} to read at most @i{max_cases} cases from the file. Use PERCENT @i{percent} to read only @i{percent} @@ -399,7 +399,7 @@ the number of cases in the file without reading the entire file. The number of cases in some kinds of unusual files cannot be estimated; @pspp{} will read all cases in such files.) -FIRSTCASE and IMPORTCASE may be used with delimited and fixed-format +@subcmd{FIRSTCASE} and @subcmd{IMPORTCASE} may be used with delimited and fixed-format data. The remaining subcommands, which apply only to one of the two file arrangements, are described below. @@ -432,50 +432,50 @@ separated by a set of user-specified delimiters. Its capabilities are similar to those of DATA LIST FREE (@pxref{DATA LIST FREE}), with a few enhancements. -The required FILE subcommand and optional FIRSTCASE and IMPORTCASE +The required @subcmd{FILE} subcommand and optional @subcmd{FIRSTCASE} and @subcmd{IMPORTCASE} subcommands are described above (@pxref{GET DATA /TYPE=TXT}). -DELIMITERS, which is required, specifies the set of characters that +@subcmd{DELIMITERS}, which is required, specifies the set of characters that may separate fields. Each character in the string specified on -DELIMITERS separates one field from the next. The end of a line also -separates fields, regardless of DELIMITERS. Two consecutive +@subcmd{DELIMITERS} separates one field from the next. The end of a line also +separates fields, regardless of @subcmd{DELIMITERS}. Two consecutive delimiters in the input yield an empty field, as does a delimiter at the end of a line. A space character as a delimiter is an exception: consecutive spaces do not yield an empty field and neither does any number of spaces at the end of a line. To use a tab as a delimiter, specify @samp{\t} at the beginning of the -DELIMITERS string. To use a backslash as a delimiter, specify +@subcmd{DELIMITERS} string. To use a backslash as a delimiter, specify @samp{\\} as the first delimiter or, if a tab should also be a delimiter, immediately following @samp{\t}. To read a data file in which each field appears on a separate line, specify the empty string -for DELIMITERS. +for @subcmd{DELIMITERS}. -The optional QUALIFIER subcommand names one or more characters that +The optional @subcmd{QUALIFIER} subcommand names one or more characters that can be used to quote values within fields in the input. A field that begins with one of the specified quote characters ends at the next matching quote. Intervening delimiters become part of the field, instead of terminating it. The ability to specify more than one quote character is a @pspp{} extension. -By default, a character specified on QUALIFIER cannot itself be +By default, a character specified on @subcmd{QUALIFIER} cannot itself be embedded within a field that it quotes, because the quote character always terminates the quoted field. With ESCAPE, however, a doubled quote character within a quoted field inserts a single instance of the quote into the field. For example, if @samp{'} is specified on -QUALIFIER, then without ESCAPE @code{'a''b'} specifies a pair of +@subcmd{QUALIFIER}, then without ESCAPE @code{'a''b'} specifies a pair of fields that contain @samp{a} and @samp{b}, but with ESCAPE it specifies a single field that contains @samp{a'b}. ESCAPE is a @pspp{} extension. -The DELCASE subcommand controls how data may be broken across lines in +The @subcmd{DELCASE} subcommand controls how data may be broken across lines in the data file. With LINE, the default setting, each line must contain all the data for exactly one case. For additional flexibility, to allow a single case to be split among lines or multiple cases to be contained on a single line, specify VARIABLES @i{n_variables}, where @i{n_variables} is the number of variables per case. -The VARIABLES subcommand is required and must be the last subcommand. +The @subcmd{VARIABLES} subcommand is required and must be the last subcommand. Specify the name of each variable and its input format (@pxref{Input and Output Formats}) in the order they should be read from the input file. @@ -588,14 +588,14 @@ particular fixed column positions within records of a case. Its capabilities are similar to those of DATA LIST FIXED (@pxref{DATA LIST FIXED}), with a few enhancements. -The required FILE subcommand and optional FIRSTCASE and IMPORTCASE +The required @subcmd{FILE} subcommand and optional @subcmd{FIRSTCASE} and @subcmd{IMPORTCASE} subcommands are described above (@pxref{GET DATA /TYPE=TXT}). -The optional FIXCASE subcommand may be used to specify the positive +The optional @subcmd{FIXCASE} subcommand may be used to specify the positive integer number of input lines that make up each case. The default value is 1. -The VARIABLES subcommand, which is required, specifies the positions +The @subcmd{VARIABLES} subcommand, which is required, specifies the positions at which each variable can be found. For each variable, specify its name, followed by its start and end column separated by @samp{-} (e.g.@: @samp{0-9}), followed by an input format type (e.g.@: @@ -651,15 +651,15 @@ data and replaces them with a dictionary and data from a system file or portable file. -The FILE subcommand, which is the only required subcommand, specifies +The @subcmd{FILE} subcommand, which is the only required subcommand, specifies the portable file to be read as a file name string or a file handle (@pxref{File Handles}). -The TYPE subcommand is currently not used. +The @subcmd{TYPE} subcommand is currently not used. -DROP, KEEP, and RENAME follow the syntax used by @cmd{GET} (@pxref{GET}). +@subcmd{DROP}, @subcmd{KEEP}, and @subcmd{RENAME} follow the syntax used by @cmd{GET} (@pxref{GET}). -@cmd{IMPORT} does not cause the data to be read, only the dictionary. The +@cmd{IMPORT} does not cause the data to be read; only the dictionary. The data is read later, when a procedure is executed. Use of @cmd{IMPORT} to read a system file is a @pspp{} extension. @@ -691,31 +691,31 @@ to be written as a string file name or a file handle (@pxref{File Handles}). By default, cases excluded with FILTER are written to the system file. -These can be excluded by specifying DELETE on the UNSELECTED -subcommand. Specifying RETAIN makes the default explicit. +These can be excluded by specifying @subcmd{DELETE} on the @subcmd{UNSELECTED} +subcommand. Specifying @subcmd{RETAIN} makes the default explicit. -The COMPRESS and UNCOMPRESS subcommand determine whether the saved +The @subcmd{COMPRESS} and @subcmd{UNCOMPRESS} subcommand determine whether the saved system file is compressed. By default, system files are compressed. This default can be changed with the SET command (@pxref{SET}). -The PERMISSIONS subcommand specifies permissions for the new system +The @subcmd{PERMISSIONS} subcommand specifies permissions for the new system file. WRITEABLE, the default, creates the file with read and write permission. READONLY creates the file for read-only access. By default, all the variables in the active dataset dictionary are written -to the system file. The DROP subcommand can be used to specify a list +to the system file. The @subcmd{DROP} subcommand can be used to specify a list of variables not to be written. In contrast, KEEP specifies variables to be written, with all variables not specified not written. Normally variables are saved to a system file under the same names they -have in the active dataset. Use the RENAME subcommand to change these names. +have in the active dataset. Use the @subcmd{RENAME} subcommand to change these names. Specify, within parentheses, a list of variable names followed by an equals sign (@samp{=}) and the names that they should be renamed to. Multiple parenthesized groups of variable names can be included on a -single RENAME subcommand. Variables' names may be swapped using a -RENAME subcommand of the form @samp{/RENAME=(A B=B A)}. +single @subcmd{RENAME} subcommand. Variables' names may be swapped using a +@subcmd{RENAME} subcommand of the form @samp{/RENAME=(A B=B A)}. -Alternate syntax for the RENAME subcommand allows the parentheses to be +Alternate syntax for the @subcmd{RENAME} subcommand allows the parentheses to be eliminated. When this is done, only a single variable may be renamed at once. For instance, @samp{/RENAME=A=B}. This alternate syntax is deprecated. @@ -725,12 +725,12 @@ each may be present any number of times. @cmd{SAVE} never modifies the active dataset. DROP, KEEP, and RENAME only affect the system file written to disk. -The VERSION subcommand specifies the version of the file format. Valid +The @subcmd{VERSION} subcommand specifies the version of the file format. Valid versions are 2 and 3. The default version is 3. In version 2 system files, variable names longer than 8 bytes will be truncated. The two versions are otherwise identical. -The NAMES and MAP subcommands are currently ignored. +The @subcmd{NAMES} and @subcmd{MAP} subcommands are currently ignored. @cmd{SAVE} causes the data to be read. It is a procedure. @@ -757,9 +757,9 @@ SAVE TRANSLATE The @cmd{SAVE TRANSLATE} command is used to save data into various formats understood by other applications. -The OUTFILE and TYPE subcommands are mandatory. OUTFILE specifies the -file to be written, as a string file name or a file handle -(@pxref{File Handles}). TYPE determines the type of the file or +The @subcmd{OUTFILE} and @subcmd{TYPE} subcommands are mandatory. +@subcmd{OUTFILE} specifies the file to be written, as a string file name or a file handle +(@pxref{File Handles}). @subcmd{TYPE} determines the type of the file or source to read. It must be one of the following: @table @asis @@ -770,19 +770,19 @@ Comma-separated value format, Tab-delimited format. @end table -By default, SAVE TRANSLATE will not overwrite an existing file. Use -REPLACE to force an existing file to be overwritten. +By default, @cmd{SAVE TRANSLATE} will not overwrite an existing file. Use +@subcmd{REPLACE} to force an existing file to be overwritten. -With MISSING=IGNORE, the default, SAVE TRANSLATE treats user-missing +With MISSING=IGNORE, the default, @subcmd{SAVE TRANSLATE} treats user-missing values as if they were not missing. Specify MISSING=RECODE to output numeric user-missing values like system-missing values and string user-missing values as all spaces. By default, all the variables in the active dataset dictionary are saved -to the system file, but DROP or KEEP can select a subset of variable -to save. The RENAME subcommand can also be used to change the names -under which variables are saved. UNSELECTED determines whether cases -filtered out by the FILTER command are written to the output file. +to the system file, but @subcmd{DROP} or @subcmd{KEEP} can select a subset of variable +to save. The @subcmd{RENAME} subcommand can also be used to change the names +under which variables are saved. @subcmd{UNSELECTED} determines whether cases +filtered out by the @cmd{FILTER} command are written to the output file. These subcommands have the same syntax and meaning as on the @cmd{SAVE} command (@pxref{SAVE}). @@ -912,7 +912,7 @@ It is similar to the @cmd{EXPORT} procedure, with two differences: the data is read by a procedure or procedure-like command. @item -@cmd{XEXPORT} does not support the UNSELECTED subcommand. +@cmd{XEXPORT} does not support the @subcmd{UNSELECTED} subcommand. @end itemize @xref{EXPORT}, for more information. @@ -944,7 +944,7 @@ procedure, with two differences: the data is read by a procedure or procedure-like command. @item -@cmd{XSAVE} does not support the UNSELECTED subcommand. +@cmd{XSAVE} does not support the @subcmd{UNSELECTED} subcommand. @end itemize @xref{SAVE}, for more information. diff --git a/doc/flow-control.texi b/doc/flow-control.texi index bee6df1484..d74a83b573 100644 --- a/doc/flow-control.texi +++ b/doc/flow-control.texi @@ -1,3 +1,4 @@ + @node Conditionals and Looping @chapter Conditional and Looping Constructs @cindex conditionals @@ -112,11 +113,11 @@ as variables, but only if used in the code block in a context that would create them, e.g.@: on a @cmd{NUMERIC} or @cmd{STRING} command or on the left side of a @cmd{COMPUTE} assignment. -Any command may appear within DO REPEAT, including nested DO REPEAT -commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within DO REPEAT, +Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT} +commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT}, the substitutions do not apply to the included file. -If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions +If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after substitutions are made are printed to the listing file, prefixed by a plus sign (@samp{+}). @@ -125,31 +126,33 @@ are made are printed to the listing file, prefixed by a plus sign @vindex LOOP @display -LOOP [index_var=start TO end [BY incr]] [IF condition]. +LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}]. @dots{} -END LOOP [IF condition]. +END LOOP [IF @var{condition}]. @end display @cmd{LOOP} iterates a group of commands. A number of termination options are offered. Specify index_var to make that variable count from one value to -another by a particular increment. index_var must be a pre-existing -numeric variable. start, end, and incr are numeric expressions +another by a particular increment. @var{index_var} must be a pre-existing +numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions (@pxref{Expressions}.) -During the first iteration, index_var is set to the value of start. -During each successive iteration, index_var is increased by the value of -incr. If end > start, then the loop terminates when index_var > end; -otherwise it terminates when index_var < end. If incr is not specified +During the first iteration, @var{index_var} is set to the value of @var{start}. +During each successive iteration, @var{index_var} is increased by the value of +@var{incr}. If @var{end} > @var{start}, then the loop terminates +when @var{index_var} > @var{end}; +otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified then it defaults to +1 or -1 as appropriate. -If end > start and incr < 0, or if end < start and incr > 0, then the -loop is never executed. index_var is nevertheless set to the value of +If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and + @var{incr} > 0, then the +loop is never executed. @var{index_var} is nevertheless set to the value of start. -Modifying index_var within the loop is allowed, but it has no effect on -the value of index_var in the next iteration. +Modifying @var{index_var} within the loop is allowed, but it has no effect on +the value of @var{index_var} in the next iteration. Specify a boolean expression for the condition on @cmd{LOOP} to cause the loop to be executed only if the condition is true. If the diff --git a/doc/pspp.texinfo b/doc/pspp.texinfo index 78e2ef8e9e..a8fd1a0ea3 100644 --- a/doc/pspp.texinfo +++ b/doc/pspp.texinfo @@ -15,8 +15,16 @@ @include version.texi +@c This macro should be used for marking command names. For the purposes of markup, +@c no distinction is made between ``commands'' and ``procedures''. @macro cmd{CMDNAME} -\CMDNAME\ +@code{\CMDNAME\} +@end macro + +@c This macro is used for fragments of command syntax that are not in themselves command names. +@c It does not necessarily have to be a subcommand. +@macro subcmd{CMDNAME} +@code{\CMDNAME\} @end macro @c Use this macro to refer to PSPP itself . Not when giving a shell command line example. diff --git a/doc/regression.texi b/doc/regression.texi index 80f5eaf68d..e9136f8950 100644 --- a/doc/regression.texi +++ b/doc/regression.texi @@ -53,16 +53,16 @@ REGRESSION The @cmd{REGRESSION} procedure reads the active dataset and outputs statistics relevant to the linear model specified by the user. -The VARIABLES subcommand, which is required, specifies the list of +The @subcmd{VARIABLES} subcommand, which is required, specifies the list of variables to be analyzed. Keyword VARIABLES is required. The -DEPENDENT subcommand specifies the dependent variable of the linear -model. The DEPENDENT subcommand is required. All variables listed in -the VARIABLES subcommand, but not listed in the DEPENDENT subcommand, +@subcmd{DEPENDENT} subcommand specifies the dependent variable of the linear +model. The @subcmd{DEPENDENT} subcommand is required. All variables listed in +the @subcmd{VARIABLES} subcommand, but not listed in the @subcmd{DEPENDENT} subcommand, are treated as explanatory variables in the linear model. All other subcommands are optional: -The STATISTICS subcommand specifies the statistics to be displayed: +The @subcmd{STATISTICS} subcommand specifies the statistics to be displayed: @table @code @item ALL @@ -78,7 +78,7 @@ Analysis of variance table for the model. The covariance matrix for the estimated model coefficients. @end table -The SAVE subcommand causes @pspp{} to save the residuals or predicted +The @subcmd{SAVE} subcommand causes @pspp{} to save the residuals or predicted values from the fitted model to the active dataset. @pspp{} will store the residuals in a variable called RES1 if no such variable exists, RES2 if RES1 already exists, diff --git a/doc/statistics.texi b/doc/statistics.texi index f7e3a0fe65..d8b1cae96b 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -45,12 +45,12 @@ descriptive statistics requested by the user. In addition, it can optionally compute Z-scores. -The VARIABLES subcommand, which is required, specifies the list of -variables to be analyzed. Keyword VARIABLES is optional. +The @subcmd{VARIABLES} subcommand, which is required, specifies the list of +variables to be analyzed. Keyword @subcmd{VARIABLES} is optional. All other subcommands are optional: -The MISSING subcommand determines the handling of missing variables. If +The @subcmd{MISSING} subcommand determines the handling of missing variables. If INCLUDE is set, then user-missing values are included in the calculations. If NOINCLUDE is set, which is the default, user-missing values are excluded. If VARIABLE is set, then missing values are @@ -58,12 +58,12 @@ excluded on a variable by variable basis; if LISTWISE is set, then the entire case is excluded whenever any value in that case has a system-missing or, if INCLUDE is set, user-missing value. -The FORMAT subcommand affects the output format. Currently the +The @subcmd{FORMAT} subcommand affects the output format. Currently the LABELS/NOLABELS and NOINDEX/INDEX settings are not used. When SERIAL is set, both valid and missing number of cases are listed in the output; when NOSERIAL is set, only valid cases are listed. -The SAVE subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all +The @subcmd{SAVE} subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all the specified variables. The Z scores are saved to new variables. Variable names are generated by trying first the original variable name with Z prepended and truncated to a maximum of 8 characters, then the @@ -72,7 +72,7 @@ ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence. In addition, Z score variable names can be specified explicitly on VARIABLES in the variable list by enclosing them in parentheses after each variable. -The STATISTICS subcommand specifies the statistics to be displayed: +The @subcmd{STATISTICS} subcommand specifies the statistics to be displayed: @table @code @item ALL @@ -105,10 +105,10 @@ Standard error of the kurtosis. Standard error of the skewness. @end table -The SORT subcommand specifies how the statistics should be sorted. Most +The @subcmd{SORT} subcommand specifies how the statistics should be sorted. Most of the possible values should be self-explanatory. NAME causes the statistics to be sorted by name. By default, the statistics are listed -in the order that they are specified on the VARIABLES subcommand. The A +in the order that they are specified on the @subcmd{VARIABLES} subcommand. The A and D settings request an ascending or descending sort order, respectively. @@ -145,13 +145,13 @@ variables. @cmd{FREQUENCIES} can also output histograms and pie charts. -The VARIABLES subcommand is the only required subcommand. Specify the +The @subcmd{VARIABLES} subcommand is the only required subcommand. Specify the variables to be analyzed. -The FORMAT subcommand controls the output format. It has several +The @subcmd{FORMAT} subcommand controls the output format. It has several possible settings: -@itemize @bullet +@itemize @subcmd{} @item TABLE, the default, causes a frequency table to be output for every variable specified. NOTABLE prevents them from being output. LIMIT @@ -165,7 +165,7 @@ AFREQ and DFREQ tables are sorted in ascending and descending order, respectively, by frequency count. @end itemize -The MISSING subcommand controls the handling of user-missing values. +The @subcmd{MISSING} subcommand controls the handling of user-missing values. When EXCLUDE, the default, is set, user-missing values are not included in frequency tables or statistics. When INCLUDE is set, user-missing are included. System-missing values are never included in statistics, @@ -181,12 +181,12 @@ mean, minimum, and maximum are reported for each variable. PERCENTILES causes the specified percentiles to be reported. The percentiles should be presented at a list of numbers between 0 and 100 inclusive. -The NTILES subcommand causes the percentiles to be reported at the +The @subcmd{NTILES} subcommand causes the percentiles to be reported at the boundaries of the data set divided into the specified number of ranges. For instance, @code{/NTILES=4} would cause quartiles to be reported. @cindex histogram -The HISTOGRAM subcommand causes the output to include a histogram for +The @subcmd{HISTOGRAM} subcommand causes the output to include a histogram for each specified numeric variable. The X axis by default ranges from the minimum to the maximum value observed in the data, but the MINIMUM and MAXIMUM keywords can set an explicit range. Specify NORMAL to @@ -194,15 +194,15 @@ superimpose a normal curve on the histogram. Histograms are not created for string variables. @cindex piechart -The PIECHART adds a pie chart for each variable to the data. Each +The @subcmd{PIECHART} subcommand adds a pie chart for each variable to the data. Each slice represents one value, with the size of the slice proportional to the value's frequency. By default, all non-missing values are given slices. The MINIMUM and MAXIMUM keywords can be used to limit the displayed slices to a given range of values. The MISSING keyword adds slices for missing values. -The FREQ and PERCENT options on HISTOGRAM and PIECHART are accepted -but not currently honored. +The FREQ and PERCENT options on @subcmd{HISTOGRAM} and @subcmd{PIECHART} are accepted +but not currently honoured. @node EXAMINE @section EXAMINE @@ -235,7 +235,7 @@ The @cmd{EXAMINE} command is used to perform exploratory data analysis. In particular, it is useful for testing how closely a distribution follows a normal distribution, and for finding outliers and extreme values. -The VARIABLES subcommand is mandatory. +The @subcmd{VARIABLES} subcommand is mandatory. It specifies the dependent variables and optionally variables to use as factors for the analysis. Variables listed before the first BY keyword (if any) are the @@ -255,7 +255,7 @@ Each unique combination of the values of @var{factorvar} and Statistics will be calculated for each cell and for the entire dataset (unless NOTOTAL is given). -The STATISTICS subcommand specifies which statistics to show. +The @subcmd{STATISTICS} subcommand specifies which statistics to show. DESCRIPTIVES will produce a table showing some parametric and non-parametrics statistics. EXTREME produces a table showing the extremities of each cell. @@ -274,41 +274,41 @@ specified. @cindex boxplot @cindex histogram @cindex npplot -The PLOT subcommand specifies which plots are to be produced if any. +The @subcmd{PLOT} subcommand specifies which plots are to be produced if any. Available plots are HISTOGRAM, NPPLOT and BOXPLOT. They can all be used to visualise how closely each cell conforms to a normal distribution. Boxplots will also show you the outliers and extreme values. -The COMPARE subcommand is only relevant if producing boxplots, and it is only +The @subcmd{COMPARE} subcommand is only relevant if producing boxplots, and it is only useful there is more than one dependent variable and at least one factor. If /COMPARE=GROUPS is specified, then one plot per dependent variable is produced, each of which contain boxplots for all the cells. If /COMPARE=VARIABLES is specified, then one plot per cell is produced, each containing one boxplot per dependent variable. -If the /COMPARE subcommand is omitted, then @pspp{} behaves as if +If the @subcmd{/COMPARE} subcommand is omitted, then @pspp{} behaves as if /COMPARE=GROUPS were given. -The ID subcommand is relevant only if /PLOT=BOXPLOT or +The @subcmd{ID} subcommand is relevant only if /PLOT=BOXPLOT or /STATISTICS=EXTREME has been given. If given, it shoule provide the name of a variable which is to be used to labels extreme values and outliers. Numeric or string variables are permissible. -If the ID subcommand is not given, then the casenumber will be used for +If the @subcmd{ID} subcommand is not given, then the casenumber will be used for labelling. -The CINTERVAL subcommand specifies the confidence interval to use in +The @subcmd{CINTERVAL} subcommand specifies the confidence interval to use in calculation of the descriptives command. The default is 95%. @cindex percentiles -The PERCENTILES subcommand specifies which percentiles are to be calculated, +The @subcmd{PERCENTILES} subcommand specifies which percentiles are to be calculated, and which algorithm to use for calculating them. The default is to calculate the 5, 10, 25, 50, 75, 90, 95 percentiles using the HAVERAGE algorithm. -The TOTAL and NOTOTAL subcommands are mutually exclusive. If NOTOTAL -is given and factors have been specified in the VARIABLES subcommand, +The @subcmd{TOTAL} and @subcmd{NOTOTAL} subcommands are mutually exclusive. If NOTOTAL +is given and factors have been specified in the @subcmd{VARIABLES} subcommand, then then statistics for the unfactored dependent variables are produced in addition to the factored variables. If there are no factors specified then TOTAL and NOTOTAL have no effect. @@ -349,7 +349,7 @@ Boxplots will also be produced. Because /COMPARE = GROUPS was given, boxplots for male and female will be shown in the same graphic, allowing us to easily see the difference between the genders. -Since the variable @var{name} was specified on the ID subcommand, this will be +Since the variable @var{name} was specified on the @subcmd{ID} subcommand, this will be used to label the extreme values. @strong{Warning!} @@ -382,11 +382,11 @@ CORRELATIONS The @cmd{CORRELATIONS} procedure produces tables of the Pearson correlation coefficient for a set of variables. The significance of the coefficients are also given. -At least one VARIABLES subcommand is required. If the WITH keyword is used, then a non-square +At least one @subcmd{VARIABLES} subcommand is required. If the WITH keyword is used, then a non-square correlation table will be produced. The variables preceding WITH, will be used as the rows of the table, and the variables following will be the columns of the table. -If no WITH subcommand is given, then a square, symmetrical table using all variables is produced. +If no @subcmd{WITH} subcommand is given, then a square, symmetrical table using all variables is produced. The @cmd{MISSING} subcommand determines the handling of missing variables. @@ -403,7 +403,7 @@ If PAIRWISE is set, then a case is considered missing only if either of the values for the particular coefficient are missing. The default is PAIRWISE. -The PRINT subcommand is used to control how the reported significance values are printed. +The @subcmd{PRINT} subcommand is used to control how the reported significance values are printed. If the TWOTAIL option is used, then a two-tailed test of significance is printed. If the ONETAIL option is given, then a one-tailed test is used. The default is TWOTAIL. @@ -413,11 +413,11 @@ If the NOSIG option is specified, then correlation coefficients with significanc If SIG is specified, then no highlighting is performed. This is the default. @cindex covariance -The STATISTICS subcommand requests additional statistics to be displayed. The keyword +The @subcmd{STATISTICS} subcommand requests additional statistics to be displayed. The keyword DESCRIPTIVES requests that the mean, number of non-missing cases, and the non-biased estimator of the standard deviation are displayed. These statistics will be displayed in a separated table, for all the variables listed -in any /VARIABLES subcommand. +in any @subcmd{/VARIABLES} subcommand. The XPROD keyword requests cross-product deviations and covariance estimators to be displayed for each pair of variables. The keyword ALL is the union of DESCRIPTIVES and XPROD. @@ -450,9 +450,9 @@ tables requested by the user. It can calculate several statistics for each cell in the crosstabulation tables. In addition, a number of statistics can be calculated for each table itself. -The TABLES subcommand is used to specify the tables to be reported. Any +The @subcmd{TABLES} subcommand is used to specify the tables to be reported. Any number of dimensions is permitted, and any number of variables per -dimension is allowed. The TABLES subcommand may be repeated as many +dimension is allowed. The @subcmd{TABLES} subcommand may be repeated as many times as needed. This is the only required subcommand in @dfn{general mode}. @@ -460,17 +460,17 @@ Occasionally, one may want to invoke a special mode called @dfn{integer mode}. Normally, in general mode, @pspp{} automatically determines what values occur in the data. In integer mode, the user specifies the range of values that the data assumes. To invoke this mode, specify the -VARIABLES subcommand, giving a range of data values in parentheses for -each variable to be used on the TABLES subcommand. Data values inside +@subcmd{VARIABLES} subcommand, giving a range of data values in parentheses for +each variable to be used on the @subcmd{TABLES} subcommand. Data values inside the range are truncated to the nearest integer, then assigned to that value. If values occur outside this range, they are discarded. When it -is present, the VARIABLES subcommand must precede the TABLES +is present, the @subcmd{VARIABLES} subcommand must precede the @subcmd{TABLES} subcommand. In general mode, numeric and string variables may be specified on TABLES. In integer mode, only numeric variables are allowed. -The MISSING subcommand determines the handling of user-missing values. +The @subcmd{MISSING} subcommand determines the handling of user-missing values. When set to TABLE, the default, missing values are dropped on a table by table basis. When set to INCLUDE, user-missing values are included in tables and statistics. When set to REPORT, which is allowed only in @@ -478,19 +478,19 @@ integer mode, user-missing values are included in tables but marked with an @samp{M} (for ``missing'') and excluded from statistical calculations. -Currently the WRITE subcommand is ignored. +Currently the @subcmd{WRITE} subcommand is ignored. -The FORMAT subcommand controls the characteristics of the +The @subcmd{FORMAT} subcommand controls the characteristics of the crosstabulation tables to be displayed. It has a number of possible settings: -@itemize @bullet +@itemize @subcmd{} @item TABLES, the default, causes crosstabulation tables to be output. NOTABLES suppresses them. @item -PIVOT, the default, causes each TABLES subcommand to be displayed in a +PIVOT, the default, causes each @subcmd{TABLES} subcommand to be displayed in a pivot table format. NOPIVOT causes the old-style crosstabulation format to be used. @@ -505,7 +505,7 @@ INDEX/NOINDEX is currently ignored. BOX/NOBOX is currently ignored. @end itemize -The CELLS subcommand controls the contents of each cell in the displayed +The @subcmd{CELLS} subcommand controls the contents of each cell in the displayed crosstabulation table. The possible settings are: @table @asis @@ -535,7 +535,7 @@ Suppress cells entirely. COLUMN, and TOTAL. If CELLS is not specified at all then only COUNT will be selected. -The STATISTICS subcommand selects statistics for computation: +The @subcmd{STATISTICS} subcommand selects statistics for computation: @table @asis @item CHISQ @@ -579,7 +579,7 @@ statistic. Certain statistics require tables of a particular size, and some statistics are calculated only in integer mode. @samp{/STATISTICS} without any settings selects CHISQ. If the -STATISTICS subcommand is not given, no statistics are calculated. +@subcmd{STATISTICS} subcommand is not given, no statistics are calculated. @strong{Please note:} Currently the implementation of CROSSTABS has the followings bugs: @@ -635,23 +635,23 @@ FACTOR VARIABLES=var_list The FACTOR command performs Factor Analysis or Principal Axis Factoring on a dataset. It may be used to find common factors in the data or for data reduction purposes. -The VARIABLES subcommand is required. It lists the variables which are to partake in the analysis. +The @subcmd{VARIABLES} subcommand is required. It lists the variables which are to partake in the analysis. -The /EXTRACTION subcommand is used to specify the way in which factors (components) are extracted from the data. +The @subcmd{/EXTRACTION} subcommand is used to specify the way in which factors (components) are extracted from the data. If PC is specified, then Principal Components Analysis is used. If PAF is specified, then Principal Axis Factoring is used. By default Principal Components Analysis will be used. -The /ROTATION subcommand is used to specify the method by which the extracted solution will be rotated. +The @subcmd{/ROTATION} subcommand is used to specify the method by which the extracted solution will be rotated. Three methods are available: VARIMAX (which is the default), EQUAMAX, and QUARTIMAX. If don't want any rotation to be performed, the word NOROTATE will prevent the command from performing any rotation on the data. Oblique rotations are not supported. -The /METHOD subcommand should be used to determine whether the covariance matrix or the correlation matrix of the data is +The @subcmd{/METHOD} subcommand should be used to determine whether the covariance matrix or the correlation matrix of the data is to be analysed. By default, the correlation matrix is analysed. -The /PRINT subcommand may be used to select which features of the analysis are reported: +The @subcmd{/PRINT} subcommand may be used to select which features of the analysis are reported: -@itemize +@itemize @subcmd{} @item UNIVARIATE A table of mean values, standard deviations and total weights are printed. @item INITIAL @@ -679,12 +679,12 @@ The /PRINT subcommand may be used to select which features of the analysis are r If /PLOT=EIGEN is given, then a ``Scree'' plot of the eigenvalues will be printed. This can be useful for visualizing which factors (components) should be retained. -The /FORMAT subcommand determined how data are to be displayed in loading matrices. If SORT is specified, then the variables +The @subcmd{/FORMAT} subcommand determined how data are to be displayed in loading matrices. If SORT is specified, then the variables are sorted in descending order of significance. If BLANK(@var{n}) is specified, then coefficients whose absolute value is less -than @var{n} will not be printed. If the keyword DEFAULT is given, or if no /FORMAT subcommand is given, then no sorting is +than @var{n} will not be printed. If the keyword DEFAULT is given, or if no @subcmd{/FORMAT} subcommand is given, then no sorting is performed, and all coefficients will be printed. -The /CRITERIA subcommand is used to specify how the number of extracted factors (components) are chosen. If FACTORS(@var{n}) is +The @subcmd{/CRITERIA} subcommand is used to specify how the number of extracted factors (components) are chosen. If FACTORS(@var{n}) is specified, where @var{n} is an integer, then @var{n} factors will be extracted. Otherwise, the MINEIGEN setting will be used. MINEIGEN(@var{l}) requests that all factors whose eigenvalues are greater than or equal to @var{l} are extracted. The default value of @var{l} is 1. The ECONVERGE and ITERATE settings have effect only when iterative algorithms for factor @@ -699,12 +699,12 @@ calculations, but system-missing values are not. If EXCLUDE is set, which is the default, user-missing values are excluded as well as system-missing values. This is the default. -If LISTWISE is set, then the entire case is excluded from analysis +If @subcmd{LISTWISE} is set, then the entire case is excluded from analysis whenever any variable specified in the @cmd{VARIABLES} subcommand contains a missing value. -If PAIRWISE is set, then a case is considered missing only if either of the +If @subcmd{PAIRWISE} is set, then a case is considered missing only if either of the values for the particular coefficient are missing. -The default is LISTWISE. +The default is @subcmd{LISTWISE}. @node MEANS @section MEANS @@ -754,7 +754,7 @@ MEANS @var{x} @var{y} BY @var{g} This example calculates the harmonic mean, the sum and the minimum values of @var{x} and @var{y} grouped by @var{g}. -The CELLS subcommand specifies which statistics to calculate. The available statistics +The @subcmd{CELLS} subcommand specifies which statistics to calculate. The available statistics are: @itemize @item MEAN @@ -829,7 +829,7 @@ By default values are omitted from the analysis only if missing values (either system missing or user missing) for any of the variables directly involved in their calculation are encountered. -This behaviour can be modified with the /MISSING subcommand. +This behaviour can be modified with the @subcmd{/MISSING} subcommand. Three options are possible: TABLE, INCLUDE and DEPENDENT. /MISSING = TABLE causes cases to be dropped if any variable is missing @@ -870,7 +870,7 @@ NPAR TESTS performs nonparametric tests. Non parametric tests make very few assumptions about the distribution of the data. One or more tests may be specified by using the corresponding subcommand. -If the /STATISTICS subcommand is also specified, then summary statistics are +If the @subcmd{/STATISTICS} subcommand is also specified, then summary statistics are produces for each variable that is the subject of any test. Certain tests may take a long time to execute, if an exact figure is required. @@ -910,7 +910,7 @@ is used. [ /BINOMIAL[(p)]=var_list[(value1[, value2)] ] ] @end display -The /BINOMIAL subcommand compares the observed distribution of a dichotomous +The @subcmd{/BINOMIAL} subcommand compares the observed distribution of a dichotomous variable with that of a binomial distribution. The variable @var{p} specifies the test proportion of the binomial distribution. @@ -960,13 +960,13 @@ even for very large sample sizes. @end display -The /CHISQUARE subcommand produces a chi-square statistic for the differences +The @subcmd{/CHISQUARE} subcommand produces a chi-square statistic for the differences between the expected and observed frequencies of the categories of a variable. Optionally, a range of values may appear after the variable list. If a range is given, then non integer values are truncated, and values outside the specified range are excluded from the analysis. -The /EXPECTED subcommand specifies the expected values of each +The @subcmd{/EXPECTED} subcommand specifies the expected values of each category. There must be exactly one non-zero expected value, for each observed category, or the EQUAL keywork must be specified. @@ -974,7 +974,7 @@ You may use the notation @var{n}*@var{f} to specify @var{n} consecutive expected categories all taking a frequency of @var{f}. The frequencies given are proportions, not absolute frequencies. The sum of the frequencies need not be 1. -If no /EXPECTED subcommand is given, then then equal frequencies +If no @subcmd{/EXPECTED} subcommand is given, then then equal frequencies are expected. @@ -1148,7 +1148,7 @@ The median test is used to test whether independent samples come from populations with a common median. The median of the populations against which the samples are to be tested may be given in parentheses immediately after the -/MEDIAN subcommand. If it is not given, the median will be imputed from the +@subcmd{/MEDIAN} subcommand. If it is not given, the median will be imputed from the union of all the samples. The variables of the samples to be tested should immediately follow the @samp{=} sign. The @@ -1169,11 +1169,11 @@ range [@var{value1},@var{value2}]. [ /RUNS (@{MEAN, MEDIAN, MODE, value@}) = varlist ] @end display -The /RUNS subcommand tests whether a data sequence is randomly ordered. +The @subcmd{/RUNS} subcommand tests whether a data sequence is randomly ordered. It works by examining the number of times a variable's value crosses a given threshold. The desired threshold must be specified within parentheses. -It may either be specified as a number or as one of MEAN, MEDIAN or MODE. +It may either be specified as a number or as one of @subcmd{MEAN}, @subcmd{MEDIAN} or @subcmd{MODE}. Following the threshold specification comes the list of variables whose values are to be tested. @@ -1189,7 +1189,7 @@ length of the data. [ /SIGN varlist [ WITH varlist [ (PAIRED) ]]] @end display -The /SIGN subcommand tests for differences between medians of the +The @subcmd{/SIGN} subcommand tests for differences between medians of the variables listed. The test does not make any assumptions about the distribution of the data. @@ -1216,7 +1216,7 @@ of variable preceding @code{WITH} against variable following [ /WILCOXON varlist [ WITH varlist [ (PAIRED) ]]] @end display -The /WILCOXON subcommand tests for differences between medians of the +The @subcmd{/WILCOXON} subcommand tests for differences between medians of the variables listed. The test does not make any assumptions about the variances of the samples. It does however assume that the distribution is symetrical. @@ -1314,14 +1314,14 @@ tell @pspp{} which variables you wish to test. @comment node-name, next, previous, up @subsection Independent Samples Mode -The @cmd{GROUPS} subcommand invokes Independent Samples mode or +The @subcmd{GROUPS} subcommand invokes Independent Samples mode or `Groups' mode. This mode is used to test whether two groups of values have the same population mean. -In this mode, you must also use the @cmd{/VARIABLES} subcommand to +In this mode, you must also use the @subcmd{/VARIABLES} subcommand to tell @pspp{} the dependent variables you wish to test. -The variable given in the @cmd{GROUPS} subcommand is the independent +The variable given in the @subcmd{GROUPS} subcommand is the independent variable which determines to which group the samples belong. The values in parentheses are the specific values of the independent variable for each group. @@ -1333,9 +1333,9 @@ it is acceptable to specify only one value inside the parentheses. If you do this, cases where the independent variable is greater than or equal to this value belong to the first group, and cases less than this value belong to the second group. -When using this form of the @cmd{GROUPS} subcommand, missing values in +When using this form of the @subcmd{GROUPS} subcommand, missing values in the independent variable are excluded on a listwise basis, regardless -of whether @cmd{/MISSING=LISTWISE} was specified. +of whether @subcmd{/MISSING=LISTWISE} was specified. @node Paired Samples Mode @@ -1407,10 +1407,10 @@ If the total sum of the coefficients are not zero, then @pspp{} will display a warning, but will proceed with the analysis. The @code{CONTRAST} subcommand may be given up to 10 times in order to specify different contrast tests. -The @code{MISSING} subcommand defines how missing values are handled. -If LISTWISE is specified then cases which have missing values for +The @subcmd{MISSING} subcommand defines how missing values are handled. +If @subcmd{LISTWISE} is specified then cases which have missing values for the independent variable or any dependent variable will be ignored. -If ANALYSIS is specified, then cases will be ignored if the independent +If @subcmd{ANALYSIS} is specified, then cases will be ignored if the independent variable is missing or if the dependent variable currently being analysed is missing. The default is ANALYSIS. A setting of EXCLUDE means that variables whose values are @@ -1509,7 +1509,7 @@ RANK The @cmd{RANK} command ranks variables and stores the results into new variables. -The VARIABLES subcommand, which is mandatory, specifies one or +The @subcmd{VARIABLES} subcommand, which is mandatory, specifies one or more variables whose values are to be ranked. After each variable, @samp{A} or @samp{D} may appear, indicating that the variable is to be ranked in ascending or descending order. @@ -1519,28 +1519,28 @@ which are to serve as group variables. In this case, the cases are gathered into groups, and ranks calculated for each group. -The TIES subcommand specifies how tied values are to be treated. The +The @subcmd{TIES} subcommand specifies how tied values are to be treated. The default is to take the mean value of all the tied cases. -The FRACTION subcommand specifies how proportional ranks are to be +The @subcmd{FRACTION} subcommand specifies how proportional ranks are to be calculated. This only has any effect if NORMAL or PROPORTIONAL rank functions are requested. -The PRINT subcommand may be used to specify that a summary of the rank +The @subcmd{PRINT} subcommand may be used to specify that a summary of the rank variables created should appear in the output. The function subcommands are RANK, NTILES, NORMAL, PERCENT, RFRACTION, PROPORTION and SAVAGE. Any number of function subcommands may appear. If none are given, then the default is RANK. -The NTILES subcommand must take an integer specifying the number of +The @subcmd{NTILES} subcommand must take an integer specifying the number of partitions into which values should be ranked. Each subcommand may be followed by the INTO keyword and a list of variables which are the variables to be created and receive the rank scores. There may be as many variables specified as there are -variables named on the VARIABLES subcommand. If fewer are specified, +variables named on the @subcmd{VARIABLES} subcommand. If fewer are specified, then the variable names are automatically created. -The MISSING subcommand determines how user missing values are to be +The @subcmd{MISSING} subcommand determines how user missing values are to be treated. A setting of EXCLUDE means that variables whose values are user-missing are to be excluded from the rank scores. A setting of INCLUDE means they are to be included. The default is EXCLUDE. @@ -1564,16 +1564,16 @@ RELIABILITY @cindex Cronbach's Alpha The @cmd{RELIABILTY} command performs reliability analysis on the data. -The VARIABLES subcommand is required. It determines the set of variables +The @subcmd{VARIABLES} subcommand is required. It determines the set of variables upon which analysis is to be performed. -The SCALE subcommand determines which variables reliability is to be +The @subcmd{SCALE} subcommand determines which variables reliability is to be calculated for. If it is omitted, then analysis for all variables named -in the VARIABLES subcommand will be used. +in the @subcmd{VARIABLES} subcommand will be used. Optionally, the @var{name} parameter may be specified to set a string name for the scale. -The MODEL subcommand determines the type of analysis. If ALPHA is specified, +The @subcmd{MODEL} subcommand determines the type of analysis. If ALPHA is specified, then Cronbach's Alpha is calculated for the scale. If the model is SPLIT, then the variables are divided into 2 subsets. An optional parameter @var{N} may be given, to specify how many variables to be in the first subset. @@ -1583,11 +1583,11 @@ The default model is ALPHA. By default, any cases with user missing, or system missing values for any variables given -in the VARIABLES subcommand will be omitted from analysis. -The MISSING subcommand determines whether user missing values are to +in the @subcmd{VARIABLES} subcommand will be omitted from analysis. +The @subcmd{MISSING} subcommand determines whether user missing values are to be included or excluded in the analysis. -The SUMMARY subcommand determines the type of summary analysis to be performed. +The @subcmd{SUMMARY} subcommand determines the type of summary analysis to be performed. Currently there is only one type: SUMMARY=TOTAL, which displays per-item analysis tested against the totals. @@ -1634,14 +1634,14 @@ In addition, a p-value under the null hypothesis that the area under the curve e printed. The COORDINATES keyword says that a table of coordinates of the ROC curve should be printed. -The CRITERIA subcommand has four optional parameters: +The @subcmd{CRITERIA} subcommand has four optional parameters: @itemize @bullet @item The TESTPOS parameter may be LARGE or SMALL. LARGE is the default, and says that larger values in the predictor variables are to be considered positive. SMALL indicates that smaller values should be considered positive. @item The CI parameter specifies the confidence interval that should be printed. -It has no effect if the SE keyword in the PRINT subcommand has not been given. +It has no effect if the SE keyword in the @subcmd{PRINT} subcommand has not been given. @item The DISTRIBUTION parameter determines the method to be used when estimating the area under the curve. @@ -1655,7 +1655,7 @@ The default is FREE. @item The CUTOFF parameter is for compatibility and is ignored. @end itemize -The MISSING subcommand determines whether user missing values are to +The @subcmd{MISSING} subcommand determines whether user missing values are to be included or excluded in the analysis. The default behaviour is to exclude them. Cases are excluded on a listwise basis; if any of the variables in @var{var_list} diff --git a/doc/transformation.texi b/doc/transformation.texi index 7ca689c27b..97711915dc 100644 --- a/doc/transformation.texi +++ b/doc/transformation.texi @@ -36,7 +36,7 @@ Cases are divided into groups that have the same values for one or more variables called @dfn{break variables}. Several functions are available for summarizing case contents. -The OUTFILE subcommand is required and must appear first. Specify a +The @subcmd{OUTFILE} subcommand is required and must appear first. Specify a system file or portable file by file name or file handle (@pxref{File Handles}), or a dataset by its name (@pxref{Datasets}). @@ -244,7 +244,7 @@ to 1), specify DESCENDING. PRINT is currently ignored. -The GROUP subcommand is relevant only if more than one variable is to be +The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be recoded. It causes a single mapping between source and target values to be used, instead of one map per variable. @@ -413,9 +413,9 @@ causes cases to be swapped with variables, and vice versa. All variables in the transposed active dataset are numeric. String variables take on the system-missing value in the transposed file. -No subcommands are required. If specified, the VARIABLES subcommand +@subcmd{N} subcommands are required. If specified, the @subcmd{VARIABLES} subcommand selects variables to be transformed into cases, and variables not -specified are discarded. If the VARIABLES subcommand is omitted, all +specified are discarded. If the @subcmd{VARIABLES} subcommand is omitted, all variables are selected for transposition. The variables specified by NEWNAMES, which must be a string variable, is diff --git a/doc/utilities.texi b/doc/utilities.texi index b40d8c8e67..941451fdc4 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -230,7 +230,7 @@ HOST COMMAND=['command'...]. to the operating system. This command cannot be used if the SAFER setting is active. -If the COMMAND subcommand is specified, as a sequence of shell +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. @@ -257,7 +257,7 @@ The @cmd{INSERT} command (@pxref{INSERT}) is a more flexible alternative to @cmd{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 on INSERT. +The optional @subcmd{ENCODING} subcommand has the same meaning as on INSERT. @node INSERT @section INSERT @@ -458,7 +458,7 @@ SET @pspp{}'s execution. Since there are many subcommands to this command, its subcommands will be examined in groups. -On subcommands that take boolean values, ON and YES are synonym, and +For subcommands that take boolean values, ON and YES are synonymous, as are OFF and NO, when used as subcommand values. The data input subcommands affect the way that data is read from data diff --git a/doc/variables.texi b/doc/variables.texi index 6fd4944a9f..1bd745fa83 100644 --- a/doc/variables.texi +++ b/doc/variables.texi @@ -81,7 +81,7 @@ be displayed. With these keywords, by default information is displayed about all variable in the active dataset, in the order that variables occur in the active dataset dictionary. The SORTED keyword causes output to be sorted alphabetically by variable name. The -VARIABLES subcommand limits output to the specified variables. +@subcmd{VARIABLES} subcommand limits output to the specified variables. @table @asis @item NAMES @@ -247,7 +247,7 @@ active dataset. At least one subcommand must be specified, and no subcommand may be specified more than once. DROP and KEEP may not both be specified. -The REORDER subcommand changes the order of variables in the active +The @subcmd{REORDER} subcommand changes the order of variables in the active dataset. Specify one or more lists of variable names in parentheses. By default, each list of variables is rearranged into the specified order. To put the variables into the reverse of the specified order, put @@ -262,10 +262,10 @@ same number of old and new variable names. Each old variable is renamed to the corresponding new variable name. Multiple parenthesized groups of variables may be specified. -The DROP subcommand deletes a specified list of variables from the +The @subcmd{DROP} subcommand deletes a specified list of variables from the active dataset. -The KEEP subcommand keeps the specified list of variables in the active +The @subcmd{KEEP} subcommand keeps the specified list of variables in the active dataset. Any unlisted variables are deleted from the active dataset. MAP is currently ignored. @@ -313,7 +313,7 @@ represents one of the responses. Any number of subcommands may be specified in any order. -The MDGROUP subcommand creates a new multiple dichotomy set or +The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or replaces an existing multiple response set. The NAME, VARIABLES, and VALUE specifications are required. The others are optional: @@ -365,19 +365,19 @@ LABELSOURCE=VARLABEL must be used with CATEGORYLABELS=COUNTEDVALUES. It is mutually exclusive with LABEL. @end itemize -The MCGROUP subcommand creates a new multiple category set or +The @subcmd{MCGROUP} subcommand creates a new multiple category set or replaces an existing multiple response set. The NAME and VARIABLES specifications are required, and LABEL is optional. Their meanings are as described above to MDGROUP. @pspp{} warns if two variables in the set have different value labels for a single value, since each of the variables in the set should have the same possible categories. -The DELETE subcommand deletes multiple response groups. A list of +The @subcmd{DELETE} subcommand deletes multiple response groups. A list of groups may be named within a set of required square brackets, or ALL may be used to delete all groups. -The DISPLAY subcommand displays information about defined multiple -response sets. Its syntax is the same as the DELETE subcommand. +The @subcmd{DISPLAY} subcommand displays information about defined multiple +response sets. Its syntax is the same as the @subcmd{DELETE} subcommand. Multiple response sets are saved to and read from system files by, e.g., the @cmd{SAVE} and @cmd{GET} command. Otherwise, multiple @@ -501,11 +501,11 @@ variable attributes are not interpreted by @pspp{}, but they are saved as part of system files and may be used by other software that reads them. -The required VARIABLES subcommand must come first. Specify the -variables to which the following ATTRIBUTE or DELETE subcommand +The required @subcmd{VARIABLES} subcommand must come first. Specify the +variables to which the following ATTRIBUTE or @subcmd{DELETE} subcommand should apply. -Use the ATTRIBUTE subcommand to add or modify custom variable +Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable attributes. Specify the name of the attribute as an identifier (@pxref{Tokens}), followed by the desired value, in parentheses, as a quoted string. The specified attributes are then added or modified in @@ -521,7 +521,7 @@ element, add an integer array index enclosed in square brackets indexes start at 1, not 0. An attribute array that has a single element (number 1) is not distinguished from a non-array attribute. -Use the DELETE subcommand to delete an attribute from the variable +Use the @subcmd{DELETE} subcommand to delete an attribute from the variable specified on VARIABLES. Specify an attribute name by itself to delete an entire attribute, including all array elements for attribute arrays. Specify an attribute name followed by an array index in -- 2.30.2