Validating Mallard XML and mallard-rng

If you are writing Mallard docs, it is a good idea to validate your XML. Yelp will sometimes render invalid markup (such as sections without id’s and title tags) without alerting you to the invalidity. First you will need the right tool. That is the yelp-tools package.

If you are running Fedora, you can install this using yum:

$ sudo yum install yelp-tools

Now that you have the tools for the job, cd into the directory containing all your .page files (usually a directory called C).

In order to validate a particular page:

$ yelp-check validate <filename>.page

To validate all the .page files you can type:

$ yelp-check validate *.page

If everything is fine, you will simply get the command prompt back with no output, otherwise there will be some error messages you will need to sift through and correct.

The catch is that you must be connected to the internet for this to work, and projectmallard.org must be up. Usually this is not a problem, however, being able to run this locally is not only faster, but allows you to not worry about connectivity or the site being available.

In order for this tool to function locally, you first must have yelp-tools and yelp-xsl-devel installed from your package manager. Then follow these steps:

$ cd

$ git clone git://gitorious.org/projectmallard/mallard-site-tool.git

$ cd ~/mallard-site tool

$ ./autogen.sh —prefix=/usr —sysconfdir=/etc

$ sudo make install

$ cd

$ git clone git://gitorious.org/projectmallard/projectmallard.git

$ cd ~/projectmallard

$ mallard-site-tool cache

$ cd ~/projectmallard/download/mallard-rng

$ ./autogen.sh —prefix=/usr —sysconfdir=/etc

$ sudo make install

Now you are all set up to validate all your pages, anytime, anywhere :-)

For those interested: yelp-check validate uses the RNG schemas, and references them by their canonical URI on projectmallard.org. The mallard-rng package provides local copies of those schemas, along with an XML catalog file that instructs libxml2 to use the local copy when the remote URI is requested.

Thanks to Shaun McCance for this info!

One less mutagen in my life

In order to be able to visualise DNA, one genotyping technique employs Phosphorus-32. This technique is called the Southern Blot. Phosphorus-32 is radioactive. Working with P-32 is a bit awkward, as one not only has to work in a fume hood designed for working with biohazardous material, but also behind a shield. Additionally, laboratories using P-32 must take care in disposing of all P-32 properly.

There are products available which claim to be as effective as P-32 in producing results. I had some experience with one such alternative a few years ago. Many weeks of attempting to troubleshoot the process yielded no useful results at all. Eventually, I gave up when I heard that others had similar difficulty with P-32 alternatives, so I had decided to stick to the radioactive method.

Another genotyping method in very common use in molecular biology is the Polymerase Chain Reaction. This method amplifies the DNA, and then the product is ran through an agarose gel containing Ethidium Bromide using electrophoresis. The EtBr allows the amplified DNA strands to be visualised under UV light.

EtBr is mutagenic, carcinogenic and tetratogenic. In a first year biology lab, only the teaching assistants were allowed to handle it, and they dealt with it in a fume hood. The students were not allowed to even be near the fume hood when the EtBr bottle was being opened!

Recently I was asked by a co-worker to test out a new alternative to EtBr, which is advertised as being safer. It also promised to give better results than EtBr. I thought to myself “Here we go again. It’s not going to work, you know, right?” Looking at the beautiful pictures included in the product pamphlet I wondered what wizadry was used to create these images.

I decided to divide the product of a PCR between two agarose gels. One agarose gel made with 5ul/100mL of EtBr, the other with 5ul (20000X)/100mL of the safe stuff. After placing 8ul of sample in each well, I ran the gel. Placing it on the UV light box, and switching on the light, I beheld the results:

So from now on, there will be one less mutagen in the lab. \o/

Warning: The safe stuff can cause skin irritation and eye irritation.

Cost analysis:
- Ethydium Bromide: negligible really
- Safe Stuff: ~ $200 for 1mL, so enough for 200 100mL gels. (Shelf life of one year at room temperature, 2 years at 4C).
- Not having to expose oneself to EtBr daily: priceless

