Evince’s annotations: “final” report

Google Summer of Code is officially over and it’s good to look back and see what happened during the summer (even if the work is not over yet!!). I will go ahead and do the list-based post which helps me keep things clear.

These were nice features that were implemented or fixed and that are already on the latest evince release (yey o/):

These are patches which are currently under review:
And there is a branch in which I am finishing developing highlight annotations. After several iterations, we decided to make it work with highlight first, so that adding strike out, squiggly, and underline is trivial afterwards. Here’s how it is working:

You can see that there is a big delay between dragging the cursor and updating the view with the highlight. It is precisely this problem that I am trying to fix at the moment, thus “final”, in quotes, as the title of this post.
Among fixing/reporting bugs and coding, I’ve met great people along the way and got to know an incredible community. The whole experience was great and I hope it lasts more than this summer 🙂

GUADEC 2014: the aftermath

It’s been more than a week since I am back from GUADEC in Strasbourg, and I must say it was an amazing experience! I went there in the middle of a chaotic time: I had just finished my PhD defense, was helping organize a huge logic conference and, because of this conference, had many friends around and even one at my place. This did not leave me much time to think, which was in fact good. Because if I stop to think about it, I was going to this place I did not know, alone, to meet people I met only over the internet. It sounds like something my parents would strongly oppose, if it was 1999. But it was not, and so I went.

I must say that, coming from a very technical conference, the talks at GUADEC were refreshing. There I was, a complete newbie, able to follow a lot of interesting stuff. But what made me most happy was in fact the people. You know when you are among a group of very cool people and everyone is so nice to you that you just think “I have to be part of this!”? This is how I felt. I got there and I did not know one soul, still people were very friendly and integrating. There was always company for lunch and dinner, and there were always programs for the evening. And in the meantime, I could even program 🙂

Evince’s hackfest on the days before GUADEC was very cool. Not only did I meet my mentor and all the other evincers, but also had progress on the annotation handling. I have a branch now on which annotation works, and we are currently working on optimizing it and organizing the code. Since I found out KaL is the only maintainer, I am trying to make my patches as easy to understand as possible to try and facilitate his work. It is almost certain that these will not be ready to be pushed to master by the end of gsoc, but honestly, I don’t even see this as gsoc anymore. I will continue working on it until it is ready, then I will go trolling for other bugs 😛

It’s funny how things happen sometimes… I enrolled on gsoc because of a career mishap on the beginning of this year. I wanted to prove something, for myself, at least. I listed some projects, some more academic, and gnome, just because I thought it would be so cool to contribute to something I have been using freely for years. My head was already full of science stuff, so I decided to go for gnome. Although academia-oriented people would say it is a waste of time, I do not regret one second. It was a very fulfilling experience, that went way beyond the point I wanted to prove, whatever that was. Maybe it took me some time from research, but I feel like I was doing something that mattered. I felt useful. It feels good 🙂
I wouldn’t like to let that go.

I hope to see you all in Sweden next year!

GUADEC 2014

Three weeks of conferences and no weekends. Next stop, GUADEC 2014 🙂
For the past weeks I have been (still am!) busy with VSL, the big logic event going on in Vienna this summer, and with my PhD. For this reason my google summer of code project was a bit delayed 🙁
I am looking forward to going back working on it, specially because there was some progress before chaos took over and I really want to finish what I have started. I basically used patches from gpoo and Anuj (the other gsoc student working on evince) and implemented text markup annotations (highlight, underline, squiggly and strike out) to evince. Although they implemented free text and line annotations, these depend on some changes to poppler. For text markup, poppler seems to be ready to go, and I guess these are nice annotation that people use more anyway.
The days before GUADEC will be evince 24/7 to finish these annotations!
Looking forward 🙂

Evince annotations: progress report n.2

So, it’s been one month and a few days since I started to work for evince, and it has been great 🙂
I’ve been managing to fix lots of things and some of my commits are even pushed to the master branch already, so next gnome release will contain a few lines which I authored! It’s good to feel useful 😀

The people have also been very nice, helpful and patient, specially jaliste, my mentor. Also, I finally get what’s the deal with git, and why there are so many adepts… once you learn it properly, it is indeed great!

Since the last report, I feel I have found more bugs than fixed… Let’s see how the lists progressed:

What is done:

  • The color issue that I have mentioned was actually filed as a bug, along with an opacity issue. I fixed them both here: https://bugzilla.gnome.org/show_bug.cgi?id=725571
  • The sidebar is refreshed once an annotation is deleted and its entry is removed from there. This was reported in this bug: https://bugzilla.gnome.org/show_bug.cgi?id=649044
  • ev-annotation-window uses “notify::rgba”, set_rgba and GdkRGBA instead of colors (Colors are deprecated according to the doc). I filed the bug and sent the patch: https://bugzilla.gnome.org/show_bug.cgi?id=732095
  • “Gtk-Message: GtkDialog mapped without a transient parent. This is discouraged.” is no longer thrown when the annotation property dialog is opened. Also filed and proposed patch: https://bugzilla.gnome.org/show_bug.cgi?id=732114
  • Clicking on the annotation icon open and closes the annotation window.
  • Annotations can be deleted (by gpoo).
  • The annotation window has one color, like a post-it.
  • The annotation window opens focused.
  • The popup menu opened upon right-clicking the annotation icon contains only annotation options (i.e., “Annotation properties” and “Delete”).
  • If the annotation window is focused, the changes to the annotation are acknowledged.
