* Some updates

docs/Makefile

@@ -85,7 +85,8 @@ DVI = $(addsuffix .dvi, $(HTML))
 TXT = $(addsuffix .txt, $(HTML))
 PDF = $(addsuffix .pdf, $(HTML))
 
-CHAPTERS = $(addsuffix .tex, crt dos getopts go32 graph linux printer strings)
+CHAPTERS = $(addsuffix .tex, crt dos getopts go32 graph linux printer\
+              strings objects heaptrc)
 
 # Check if ascii-mode requested
 ifeq ($(ASCIIMODE),YES)
@@ -159,6 +160,8 @@ clean:
 	-$(MAKE) -C go32ex clean
 	-$(MAKE) -C stringex clean
 	-$(MAKE) -C refex clean
+	-$(MAKE) -C heapex clean
+	-$(MAKE) -C objectex clean
 
 $(TXT) : %.txt: %.dvi
 
@@ -178,6 +181,8 @@ unitex.chk:
 	$(MAKE) -C sockex tex
 	$(MAKE) -C mouseex tex
 	$(MAKE) -C go32ex tex
+	$(MAKE) -C heapex tex
+	$(MAKE) -C objectex tex
 	touch unitex.chk
 
 refex.chk:
@@ -326,7 +331,10 @@ linuxexamples: examples
 
 #
 # $Log$
-# Revision 1.15  1998-11-17 23:42:02  michael
+# Revision 1.16  1998-12-15 23:50:53  michael
+# * Some updates
+#
+# Revision 1.15  1998/11/17 23:42:02  michael
 # + too many changes to enumerate
 #
 # Revision 1.14  1998/10/01 12:57:22  michael

docs/heaptrc.tex

@@ -93,21 +93,21 @@ Call trace for block 0x080528A0 size 4
 
 \section{Constants, Types and variables}
 
-The \var{fill\_extra\_info\_type} is a procedural type used in the
-\seepl{Set\_Extra\_Info}{SetExtraInfo} call.
+The \var{FillExtraInfoType} is a procedural type used in the
+\seep{SetExtraInfo} call.
 
 \begin{listing}
 type
-    fill_extra_info_type = procedure(p : pointer);
+    FillExtraInfoType = procedure(p : pointer);
 \end{listing}
 The following typed constants allow to fine-tune the standard dump of the
-memory usage by \seepl{Dump\_Heap}{DumpHeap}:
+memory usage by \seep{DumpHeap}:
 
 \begin{listing}
 const
   tracesize = 8;
   quicktrace : boolean = true;
-  halt_on_error : boolean = true;
+  HaltOnError : boolean = true;
   keepreleased : boolean = false;
 \end{listing}
 
@@ -121,11 +121,14 @@ to be dumped for the getmem call if \var{keepreleased} is \var{False}. If
 the \var{GetMem} call and 4 frames wil be dumped for the \var{FreeMem} call.
 If you want to change this value, you must recode the \file{heaptrc} unit.
 
-\var{Quicktrace} determines whether
+\var{Quicktrace} determines whether the memory manager checks whether a 
+block that is about to be released is allocated correctly. This is a rather
+time consuming search, and slows program execution significantly, so by
+default it is set to \var{False}.
 
-If \var{halt\_on\_error} is set to \var{True} then an illegal call to 
+If \var{HaltOnError} is set to \var{True} then an illegal call to 
 \var{FreeMem} will cause the memory manager to execute a \var{halt(1)} 
-instruction, causing a memory dump.
+instruction, causing a memory dump. By Default it is set to \var{True}.
 
 If \var{keepreleased} is set to true, then a list of freed memory 
 blocks is kept. This is useful if you suspect that the same memory block is
@@ -134,36 +137,36 @@ sparingly, and only when it's really necessary.
 
 \section{Functions and procedures}
 
-\begin{procedurel}{Dump\_Heap}{DumpHeap}
+\begin{procedure}{DumpHeap}
 \Declaration 
-procedure Dump\_Heap;
+procedure DumpHeap;
 \Description
-\var{dump\_heap} dumps to standard output a summary of memory usage.
+\var{DumpHeap} dumps to standard output a summary of memory usage.
 It is called automatically by the heaptrc unit when your program exits
 (by instaling an exit procedure), but it can be called at any time
 \Errors
 None.
 \SeeAlso
-\seepl{Mark\_Heap}{MarkHeap}
-\end{procedurel}
+\seep{MarkHeap}
+\end{procedure}
 
