mario::blog

Monodoc internals and a little annoying fly

2008-04-05T18:40:00.012+02:00

If anyone out there still does not know, Monodoc is the mono documentation system. It is the core that allows the mono documentation web and the mono documentation browser work. Well, it is also behind a handful of other nice tools like monodoc2html. Once the presentation are done let's move on...

Monodoc works with several different sources of documentation. It renders API documentation, but also C# compiler errors, the Ecma specification and, in the past, even the monkeyguide (which was obsolete and removed). The nice thing is that it keeps a uniform documentation tree no matter where the documentation comes from (API, man pages, error references, ...)

This tree is generated from a skeleton and feed with different documentation sources. This skeleton is defined in a file called monodoc.xml which is something like this:


<node label="Mono Documentation" name="root:">
    <node label="Class Library" name="classlib"/>
    <node label="Mono Libraries" name="classlib-mono"/>
... (more contents here)
    <node label="Various" name="various">
        <node label="DiaCanvas Libraries" name="classlib-diacanvas"/>
        <node label="NUnit Libraries" name="classlib-nunit"/>
        <node label="Tao" name="tao"/>
    </node>

</node>

Then, when monodoc starts, it looks for all the *.sources files it founds and feeds its contents to the nodes:

In the image above, the "Class Library" node is feed with the contents of netdocs.source, the "C# Compiler errors reference" with cs-errors.source and the "NUnit Libraries" with nothing, because that documentation is not currently installed on my system.

And that's it. That's how monodoc manages the documentation tree.

Well, there is this little annoying fly I'm sure everyone using monodoc has met at least once. What happens if you click on "NUnit Libraries" node which has no documentation:

Unhandled URL

Functionality to view the resource root:/classlib-nunit is not available on your system or has not yet been implemented.

That is the problem of having a static skeleton for documentation which is filled with the *.source files found. I know, the problem is not big, one possible solution is to purge those entries which does not have documentation (no *.source file was found), and that is exactly what is done as of r99894.

Documenting is a Good-ThingTM

2005-10-10T12:54:00.000+02:00

I've been cleaning and writing some documentation on the Wiki regarding Monodoc. The problem is that, lately, my english is more broken that it should be (probably due to my year in Germany and that I haven't study english since..since..a lot).

Well, the thing is that someone please check the pages I modified. Here is the list:

http://www.mono-project.com/Monodoc
http://www.mono-project.com/Monodoc_Editing
http://www.mono-project.com/Generating_Documentation
http://www.mono-project.com/Monodocer
http://www.mono-project.com/Monodoc_Contributing

Of course, I will also appreciate all types of comments: style, things not clearly explained, things that lack. The Monodocer page should be reviewed a lot and, also, I have to add an Assembler page (the link is there but I didn't write the page yet).

I recommend you to grab the SVN version of monodoc and mono-tools as some minor bugs are corrected. They were little annoying things that appear when using uncompiled sources from monodoc (the ones being created by monodocer). The bug that hanged Gecko-sharp when visiting big pages is also corrected.

There is yet one more bug that makes Monodoc browser to hang, which is really difficult to track. It doesn't reproduce in the same docs (at least, the docs of the bug review doesn't hang monodoc for me, but the same error appears in other places) and is due to a cast from an String somewhere in Gtk. The point is that, the same code is used once and again (setting the title label, near the back/forward arrows) and nothings happens until you enter some specific docs. I will need to sit down and spend some time on this.

Just one last question. Why don't try monodocer/monodoc for documenting your libraries?

Welcome to the Real World

2005-09-28T13:24:00.000+02:00

The other night I went out with some friends and decided to wear a new-awesome-incredible T-Shirt I have. Luckily there was some paparazzi around who could register everything:

Thanks miguel!!!

In the monodoc camp there are little steps going on. First, and thanks to Rafael Ferreira, we have printing support now. The printing is performed by the GtkHTML widget even when using gecko, since gecko-sharp doesn't support printing by now; that means the printed documentation won't be so sexy as the rendered one (just substitute sexy with CSS-enabled). But, hey, it will be updated when gecko gets improved.

Other recent addition is that you don't have to create the indexes using a command-line option anymore (the search and the normal index) because monodoc handles it with a nice and simple GUI addition. However, the indexes created from inside the browser will be only accesible to that user, since there are created in the config folder. To try this, download a fresh SVN version of monodoc and mono-tools, remove from the monodoc directory the file monodoc.index and the directory search_index and start monodoc.

