[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