-\begin{procedurel}{Mark\_Heap}{MarkHeap}
+\begin{procedure}{MarkHeap}
 \Declaration
-procedure Mark\_Heap;
+procedure MarkHeap;
 \Description
-\var{Mark\_Heap} marks all memory blocks with a special signature.
-You can use this if you think that you corruped the
+\var{MarkHeap} marks all memory blocks with a special signature.
+You can use this if you think that you corruped the memory.
 \Errors
 None.
 \SeeAlso
-\seepl{Dump\_Heap}{DumpHeap}
-\end{procedurel}
+\seep{DumpHeap}
+\end{procedure}
 
-\begin{procedurel}{Set\_Extra\_Info}{SetExtraInfo}
+\begin{procedure}{SetExtraInfo}
 \Declaration
-procedure Set\_Extra\_Info( size : longint;func : fill\_extra\_info\_type);
+procedure SetExtraInfo( size : longint;func : FillExtraInfoType);
 \Description
-You can use \var{Set\_Extra\_Info} to store extra info in the blocks that
+You can use \var{SetExtraInfo} to store extra info in the blocks that
 the heaptrc unit reserves when tracing getmem calls. \var{Size} indicates the
 size (in bytes) that the trace mechanism should reserve for your extra
 information. For each call to \var{getmem}, \var{func} will be called,
@@ -172,13 +175,13 @@ and passed a pointer to the memory reserved.
 When dumping the memory summary, the extra info is shown as Longint values.
 
 \Errors
-You can only call \var{Set\_Extra\_Info} if no memroy has been allocated
+You can only call \var{SetExtraInfo} if no memroy has been allocated
 yet. If memory was already allocated prior to the call to
-\var{Set\_Extra\_Info}, then an error will be displayed on standard error
-output, and a \seepl{Dump\_Heap}{DumpHeap} is executed.
+\var{SetExtraInfo}, then an error will be displayed on standard error
+output, and a \seep{DumpHeap} is executed.
 \SeeAlso
-\seepl{Dump\_Heap}{DumpHeap}
-\end{procedurel}
+\seep{DumpHeap}
+\end{procedure}
 
 \latex{\inputlisting{heapex/setinfo.pp}}
 \html{\input{heapex/setinfo.tex}}
@@ -186,7 +189,10 @@ output, and a \seepl{Dump\_Heap}{DumpHeap} is executed.
 
 %
 % $Log$
-% Revision 1.1  1998-12-14 23:17:02  michael
+% Revision 1.2  1998-12-15 23:50:52  michael
+% * Some updates
+%
+% Revision 1.1  1998/12/14 23:17:02  michael
 % + INitial implementation
 %
 %

docs/objects.tex

@@ -183,7 +183,7 @@ otherwise.
 \Errors
 None.
 \SeeAlso
-\seef{TRect.Empty}, \seef{TRect.Contains}
+\seefl{Empty}{TRect.Empty}, \seefl{Contains}{TRect.Contains}
 \end{function}
 
 For an example, see \seef{TRect.Empty}
@@ -197,7 +197,7 @@ in the rectangle (including borders), \var{False} otherwise.
 \Errors
 None.
 \SeeAlso
-\seep{TRect.Intersect}, \seef{TRect.Equals}
+\seepl{Intersect}{TRect.Intersect}, \seefl{Equals}{TRect.Equals}
 \end{function}
 
 \begin{procedure}{TRect.Copy}
@@ -209,7 +209,7 @@ rectangle R has been copied to the object that invoked \var{Copy}.
 \Errors
 None.
 \SeeAlso
-\seep{TRect.Assign}
+\seepl{Assign}{TRect.Assign}
 \end{procedure}
 
 \latex{\inputlisting{objectex/ex2.pp}}
@@ -224,7 +224,7 @@ of the current rectangle with the rectangle \var{R}.
 \Errors
 None.
 \SeeAlso
-\seep{TRect.Intersect}
+\seepl{Intersect}{TRect.Intersect}
 \end{procedure}
 
 \latex{\inputlisting{objectex/ex3.pp}}
@@ -240,7 +240,7 @@ rectangle at coordinate (0,0).
 \Errors
 None.
 \SeeAlso
-\var{TRect.Union}
+\seepl{Union}{TRect.Union}
 \end{procedure}
 
 \latex{\inputlisting{objectex/ex4.pp}}
@@ -256,7 +256,7 @@ points, and \var{ADY} to both end points.
 \Errors
 None.
 \SeeAlso
