Initial commit

1 files changed, 154 insertions, 0 deletions

diff --git a/pkg/language/doc/fprint.hlp b/pkg/language/doc/fprint.hlp
new file mode 100644
index 00000000..37a83ef8
--- /dev/null
+++ b/pkg/language/doc/fprint.hlp
@@ -0,0 +1,154 @@
+.help "fprint,print,printf" Jul95 language
+.ih
+NAME
+.nf
+print  -- print to the standard output
+fprint -- print to a parameter
+printf -- formatted print to the standard output
+.fi
+.ih
+USAGE
+.nf
+print  expr [expr ...]
+fprint param expr [expr ...]
+printf format [arg ...]
+.fi
+.ih
+PARAMETERS
+.ls expr
+Any expression, the string value of which is to be printed.
+.le
+.ls param
+The \fIfprint\fR call will deposit the output string in the value field of 
+this parameter.
+.le
+.ls format
+A C-like format specification string containing plain characters, which 
+are simply copied into the output string, and conversion specifications,
+each of which causes conversion and printing of zero or more \fIargs\fR.
+.le
+.ls arg    
+Any expression, variable, parameter value or constant to be used in the
+\fIformat\fR string's conversion specifications.  One arg is required for
+each conversion specification.
+.le
+.ih
+DESCRIPTION
+The \fIprint\fR and \fIfprint\fR commands format a line of text and write
+it to either the standard output or in the case of \fIfprint\fR,
+the p_value field of the named parameter.  The output is free format although
+spaces may be specifically inserted (as quoted string constants) to make the
+output easier to read.  One space is automatically inserted after each
+numeric argument; this can be defeated by coercing the argument to a string
+with the \fIstr\fR intrinsic function.  A newline is automatically output
+at the end of the output line.  I/O redirection may be used with \fIprint\fR
+or \fIprintf\fR to write to a file or through a pipe to another task.
+
+The \fIprintf\fR command allows more control over the output format and can
+convert arguments for printing as another type.  The \fIformat\fR string
+contains plain text characters and format specifications as well as
+escape sequences for printing tabs, newlines, etc. Unlike the other
+two commands, spaces and newlines must be explicitly given in the format
+string.  
+
+A format specification has the form "%[W][.D]Cn", where W is  the  field
+width,  D is the number of decimal places or the number of digits of
+precision, C is the format  code,  and  N  is  radix  character  for
+format  code "r" only.  The W and D fields are optional.  The format
+codes C are as follows:
+
+.nf
+       b    boolean (YES or NO)
+       c    single character (c or '\c' or '\0nnn')
+       d    decimal integer
+       e    exponential format (D specifies the precision)
+       f    fixed format (D specifies the number of decimal places)
+       g    general format (D specifies the precision)
+       h    hms format (hh:mm:ss.ss, D = no. decimal places)
+       m    minutes, seconds (or hours, minutes) (mm:ss.ss)
+       o    octal integer
+       rN   convert integer in any radix N
+       s    string (D field specifies max chars to print)
+       t    advance To column given as field W
+       u    unsigned decimal integer 
+       w    output the number of spaces given by field W
+       x    hexadecimal integer
+       z    complex format (r,r) (D = precision)
+.fi
+
+Conventions for W (field width) specification:
+
+.nf
+    W =  n      right justify in field of N characters, blank fill
+        -n      left justify in field of N characters, blank fill
+        0n      zero fill at left (only if right justified)
+    absent, 0   use as much space as needed (D field sets precision)
+.fi
+
+Escape sequences (e.g. "\n" for newline):
+.nf
+        \f      formfeed
+        \n      newline (crlf)
+        \r      carriage return
+        \t      tab
+        \"      string delimiter character
+        \'      character constant delimiter character
+        \\      backslash character
+        \nnn    octal value of character
+.fi
+
+Compute mode (a parenthesized argument list) is recommended for this task
+to avoid surprises.
+.ih
+EXAMPLES
+1. Print the name of the current terminal.
+
+	cl> print ("terminal = ", envget ("terminal"))
+
+2. Output a blank line on the standard output, e.g., in a script.
+
+	print ("")
+
+3. Format a command and send it to the host system.  In this example,
+"fname" is a string valued parameter.
+
+	cl> print ("!ls -l ", fname) | cl
+
+4. Write to a file.
+
+.nf
+	for (x=1.;  x < 1E5;  x *= 10) 
+	    print ("the sqrt of ", x, "is ", sqrt(x), >> "output")
+.fi
+
+5. Print a formatted string.
+
+.nf
+	cl> printf ("pi = %.6f\n", 2*atan2(1.0,0.0))
+	pi = 3.141593
+	cl> printf ("RA = %h  DEC = %m\nExptime = %8.2f\n",ra,dec,etime)
+	RA = 18:32:33.5 DEC = 23:45.2	Exptime =     1.57
+.fi
+
+6. Print to a parameter.  Note that \fIfprint\fR allows you to create a 
+formatted string, whereas the scan() example requires a struct parameter.
+
+.nf
+	cl> x = 3.14159
+	cl> fprint (s1, "pi = ", x)
+	cl> = s1
+	pi = 3.14159
+
+	     or 
+
+	cl> printf ("pi = %g\n", x) | scan (line)
+.fi
+
+.ih
+BUGS
+The \fIfprint\fR task is not very useful since the same thing can be
+accomplished by string concatenation and assignment.
+.ih
+SEE ALSO
+scan, scanf, fscan, fscanf, strings
+.endhelp