[fpc-pascal] Documentation and posts suggestions [LONG]

Tomas Hajny XHajT03 at mbox.vol.cz
Sun Mar 15 19:08:13 CET 2009


On 15 Mar 09, at 17:50, Michael Van Canneyt wrote:
> On Sun, 15 Mar 2009, Francisco Reyes wrote:
> 
> > Whether coming from Delphi or a totally new to pascal user there are a couple
> > of changes we could made to the documentation to make it friendlier and to
> > posts we make on the list.
> > 
> > I was thinking that including the unit and, if needed, the compiler mode for
> > functions in the documentation may be very helpfull.
> > 
> > My example.
> > Have been following the list for a while. Have a few projects that I kept
> > thinking to do in FPC and have asked questions in the past about specific
> > functionality.
> > 
> > I finally sat down to start one project. Given an example I was given some
> > months back I set myself to try and get this to run:
> > 
> > var
> >  SL: TStringList;
> > begin
> >  SL := TStringList.Create;
> >  try
> >    SL.Delimiter := ',';
> >    SL.DelimitedText := 'This,Is,Some,Delimited,Text';
> >    ShowMessage(SL[0] + ' ' + SL[2]);
> >  finally
> >    SL.free;
> >  end;
> > end.
> > 
> > I had no idea where TStringList was defined.
> > I have the PDF docs so was looking at the rtl pdf. From reading it I could not
> > figure out what unit I needd to include. Looking at the online reference I saw
> > on the top right "Reference fo unit classes" so I just included classes.
> > 
> > Then I got errors because of the try. I knew this was object pascal so I set
> > to find which modes supported object pascal.
> > 
> > Lastly I got an error because of ShowMessage. After searching the web I see
> > that is in the dialogs unit. Even after including the dialogs unit it still
> > fails. In my simple program even a writeln will do the trick so I am skipping
> > this altogether.
> > 
> > Thoughts I gathered from this exercise:
> > * It would be helpfull if we included the uint for each function in the PDF
> > documentation. May be a little redundant, but I think often people will do a
> > find and will be looking at a partiduclar function in the PDF.
> 
> The unit name is always displayed on the top of the page.

I'm not sure if Francisco meant the Reference Guide or possibly some 
examples appearing in the other documents; if it's the latter, a more 
concrete example would be probably useful.


> > * In cases were some code needs a particular mode other than the default mode
> > we can include which mode is needed.
> 
> There is no need for this: Classes and exception handling always need mode objfpc 
> or Delphi. Regular functions do not need a mode at all. 
> 
> This is a simple rule, which can easily be remembered, no ?

Well, out of curiousity, I tried searching for the word "exceptions" 
in the Programmer's Guide and Reference Guide and look at it with 
eyes of a newcomer as suggested by Francisco. I don't think that the 
places I found (including the dedicated chapter for exceptions in the 
Reference Guide) make this rule very obvious, so there may be some 
room for improvement, IMHO. Indeed, this rule is clear from the 
description of the different compiler modes and various methods 
allowing to change the mode, but the newcomer may not even know / 
understand that he should be interested in changing the compiler mode 
(i.e. visit that part of the document). If nothing else, I'd 
certainly expect to find this information in the Reference Guide in 
chapters describing the appropriate language elements.

Tomas




More information about the fpc-pascal mailing list