What is still missing (unfortunately all but one* issues from the last list still need work, and this list keeps growing and growing!):
  • “New annotations cannot be selected under a specific circumstance: Remove every annotation in a page, add a new one. The annotation is added, but the cursor does not change. Like if ev_view didn’t know there is one. This does not happen if there is at least one annotation left.” (reported by gpoo in https://bugzilla.gnome.org/show_bug.cgi?id=649044, verified that it is still a bug)
  • The sidebar is not refreshed after renaming of annotations’ labels.
  • When the annotation sidebar is reloaded, the open page tab (if there is one open) closes again.
  • When an annotation window appears as a result of scrolling through the document, it should not get the focus.
  • The icon needs to be “movable”.
  • Alt-tab behaves in a weird way if there is an annotation window open.
  • There should be an indication as to which comment icon a note belongs to when it is opened.
* The clicking and moving issue mentioned before was not an effect of my changes. Turns out it happens also in the master branch and even in older gnome releases. And it seems it’s only on my machine, so I need to check the configuration and ask gtk+ people.

Evince annotations: progress report

What is done:

  • Clicking on the annotation icon open and closes the annotation window.
  • Annotations can be deleted (by gpoo).
  • The annotation window has one color, like a post-it.
  • The annotation window opens focused.
  • The popup menu opened upon right-clicking the annotation icon contains only annotation options (i.e., “Annotation properties” and “Delete”).
  • If the annotation window is focused, the changes to the annotation are acknowledged.
  • The annotation window color is changed immediately once the user selects another color in the properties window and clicks on “Apply”.
What is still missing:
  • Clicking and moving the pointer on the annotation window does not select the text but moves the window (used to work before 🙁 ).
  • When an annotation window appears as a result of scrolling through the document, it should not get the focus.
  • The icon needs to be “movable”.
  • Alt-tab behaves in a weird way if there is an annotation window open.
  • There should be an indication as to which comment icon a note belongs to when it is opened. 
And of course… implementation of other annotations!
Here are screenshots of before and after:

Git + Gnome + Github

Now that you know more or less how things in git work, it’s time to set up your repositories to contribute with gnome. First thing you want to do is to get the latest source code, but jhbuild does that for you (see https://wiki.gnome.org/GnomeLove/JhbuildIntroduction). Acutally, for me, jhbuild was getting the latest stable branch (i.e. gnome-3.12 at the moment) and not master, which is the most recent development branch. In order to force jhbuild to get the master branch for evince (which is the project I am working on) I had to add this line to my jhbuildrc:

branches[‘evince’] = ‘master’

So jhbuild downloaded the source to the ‘checkoutroot‘ set in jhbuildrc. You can go there and type ‘git status‘ to see that it is a git repository. After building, I get this:

# On branch master
# Untracked files:
#   (use “git add …” to include in what will be committed)
#
# test-driver
nothing added to commit but untracked files present (use “git add” to track)

Don’t worry about this untracked file. It’s always there (at least for me!).

If you are very brave, you can start making changes right there and then, but it is probably better to create a branch on which you can test and develop stuff without messing up the stable code. To see the existing branches, just type

git branch‘ or ‘git branch -v‘.

The -v option will inform you what was the latest commit on each branch. I think it’s useful. You will probably see only one branch, called ‘master’ marked with a *. The * is there to show you that this is the branch you’re at. Go ahead and create another branch with

git branch dev‘.

You can replace ‘dev’ with a better name. In my case it is called annotations, since this is evince’s feature I will work on. Check the branches again. See the new one? You can change to this branch using:

git checkout dev‘.

So far so good. Let’s say you change something there, and it’s ready to be committed:

git commit -a‘.

The -a option will include all the changes to all the previously existing files. Make sure that the code still compiles and runs with the new commit! Check the log:

git log‘.

See the commit there? So everything is good. Now what? Well, I doubt you will have permission to push this directly to gnome’s git. Someone needs to revise the changes you made and, at least for the first few changes, you will receive a lot of feedback. But how can they revise your changes if your commit is local? If you are fixing a bug, you can create a patch from your commit and attach it there. For creating a patch from one commit, you need to run:

git format-patch -1 sha‘.

Where “sha” is a big string with numbers and letters that appears right after the word ‘commit’ when you see the log. Now, if you are a gsoc student like me, you wouldn’t like to flood your mentor with patches every time you make a change. My solution was to create a github account and push my commits there. So every time my mentor wants to check what’s new, he can take a look there. (Here goes a big thank you to jaliste, my mentor, and gpoo, my sub-mentor, for helping me organize this!!)

Github has instructions on how to set up a repository (https://help.github.com/articles/create-a-repo). You can follow this until step 1. Don’t create the readme file, you already have files. Instead, go straight to step 3. What you need to do is add the github rep as a remote repository, in parallel with gnome’s git. If you go to the directory where your project is and type

git remote -v

you will see that you have one remote entry, called origin, that points to gnome’s git. Now create another entry:

git remote add github https://github.com/username/yourprojectname.git

If you list your remotes again you will see origin and github. Now let’s push the stuff to github! First, go to the master branch (‘git checkout master‘). You will push whatever is there (i.e. the official gnome commits) to your github:
git push github master‘.
If you go to github’s website, you will see all of gnome’s commits listed on the master branch of your project. I am keeping my local master branch as a bridge between gnome’s master and github’s master. They are always in sync. To do that, I pull the changes from gnome and push them to github:
git pull origin master
git push github master
Make sure you are on your local master branch when you do this, and that you did not accidentally commit anything there. You’re almost set. Next step is to send your dev branch commits to github. Again, change to dev (‘git checkout dev‘), and push:
git push github development
Note that github’s branch name is not necessarily the same as yours. Also, if ‘development’ does not exist on github, this command creates it for you! Practical, right? You can go there on github’s website to check if it’s all ok!
Remember you can create as many branches as you want, depending on the tasks you are working on. Just make sure you are on the correct branch for changing and committing the code. After a lot of fighting with git and github and gnome, I found that this is a nice way to keep things. I hope it is also easy for others to track and review my changes 🙂

Learning git (for svn users)

Since I had to start programming for gnome, I had to start learning how to use git. I had heard of git before, about all its wonders… but I was ok with svn, I knew how to work with it and all the other projects I was working on were using svn. Of course these projects did not have hundreds or thousands of collaborators 😉

It was a rough patch in the beginning, and I still struggle with conflicts and rebasing and such from time to time, but it’s getting better. I decided to write this for svn users that suddenly had to change to git, since the shift, at least for me, was not so straightforward as some people claim.

This need to be *really* clear:

git commits are *not* svn commits.

git checkouts are *not* svn checkouts.

Now let me show a picture of how I see the cycle of information on svn and on git.

While commits in svn will send your changes to the server (and keep them safe there), git commits are just “checkpoints” which help you keep changes related to some task together. I had a lot of troubles with this in the beginning, probably because I also use svn as a backup system. If I am working on something on one machine, and need to change to another, I would commit my work to svn and then update the code on the other side. You might imagine that they were not the cleanest commits… In git this would not work. My commit will only stay local, unless I push it to the server. Of course you can push this to the server, but then when someone wants a patch from your changes you will need to reorganize the commits by rebasing and squashing and editing until you get a clean one. Trust me, you don’t want to keep rebasing all the time… specially if these commits are not the latest ones. The lesson I learned from this was: git is *not* a backup system. A commit should be a clean, self-contained, change in the code for a specific purpose. It goes without saying that the change must compile and run!

Now about the checkout. The equivalent of an svn checkout in git is clone. This command will get the source from the server and create a copy on your machine. Git’s checkout is a completely different thing. It is related to branches. While svn branches are created on the server from where you can check them out, git branches are local or on the server. And these are not necessarily in 1:1 correspondence. You can have 5 local branches and the server can have 3, and you can push commits of any of your local branches to any of the server’s branches (although it is safer if you keep a 1:1 correspondence for pushes). Git checkout will only change the local branch you are working on (quite fast actually, so you can do this all the time). Currently I am keeping three branches, one “master” which is always in sync with Gnome’s, one “multiscreen” with some commits I had regarding multiscreen support, and one “annotations” with the commits related to annotations.

I hope this is more or less helpful to understand some of git’s semantic.

PDF, annotations and evince

So, my GSoC project is regarding PDF files. More specifically, I’ll be working on evince and improving its annotation system (yes! evince has annotations! It is kind of hidden and I also didn’t know about it, but we’ll improve that now 😉

I started reading about the PDF file format last week, and I was impressed how much you can do with it. When I think of PDFs, text files immediately come to mind. Of course you can have some forms to fill in (which is quite practical) and pictures, but it is used mostly for text. So what was my surprise when the first chapters of the PDF book I am reading (Developing with PDF by Leonard Rosenthol) were all about paths… In principle, I can draw *anything* in a pdf. Pretty cool, no?
But I am deviating.

I will improve annotations, so I need to know how annotations work. These are embedded in the pdf file itself, and there are 17 possible types. Whenever you are implementing a viewer for pdfs, you need to be able to read these elements and show them on the screen. In the case of evince, poppler is responsible for reading the pdf info, and poppler elements are then translated into evince elements, which are displayed properly.

Currently, evince supports 2 annotations (text and file attachment) as annotations themselves and 2 (link and widget) not exactly as annotations internally. From the supported annotations, the text one presents some problems. The text annotation is like a comment, like a post-it note on the document, and it is not associated with any part of the text (that’s the popup annotation).
I am trusting that poppler has the necessary support for all annotations, otherwise I’ll have to tweak some code there too.

My main goal will be to fix this text annotation and extend the support for other types, such as highlighting, underlining and popup.