Wrapping up – Integrating Mallard Help into GTG

flattr this!

If you already installed the 0.2.9.r1206 release, than you can meet our newest “baby”: brand new GTG user docs in Mallard!

Delivery of this baby was pretty painless (no need for an epidural ;):

– Bertrand and Izidor received the Mallard files that I prepared

– after some brainstorming they decided to follow the standard procedure (check this resource on Stackoverflow):

  • Mallard pages are placed in the doc/userdoc/C folder (once we have the user docs localized, each locale will go into its own subfolder (es_ES, sk_SK, it_IT…)
  • setup.py file has been modified to install those pages in the $PREFIX/share/help/$LANG/gtg folder
  • Contents item has been added to the Help menu and the browser code has been modified to open help:gtg when pressing F1
  • Help button has been added to the Edit > Synchronization Services dialog to open directly the respective help page

Of course, as Murphy’s Law demands, as soon as the release was ready and public, I noticed a couple things that needed revision and correction. Documentation is a work-in-progress – it will need periodic revisions and improvements!

The next step is including the GTG user docs into the GNOME Library. However, since it is not part of the official modulesets on git.gnome.org, we’ll have to file a bug at Bugzilla for the component library.gnome.org. That way, the userdocs that are now included into the GTG tarball will be processed by library-web autotools build system and become available online as the rest of GNOME user apps.

Mallard Docs on the Web

flattr this!


Countdown for the version 0.1 of the GTG User Docs in Mallard format is on… :)

I am collecting the last suggestions and corrections from the developers and in about one week or so, on behalf of all of us from the GTG team, I hope to present to the world the final result of the GTG User Documentation in Mallard effort. Izidor has been triaging the bugs for the 0.3 version and hopefully the docs will be integrated into the app by then.

During the last week I have mostly been experimenting with the yelp-tools. Handy one for checking the validity of the Mallard pages is this:

yelp-check validate *.page

For example, if you forget to close a tag, Yelp will not even open the .page file! This leaves you a bit frustrated since you do not know where to start looking, especially if the page is long. Solution is to run the ‘yelp-check validate’ command and you will receive the info about the error:

yelp-check validate gtg-translate.page
 gtg-translate.page:19: parser error : Opening and ending tag mismatch: app line 19

The above example was a clear indication that I left out the closing </app> tag on line 19 of the gtg-translate.page file. Problem solved! :)

Next yelp tool to use was the:

yelp-build html *.page

When run in the folder with all your .page files it will output the HTML files from Mallard. Here you can browse the HTML version of the GTG User Documentation. Once the docs are ready, we will publish them on the new GTG blog (yes, we are working on that too 😉 and they will also be included into the GNOME Library.

All the above commands assume that you have installed yelp-tools on your system. Check these posts by Tifanny and Shaun for more details.

Linux Screencasting, Video Editing and Venus Transit

flattr this!

Writing the user docs for GTG was coming along quite nicely but I wanted to add a little kick so instead of all screen shots, I decided to make some screen casts. This was a completely new task for me as I never did any screen recording or video editing on Linux. But hey, this GNOME experience is about doing the things the new way, right? 😉

As far as recording what happens on the screen, the choice seemed clear – recordMyDesktop. This a is simple, no frills app, works consistently and produces a decent result. I did not, however, test any advanced options so those remain to see…

OGV video file that recordMyDesktop outputs works perfectly in Mallard with a simple syntax:

<media type="video" src="videos/get-started.ogv"/>

The intention was to keep the video file size as small as possible so I did not record the audio. Unfortunately you can not do much more with recordMyDesktop apart from, well, recording your desktop. The problem with the straight recording is that it does not offer enough visual clues as to what are you doing especially if you do not provide audio. However, I was unable to find the program equivalent to Camtasia for Linux – something that is easy to use but offers certain features for making instructional videos. PiTiVi seemed too simple and has only one video and one audio layer* and I found both Kdenlive and LiVES not very intuitive and way too complex for what I had to achieve. There are more video editing apps available (Cinelerra, Blender…) but again, it would be like using a cannon to kill a mosquito.

So at first it seemed that I had no other choice but to jump back to Windows, edit the screen cast to add some color and callouts with text, and reimport the video into Mallard page. This approach involved the additional requirement of converting the OGV file. I found that both OggConvert and Transmaggedon did a very good job. You can see the result by clicking on the image below (it seems that I am unable to insert the video player here so you’ll have to bear with the link towards YouTube):

Video lost a lot of quality during the YouTube conversion but the version that will be in Mallard is decent enough. The ideal situation would be having a video editor with at least basic instructional features that can handle the OGV files natively so there is no need for conversion that is almost always lossy.

After accomplishing this step, I remembered that the user documentation files will eventually be localized so the embedded text is not a solution. I also remembered that Tiffany mentioned that videos in Mallard can be subtitled easily and that’s the work I have ahead. Stay tuned… :)

PS: Venus revealed itself for the last time this century right on my birthday! Here is how NASA saw it:

* Thanks bronte for commenting that this is indeed possible… :)

GTG User Documentation Project – Call for FAQs

flattr this!


image ©2008-2012 ~VanHeist

Hi everybody!

My name is Radina and I just started my GOPW internship during which I will be writing the User Documentation for Getting Things GNOME!

Yeah, I know what are you thinking: It was about time! Izidor had already put some basic stuff on our wiki some time ago, but baring some natural disaster, by the end of this summer GTG will have a proper topic-based user manual written in Mallard language – the standard for GNOME apps.

In case anybody is interested to see the overall structure and the draft of the first guide and topic pages – just check the project on Gitorious repository.

The idea is to include the comprehensive Frequently Asked Questions topic into the User Documentation, and for that I was thinking of asking all the Getting Things GNOME! users and collaborators for help.

image © electricjonny

You may try to remember all the questions you asked yourself about the GTG usage on one point or the other, since you first installed it; and all the “How the hell do I…?” and “Eureka!!!” moments… :)

image © uizu

If you are willing to lend us a hand with compiling the list of useful questions, you can post your suggestions here or, if you have an account for GNOME Live!, just edit the GTG FAQ page that Bertrand started recently.

Before the end of my internship I will revise all the questions and include them into the final version of the GTG User Documentation prior to its release.

Thanks in advance for all the help!

image © ipyuri