Documentation Hackfest - Brno, Czech Republic

After a 17 hour commute (plane:plane:bus:bus) I finally arrived in Brno to join the GNOME Documentation Team on Saturday February 18. I have taken part in a couple of other docs hackfests last year, mainly working on gnome-user-docs as well as application help. This year I have become interested in helping to create tutorials for new developers. Some instructional tutorials had already been written and are included in developer.gnome.org. These were the result of work completed during the Developer Documentation Hackfest in Berlin last year.

I first started testing and adding some content to the existing Vala tutorials, partially to become familiar with the current state of this module, and partially to become familiar with the content that is being presented thus far, fixing a few bugs along the way.

I met Susanna Huhtanen who is working on JavaScript code examples for new developers. Susanna and I first discussed the importance of bite-size code snippets that can be easily run to demonstrate platform concepts. Our discussion led us to identify two different levels of “beginner developers”.

We often talk about new developers, or beginner developers as those being new to GNOME, or beginning development for GNOME. These ‘new’ developers may have years of experience working on other platforms. They may also be university students who have been programming for a little while without much “real” experience. These two types of ‘beginner’ developers have different needs.

There is a need for a tutorial or set of tutorials aimed at college and university students excited about starting open-source development. What we first came up with was a plan to have a series of basic step-by-step tutorials that demonstrate how to make a complete GNOME application from start to finish. Using the concept of the existing GNOME Hello application, and using the Anjuta IDE, we can have a set of tutorials that demonstrate:

1. Gtk+ programming
2. Signals and Callbacks
3. Menus
4. About dialogs
4. Linking the help files to the application
5. Setting up your application for translations

In the end, we would end up with a Complete Beginner’s Guide to GNOME Programming. Now we need to define “complete beginner” (for completeness). The tutorials will have to assume the student has object oriented programming experience, but not necessarily GUI programming experience. So, signals and callbacks would be explained in-depth, but not for loops, classes and objects.

Once this initial tutorial is covered, the next step would be furthering the platform-demo tutorials, which aim to introduce GNOME technologies such as Gstreamer, Cairo, Clutter, Telepathy etc.

That is the plan. An outline of this has been started in gnome-devel-docs/platform-demos. Additionally, Phil Bull has started some preliminary work on reorganising the platform-overview.

Susanna Huhtanen and I at the RedHat offices in Brno.

This hackfest allowed us to brainstorm some good ideas and create a direction. I also had the opportunity to chat with many of the hackers attending the simultaneous GTK+ Hackfest about the use of our development tools for these tutorials. There is the problem that Glade and Anjuta are always slightly behind the bleeding edge and that they often don’t support the way that very large applications are written. This presents the problem of using such tools in “complete beginner” tutorials and not being able to demonstrate the “real” way of doing things. Therefore, there is a need for a “bridging”, in the sense that the tools can be used to demonstrate the necessary concepts, but then a break away from these tools must occur in the tutorials in order to create developers that can program using bleeding-edge technology. I would like to thank Cosimo Cecchi, Emmanuele Bassi, Ryan Lortie and Matthias Clasen for attending the development docs presentations and for their input and advice, and also Shaun McCance and Phil Bull for helping to further this goal.

GCI Update

This was my first year mentoring the Google Code In. Seeing as the GNOME Games are undergoing modernisation, I thought I would try my hand at mentoring the writing of Mallard topics for Gnome Games. The following tasks were accomplished:

