I have to admit, I think I owe Miguel de Icaza an apology. When we last butt heads, I believe I accused him of choosing .NET over the existing Java projects out of a case of "Not Invented Here" syndrome. And after the Silverlight announcement (which he wants to name fad-da daw'), I was even starting to buy into the idea that he might be a blind Microsoft follower.
But after spending a few days with Mono, I have changed my mind. It is quite obvious to anyone using the platform that the Mono team is not in bed with Microsoft. In fact, it would seem that the Mono team is explicitly trying to warn you away from .NET technology. Otherwise, why would they make it SO GODDAMN HARD TO DEVELOP FOR?
Excuse my outburst, but I'm just about at my wits end. Allow me to explain.
The whole thing started when I was working on a side project that required ASP.NET. As much as I might want to get around this requirement, it was non-negotiable. So, I looked into Mono and found that they had a special development server capable of running ASP.NET pages. I thought, "Great! Now I can develop on my Mac on the go!"
So I downloaded the Mono for OS X package and installed it. It compiled the requisite "Hello World" program with no issues. (Though it spat out Hello.exe for a binary. WTF?) The XSP server also ran a simple ASP.NET page without any problems. Great! Now all I needed was some documentation.
Before I get to that part, however, let me take a moment and address Microsoft documentation. I've heard plenty of programmers beam about how wonderful Microsoft documentation is, and how they absolutely love Microsoft documentation. If they had it their way, every program would have Microsoft documentation. Personally, I've always wondered what these people are smoking.
My experience has been that Microsoft documentation is poorly organized, lacking in detail, designed to run you around in circles, and packaged in a proprietary format that makes it non-portable and generally quite useless. The only positives to Microsoft documentation is that their docs are very pretty to look at and there is a LOT of it. (Which is what happens when you try to document every possible use rather than how to use the technology.)
Back to my story. Here I am thinking that I will simply download an HTML class reference and be about my business. After all, I'm an experienced programmer. Just tell me the library calls and I'll be good to go.
A quick check of the official Mono site produced the necessary HTML documentation. But only online. Nowhere could I find a download that I could take with me. The more I looked, the more I realized that the Mono folks want you to use a GTK# MonoDoc Browser. Oooook....
MonoDoc browser is (unsurprisingly) not shipped with the Mac OS X Mono package. So I went and downloaded the only package available: The sources. Of course, the MonoDoc browser requires GTK#, so I download those sources as well. It's all cross-platform code, so it should be easy to compile, right? *sigh*
When I untarred the source archives, what do I find? Something incredibly simple and reliable like ANT? Nope. The same old configure/make scripts that have been giving me nightmares for the last decade or so. No problem. I can do this. It's CLR code, so it MUST be a simple compile, right?
First thing that happens is that the configure script can't find Mono. Wait, what? How can it not find mono? It's in the path! After some checking around, I find that the build script is using pkg-config and pkg-config doesn't know about mono. Ok, so I create a mono.pc file in the /usr/lib/pkgconfig directory. Still can't find it. I move the mono.pc to /usr/local/lib/pkgconfig. Still can't find it. I set the PKG_CONFIG_PATH to the folder containing mono.pc. STILL CAN'T FIND IT!
As you can imagine, my blood pressure is getting dangerously high at this point.
I go back to the configure scripts to see if I can simply route around the check. No, it's pretty integral. But I do manage to find that the pkg-config it's pulling is an older version in /sw/bin. Mono apparently installed its own copy in /usr/bin. Ok, I can see that. So I switch the path around (making certain it's exported to the environment) so that /usr/bin will get checked first. It still finds the older copy. I struggle with it a bit more. It still finds the old copy. Finally, I rename the older pkg-config to pkg-config.old.
Eureka! It finds mono! Just to fail on GTK+!
According to the configure script I don't have GTK+ or Pango. Yet I know they're both installed because of a few other OSS apps I compiled a while back. Finally, I give up. This is a dead end that's already sapped too many hours of my time. The craptacular Linux build process bests me again.
Let's try another tack, shall we? The mono package contained a pre-compiled (thank God) tool called monodocs2html.exe. All I need to do is feed the documentation sources into the tool, and voila! Instant HTML docs! Or so I hoped.
Unfortunately, I couldn't make heads or tails of the process. The documentation on generating documentation seems nice and all, but is a bit difficult to understand without some experience with the platform. And since I can't get any documentation on how to use the platform, I'm kind of stuck with a catch-22 there.
In theory, I just point the tool at the "assembled" documentation and it works. In practice, it keeps telling me that I need index.xml. Yet there's no index.xml anywhere in the lib/monodoc/sources directory. Not even inside the Mono.zip file. Rats, foiled again!
At this point I've resigned myself to wearing the ball and chain of an ethernet cable. After all, why would anyone possibly want to take HTML documentation on the go? Not that I've been too impressed in the online docs themselves. In Java, you tend to document API methods as you go. But with Mono, they separate out the docs from the sources, ensuring that no one ever documents anything! Documentation is handled entirely by online volunteers in a Wiki-like fashion, leading to a great deal of the library being documented with "Documentation for this section has not yet been entered."
So here I am now. My laptop useless in the face of such incredible resistance to using Mono. My blood pressure at all time highs. My patience long ago exhausted. For an instant, Google gives me hope that someone else has shared their generated docs! Yet it's nothing more than an apparition of a carrot dangling in the air as if to mock me.
I really do owe Miguel an apology. His team has been making wonderful strides in ensuring that the platform is completely inaccessible to new users. Thanks, man! We always knew you were secretly anti-Microsoft.