There is also an interesting conversation in the monodoc mailing list about whether it would be positive or negative for contributors the integration in the monodoc browser of the msdn-browser from Ben Maurer. What do you think?

The other day I was at the Beagle hack-fest in IRC. I had a lot of fun, special thanks goes to Lukas for organizing everything. At the end, I contributed with the first version (so far) of the search sidebar. At least it is more or less what Garret drawed.

Aside from Mono, I finished my degree and now, in the Real World, I'm looking for a job. I would love getting some response from these guys; meanwhile, I will be sending my CV everywhere. Do you need a Telecommunications Engineer?

Just an advice to finish the post. The other day I went to see Mayumana. If they go near to you, don't miss them. Is one of the most awesome things I've seen in the last months.

SOC ends

2005-09-01T03:10:00.000+02:00

The SOC is over. The dialog wasn't finally added to Monodoc. However, there is the list of contributions at the home page and a new "Restore" button next to "save" and "close" buttons, that lets you delete your contribution and restore the old text.

Also, the Monodoc search patch is waiting approval at the mailing list. Just for the curious, here is an screenshot:

At the end I wasn't able to finish all the desired features like Comments or downloading new documentation. However, I plan to continue contributing, so they will come, sooner or later. I don't know yet how many free time I will have, but I'm sure I will find some to work with mono.

After reading lluis post I decided to play a little bit with Inkscape and, then, I realized why I spend more time programming than designing:

well, at least, the guys at simios.org seem happy with the logo I made for them.

Contributor-experienceTM revisited

2005-08-26T13:31:00.000+02:00

Hey, the people still read the monodoc mailing list. hehehe, just kidding. I've improved the contributor-experience^TM with a nice dialog to deal with your contributions:

From that dialog you are able to open and remove your contributions and upload the selected ones.

The problem is that contributions made before the patch will not be listed here nor in the root page (however, a message appears at the root page telling you have xx old contribs pending). Also, old contributions will be automatically uploaded with your next upload.