-\seep{TRect.Grow}
+\seepl{Grow}{TRect.Grow}
 \end{procedure}
 
 \latex{\inputlisting{objectex/ex5.pp}}
@@ -272,12 +272,12 @@ length 2*ADX to the width of the rectangle), and an amount \var{ADY} in
 the \var{Y} direction (both on the top and the bottom side of the rectangle,
 adding a length 2*ADY to the height of the rectangle. 
 
-X and Y can be negative. If the resulting rectangle is empty, it is set 
+\var{ADX} and \var{ADY} can be negative. If the resulting rectangle is empty, it is set 
 to the empty rectangle at \var{(0,0)}.
 \Errors
 None.
 \SeeAlso
-\seep{TRect.Move}.
+\seepl{Move}{TRect.Move}.
 \end{procedure}
 
 
@@ -292,6 +292,8 @@ Procedure Trect.Assign (XA, YA, XB, YB: Sw\_Integer);
 \var{(Xb,Yb)}.
 \Errors
 None.
+\SeeAlso
+\seepl{Copy}{TRect.Copy}
 \end{procedure}
 
 For an example, see \seep{TRect.Copy}.
@@ -318,10 +320,10 @@ with Zero bytes.
 \Errors
 None.
 \SeeAlso
-\seep{TObject.Free}, \seep{TObject.Done}
+\seepl{Free}{TObject.Free}, \seepl{Done}{TObject.Done}
 \end{procedure}
 
-For an example, see \seep{TObject.Free}
+For an example, see \seepl{Free}{TObject.Free}
 
 \begin{procedure}{TObject.Free}
 \Declaration
@@ -333,7 +335,7 @@ occupied by the instance of the object.
 No checking is performed to see whether \var{self} is \var{nil} and whether
 the object is indeed allocated on the heap.
 \SeeAlso
-\seep{TObject.Init}, \seep{TObject.Done}
+\seepl{Init}{TObject.Init}, \seepl{Done}{TObject.Done}
 \end{procedure}
 
 \latex{\inputlisting{objectex/ex7.pp}}
@@ -348,7 +350,7 @@ intended to be used in the \seep{TObject.Free} method.
 \Errors
 None.
 \SeeAlso
-\seep{TObject.Free}, \seep{TObject.Init}
+\seepl{Free}{TObject.Free}, \seepl{Init}{TObject.Init}
 \end{procedure}
 
 \section{TStream}
@@ -359,10 +361,11 @@ objects that have the capability to store and retrieve data.
 
 It defines a number of methods that are common to all objects that implement
 streaming, many of them are virtual, and are only implemented in the
-descendant types.
+descendrnt types.
 
 Programs should not instantiate objects of type TStream directly, but
-instead instantiate a descendant type.
+instead instantiate a descendant type, such as \var{TDosStream},
+\var{TMemoryStream}.
 
 This is the full declaration of the \var{TStream} object:
 \begin{verbatim}
@@ -394,6 +397,249 @@ TYPE
    PStream = ^TStream;
 \end{verbatim}
 
+\begin{function}{TStream.Get}
+\Declaration
+Function TStream.Get : PObject;
+\Description
+\var{Get} reads an object definition  from a stream, and returns
+a pointer to an instance of this object.
+\Errors
+On error, \var{TStream.Status} is set, and NIL is returned.
+\SeeAlso 
+\seepl{Put}{TStream.Put}
+\end{function}
+
+\begin{function}{TStream.StrRead}
+\Declaration
+Function TStream.StrRead: PChar;
+\Description
+\var{StrRead} reads a string from the stream, allocates memory
+for it, and returns a pointer to a null-terminated copy of the string
+on the heap.
+\Errors
+On error, \var{Nil} is returned.
+\SeeAlso
+\seepl{StrWrite}{TStream.StrWrite}, \seefl{ReadStr}{TStream.ReadStr}
+\end{function}
+
+\begin{function}{TStream.GetPos}
+\Declaration 
+TSTream.GetPos : Longint; Virtual;
+\Description
+If the stream's status is \var{stOk}, \var{GetPos} returns the current 
+position in the stream. Otherwise it returns \var{-1}
+\Errors
+\var{-1} is returned if the status is an error condition.
+\SeeAlso
+\seepl{Seek}{TStream.Seek}, \seefl{GetSize}{TStream.GetSize}
+\end{function}
+
+\begin{function}{TStream.GetSize}
+\Declaration
+Function TStream.GetSize: Longint; Virtual;
+\Description
+If the stream's status is \var{stOk} then \var{GetSize} returns
+the size of the stream, otherwise it returns \var{-1}.
+\Errors
+\var{-1} is returned if the status is an error condition.
+\SeeAlso
+\seepl{Seek}{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
+\end{function}
+
+\begin{function}{TStream.ReadStr}
+\Declaration
+Function TStream.ReadStr: PString;
+\Description
+\var{ReadStr} reads a string from the stream, copies it to the heap
+and returns a pointer to this copy. The string is saved as a pascal
+string, and hence is NOT null terminated.
+\Errors
+On error (e.g. not enough memory), \var{Nil} is returned.
+\SeeAlso
+\seefl{StrRead}{TStream.StrRead}
+\end{function}
+
+\begin{procedure}{TStream.Open}
+\Declaration
+Procedure TStream.Open (OpenMode: Word); Virtual;
+\Description
+\var{Open} is an abstract method, that should be overridden by descendent
+objects. Since opening a stream depends on the stream's type this is not
+surprising.
+\Errors
+None.
+\SeeAlso
+\seepl{Close}{TStream.Close}, \seepl{Reset}{TStream.Reset}
+\end{procedure}
+
+\begin{procedure}{TStream.Close}
+\Declaration
+Procedure TStream.Close; Virtual;
+\Description
+\var{Close} is an abstract method, that should be overridden by descendent
+objects. Since Closing a stream depends on the stream's type this is not
+surprising.
+\Errors
+None.
+\SeeAlso
+\seepl{Open}{TStream.Open}, \seepl{Reset}{TStream.Reset}
+\end{procedure}
+
+\begin{procedure}{TStream.Reset}
+\Declaration
+PROCEDURE TStream.Reset;
+\Description
+\var{Reset} sets the stream's status to \var{0}, as well as the ErrorInfo
+\Errors
+None.
+\SeeAlso
+\seepl{Open}{TStream.Open}, \seepl{Close}{TStream.Close}
+\end{procedure}
+
+\begin{procedure}{TStream.Flush}
+\Declaration 
+Procedure TStream.Flush; Virtual;
+\Description
+\var{Flush} is an abstract method that should be overridden by descendent
+objects. It serves to enable the programmer to tell streams that implement 
+a buffer to clear the buffer.
+\Errors
+None.
+\SeeAlso
+\seepl{Truncate}{TStream.Truncate}
+\end{procedure}
+
+\begin{procedure}{TStream.Truncate}
+\Declaration
+Procedure TStream.Truncate; Virtual;
+\Description
+\var{Truncate} is an abstract procedure that should be overridden by
+descendent objects. It serves to enable the programmer to truncate the
+size of the stream to the current file position.
+\Errors
+None.
+\SeeAlso
+\seepl{Seek}{TStream.Seek}
+\end{procedure}
+
+\begin{procedure}{TStream.Put}
+\Declaration
+Procedure TStream.Put (P: PObject);
+\Description
+\var{Put} writes the object pointed to by \var{P}. \var{P} should be
+non-nil. The object type must have been registered with \seep{RegisterType}.
+
+After the object has been written, it can be read again with \seefl{Get}{TStream.Get}.
+\Errors
+No check is done whether P is \var{Nil} or not. Passing \var{Nil} will cause
+a run-time error 216 to be generated. If the object has not been registered,
+the status of the stream will be set to \var{stPutError}.
+\SeeAlso
+\seefl{Get}{TStream.Get}
+\end{procedure}
+
+\begin{procedure}{TStream.StrWrite}
+\Declaration
+Procedure TStream.StrWrite (P: PChar);
+\Description
+\var{StrWrite} writes the null-terminated string \var{P} to the stream.
+\var{P} can only be 65355 bytes long.
+\Errors
+None.
+\SeeAlso
+\seepl{WriteStr}{TStream.WriteStr}, \seefl{StrRead}{TStream.StrRead},
+\seefl{ReadStr}{TStream.ReadStr}
+\end{procedure}
+
+\begin{procedure}{TStream.WriteStr}
+\Declaration
+Procedure TStream.WriteStr (P: PString);
+\Description
+\var{StrWrite} writes the pascal string pointed to by \var{P} to the stream.
+\Errors
+None.
+\SeeAlso
+\seepl{StrWrite}{TStream.StrWrite}, \seefl{StrRead}{TStream.StrRead},
+\seefl{ReadStr}{TStream.ReadStr}
+\end{procedure}
+
+\begin{procedure}{TStream.Seek}
+\Declaration      
+PROCEDURE TStream.Seek (Pos: LongInt); Virtual;
+\Description
+Seek sets the position to \var{Pos}. This position is counted
+from the beginning, and is zero based. (i.e. seeek(0) sets the position
+pointer on the first byte of the stream)
+\Errors
+If \var{Pos} is larger than the stream size, \var{Status} is set to
+\var{StSeekError}.
+\SeeAlso
+\seefl{GetPos}{TStream.GetPos}, \seefl{GetSize}{TStream.GetSize}
+\end{procedure}
+
+\begin{procedure}{TStream.Error}
+\Declaration
+Procedure TStream.Error (Code, Info: Integer); Virtual;
+\Description
+\var{Error} sets the stream's status to \var{Code} and \var{ErrorInfo}
+to \var{Info}. If the \var{StreamError} procedural variable is set,
+\var{Error} executes it, passing \var{Self} as an argument.
+
+This method should not be called directly from a program. It is intended to
+be used in descendent objects.
+\Errors
+None.
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{TStream.Read}
+\Declaration
+Procedure TStream.Read (Var Buf; Count: Sw\_Word); Virtual;
+\Description
+\var{Read} is an abstract method that should be overridden by descendent
+objects.
+
+\var{Read} reads \var{Count} bytes from the stream into \var{Buf}.
+It updates the position pointer, increasing it's value with \var{Count}. 
+\var{Buf} must be large enough to contain \var{Count} bytes.
+\Errors
+No checking is done to see if \var{Buf} is large enough to contain
+\var{Count} bytes. 
+\SeeAlso
+\seepl{Write}{TStream.Write}, \seefl{ReadStr}{TStream.ReadStr},
+\seefl{StrRead}{TStream.StrRead}
+\end{procedure}
+
+\begin{procedure}{TStream.Write}
+\Declaration
+Procedure TStream.Write (Var Buf; Count: Sw\_Word); Virtual;
+\Description
+\var{Write} is an abstract method that should be overridden by descendent
+objects.
+
+\var{Write} writes \var{Count} bytes to the stream from \var{Buf}.
+It updates the position pointer, increasing it's value with \var{Count}. 
+\Errors
+No checking is done to see if \var{Buf} actually contains \var{Count} bytes. 
+\SeeAlso
+\seepl{Read}{TStream.Read}, \seepl{WriteStr}{TStream.WriteStr},
+\seepl{StrWrite}{TStream.StrWrite}
+\end{procedure}
+
+\begin{procedure}{TStream.CopyFrom}
+\Declaration
+Procedure TStream.CopyFrom (Var S: TStream; Count: Longint);
+\Description
+\var{CopyFrom} reads Count bytes from stream \var{S} and stores them
+in the current stream. It uses the \seepl{Read}{TStream.Read} method
+to read the data, and the \seepl{Write}{TStream.Write} method to
+write in the current stream.
+\Errors
+None.
+\SeeAlso
+\seepl{Read}{TStream.Read}, \seepl{Write}{TStream.Write}
+\end{procedure}
+
 \section{TDosStream}
 \label{se:TDosStream}
 
@@ -633,7 +879,12 @@ FUNCTION NewStr (Const S: String): PString;
 PROCEDURE DisposeStr (P: PString);
 PROCEDURE Abstract;
 PROCEDURE RegisterObjects;
+\end{verbatim}
+\begin{procedure}{RegisterType}
+\Declaration
 PROCEDURE RegisterType (Var S: TStreamRec);
+\end{procedure}
+\begin{verbatim}
 FUNCTION LongMul (X, Y: Integer): LongInt;
 FUNCTION LongDiv (X: Longint; Y: Integer): Integer;
 

docs/onechap.tex

@@ -22,14 +22,16 @@
 \usepackage{a4}
 \usepackage{makeidx}
 \usepackage{html}
-\begin{latexonly}
-\usepackage{fpc}
-\usepackage{listings}\blankstringtrue
-\selectlisting{tp}\stringstyle{\ttfamily}}
-\end{latexonly}
-\begin{htmlonly}
-\input{fpc-html.tex}
-\end{htmlonly}
+\latex{%
+\usepackage{fpc}%
+\usepackage{listings}%
+\blankstringtrue%
+\selectlisting{tp}%
+\stringstyle{\ttfamily}%
+}
+\html{%
+\input{fpc-html.tex}%
+}
 \begin{document}
 %\input{crt.tex}
 %\input{dos.tex}