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.

The unit name is always displayed on the top of the page.

* 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 is a simple rule, which can easily be remembered, no ?

Michael.

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.

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

Michael Van Canneyt wrote

The unit name is always displayed on the top of the page.

Thanks for pointing it out. Every time I have used the rtl.pdf I have used primarily the search function and had never noticed that.

or Delphi. Regular functions do not need a mode at all. This is a simple rule, which can easily be remembered, no ?

If those are the only two cases sure, but if there are other instances that may suffer from the same it may be helpful to have the mode mentioned on the instances where it matters.

Tomas Hajny wrote

I'm not sure if Francisco meant the Reference Guide or possibly some examples appearing in the other documents;

I was looking specifically about the rtl pdf.

if it's the latter, a more concrete example would be probably useful.

Where are the examples? I recall seem them in the past, but can't find them now.

Also as I become more serious about FPC what would be the recommended order of reading the docs?

I have:
prog.pdf
ref.pdf
rtl.pdf
user.pdf

Want to go over them in the coming week. I like to read as much as I can before jumping into more serious development. Right now doing a couple of simple utilities partly because I need them for work and partly to re-learn pascal.

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

Just looked at that part in the reference and agree that it could at least mention it needs delphi or objectpascal modes.

allowing to change the mode, but the newcomer may not even know / understand that he should be interested in changing the compiler mode

Exactly. Specially newcomers may have a good chance to not know what documents and in what order they need to read them. I think it may be a bit easier for someone coming from Delphi, but someone just starting out, may not even know that exception handling is object pascal and not part of the standard pascal.

There's at least also "out" parameters, using the "result" keyword and default parameters.

Jonas

A good point, and I will add some statements to the docs in the appropriate chapters/sections !

Michael.

Only the RTL units have examples in them. FCL units do not, and the classes unit also do not have them any more. The reason is 2-fold:

- Time
- More complex concepts require more complex examples.

I don't think it is possible to give an order. Normally I would think user
ref
prog

and the rtl/fcl as you need them.

I will do so.

Like I said, I will add some sentences/paragraphs about this.

Michael.