X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=116c49fa8cb6b5a6ca4dc359bbad58108798f587;hb=6f422d9a7e709779c5ba8d1589fe294849dd38e8;hp=63a26196688d5ef7a9d307daf09e86bc85266786;hpb=3fea8cd4cbac70bb4e5f9e91e8505ed1dd4c3ea7;p=pspp-builds.git

diff --git a/doc/utilities.texi b/doc/utilities.texi
index 63a26196..116c49fa 100644
--- a/doc/utilities.texi
+++ b/doc/utilities.texi
@@ -1,4 +1,4 @@
-@node Utilities, Not Implemented, Statistics, Top
+@node Utilities
 @chapter Utilities
 
 Commands that don't fit any other category are placed here.
@@ -9,6 +9,7 @@ they take effect only once, unconditionally, at the time that they are
 encountered in the input.
 
 @menu
+* ADD DOCUMENT::                Add documentary text to the active file.
 * COMMENT::                     Document your syntax file.
 * DOCUMENT::                    Document the active file.
 * DISPLAY DOCUMENTS::           Display active file documents.
@@ -22,14 +23,35 @@ encountered in the input.
 * HOST::                        Temporarily return to the operating system.
 * INCLUDE::                     Include a file within the current one.
 * PERMISSIONS::                 Change permissions on a file.
-* QUIT::                        Terminate the PSPP session.
 * SET::                         Adjust PSPP runtime parameters.
 * SHOW::                        Display runtime parameters.
 * SUBTITLE::                    Provide a document subtitle.
 * TITLE::                       Provide a document title.
 @end menu
 
-@node COMMENT, DOCUMENT, Utilities, Utilities
+@node ADD DOCUMENT, COMMENT, Utilities, Utilities
+@comment  node-name,  next,  previous,  up
+@section ADD DOCUMENT
+@vindex  ADD DOCUMENT
+
+@display
+ADD DOCUMENT 
+    'line one' 'line two' @dots{} 'last line' .
+@end display
+
+
+@cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to 
+the active file.  Documents added in this way are saved to system files.
+They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
+DOCUMENTS}.  They can be removed from the active file with @cmd{DROP
+DOCUMENTS}.
+
+Each line of documentary text must be enclosed in quotation marks, and 
+may not be more than 80 bytes long. @xref{DOCUMENT}.
+
+
+
+@node COMMENT
 @section COMMENT
 @vindex COMMENT
 @vindex *
@@ -46,12 +68,14 @@ the author and other readers of the PSPP syntax file.
 @cmd{COMMENT} can extend over any number of lines.  Don't forget to
 terminate it with a dot or a blank line.
 
-@node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities
+
+
+@node DOCUMENT
 @section DOCUMENT
 @vindex DOCUMENT
 
 @display
-DOCUMENT documentary_text.
+DOCUMENT @var{documentary_text}.
 @end display
 
 @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the
@@ -60,12 +84,14 @@ They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY
 DOCUMENTS}.  They can be removed from the active file with @cmd{DROP
 DOCUMENTS}.
 
-Specify the documentary text following the DOCUMENT keyword.  You can
-extend the documentary text over as many lines as necessary.  Lines are
-truncated at 80 characters width.  Don't forget to terminate
-the command with a dot or a blank line.
+Specify the @var{documentary text} following the DOCUMENT keyword.  
+It is interpreted literally --- any quotes or other punctuation marks 
+will be included in the file.
+You can extend the documentary text over as many lines as necessary.  
+Lines are truncated at 80 bytes.  Don't forget to terminate
+the command with a dot or a blank line. @xref{ADD DOCUMENT}.
 
-@node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities
+@node DISPLAY DOCUMENTS
 @section DISPLAY DOCUMENTS
 @vindex DISPLAY DOCUMENTS
 
@@ -77,7 +103,7 @@ DISPLAY DOCUMENTS.
 document is preceded by a line giving the time and date that it was
 added.  @xref{DOCUMENT}.
 
