From a2d3269fb89d2d2aaa7d5e86a9106017c7cd948f Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 24 Feb 2003 23:37:52 +0000 Subject: [PATCH] + Preparations for version 1.0.8 --- docs/Makefile | 33 ++++++++++++++------ docs/crt.tex | 20 ++++++++++++ docs/dos.tex | 2 +- docs/fpc.sty | 4 +-- docs/go32.tex | 2 +- docs/graph.tex | 20 +++++++----- docs/math.tex | 2 +- docs/mouse.tex | 4 +++ docs/onechap.tex | 3 +- docs/printer.tex | 8 ++--- docs/prog.tex | 14 ++++----- docs/ref.tex | 79 ++++++++++++++++++++++++++++++++++------------- docs/sockets.tex | 2 +- docs/sysutils.tex | 2 +- docs/user.tex | 12 ++++++- 15 files changed, 150 insertions(+), 57 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 9a02d5428e..4fb19206e2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -22,7 +22,7 @@ #INSTALLDEBUG=1 # Which docs are made when 'html' is specified -HTML = user units ref prog +HTML = user units ref prog # Can be 'report','book' or 'html' PREAMBLETYPE = report @@ -36,7 +36,7 @@ ifndef DOCINSTALLDIR DOCINSTALLDIR:=$(PREFIXINSTALLDIR)/doc/fpc-$(shell ppc386 -iV) endif -FPDOC=fpdoc +FPDOC=/home/michael/projects/fpdoc/fpdoc # # Program definitions @@ -124,7 +124,8 @@ endif ##################################################################### .PHONY: clean dvi help html ps psdist htmldist pdfdist txtdist \ - htm txt pdf refex alldist messages onechap gtk + htm txt pdf refex alldist messages onechap gtk \ + user ref prog units .SUFFIXES: .dvi .tex .ps .txt .pdf @@ -186,6 +187,7 @@ clean: -$(MAKE) -C heapex clean -$(MAKE) -C ipcex clean -$(MAKE) -C linuxex clean + -$(MAKE) -C mmouseex clean -$(MAKE) -C mouseex clean -$(MAKE) -C objectex clean -$(MAKE) -C optex clean @@ -198,6 +200,7 @@ clean: -$(MAKE) -C gpmex clean -$(MAKE) -C typinfex clean -$(MAKE) -C kbdex clean + -$(MAKE) -C videoex clean # Reference -$(MAKE) -C refex clean # Programmers manual @@ -280,7 +283,7 @@ endif ##################################################################### # Tex from XML ##################################################################### -FPCLASSESOPT=--descr=classes.xml --input='../fcl/linux/classes.pp -I../fcl/inc' +FPCLASSESOPT=--package=fcl --descr=classes.xml --input='../fcl/linux/classes.pp -I../fcl/inc' classes.tex: classes.xml $(FPDOC) --output=. $(FPCLASSESOPT) --format=latex @@ -476,7 +479,7 @@ htmlinstall: html cp -R buttons $(DOCINSTALLDIR) cp -R pics $(DOCINSTALLDIR) cp -R $(HTML) $(DOCINSTALLDIR) - find $(DOCINSTALLDIR) -name 'CVS' | xargs -n1 rm -rf + find $(DOCINSTALLDIR) -name 'CVS' -or -name '*.eps' | xargs -n1 rm -rf install: @echo Choose install from: @@ -507,27 +510,36 @@ txtdist: txt DOCPREFIX=doc BASEDIR=$(shell pwd) -htmltar: +htmltar: +ifndef SKIPINSTALL $(MAKE) htmlinstall DOCINSTALLDIR=$(DOCPREFIX) +endif cd $(DOCPREFIX) ; tar cz * > $(BASEDIR)/fpcdoc.tar.gz ; cd $(BASEDIR) rm -rf $(DOCPREFIX) htmlzip: +ifndef SKIPINSTALL $(MAKE) htmlinstall DOCINSTALLDIR=$(DOCPREFIX) +endif zip -D9rq doc-html $(DOCPREFIX)/* rm -rf $(DOCPREFIX) htmzip: +ifndef SKIPINSTALL $(MAKE) htmlinstall DOCINSTALLDIR=$(DOCPREFIX) +endif makehtm `find $(DOCPREFIX) -name '*.html'` - zip -D9rq doc-htm `find $(DOCPREFIX) -name '*.htm' -or -name '*.gif' -or -name '*.css'` + zip -D9rq doc-htm `find $(DOCPREFIX) -name '*.htm' -or -name '*.gif' -or -name '*.png' -or -name '*.css'` rm -rf $(DOCPREFIX) htmldist: htmlzip htmltar htmdist: htmzip -alldist: dvidist psdist txtdist pdfdist htmldist htmdist +alldist: dvidist psdist txtdist pdfdist + $(MAKE) htmltar + $(MAKE) htmlzip SKIPINSTALL=Y + $(MAKE) htmzip SKIPINSTALL=Y distclean: clean -rm -f *.tar.gz *.zip @@ -577,7 +589,10 @@ execute: # # $Log$ -# Revision 1.15 2002-11-10 12:22:10 carl +# Revision 1.16 2003-02-24 23:37:52 michael +# + Preparations for version 1.0.8 +# +# Revision 1.15 2002/11/10 12:22:10 carl # * update makefiles for testing # * update example which did not compile # diff --git a/docs/crt.tex b/docs/crt.tex index 625898306c..bdd9253ea7 100644 --- a/docs/crt.tex +++ b/docs/crt.tex @@ -30,12 +30,32 @@ and Peter Vreman. It works on the \linux console, and in xterm and rxvt windows under X-Windows. The functionality for both is the same, except that under \linux the use of an early implementation (versions 0.9.1 and earlier of the compiler) the crt unit automatically cleared the screen at program startup. + +There are some caveats when using the CRT unit: +\begin{itemize} +\item Programs using the CRT unit will {\em not} be usable when input/output +is being redirected on the command-line. + +\item For similar reasons they are not usable as CGI-scripts for use with a +webserver. + +\item The use of the CRT unit and the graph unit may not always be supported. + +\item On \linux or other unix OSes , executing other programs that expect +special terminal behaviour (using one of the special functions in the linux +unit) will not work. The terminal is set in RAW mode, which will destroy +most terminal emulation settings. +\end{itemize} + This chapter is divided in two sections. \begin{itemize} \item The first section lists the pre-defined constants, types and variables. \item The second section describes the functions which appear in the interface part of the CRT unit. \end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Types, Variables, Constants \section{Types, Variables, Constants} Color definitions : \begin{verbatim} diff --git a/docs/dos.tex b/docs/dos.tex index 13042eab17..9a4b3a6a4f 100644 --- a/docs/dos.tex +++ b/docs/dos.tex @@ -26,7 +26,7 @@ unit gives access to some operating system calls related to files, the file system, date and time. Except for the \palmos target, this unit is available to all supported platforms. -The unit was first written for \dos by Florian kl\"ampfl. It was ported to +The unit was first written for \dos by Florian Kl\"ampfl. It was ported to \linux by Mark May\footnote{Current e-mail address \textsf{mmay@dnaco.net}}, and enhanced by Micha\"el Van Canneyt. The \amiga version was ported by Nils Sjoholm. diff --git a/docs/fpc.sty b/docs/fpc.sty index 160996dd77..8d326a83d3 100644 --- a/docs/fpc.sty +++ b/docs/fpc.sty @@ -50,7 +50,7 @@ {\raggedleft\large% \begin{tabular}[t]{r}% \@FPCDescription \\ - \@FPCVersion \\ + Document version \@FPCVersion \\ \@date \end{tabular}\par}% \vskip 5cm% @@ -201,7 +201,7 @@ % % Some versions % -\newcommand{\fpcversion}{1.0.6} +\newcommand{\fpcversion}{1.0.8} % % PDF support % diff --git a/docs/go32.tex b/docs/go32.tex index 80c3c5b629..299bd107fd 100644 --- a/docs/go32.tex +++ b/docs/go32.tex @@ -2,7 +2,7 @@ This chapter of the documentation describe the GO32 unit for the Free Pascal compiler under \dos. It was donated by Thomas Schatzl (tom\_at\_work@geocities.com), for which my thanks. -This unit was first written for \dos by Florian Klaempfl. +This unit was first written for \dos by Florian Kl"ampfl. This chapter is divided in four sections. The first two sections are an introduction to the GO32 unit. The third section lists the pre-defined constants, types and variables. The last section describes the functions diff --git a/docs/graph.tex b/docs/graph.tex index c9471cde1a..f27573dcc7 100644 --- a/docs/graph.tex +++ b/docs/graph.tex @@ -1373,13 +1373,19 @@ Procedure SetTextStyle (Font,Direction,Magnitude : Word); \var{SetTextStyle} controls the style of text to be put on the screen. pre-defined constants for \var{Font} are: -\begin{itemize} -\item \var{DefaultFont=0;} -\item \var{TriplexFont=2;} -\item \var{SmallFont=2;} -\item \var{SansSerifFont=3;} -\item \var{GothicFont=4;} -\end{itemize} +\begin{verbatim} +DefaultFont = 0; +TriplexFont = 1; +SmallFont = 2; +SansSerifFont = 3; +GothicFont = 4; +ScriptFont = 5; +SimpleFont = 6; +TSCRFont = 7; +LCOMFont = 8; +EuroFont = 9; +BoldFont = 10; +\end{verbatim} Pre-defined constants for \var{Direction} are : \begin{itemize} diff --git a/docs/math.tex b/docs/math.tex index 01bdadfc61..747a931822 100644 --- a/docs/math.tex +++ b/docs/math.tex @@ -22,7 +22,7 @@ \FPCexampledir{mathex} This chapter describes the \file{math} unit. The \var{math} unit -was initially written by Florian Klaempfl. It provides mathematical +was initially written by Florian Kl\"ampfl. It provides mathematical functions which aren't covered by the system unit. This chapter starts out with a definition of all types and constants diff --git a/docs/mouse.tex b/docs/mouse.tex index dd2ed37ceb..6a09385a2f 100644 --- a/docs/mouse.tex +++ b/docs/mouse.tex @@ -28,6 +28,10 @@ The \var{Mouse} unit implements a platform independent mouse handling interface. It is implemented identically on all platforms supported by \fpc{} and can be enhanced with custom drivers, should this be needed. +It is intended to be used only in text-based screens, for instance in +conjunction with the keyboard and video unit. No support for graphical +screens is implemented, and there are (currently) no plans to implement +this. \section{Constants, Types and Variables} \subsection{Constants} diff --git a/docs/onechap.tex b/docs/onechap.tex index 1f0b605c73..0db7a8d604 100644 --- a/docs/onechap.tex +++ b/docs/onechap.tex @@ -53,7 +53,7 @@ %\input{math.tex} %\input{msmouse.tex} %\input{mmx.tex} -\input{mouse.tex} +%\input{mouse.tex} %\input{objects.tex} %\input{printer.tex} %\input{sockets.tex} @@ -64,4 +64,5 @@ %\input{makefile.tex} %\input{classes.tex} %\input{excepti.tex} +\input{options.tex} \end{document} diff --git a/docs/printer.tex b/docs/printer.tex index eaa119f330..2297ff2017 100644 --- a/docs/printer.tex +++ b/docs/printer.tex @@ -20,10 +20,10 @@ % \chapter{The PRINTER unit.} This chapter describes the PRINTER unit for Free Pascal. It was written for -\dos by Florian kl\"ampfl, and it was written for \linux by Micha\"el Van -Canneyt, and has been ported to \windows as well. -Its basic functionality is the same for both systems, although there are -minor differences on \linux. +\dos by Florian Kl\"ampfl, and it was written for \linux by Micha\"el Van +Canneyt, and has been ported to \windows and \ostwo as well. +Its basic functionality is the same for al supported systems, although there +are minor differences on \linux. The chapter is divided in 2 sections: \begin{itemize} diff --git a/docs/prog.tex b/docs/prog.tex index 46424e41cf..44ffef4b1a 100644 --- a/docs/prog.tex +++ b/docs/prog.tex @@ -3952,11 +3952,10 @@ should do thereafter (cf. \seet{Heaperrorresult}). \begin{FPCltable}{|c|l|}{Heap error result}{Heaperrorresult} \hline - Value returned & Memory manager action \\ - \hline - 0 & Generates a runtime error 203 \\ - 1 & \var{GetMem},\var{ReallocMem} and \var{New} returns \var{nil} \\ - 2 & Try allocating the memory block once again \\ + Value returned & Memory manager action \\ \hline + 0 & Generates a runtime error 203 \\ + 1 & \var{GetMem},\var{ReallocMem} and \var{New} returns \var{nil} \\ + 2 & Try allocating the memory block once again \\ \hline \end{FPCltable} @@ -4064,7 +4063,8 @@ be filled with zeroes before the call returns. and should fill it with the contents of the memory block pointed to by \var{P}, truncating this to the new size of needed. After that, the memory pointed to by P may be deallocated. The return value is a pointer to the -new memory block. +new memory block. Note that \var{P} may be \var{Nil}, in which case the +behaviour is equivalent to \var{GetMem}. \item[MemSize] should return the total amount of memory available for allocation. This function may return zero if the memory manager does not allow to determine this information. @@ -5963,7 +5963,7 @@ i.e. under a separate directory. The directory will be named with the name specified in the \var{package} section. \item[files] extra data files to be installed in the directory specified with the \var{datadir} key. -\item[prefix] is the directory below wchich all installs are done. +\item[prefix] is the directory below which all installs are done. This corresponds to the \var{--prefix} argument to \gnu \file{configure}. It is used for the installation of programs and units. By default, this is \file{/usr} on \linux, and \file{/pp} on all other platforms. diff --git a/docs/ref.tex b/docs/ref.tex index 4ee922f1d5..b04e0691b6 100644 --- a/docs/ref.tex +++ b/docs/ref.tex @@ -480,6 +480,15 @@ Const \end{verbatim} The order of the fields in a constant record needs to be the same as in the type declaration, otherwise a compile-time error will occur. + +\begin{remark} +It should be stressed that typed constants are initialized at program start. +This is also true for {\em local} typed constants. Local typed constants are +also initialized at program start. If their value was changed during previous +invocations of the function, they will retain their changed value, i.e. they +are not initialized each time the function is invoked. +\end{remark} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % resource strings \section{Resource strings} @@ -799,7 +808,6 @@ conversions. Note, however, that the result of an expression that contains ansistrings and short strings will always be an ansistring. \subsection{Short strings} - A string declaration declares a short string in the following cases: \begin{enumerate} @@ -808,7 +816,6 @@ will always be a short string declaration. \item If the switch is on \var{\{\$H+\}}, and there is a length specifier, the declaration is a short string declaration. \end{enumerate} - The predefined type \var{ShortString} is defined as a string of length 255: \begin{verbatim} ShortString = String[255]; @@ -829,21 +836,25 @@ Type \var{StreetString} can contain up to 255 characters. \subsection{Ansistrings} - -If the \var{\{\$H\}} switch is on, then a string definition that doesn't -contain a length specifier, will be regarded as an ansistring. - Ansistrings are strings that have no length limit. They are reference -counted. Internally, an ansistring is treated as a pointer. +counted and null terminated. Internally, an ansistring is treated as +a pointer. This is all handled transparantly, i.e. they can be manipulated +as a normal short string. Ansistrings can be defined using the predefined +\var{AnsiString} type. -If the string is empty (\var{''}), then the pointer is nil. -If the string is not empty, then the pointer points to a structure in -heap memory. +If the \var{\{\$H\}} switch is on, then a string definition using the +regular \var{String} keyword and that doesn't contain a length specifier, +will be regarded as an ansistring as well. If a length specifier is present, +a short string will be used, regardless of the \var{\{\$H\}} setting. -It is possible to typecast an ansistring to a pchar. -If the string is empty (so the pointer is nil) then the compiler -makes sure that the typecasted pchar will point to a null byte. AnsiStrings -can be unlimited in length. +If the string is empty (\var{''}), then the internal pointer representation +of the string pointer is \var{Nil}. If the string is not empty, then the +pointer points to a structure in heap memory. + +The internal representation as a pointer, and the automatic null-termination +make it possible to typecast an ansistring to a pchar. If the string is empty +(so the pointer is nil) then the compiler makes sure that the typecasted +pchar will point to a null byte. Assigning one ansistring to another doesn't involve moving the actual string. A statement @@ -855,13 +866,14 @@ The referece count of \var{S1} is increased by one, and finally \var{S1} (as a pointer) is copied to \var{S2}. This is a significant speed-up in the code. -If a reference count reaches zero, then the memory occupied by the +If the reference count reaches zero, then the memory occupied by the string is deallocated automatically, so no memory leaks arise. When an ansistring is declared, the \fpc compiler initially allocates just memory for a pointer, not more. This pointer is guaranteed to be nil, meaning that the string is initially empty. This is -true for local, global or part of a structure (arrays, records or objects). +true for local and global ansistrings or anstrings that are part of a +structure (arrays, records or objects). This does introduce an overhead. For instance, declaring \begin{verbatim} @@ -869,12 +881,15 @@ Var A : Array[1..100000] of string; \end{verbatim} Will copy 100,000 times \var{nil} into \var{A}. When \var{A} goes out of scope, then -the 100,000 strings will be dereferenced one by one. All this happens +the reference count of the 100,000 strings will be decreased by 1 for each +of these strings. All this happens invisibly for the programmer, but when considering performance issues, this is important. Memory will be allocated only when the string is assigned a value. -If the string goes out of scope, then it is automatically dereferenced. +If the string goes out of scope, then its reference count is automatically +decreased by 1. If the reference count reaches zero, the memory reserved for +the string is released. If a value is assigned to a character of a string that has a reference count greater than 1, such as in the following @@ -922,6 +937,8 @@ It is therefore NOT advisable to typecast one of the following: \item strings that have reference count larger than 0. (call uniquestring to ensure a string has reference count 1) \end{enumerate} + +% Constant strings \subsection{Constant strings} To specify a constant string, it must be enclosed in single-quotes, just @@ -943,8 +960,8 @@ between them. Strings can not be substracted, however. Whether the constant string is stored as an ansistring or a short string depends on the settings of the \var{\{\$H\}} switch. - -\subsection{PChar} +% PChar +\subsection{PChar - Null terminated strings} \fpc supports the Delphi implementation of the \var{PChar} type. \var{PChar} is defined as a pointer to a \var{Char} type, but allows additional operations. @@ -3124,7 +3141,7 @@ Because of this, the calling block must pass a parameter of {\em exactly} the same type as the declared parameter's type. If it does not, the compiler will generate an error. -Variable parameters can be untyped. In that case the variable has no type, +Variable and constant parameters can be untyped. In that case the variable has no type, and hence is incompatible with all other types. However, the address operator can be used on it, or it can be can passed to a function that has also an untyped parameter. If an untyped parameter is used in an assigment, @@ -4929,6 +4946,7 @@ Functions concerning memory issues. \procref{New}{Dynamically allocate memory for variable} \funcref{Ofs}{Return offset of variable} \funcref{Ptr}{Combine segment and offset to pointer} +\funcref{ReAllocMem}{Resize a memory block on the heap} \procref{Release}{Release memory above mark point} \funcref{Seg}{Return segment} \procref{SetMemoryManager}{Set a memory manager} @@ -7512,6 +7530,25 @@ In case \var{Param} is an invalid value, an empty string is returned. For an example, see \seef{Paramstr}. +\begin{function}{ReAllocMem} +\Declaration +function ReAllocMem(var p:pointer;Size:Longint):pointer; +\Description +\var{ReAllocMem} resizes the memory pointed to by \var{P} so it has size +\var{Size}. The value of \var{P} may change during this operation. +The contents of the memory pointed to by \var{P} (if any) will be copied to +the new location, but may be truncated if the newly allocated memory block +is smaller in size. If a larger block is allocated, only the used memory is +initialized, extra memory will not be zeroed out. + +Note that \var{P} may be nil, in that case the behaviour of \var{ReAllocMem} +is equivalent to \seep{Getmem}. +\Errors +If no memory is available then a run-time error will occur. +\SeeAlso +\seep{Getmem}, \seep{Freemem} +\end{function} + \begin{procedure}{ResetResourceTables} \Declaration Procedure ResetResourceTables; diff --git a/docs/sockets.tex b/docs/sockets.tex index bb318b58ee..e03206ab37 100644 --- a/docs/sockets.tex +++ b/docs/sockets.tex @@ -21,7 +21,7 @@ \chapter{The SOCKETS unit.} This chapter describes the SOCKETS unit for Free Pascal. it was written for \linux by Micha\"el Van Canneyt, and ported to \windows -by Florian Klaempfl. +by Florian Kl\"ampfl. The chapter is divided in 2 sections: \begin{itemize} \item The first section lists types, constants and variables from the diff --git a/docs/sysutils.tex b/docs/sysutils.tex index bf9b8c2910..9cfdf42336 100644 --- a/docs/sysutils.tex +++ b/docs/sysutils.tex @@ -22,7 +22,7 @@ \FPCexampledir{sysutex} This chapter describes the \file{sysutils} unit. The \file{sysutils} unit -was largely written by Gertjan Schouten, and completed by Michael Van Canneyt. +was largely written by Gertjan Schouten, and completed by Micha\"el Van Canneyt. It aims to be compatible to the Delphi \file{sysutils} unit, but in contrast with the latter, it is designed to work on multiple platforms. It is implemented on all supported platforms. diff --git a/docs/user.tex b/docs/user.tex index 47c7be4d85..15b210155e 100644 --- a/docs/user.tex +++ b/docs/user.tex @@ -246,8 +246,13 @@ your path variable to contain the \verb|C:\PP\BIN| directory. Usually this is done in the \file{AUTOEXEC.BAT} file. It should look something like this : \begin{verbatim} - SET PATH=%PATH%;C:\PP\BIN + SET PATH=%PATH%;C:\PP\GO32V2\BIN \end{verbatim} +for \dos or +\begin{verbatim} + SET PATH=%PATH%;C:\PP\WIN32\BIN +\end{verbatim} +for \windows (Again, assuming that you installed in the default location). @@ -3583,4 +3588,9 @@ document pst end \end{verbatim} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Options summary tables +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\input{options.tex} + \end{document}