Hi,

Maybe it's just me (please let me know if it is), but looking at the various FPC .pdf files in a folder, I am never sure which one I should open for whatever I am looking for.

We currently have:
ref.pdf
user.pdf
rtl.pdf
prog.pdf
fcl.pdf
fpdoc.pdf

Out of those 3 seems to have logical names. rtl, fcl and fpdoc. The problem I have is the 'user', 'ref' and 'prog' names. Maybe somebody can explain to me how I can remember the various information in each of these. For example, if I want to know about a Compiler Parameter, or a Language syntax, it is never clear which document I should open.

Now seeing that all (half-descent) OSes support long filenames these days, couldn't we name them better.

For example:
ref.pdf is actually about the Object Pascal Language. So why not name it Language_Reference_Guide.pdf or Language_Guide.pdf?

prog.pdf is actually about the compiler support options like parameters etc... So name this Free_Pascal_Compiler_Guide.pdf

user.pdf is actually and installation guide. So why not name it FPC_Installation_Guide.pdf

Yes I know I can rename them locally, but I also thing it makes sense to give the documents better "default" names than ref, prog, user.

Just my 2c worth!

Regards,
- Graeme -

If there is a more or less consensus about such things, I don't see why we couldn't rename them.

The names actually stem from the TP documentation, which was divided into 3 books:
Language Reference
User's manual
Programmer's manual

Michael.

In our previous episode, Graeme Geldenhuys said:

The names would then be out of sync with the forms of documentation supported on apparantly less than half-decent OSes. (like CHM)

Moreover I don't have a problem with the names themselves. One could wonder about the division of the three, but the association of "ref" with "reference guide", prog with "programmers's guide" etc isn't THAT hard.

In our previous episode, Michael Van Canneyt said:

If you do, don't forget to update fpcdocs/gentoc :-)

Still, short names for the files themselves would be better I think.

Michael Van Canneyt het geskryf:

If there is a more or less consensus about such things, I don't see why we couldn't rename them.

Glad to hear you are willing to consider this. ;-)

That's what I gather -- or vaguely remember from my TP days. But with todays IDE and built-in help, I don't even know which document the IDE is referencing when I press F1 or Ctrl+F1. So when I look at the actual document files and names as you listed above, it is not immediately clear which document I should open to look for help.

OK, in the list above "Language Reference" seems obvious, but everywhere else (as far as I remember) it is listed as FPC Reference Guide, which isn't obvious.

FPC = Free Pascal Compiler.
...so FPC Reference Guide might mean a reference about the Free Pascal Compiler and not about the Object Pascal Language or as I suggested (and which is used in Kylix.

Also, does the documentation about the language reference "Object Pascal" as the language or "Free Pascal" as the language? I hope it's Object Pascal, because using Free Pascal as the language would be just as confusing as what Borland did what they changed the language name from Object Pascal to Delphi. In forums and mailing lists, when they mention Delphi, I never know if they are talking about the IDE or the Language. The Object Pascal name was nice and clear.

Regards,
- Graeme -

In our previous episode, Graeme Geldenhuys said:

OK, in the list above "Language Reference" seems obvious, but everywhere else (as far as I remember) it is listed as FPC Reference Guide, which isn't obvious.

(in the pre-fpdoc past, the reference guide also included the system unit reference)

Also, does the documentation about the language reference "Object Pascal" as the language or "Free Pascal" as the language?

I'd say Object Pascal. Free Pascal is the implementation, Object Pascal is the language.

Not entirely since afaik also used for the TP object syntax. But still I agree that it is the best choice.

I agreed with Graeme.
FPC is very well documented, but some informations are easy to found, some other not.
A first pass to help us (i'm an fpc early developer) could be to give a clear name to the docs you provide.
Better docs nomenclature could help fpc users, developers, teams and so on. Thanks :-)
Bye
Corrado

Since you now discovered what each document describes, the problem has solved itself :-)

It's not "Object Pascal". It's Pascal, because it treats plain pascal, the old TP objects and Delphi's 'Object Pascal'.

That's why I refrain from using 'object pascal' or just 'pascal' in the title, and use FPC Reference guide. It could be changed to "FPC Language Reference guide".

Michael.

In that case I don't need to do anything :)

Michael.

Michael Van Canneyt het geskryf:

Since you now discovered what each document describes, the problem has solved itself :-)

My brain is saturated with other information. By the end of the week I would have forgotten all this already. :-) To help myself, I locally renamed the PDF documents to more descriptive names.

title, and use FPC Reference guide. It could be changed to "FPC Language Reference guide".

That will be an improvement, yes.