-@node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities
+@node DISPLAY FILE LABEL
 @section DISPLAY FILE LABEL
 @vindex DISPLAY FILE LABEL
 
@@ -89,7 +115,9 @@ DISPLAY FILE LABEL.
 active file,
 if any.  @xref{FILE LABEL}.
 
-@node DROP DOCUMENTS, ECHO, DISPLAY FILE LABEL, Utilities
+This command is a PSPP extension.
+
+@node DROP DOCUMENTS
 @section DROP DOCUMENTS
 @vindex DROP DOCUMENTS
 
@@ -103,7 +131,7 @@ New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}).
 @cmd{DROP DOCUMENTS} changes only the active file.  It does not modify any
 system files stored on disk.
 
-@node ECHO, ERASE, DROP DOCUMENTS, Utilities
+@node ECHO
 @section ECHO
 @vindex ECHO
 
@@ -113,7 +141,7 @@ ECHO 'arbitrary text' .
 
 Use @cmd{ECHO} to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (@pxref{Tokens}).
 
-@node ERASE, EXECUTE, ECHO, Utilities
+@node ERASE
 @comment  node-name,  next,  previous,  up
 @section ERASE
 @vindex ERASE
@@ -127,7 +155,7 @@ file_name must be quoted.
 This command cannot be used if the SAFER setting is active.
 
 
-@node EXECUTE, FILE LABEL, ERASE, Utilities
+@node EXECUTE
 @section EXECUTE
 @vindex EXECUTE
 
@@ -138,7 +166,7 @@ EXECUTE.
 @cmd{EXECUTE} causes the active file to be read and all pending
 transformations to be executed.
 
-@node FILE LABEL, FINISH, EXECUTE, Utilities
+@node FILE LABEL
 @section FILE LABEL
 @vindex FILE LABEL
 
@@ -153,7 +181,7 @@ created during this PSPP run.
 file_label need not be quoted.  If quotes are
 included, they become part of the file label.
 
-@node FINISH, HOST, FILE LABEL, Utilities
+@node FINISH
 @section FINISH
 @vindex FINISH
 
@@ -164,9 +192,7 @@ FINISH.
 @cmd{FINISH} terminates the current PSPP session and returns
 control to the operating system.
 
-This command is not valid in interactive mode.
-
-@node HOST, INCLUDE, FINISH, Utilities
+@node HOST
 @comment  node-name,  next,  previous,  up
 @section HOST
 @vindex HOST
@@ -180,15 +206,15 @@ to the operating system.
 This command cannot be used if the SAFER setting is active.
 
 
-@node INCLUDE, PERMISSIONS, HOST, Utilities
+@node INCLUDE
 @section INCLUDE
 @vindex INCLUDE
 @vindex @@
 
 @display
 Two possible syntaxes:
-        INCLUDE 'filename'.
-        @@filename.
+        INCLUDE 'file-name'.
+        @@file-name.
 @end display
 
 @cmd{INCLUDE} causes the PSPP command processor to read an
@@ -198,7 +224,7 @@ command file.
 Include files may be nested to any depth, up to the limit of available
 memory.
 
-@node PERMISSIONS, QUIT, INCLUDE, Utilities
+@node PERMISSIONS
 @comment  node-name,  next,  previous,  up
 @section PERMISSIONS
 @vindex PERMISSIONS
@@ -208,7 +234,7 @@ memory.
 
 @display
 PERMISSIONS
-        FILE='filename'
+        FILE='file-name'
         /PERMISSIONS = @{READONLY,WRITEABLE@}.
 @end display
 
@@ -223,22 +249,7 @@ unchanged.
 This command cannot be used if the SAFER setting is active.
 
 
-@node QUIT, SET, PERMISSIONS, Utilities
-@section QUIT
-@vindex QUIT
-
-@display
-Two possible syntaxes:
-        QUIT.
-        EXIT.
-@end display
-
-@cmd{QUIT} terminates the current PSPP session and returns control
-to the operating system.  
-
-This command is not valid within a command file.
-
-@node SET, SHOW, QUIT, Utilities
+@node SET
 @section SET
 @vindex SET
 
