I'm amazed how much sometimes programmers ignore the work of others, especially in the domain of their own tools. So many nice ideas, practices and even standards (in usability) are simply ignored because they were made by the other guys. This can be seen clearly in open source/free software world which prefers to ignore good stuff simply because they were made by some entity they dislike (usually the suspect here is Microsoft), even if there is absolutely no reason to do so. But this isn't something only FLOSS people do. Freeware, shareware, commercial, etc developers are guilty of this too. But i'm going to focus on the FLOSS side of things only because that's what i can't fix.
The story begins about the moment when i decided to press the almighty Ctrl+F1 key in my FreePascal IDE. You know, the IDE that looks like the old Turbo Vision-based Borland IDE for Turbo/Borland Pascal 7 and some Turbo/Borland C/C++ IDE of that period. I wanted to see the docs about some function or something. Well, i was greeted with a nice screen telling me that i need to download the docs because they decided to not include it for some reason having to do with including a 5mb package in a 60mb package would be wasteful or something like that (ok, i'm exaggerating, the help package is 11mb and the compiler package is 35mb). Apparently everyone who uses FreePascal knows the docs inside out and they never need to read them. Ok, actually they don't know them, they do read them. That's because they're included in the compiler actually, but they're in PDF format. Unfortunately the IDE cannot read PDF files so you need to read them outside of the IDE using a program like, say, Adobe Reader or some sort of half baked PDF reader that can read most of the PDF files their developers feed it but always fail when you want to read a specific PDF. Ok the PDFs that come with FreePascal can be read by all PDF readers i've tried (which include Adobe Reader, whatever comes with GNOME and nothing else). But correct me if i'm wrong, i don't find it easy to search through a bunch of PDF files for the definition of a single function, not to mention that if this function is a widely used one (like writeln), i'll need to skip a bunch of examples. So the next part is to download the HTML files from the site and feed them to the IDE (which, btw, cannot find them automatically - no, you have to inform it where the files are). This will make the IDE read all these files and after processing for a few minutes (in my quadcore computer, YMMV) to generate some sort of index (which sometimes it fails to save to disk and crash). After this process is done, we can finally use the help files from within the IDE. Pressing Ctrl+F1 will now almost do the job of showing the help you request. I say almost because usually the help system isn't sure what you want to do and displays either some random page or an index which takes ages to load and contains a few billion words to choose from.
Now you might be thinking (as a knee-jerk reaction, i'm sure) that the FreePascal situation is the fault of the project's programmers and it doesn't represent the situation in all tools. Actually i agree with both: it is the fault of the project's programmers and it doesn't represent the situation in all tools. This is because FreePascal has actually some of the best documentation system and unlike most tools out there there is actually human (as opposed to drone) readable documentation. And the fact that i can press a single key and get some sort of context-sensitive docs (even if usually aren't what i'm looking for, but at least they're trying) is good. Another project that has the half part done right is OpenWatcom, which includes documentation for almost everything. Unfortunately OpenWatcom's IDE is an abomination even for 1993 standards when the Watcom part was popular.
But the problem exists in other tools as well. Eclipse, for example, simply fails to provide any sort of similar functionality. While there are some nice touches, like the ability to display JavaDocs while editing Java files and maybe comments in C/C++ files (or the whole source if its around, which in the case of small functions is helpful), it is simply impossible in the stock installation to get something like the FreePascal system above: pressing a key and getting info for whatever is under the cursor. There is some plugin which under some situations -which i never managed to encounter- can display the docs from glibc, but i think the docs are displayed as a popup.
A better case is NetBeans which simply has a better JavaDoc browser - the default OS web browser. But that's all you can get. Try to ask for information about what class means and the IDE will hang for a while (probably it tries to figure out why someone might want to know a language construct) and then will simply beep. Beep. As if saying fuck you to the developer, fuck you for wanting documentation about something not part of the API.
I'm not going to mention vim and emacs. The former is a generic text editor which tries to become a development environment and the latter is an operating system which tries to become a text editor. From the two, i prefer emacs but only because i hate the modal nature of vim and it works via ssh. Unfortunately, like Eclipse, emacs' idea of context-sensitive documentation is launching some sort of hypertext system (info) to display glibc documentation.
Now let's take a look on some old environment we hopefully all know and used to be one of the best, if not the best, at its time: Turbo Pascal 5.5. I chose this specific version because its available for free from Embarcadero's site (which currently holds the copyright). Running the IDE greets us with a nice warm screen (as warm as can be done in DOS colors without bleeding your eyes anyway - oh sorry, Linux console has the same colors too... but i'm going to leave that part for another rant some other day).
Here is what we see after we type TURBO.
So, we start typing some code here. Nothing special, just some program that asks us our name and displays a greeting back. This is something a lot of people who are learning programming will write as one of their first steps...
Now, excuse me, but isn't this a much better looking screen than what we would get if we wrote this in Emacs?
But i'm comparing apples with oranges here. Or blues with blacks. Or whatever. So, at this point lets assume we want to learn what the hell writeln is here. So we move our cursor to the begin word and press Ctrl+F1. This is what we see...
Well, it isn't the best description, but there is a pointer to the Write procedure and an example:
Check the text at the bottom right part of the screen: you can put this example in your code. Not only the documentation explains what the function is all about, but you can test the function right there. Doing the same in FreePascal shows the documentation for the WriteLn function in its own help system:
That contains a lot of more information and while there doesn't seem to be a method to automatically put the example in the editor, the text can be copy/pasted to the editor using normal editing keys. I'm going to argue though that i don't care about the source position part and that the syntax in Turbo Pascal 5.5's help made more sense. Also i think the text would be formatted better but anyway. On the positive part, there is information on what can go wrong, portability notes and more suggestions for similar functions.
Unfortunately, the nice part stops when i'm trying to see documentation about a language feature. For example, lets see what begin is all about. In Turbo Pascal 5.5 pressing Ctrl+F1 over the begin word i get this screen:
Compound statements are a group of statements, separated by semicolons, that are surrounded by the keywords Begin and End. The last statement - before the End keyword - doesn’t need to be followed by a semicolon, although it is allowed. A compound statement is a way of grouping statements together, executing the statements sequentially. They are treated as one statement in cases where Pascal syntax expects 1 statement, such as in if...then...else statements.I'm not sure the part about the semicolon needs to be mentioned there too, but anyway. Trying to do the same (press Ctrl+F1 over the begin word) in FreePascal i get this screen:
Oops.
Obviously the help system couldn't find any topic about begin, so it displayed the closest it could find. Unfortunately this isn't what i'm looking for. Pressing Shift+F1 to view the index, it seems that there isn't a topic about the begin keyword. And there isn't a topic about any keyword.
FreePascal's context-sensitive documentation doesn't care about the language itself.
And this isn't a problem with FreePascal only as i figured out. In Eclipse i simply can't find information about the case structure in C, C++ or Java. I simply can't find documentation about C++ templates anywhere in the otherwise huge /usr/share/doc directory in my Ubuntu account. Nothing related to these languages can be found in these places.
The documentation case sucks. As i said at the beginning though, FreePascal and OpenWatcom do include documentation for the languages (a huge thumbs up for these people doing something like that). Having documentation for the language is a good thing, even if GCC simply ignores that for decades now. All i'm asking for is for this documentation to be accessible in a context sensitive way from within the IDEs of my choice, just like it used to be in popular environments 21 years ago.
Two decades ago the development experience was much better than it is today.
I've become a bit bored writing stuff right now, so i'm going to close with two things: first, Microsoft does the right thing by including documentation for everything. If you press F1 over any word, be it API or language keyword, you'll get the docs for it. I don't like the fact that this is done over the Internet, which makes it very slow and the new help browser they have sucks big time (what was wrong with the old CHM or even better, the lightning fast HLP?). But at least they have it.
Second, the rant isn't over. Getting help is one thing, but its not the only issue we have today and was solved at the past. Creating projects and making GUI applications are two other issues. I'll post about them at some point later. Especially on the GUI part is amazing how much people don't get how it should be done.







