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

[Francisco Reyes]

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.

* In cases were some code needs a particular mode other than the 
default mode we can include which mode is needed.

* If an example is Lazarus specific indicate so.
Looking at http://wiki.freepascal.org/Dialog_Examples I tried to copy/paste 
the simple ShowMessage example in a program and it failed. I guess the code 
may need Lazarus. Just looking at that page I have no idea what else I am 
missing or if that is Lazarus only code. Given that someone could land on 
that page, like I did, from a search it would help to indicate if that is 
Lazarus only code.

* Lastly, I think the people in the list are extremely helpful, but 
sometimes forget that what may be obvious to them (ie that a class needs to 
be included) may not be obvious to the reader. So, it would be most helpfull 
to include the "uses" section with an example. Obviously a good reply with a 
few details missing is better than no reply at all, but figure that it would 
save a little bit of back and forth if people remembered this detail.

If given any pointers of how to work on the docs and if some of my points 
are though to be something we want to do, I could start working on this 
myself.