@@ -250,6 +261,8 @@ SET
         /DECIMAL=@{DOT,COMMA@}
         /FORMAT=fmt_spec
         /EPOCH=@{AUTOMATIC,year@}
+        /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
+        /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 
 (program input)
         /ENDCMD='.'
@@ -276,6 +289,8 @@ SET
         /CC@{A,B,C,D,E@}=@{'npre,pre,suf,nsuf','npre.pre.suf.nsuf'@}
         /DECIMAL=@{DOT,COMMA@}
         /FORMAT=fmt_spec
+        /WIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@}
+        /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@}
 
 (output routing)
         /ECHO=@{ON,OFF@}
@@ -288,12 +303,12 @@ SET
 (output driver options)
         /HEADERS=@{NO,YES,BLANK@}
         /LENGTH=@{NONE,length_in_lines@}
-        /LISTING=@{ON,OFF,filename@}
+        /LISTING=@{ON,OFF,'file-name'@}
         /MORE=@{ON,OFF@}
         /WIDTH=@{NARROW,WIDTH,n_characters@}
 
 (logging)
-        /JOURNAL=@{ON,OFF@} [filename]
+        /JOURNAL=@{ON,OFF@} ['file-name']
 
 (system files)
         /COMPRESSION=@{ON,OFF@}
@@ -338,22 +353,86 @@ system-missing value to be assigned to null items.  This is the
 default.  Any real value may be assigned.
 
 @item DECIMAL
+@anchor{SET DECIMAL}
 The default DOT setting causes the decimal point character to be
-@samp{.}.  A setting of COMMA causes the decimal point character to be
-@samp{,}.
+@samp{.} and the grouping character to be @samp{,}.  A setting of COMMA
+causes the decimal point character to be @samp{,} and the grouping
+character to be @samp{.}.
 
 @item FORMAT
 Allows the default numeric input/output format to be specified.  The
-default is F8.2.  @xref{Input/Output Formats}.
+default is F8.2.  @xref{Input and Output Formats}.
 
 @item EPOCH
 @anchor{SET EPOCH}
 Specifies the range of years used when a 2-digit year is read from a
 data file or used in a date construction expression (@pxref{Date
-Construction}).  If a 4-digit year is specified, then 2-digit years
-are interpreted starting from that year, known as the epoch.  If
-AUTOMATIC (the default) is specified, then the epoch begins 69 years
-before the current date.
+Construction}).  If a 4-digit year is specified for the epoch, then
+2-digit years are interpreted starting from that year, known as the
+epoch.  If AUTOMATIC (the default) is specified, then the epoch begins
+69 years before the current date.
+
+@item RIB
+@anchor{SET RIB} 
+
+PSPP extension to set the byte ordering (endianness) used for reading
+data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
+Formats}).  In MSBFIRST ordering, the most-significant byte appears at
+the left end of a IB or PIB field.  In LSBFIRST ordering, the
+least-significant byte appears at the left end.  VAX ordering is like
+MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
+the default, is equivalent to MSBFIRST or LSBFIRST depending on the
+native format of the machine running PSPP.
+
+@item RRB
+@anchor{SET RRB}
+
+PSPP extension to set the floating-point format used for reading data in
+RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The
+possibilities are:
+
+@table @asis
+@item NATIVE
+The native format of the machine running PSPP.  Equivalent to either IDL
+or IDB.
+
+@item ISL
+32-bit IEEE 754 single-precision floating point, in little-endian byte
+order.
+
+@item ISB
+32-bit IEEE 754 single-precision floating point, in big-endian byte
+order.
+
+@item IDL
+64-bit IEEE 754 double-precision floating point, in little-endian byte
+order.
+
+@item IDB
+64-bit IEEE 754 double-precision floating point, in big-endian byte
+order.
+
+@item VF
+32-bit VAX F format, in VAX-endian byte order.
+
+@item VD
+64-bit VAX D format, in VAX-endian byte order.
+
+@item VG
+64-bit VAX G format, in VAX-endian byte order.
+
+@item ZS
+32-bit IBM Z architecture short format hexadecimal floating point, in
+big-endian byte order.  
+
+@item ZL
+64-bit IBM Z architecture long format hexadecimal floating point, in
+big-endian byte order.
+
+Z architecture also supports IEEE 754 floating point.  The ZS and ZL
+formats are only for use with very old input files.
+@end table
+The default is NATIVE.
 @end table
 
 Program input subcommands affect the way that programs are parsed when