Gnome Sudoku:
- The intro, basics, keyboard shortcuts, toolbar, notes and rules topics completed by Chris Beiser (USA).
(Bug #618342)

Gnome Sudoku Strategy:
- The strategy page completed by Radoslav Asparuhov (Bulgaria).

- An outline including the index page, 8 topic stub pages, and 3 completed topics was brainstormed. This task helped layout a solid foundation for the mahjongg documentation. Completed by Chris Beiser (USA).
(Bug #618344)

- the intro, play, fast-moves, change-board-size and change-theme topics were completed, as well as the addition of screenshots to the documentation was was accomplished by Lanka Rathnayaka (Sri Lanka).
(Bug #664949)

- The keyboard-shortcuts, change-promotion-type, change-board orientation and save-resume topic pages were completed by Brian Grohe (USA)
(Bug #649146)

- The 2player, ai-game, quickmoves, shortcuts and visual results topic pages were completed by Brian Grohe (USA).
(Bug #664950).

All tasks completed have been committed to the master branch of the Gnome Games.

I really enjoyed the opportunity to mentor gci this year. Thank-you to Google for offering High School students the opportunity to make contributions to open-source projects. And thank-you to all the students who participated!

RIP Bug #79348

I just wanted to say thank-you to the many GNOME developers and documenters who contributed their time and skills to helping us close an almost 10 year-old bug today. As I stated in the comment on the bug, I think work on developer.gnome.org should remain a work in progress. In this spirit, I hope more ideas and thoughts can be put towards this effort as we approach the Doc Sprint at the Developer Conference 2012 in Brno next month.

Montréal Summit - GNOME Strategy

I am at the GNOME summit in Montréal. This morning Robert Ancell ran a discussion about GNOME strategy. The three main areas covered were:

1. What are we building?
2. Who is it for?
3. How do we get there?

The answers, of course, are multi-fold. We are building a desktop shell, applications, an active community, an ethos, a brand, a developer story, and an OS. There are side-effects to all this building such as libraries, middleware, stable API’s, and the emergence of a viable market and ecosystem.

Form factors (the form in which a consumer gets GNOME) include the traditional desktop, workstations, laptops, tablets, in-car systems, set tops and mobile devices.

GNOME is for enthusiasts, ourselves, family, friends, businesses, and in general, people. We discussed that it is still the case that GNOME tends to be in the domain of the technically savvy user. Our friends and family who use GNOME call us up for help. Occasionally it may take a couple of hours on the phone to sort out problems. Sometimes, they are ready to pack up their computer and hop on a bus or drive out to see us, even with easy to fix issues. Such trivial fixes are not obvious to a general user. It would be great if friends and family could depend on us less for technical support, and call us to talk about other things.

The effort put into localisation/internationisation and accessibility is put forth because it is important to us as a community that our product(s) can be used by all people. Meg Ford brought up an interesting point about the use of computer systems in businesses. If there is an employee who requires accessibilty features, the business is legally required to provide them and would want those features to be available in the system that is already used by the rest of the office. Therefore, it is important that our product can be accessible to as many people as possible.

At the moment, we seem to be reaching the enthusiasts, the people willing to take the time to download and install GNOME. A large percentage of the population will not do this.

So how DO we get there? Modules and tarballs…by delivering our modules and tarballs to distributions to pass on to the consumers.

Robert Ancell, re modules and tarballs: “There it is, that’s GNOME.”
Ryan Lortie: “We heart distributions.”

Can we change the strategy from being an application to being an OS, and then from OS to OEM (indirectly)? GNOME OS would be three things:

1. A set of minimum requirements we call GNOME. It includes the full package of vertical integration.
2. A nightly build.
3. Mobile reference build (for tablets).

I was new to being involved in this type of discussion within GNOME, which involved terminilogy that was new to me. These slides from a talk given by Rob McQueen at the Software Freedom Day in Boston (thanks Marina for pointing me to this) helped explain many of the concepts related to mobile devices running free software. I include it here for anyone else who may benefit.

What I learned and took away from this lively discussion is that we are building a set of complete yet modifiable products, not just a “box of bits” that others turn into products. It seems that the only way to get there is through hardware pre-installs. In order to accomplish this we need money and contributors. Contributions in the form of development, documentation, art, translation, community building and marketing will help GNOME reach more people with its products, ethos and brand.

Desktop Summit 2011

It has been a week since we returned from Berlin. First, I want to thank the GNOME foundation for giving me the opportunity to attend this years desktop-summit. Without their sponsorship my attendance would not have been possible!

Second, I want to reflect on the gains I made through this experience. A big thank-you to my room mate Marina Zhurakhinskaya! I first met Marina at the Boston summit. In Berlin I had the opportunity to talk to her about some of the doubts and concerns I was having about my project and being an asset to the community in general. Her input was extremely valuable. Meeting other students and hearing their stories helped me feel like I was really not alone as a new contributor of code to the GNOME project. I really enjoyed meeting and getting to know Anita, Luciana, Raluca, Richard, Srishti and Tamara who are all fairly new contributors. You guys are all awesome! I especially appreciated the student lightening talks. I still can’t believe I managed to put together a slide presentation in the last minute for this event. Thanks to all for the nudge and support. All the presenters did an awesome job.

Some of the conference talks that stand out in my mind include Zeeshan Ali’s Vala talk (thanks for the code examples Zeeshan), Shaun McCance’s Ducks talk, and Travis Reiter’s Folks Talk.

I found the BoFs especially beneficial. I attended the Folks BoF and touched base with Alex, Phil, Travis and Will. My GSOC project involves Folks (which sadly lacks beginner tutorials), so having face-time with the developers was very helpful. A big thank-you to Phil for the great feedback on my contact-selector. Phil also spent an hour with me on the Thursday. He walked through all of his comments, discussed the new branches he created, and pointed out things I hadn’t even thought of such as marking strings for translations, choosing a licence for my code and overall code design. I was pleasantly surprised by all the time he put into helping me.

I also attended a bugsquads BoF. During the past year I have been filing bugs, committing patches and closing a bug here and there. I hope to become more involved in bug triaging in the future, so it was good to make some connections in this area. I wish I had had more time to speak to André Klapper in person about joining the bugsquad.

I also wanted to say thanks to Lucian (co-ordinator of the Romanian translation team) for taking some time to walk me through translation contributions and how they work. I have been interested in contributing translations for a while. After the step-by-step explanation, the process is not as daunting as I had imagined. I have already completed an eo.po file and managed to test it and submit it. I have also translated the strings in my GSOC contact-selector, but for some reason these do not seem to be working yet.

Also, thank-you to Shaun McCance for taking the time to answer my questions about xslt, at a party nonetheless! I really appreciated it.

In some ways I feel like I am all over the place, having started my contributions to GNOME with documentation, trying my hand at development through GSOC, now also learning about bug triaging and translations, and needing to learn xslt for a personal project. In many ways I feel that I am not concentrating enough on any one area, however there are so many ways I feel I can contribute, that it is difficult to stay focused on just one thing.

As for my GSOC project, although GSOC is officially done, I am not done. Therefore, I plan on finishing what I started, slowly but surely :-)

And, last but definitely not least, I want to thank Ryan Lortie for introducing me to the GNOME world, inspiring me to get involved at my comfort level, and gently nudging me to learn more and do more. Thank-you for believing in me even when I have doubts. And thank-you for introducing me to such a great community of Ducks and Folks.

Open Help Conference and Hackfest

Last Thursday I returned home from the Open Help Conference and Hackfest in Clifton, Cincinatti.

The conference gave us the chance to meet with members of the Mozilla documentation team as well as participate in insightful talks and discussions by Anne Gentle, Dave Robbins, Dru Lavigne, Janet Swisher, Jennifer Zickerman, Lana Brindley and Shaun McCance. Many of us kept the world up to date on the Open Help events using #openhelp on Twitter.

The post conference hackfest gave the Gnome Documentation Team another chance to work together and make the gnome-help awesome. Last term I interned with the team as part of the GWOP. This time around I was able to work as part of the team and meet two of the current interns, Julita Inca and Kelly Sinnott. We worked together on testing the existing documentation for correctness, updating pages and adding topics to the gnome-help pages.

In addition to adding content and reviewing and making changes to the current documentation I learned how to apply patches, and deal with bugs on bugzilla. Although Phil Bull triaged the bugs this time around, I picked up some hints, and will triage gnome-help bugs in the future. I successfully applied outstanding patches with help from Shaun McCance, and was able to close a few bugs on bugzilla. The docs-team has a collection of patches on our mailing list. With my newly acquired patch-applying skills and powers I hope to be able to help minimise this patch collection :-)

The Clifton neighbourhood has some lovely coffee houses. The following chessboard was hanging on the wall in one of them. It is one variation of a three-player chess board. Apparently, 3-player chess can also be played using a hexagonal board, where each cell is a hexagon instead of a square. I thought this was pretty cool. Anyone up for a game?

I would like to thank the GNOME foundation for making it possible for us to attend the hackfest. A big thank-you also to Jim Campbell for picking us up from CVG airport, to Shaun and Silke McCance for organising and running the conference and arranging our accommodations, and to Sandra and Napoleon for giving us a great place to rest our weary heads.

Contact Wizard in the Document Viewer

I did a quick mock-up of two possible ways I see the contact wizard fitting into Evince. First, there’s the obvious choice of accessing it through the Files menu. I showed the original design to the docs team over coffee at the Open Help Hackfest, and got some input. Initially, I had named the menu item Share…. Shaun and Phil suggested Meeting… and Phil suggested Start Meeting…. I must agree that Share doesn’t convey the nature of what the program should do, which is to allow for remote control of client instances of Evince via Telepathy tubes. The user should be able to invite participants to a ‘meeting’. If a participant accepts the invitation, an instance of Evince will open up on the remote machine, controlled by the machine that sent the invite.

People who use Evince when doing a live presentation (like I have done), may be more likely to stumble across the new feature when setting up to View their file in Fullscreen or Presentation mode. Jim suggested placing the Share Meeting… menu item in the View menu for the purpose of discoverability.

The contact wizard itself has access to the user’s Empathy contact list. The user will select particants to invite. The mock-up contains one possible design for the wizard. This version allows the user to select contacts by clicking on their name in a list, or by typing the name in the entry box. The entry box is useful for very long contact lists. I don’t think this is the best design. After drawing this design I have come up with other possible designs. Stay tuned…

When designing the wizard, another thing to consider is what to do if the user wants to invite someone who is only an e-mail contact and not in the Empathy contact list. Of course, it is simple enough to quickly add someone to this list, but perhaps may not always be possible. Food for thought.

Getting and Building Evince from Source on Fedora15

Recently I built Evince from git source. I ran into a couple of issues while doing so, and googling around revealed that I wasn’t the only one who was wishing for some step-by-step instructions. This is what worked for me, although there may be slight variations.

In a terminal, type:

git clone git://git.gnome.org/evince
cd evince
yum install gnome-common glib2-devel intltool
yum install gtk-doc gnome-doc-utils gtk3-devel
yum install libxml2-devel gnome-keyring-devel
yum install poppler-glib-devel gcc-c++
./autogen.sh —disable-nautilus —disable-static —prefix=`pwd`/install
make install

To run:

Of course if you are working on a different distro, you will need to download the appropriate packages for your distro. So the list of the requirements (and location of source tarballs for anyone interested) is:

- gnome-common
- glib-gettext >=2.2.0 (ftp:ftp.gtk.org/pub/gtk/v2.2/glib-2.2.0.tar.gz)
- intltool >=0.25 (http://ftp.gnome.org/pub/GNOME/sources/intltool)
- gtk-doc >=1.13 (http://ftp.gnome.org/pub/GNOME/sources/gtk-doc)
- gnome-doc-utils >=0.4.2 (http://ftp.gnome.org/pub/GNOME/sources/gnome-doc-utils)
- gkt+=3.0 >=3.0.2
- libxml-2.0 >=2.5.0
- gnome-keyring-1 >=2.22.0
- poppler-glib library version 0.16.0 or newer
- gcc-c++

I’m back: GSOC 2011

Last term I participated in GWOP. It was a very rewarding experience, which allowed me to integrate into the GNOME community, learn tonnes about the new GNOME3 by documenting it using Mallard, learn how to use tools such as irc, git, and work as part of the documentation team. You guys rock!

Since the end of my internship, I have written new mallard docs for eog, become a foundation member and decided to try my hand at development through the opportunity offered by Google Summer of Code.

My project is to integrate Telepathy into Evince. The idea is to be able to share files from Evince to a subset of the users Empathy contacts.

I didn’t feel comfortable just jumping in to my project for a few reasons. First, I have never worked on such a big project. Second, I have never done any Gtk+ programming. Third, my knowledge of Telepathy and D-bus is on the overview level. Before starting work on my project, I feel it is best to get a grasp of these technologies.

Currently I am working my way Foundations of GTK+ Development. The book is a bit out of date, but still quite useful, especially along side Devhelp. The API documentation is of course an indispensable resource, and I feel that learning how to use it is a bit of a skill :-). I am also working with gtk+-3.0, and the book is based on gtk+-2.0.

My mentor is Danielle Madeley (who recently blogged about The Architecture of Open Source Applications which includes a chapter about Telepathy). Congratulations on the publication Danielle!

My SOC start has been slow but steady. I feel that it will be beneficial to creating a solid foundation for this project.

The Eye of Gnome is getting Mallard Documentation!

I have been wanting to write Mallard docs for EOG for awhile, so
when I came across bug #633522, I decided now is as good time as any.

I committed an outline and some topic stubs yesterday.

You can:
$ git clone git://git.gnome.org/eog
$ cd eog/help/C; yelp $PWD/

to have a look at this outline. If you feel there are topics
that need to be covered that you do not see in the outline, feel free to
comment on the bug, and I will do my best to include them.

Yelp it!

It is great to be participating in the documentation hackfest at the very end of my internship with the Gnome Documentation Team. Mallard is fun. Try it! You just might like it. Yelp 3 really show off its powers.

Natalia and I have been working with the docs team over the past few months, contributing to the contents of the the Gnome Help for Gnome 3.0. Over that last 4 days, we have been here in Toronto, working with the handful of dedicated and talented folks on putting it all together. It is really awesome how the the ideas just fly when you are all working together in one room. In case you need some proof, here is a screenshot from blip.

It is great to be sitting here in person, getting immediate feedback on ideas and how to get things working in Yelp, Mallard and Gnome Shell.

Shaun, Phil, Jim, Germán, Johannes, Natalia and I will be working on the help together till Tuesday. Additionally, I heard that there are a couple of people participating remotely. If you would like to write some Mallard with us, you are welcome to join in. The team can be found on #docs. We still have some stub pages that need filling in.

Thank-you to Shaun and Ryan for organising the hackfest. It’s been a quack so far!

This is my attempt at trying to make a very quick video tour of the Gnome Shell Desktop. It is a one minute taste of Gnome 3. I started out with a list of things I wanted to show, but then there was just too much happening in too short a time, and the video was too long. The idea is to include a video introduction with the user docs. This screen capture video was made using the Gnome Shell’s built-in screen capture feature.

Most recently I have been concentrating on the Gnome Shell pages of the user help. Topics about managing windows, workspaces and applications have been covered. Additionally, I have written some pages about managing user accounts and groups.

This week also involved two jbuilds of Gnome Shell on two different machines, both successful. Thank-you to #gnome-shell for helping me trouble shoot issues during the builds.

I am also very excited about the possibility of the Use Help Hackfest taking place in Toronto! It will be a great opportunity to be able to spend the better part of 5 days with the members of the Documentation Team, finishing up the user help for Gnome 3.0 under one roof. This is a link to the wiki about the tentative hackfest.