AKAImBatman's Journal: A Day Without Mono is like a Day Without a Bullet in my Head

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+!

Wait... what?

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.

So.....

[iplayfast]

How do you really feel?

Re:

[AKAImBatman]

Much better, actually. I just needed to vent somewhere.

Not that I'm excusing the poor state of Mono documentation, mind you. ;-)

Re:

[jambarama]

I've long thought there are a lot of "emporers with no clothes" running around the OSS scene. Mono was one of them in my, albeit short, experience. I was on debian, so it installed fine, but the documentation--once working--isn't stellar, and I found some major (for me) compatibility issues with .NET apps developed in visual studio and mono.

It isn't just Mono, there are a lot of fugly things I have to do to get somethings to work that my kool-aid drinking microsoftie friends laugh about. I'm glad it wasn

Preach it from the mountain, brother!

[Yaztromo]

I had to do a project in C# last fall, with two Windows users. Being a Mac guy, I threw Mono onto my system.

Now fortunately this project had absolutely no UI exposure (it was a CLI tool), but I ran into many of the same issues you did: Microsoft's online documentation was terrible (why is it when I wanted to look up what methods a class has available that it would instead send me to a page that just talked about what the class does, and then proceeds to show me very basic usage examples in several different .NET languages I don't care about, with no obvious linkage to somewhere where I can just see what damn members the class exports?). The language itself is ugly as sin (why is it some people gush over how wonderful .NET is?). I was so happy when that project was finished -- I hope to never see C# or any piece of .NET or Mono ever again. The language and API are badly designed (like pretty much everything else Microsoft puts their touch on), and the documentation is just horrid.

So I feel for you. I've been there. I can't imagine what anybody sees in it. .NET makes Java look good.

Just thinking about the experience makes me want to take a long shower with some powerful disinfectant...

Yaz.

Re:

[morgan_greywolf]

Agreed. At one point I thought that Mono would be cool and fun to learn. My experience was almost the same as yours. Some things have me itching to try Mono again -- one of them being IronPython, since Python happens to be my favorite language for quick-and-dirty programming, and another being that my last attempt at Mono was more than 2 years ago, and I was certain it had gotten better by now...until I read this journal article.

Thanks, everyone, for saving me the frustration!

Re:

[Yaztromo]

Some things have me itching to try Mono again -- one of them being IronPython, since Python happens to be my favorite language for quick-and-dirty programming

Well, if you're running on Mac OS X, you may want to take a look at PyObjC [sourceforge.net], a Python-Objective-C binding subsystem.

Mono can't be saved, and it's not because of any lack of talent on the OSS developers part, but because the C# language itself just sucks. The API isn't much better (Microsoft hasn't been able to create a decent API since, well, ever)

I agree completely

[Thuktun]

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.

I fully concur with your assessment. That has pissed me off for years.

On a slightly-related note, I'd like to point to their documentation on the MFC CString::Find method [microsoft.com], which has had incorrect information for the better part of a decade. (I didn't know until just now that this still had this problem, I just went and checked on a whim.) This simple method provides a way to search the encapsulated string for a substring or a character, either from the beginning of the string or from a specified index.

H