The uploaded contributions are controlled by a serial number (I've realized that was already done after implementing one myself) that acts like an ACK. Every time you upload a contribution, you get a new serial number so new contributions are marked with it and, both, the server and you, know which ones are new contributions and which ones are contributions already uploaded. This way, contributions not being uploaded (not selected) get its serial number updated after a successful upload.

Now, it's time to concentrate in the search thing that I've postponed for a month or so.

Back to work

2005-08-22T04:23:00.000+02:00

At the moment I'm dealing with two aspects of monodoc: searching and contributions.

The searching is almost done (it searches and highlights the results), but while I was polishing things, I introduced a bug I've not been able to repair yet. I'm getting a NullPointerException from a line of code that is almost the same as before. It is one of those bugs you end up thinking if your computer is pulling your leg.

For improving the contributions-experience^TM I've added to the home page a text that says if you have made any contributions (which are not uploaded yet) or explains a little bit how to make a contribution. The point is that I wanted a list with links to all the contributions, but that was more difficult to obtain than I thought. The information being saved with every change was not enough to get those links, so I've added a nice URL to every change being saved in chageset.xml.

The problem is that the Urls in monodoc are a little weird. In the case of ecma documentation, if you click on the TreeView, you get something like ecma:10#Array/ while through the links you get T:System.Array. Depending on the place you are working you use one or another (although they point to the same doc), adding some confusion to the internals of the program. To get my desired list I've written a new method that figures out the nice url T:System.Array when it is not available. The results here:

The thing is that, in my opinion, we should revise the internals of monodoc at some point, because the design is sometimes limited or confusing. I don't mean a rewrite of the program, but a reorganization, localizing the points where we are doing almost the same thing (two different urls pointing the same doc for example) in slightly different ways and looking for a design that facilitates more the manipulation of documents.
Tomorrow, the contributions-experience^TM patch will land the mailing lists. Stand by. Now is time to sleep.

The yo-yo

2005-07-29T11:31:00.000+02:00

After finishing the last patch for Gecko support in monodoc I realized that some links were broken. Looking a little bit more on detail I found the problem. The nice URLs like T:System.Activator are being lower-cased by gecko to t:System.Activator, so the ecma-provider gets lost. I tried in firefox, epiphany, etc and found the same behavior. I remembered then a post in monologue about URLs and following a link to the RFC-spec I found the following:

Scheme names consist of a sequence of characters. The 
lower case letters "a"--"z", digits, and the characters plus 
("+"), period ("."), and hyphen ("-") are allowed. For 
resiliency, programs interpreting URLs should treat upper case 
letters as equivalent to lower case in scheme names (e.g., 
allow "HTTP" as well as "http").

So I suppose gecko is just acting "polite" and lower-casing everything before the ':' for us. Thank you very much.

On the other hand, I've almost finished the search for Monodoc. I'm just playing with the process to try to improve the results and I realized It would be great if the people tell me different searches they would make and the results they would expect.

I couldn't resist to post this thingy Paula sent me. I'm sooooooo impressed how imperfect we are.

Hey, just open the GIMP and check it for yourself

Return to Karlsruhe

2005-07-26T16:52:00.000+02:00

I've visited Belgium this weekend with Paula. We were in Brussels, Brugges and Gehnt. The three of them are great places for tourism and Belgium is a nice country with three gastronomic attractions: Chocolate, Mussels and Beer. We have tried to enjoy all of them.

Chocolate fountain

/me enjoying a great meal

Brugges at night

Search for the Holy Documentation

2005-07-16T19:12:00.000+02:00

The last week was not very productive, I was just infected with a virus called lazyness. However I can post the first world premiere screenshot of Monodoc browser searching feature:

The GUI is not feature complete, but the idea it's clear. You write a search term, hit return and get your results grouped by that search term (woooooooooow). The thing would be as good as the performance of the searching. Just as Jon Trowbridge said at the Guadec, if you cannot give the user what he is looking for in the first 5-8 results, that is a bug. Nothing more to add.
At the moment, the search only works for the ECMA-C# spec, but I'm already working in the ECMA API, which, of course, is the most interesting.
I'm visiting Brussel with Paula next weekend so I will have to work hard next week to finish the Search'o'matic feature. It would be also great to write down all the ideas I'm thinking for Monodoc and send that to the list. Just as Lelalau uses to say: "mal sehen".

First commit to Monodoc

2005-07-10T19:05:00.000+02:00

Today I commited my first patch addressing the first goal, use gecko to render html in monodoc. The patch is far from being complete but it is the first step in the right direction. Some things don't work but it renders the documentation nicely. For completing the task I will wait for the work of Michael which is doing an ASP.NET editor with Mozilla. He has already a way to call Javascript from C# (which can solve some of my problems).

Meanwhile I will be adding search support for Monodoc with Lucene. Also, I want to write down a TODO list as I found several things that can be improved.

This Friday the "Tour de France" came to Karlsruhe, two hours waiting for 10 seconds of emotion. I could barely see nothing but, at least, I have some good photos. Also, I was at two parties, the first one, N&N Abschied party, was really good, the second, in Hadiko, not so good.

Just one more thing. This week we had two remarkable things, the first one really good (Software patents were rejected) and the second one really sad (London Bombings).

Why does it rain so much in Summer?

2005-07-05T13:37:00.000+02:00

The first week of the Summer of Code is gone.

Every day I get a clearer vision of the whole Monodoc system. I've opened three battlefronts:

Integrate Gecko in Monodoc: I've already a working system but it lacks some functionality. I'm a little bored of fighting with the GtkMozEmbed and looking in Epiphany and Galeon source codes. Waiting a response from the tutor.
Use of CSS: I've started looking into this. Much of the works comes from rewriting the XSLT files.
Integrating search engine (Lucene): This one is the funniest at the time writing. I can already make easy searches and I'm looking how to integrate it nicely with the code.

From the not-so-Summer-of-Code department, I've been interviewed today for the tech section of a spanish newspaper: El País. I hope my grandma like it.

Eating a Kebab and drinking a Czech Budweiser in front of the Karlsruhe Schloss, with all the starts and some friends, is pretty near to the idea of happiness.

Summer of Code starts

2005-06-29T13:53:00.000+02:00

Dear Mario Sopena Novales,

We are delighted to tell you that your project has been selected to receive a grant in Google's Summer of Code program.

That's all.