Regards,
- Graeme -

Graeme Geldenhuys wrote

Maybe it's just me (please let me know if it is), but looking at the various FPC .pdf files in a folder, I am never sure which one I should open for whatever I am looking for.

For the Mac OS X releases, I rename them before packing the installer. The names I use are:

Code Documenter.pdf
Compiler Switches.pdf
Free Component Library.pdf
Language Reference Guide.pdf
Programmer's Manual.pdf
Units Reference Guide.pdf
User's Manual.pdf

Jonas

Jonas Maebe het geskryf:

For the Mac OS X releases, I rename them before packing the installer. The names I use are:

Much better names. :-) I think my main problem is distinguishing between the Programmers Manual and the Users Manual. See, I am both — so I never know which PDF to view for a specific problem.

Regards,
- Graeme -

Jonas Maebe het geskryf:

Simply out of interest/completeness, here is the names I now use.

Class Chart.pdf
fpdoc - Code Documenter.pdf
Free Pascal Component Library (FCL).pdf
Language Reference Guide.pdf
Programmers Guide - Compiler Usage Manual.pdf
Run-Time Library (RTL).pdf
Users Guide - Compiler Installation Manual.pdf

Regards,
- Graeme -

Spaces and quotes are vetoed as a general rule :)

Michael.

Michael Van Canneyt het geskryf:

Spaces and quotes are vetoed as a general rule :)

Such an "old" file-system limitation does not apply in newer OS versions anymore. I must say, old habits die hard! :) I often find myself naming eBooks, TV series or music with underscores instead of spaces. But lately I started using actual spaces in such file names as well. It simply makes them look prettier in my file manager tool.

Regards,
- Graeme -

That's fine as a general rule, but at least on Mac OS X specifically it's no problem. I think more documents and applications (other than the command line unix ones) than not have a space in their name on that platform.

Jonas

In our previous episode, Jonas Maebe said:

While Windows NT4+ does fine in general, but sometimes in places with old 3rd party network clients (decnet, older novell clients) can still give problems.

Local never really has been a problem on NT (if you forget Dos app usage)

I almost exclusively use the command-line, and a lot of shell scripts, and in that case quotes and spaces are a pain.

Michael.

...

In Linux, and I guess other unixish OSes like the Mac, it's quite possible to have spaces or punctuation in file names. That doesn't mean they're a good idea. 99.something% of the time you're probably OK, especially if you stay in a GUI. Command line scripts sometimes have problems because they won't have a name quoted properly, or you want to use some file but you have to slip several \ chars in, to escape "special" chars. Or, if we're not just talking about PDFs, you start using chars that the FAT filesystem does not support, like <, and then try copying MP3s with those chars to a cheapo MP3 player and wonder why it doesn't work. Hehe.

Frank

Frank Peelo wrote

In Linux, and I guess other unixish OSes like the Mac, it's quite possible to have spaces or punctuation in file names. That doesn't mean they're a good idea.

Since they're ubiquitous already anyway on Mac OS X (partly due to its heritage of classic MacOS, where there was no command line or anything else that could have problems with spaces or other "special" characters), stuff that can't deal with such file names is usually fixed pretty quickly. And you're of course free to rename the documentation files to whatever you want after installing them, if your own usage/scripts/whatever don't play nice with them.

Jonas

My 2 cents are that the worst problem with the docs is this: Very often I do not know in which one to look for what i want to know or similarly I have to look in three of them at the same time. In my view rtl and fcl are even more important than user, ref and prog, and therefore should be included in the discussion. Unification to a super manual with another top layer of chapters would make searching and browsing through the TOC much easier.

Michael Schindler
________________________________________________________________ Neu: WEB.DE Doppel-FLAT mit Internet-Flatrate + Telefon-Flatrate für nur 19,99 Euro/mtl.!* http://produkte.web.de/go/02/

On Mon, 7 Sep 2009 12:12:42 +0200 (CEST), Michael Van Canneyt wrote about Re: [fpc-pascal] The names of the various FPC documentation:

Indeed, quotes (") and apostrophes (') are a particular pain, as most shells use them as meta-characters for wrapping arguments to programs. They need to be escaped or wrapped, so that the shell ignores them and passes them through to the underlying application program -- in this case a PDF reader.

Well, decent OSes allow distinguishing filenames from titles in GUI, don't they? ;-)

I personally prefer keeping the short names at least in SVN. For the distribution, renaming the files during installation (or creation of the installation package as already done by Jonas) may be reasonable options, IMHO. It would be probably useful to maintain a uniform set of long names (titles) - probably based on those appearing on the cover page.

Tomas