@@ -426,18 +505,10 @@ subcommands are
 @itemx CCC
 @itemx CCD
 @itemx CCE
-Set up custom currency formats.  The argument is a string which must
-contain exactly three commas or exactly three periods.  If commas, then
-the grouping character for the currency format is @samp{,}, and the
-decimal point character is @samp{.}; if periods, then the situation is
-reversed.  
-
-The commas or periods divide the string into four fields, which are, in
-order, the negative prefix, prefix, suffix, and negative suffix.  When a
-value is formatted using the custom currency format, the prefix precedes
-the value formatted and the suffix follows it.  In addition, if the
-value is negative, the negative prefix precedes the prefix and the
-negative suffix follows the suffix.
+@anchor{CCx Settings}
+
+Set up custom currency formats.  @xref{Custom Currency Formats}, for
+details.
 
 @item DECIMAL
 The default DOT setting causes the decimal point character to be
@@ -446,7 +517,26 @@ The default DOT setting causes the decimal point character to be
 
 @item FORMAT
 Allows the default numeric input/output format to be specified.  The
-default is F8.2.  @xref{Input/Output Formats}.
+default is F8.2.  @xref{Input and Output Formats}.
+
+@item WIB
+@anchor{SET WIB} 
+
+PSPP extension to set the byte ordering (endianness) used for writing
+data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric
+Formats}).  In MSBFIRST ordering, the most-significant byte appears at
+the left end of a IB or PIB field.  In LSBFIRST ordering, the
+least-significant byte appears at the left end.  VAX ordering is like
+MSBFIRST, except that each pair of bytes is in reverse order.  NATIVE,
+the default, is equivalent to MSBFIRST or LSBFIRST depending on the
+native format of the machine running PSPP.
+
+@item WRB
+@anchor{SET WRB}
+
+PSPP extension to set the floating-point format used for writing data in
+RB format (@pxref{Binary and Hexadecimal Numeric Formats}).  The choices
+are the same as SET RIB.  The default is NATIVE.
 @end table
 
 Output routing subcommands affect where the output of transformations
@@ -522,7 +612,7 @@ The HOST command.
 @item
 The PERMISSIONS command.
 @item
-Pipe filenames (filenames beginning or ending with @samp{|}).
+Pipes (file names beginning or ending with @samp{|}).
 @end itemize
 
 Be aware that this setting does not guarantee safety (commands can still
@@ -531,7 +621,7 @@ When set, this setting cannot be reset during the same session, for
 obvious security reasons.
 @end table
 
-@node SHOW, SUBTITLE, SET, Utilities
+@node SHOW
 @comment  node-name,  next,  previous,  up
 @section SHOW
 @vindex SHOW
@@ -580,7 +670,7 @@ Display the terms of PSPP's copyright licence (@pxref{License}).
 
 Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL.
 
-@node SUBTITLE, TITLE, SHOW, Utilities
+@node SUBTITLE
 @section SUBTITLE
 @vindex SUBTITLE
 
@@ -598,7 +688,7 @@ Specify a subtitle as a string in quotes.  The alternate syntax that did
 not require quotes is now obsolete.  If it is used then the subtitle is
 converted to all uppercase.
 
-@node TITLE,  , SUBTITLE, Utilities
+@node TITLE
 @section TITLE
 @vindex TITLE