Align parameters of a C function declaration, with lineup-parameters

Renaming a GObject class can involve a lot of manual work. Once the type is renamed, the parameters of the function declarations are no longer aligned. In the following example, GtkSourceSearch has been renamed as GtkSourceSearchContext:

_gtk_source_search_replace_all (GtkSourceSearchContext *search,
                                const gchar     *replace,
                                gint             replace_length)
        /* ... */

It is a GNOME convention to align the parameters, so the code must be fixed:

 _gtk_source_search_replace_all (GtkSourceSearchContext *search,
                                 const gchar            *replace,
                                 gint                    replace_length)
        /* ... */

As programmers, we don’t like doing such a manual work, and even less when we are renaming a big class. Unfortunately, the Indent program doesn’t have an option for that. If you use Vim, there is the Align plugin, that have the \afnc alignment mapping. But it doesn’t align the parameters on the parenthesis.

So I wrote a script! The result is in my gnome-c-utils repository (containing only the lineup-parameters script for the moment).

To detect the parameters, a few regular expressions are used. There are quite a lot of restrictions, but it should work for most GNOME software. To have a perfect script, libclang could be used, but I’ve never used it, so regular expressions was a quicker solution.

The script can be used to convert an entire file, or can be used from a text editor (stdin is read, and the output is written to stdout). I’ve documented how to add a key binding in Vim. So by pressing a single key, the parameters are correctly aligned!

This is just a small step to improve the developer experience in GNOME. But I hope this will be useful for other developers. I dream of a GNOME C IDE that handles the boilerplate (for renaming classes too), that aligns the parameters and the function prototypes in the headers, with auto-completion for signals and properties names, and so on.

Search and replace in gedit and GtkSourceView

My GSoC on GtkSourceView/gedit/… is coming along nicely. Here is a screenshot of the new search in gedit:

New gedit search
New gedit search

The visible new thing is the “298 of 703” in the search entry, that shows the position of the current search match, and the total number of occurrences. This is just the tip of the iceberg, as much of the work has been done under the hood. Ignacio (nacho), my mentor, has improved GdTaggedEntry, and I worked on the new API in GtkSourceView, and adapted gedit to use the new API.

Note: almost all my work has already been merged upstream, but not the new search entry.

Search and replace API in GtkSourceView

The new API in GtkSourceView is available. One thing is missing though: regex search.

Why you should use this API:

  • It is asynchronous, i.e. the user interface is normally not blocked when the GtkTextBuffer is scanned. And the asynchronous overhead is small;
  • The search matches are highlighted;
  • You can get the total number of occurrences and the position of a certain occurrence easily;
  • For each search, the buffer is scanned at most once. Once the search occurrences are found, navigating through them doesn’t require to re-scan the buffer, thanks to gtk_text_iter_forward_to_tag_toggle(). As a result, most operations are really fast;
  • The regex search (still to come) will normally do multi-segment matching, also called incremental matching: when a partial match is returned, we take a bigger segment. No need to waste memory space to retrieve the entire buffer contents.

Nice, isn’t it?

Developing graphical IDEs the UNIX way

Programming on a UNIX environment generally involves the use of command line tools: vim/emacs, git, grep, sed, screen/tmux, and so on. What is really nice about these tools is that they do only one thing, but do it well. Now, what about people not wanting to learn shell commands? And sometimes (sometimes), graphical interfaces are more convenient.

An IDE is an integrated development environment. What people think about this “environment” is generally a bloated program (*cough* eclipse *cough*). But what if the environment is not one big application, but several small programs? The small programs can interact a little together through D-Bus, if needed.

Let’s take a few examples.

Specialized text editors

To have a good user experience, the text editor should be smart enough to know the language used (C, C++, Python, Vala, LaTeX, etc.) and implement features specifically for the language. A few examples:

  • Code completion;
  • Switching between the call of a function to its definition;
  • Have an overview of the file (the list of functions, or the structure of a LaTeX document).

Having only one text editor for several types of tasks (C and LaTeX for instance) is not convenient. It works with vim or emacs, but at the cost of passing lots of time in the configuration files. If a graphical application have thousands of settings, we end up with something worse than eclipse. No, instead, there should be one text editor for each task. And one another general-purpose text editor that don’t include specialized features.

This is not just about settings. With a single text editor for all tasks, the UI must be generic enough for the plugins, but they will always be restrictions. On the other hand, with an independent application, the UI can be exactly what is needed: not too generic nor too restrictive.

The common features between all those specialized text editors can be shared in a library. A project is to make the gedit source code more reusable. It would have been a nice GSoC for me (see this draft proposal for more details), but instead I work on GtkSourceView, which is also nice.


Working on a git repository can be a bit difficult at the beginning. A graphical application that implements the basic features can be useful for some people. But it doesn’t need to be available in the same program as the text editor!

Creating a commit, navigating through the repository history, pull, push, changing branches, … have nothing to do in a text editor, in my opinion. There are some things that can be useful in the text editor though: if there is an integrated file browser, we can mark the modified/added/removed files. And in the margin of the text content, we can mark the modified sections.

Search and replace

The search and replace in a text editor can be limited at one file at a time. The search and replace entries can be shown in the top-right corner of the file, with a little button to show and hide the replace entry.

The search and replace in multiple files is another beast. Integrating it nicely in the text editor is a difficult task. Generally the developer choose a dialog window, because it is the best available option, but it partially hides the file contents…

Why not a small application that do only that? It would roughly select a directory, and search in all files in this directory. The text editor can have a menu item “Advanced search and replace” that would launch the small program with some parameters. The advantage of this small program is that the UI is really better, since it doesn’t have all the text editor features.

When we replace some text, sometimes we want to do small modifications afterwards. But normally, the specialized text editor features would not be needed in the small search and replace application.

The specialized text editors would already have features to edit several files at once. For example, when we change the name of a function, all the calls to the function can be renamed too, and adjusting automatically the indentation of the parameters (should be doable).


The general idea is to have small programs with a clean and simple UI, which don’t require lots of configuration, and that work well together. Ideally, they should Just Work™, like other GNOME applications.

Hi, planet GNOME! GSoC on (mainly) GtkSourceView

My blog has just been added to the planet GNOME!

I’m now a GSoC student, working mainly on GtkSourceView (my proposal).

I’m implementing a higher-level asynchronous API for the search and replace. I hope to finish this task in two weeks.
Then: regex search, adapt gedit, modernize the color schemes and ideally GtkTextTag to use CSS.

Search API, some progress

The highlighting of search matches works fine, there was a flickering issue that I fixed.

A property contains the total number of search occurrences. So while the user is typing the text to search, the buffer is scanned to highlight and count the number of matches. What will be really nice is that, once the buffer is entirely scanned, going to the previous/next occurrence will be a O(log n) operation, thanks to gtk_text_iter_forward_to_tag_toggle() (that’s why the matches must be highlighted even if they are not visible on the screen). It was more difficult to implement than always using gtk_text_iter_forward_search() and backward_search() to navigate through the occurrences, but I think it was worth the effort.

If you want to read more details, I’ve written a quite long implementation overview, with the problems to avoid, at the top of gtksourcesearch.c (it will also be useful to future maintainers).

I’ll continue to blog to explain my progress, so stay tuned!

My work on GtkSourceView so far

During the GNOME 3.7 development cycle I’ve been busy working on GtkSourceView, a library used by gedit, Anjuta DevStudio, LaTeXila, and other applications.

The main change is that the completion system has been revamped, mainly under the hood.

Completion: user-visible changes

The only user-visible changes are the bug fixes and the new calltip window sizing, also used for displaying extra pieces of information for proposals. In GtkSourceView 2 there was a function for tuning the calltip sizing, but this function has been removed when porting GtkSourceView to GTK+ 3. Now the sizing works correctly without any tuning function, the window simply fits the natural size of its child widget.

Now the user-comprehensible explanation:


You see that the main completion window is still quite big when there are only a few proposals. For now it’s not possible to change that, but a more compact completion window should be possible in the future.

Completion: developer-visible changes

The completion system is now better documented. A few functions have been deprecated. The code has been simplified (two classes have been almost completely rewritten). There are also some performance improvements, but it was not really an issue previously. Some statistics on the number of lines:


$ wc -l gtksourcecompletion*.{c,h} | tail -1
8012 total


$ wc -l gtksourcecompletion*.{c,h} | tail -1
6728 total

Perfection is achieved not when there is nothing more to add, but rather when there is nothing more to take away. (Antoine de Saint-Exupéry)

Other enhancements to GtkSourceView

Paolo and I wrote more unit tests, and code coverage support has been added, to have statistics with nice colors.

Lots of compilation warnings have been fixed, especially for the API documentation. For example, the links to GLib or GTK+ symbols work now in the documentation. Compilation warnings are generally easy to fix, it’s a good way to get involved in a project I think, if there are no easy bugs to fix.

That’s all folks. Thanks to Paolo, Ignacio and Jesse for their advices and reviews!

Switch from CMake to Autotools

Last week I’ve migrated the build system of LaTeXila from CMake to the Autotools. Here are the reasons.

The GNU Coding Standards

With CMake, some important make’s targets are missing, for example make uninstall. The main problem is that CMake doesn’t follow the GNU Coding Standards (GCS). The purposes of the GCS, with regard to a build system, is to make a program portable, easy to install, and consistent with the way other softwares are built and installed.

The GCS has several decades of experience, the standards are well established, and we can trust the GNU hackers for having well conceived them. Those that don’t follow them are devoted to reinvent the wheel: they will be faced sooner or later by the same problems already solved by the GCS and the Autotools…

Following standards is important both for users and packagers. If every software uses a different build system, with different options etc, it is a nightmare.

Available macros for GNOME applications

Another reason to use the Autotools, for a GNOME application, is to use the available macros: for the translations (intltool, ITS Tool), the documentation (yelp), the settings (gsettings), …

Creating a tarball

With the Autotools it is as simple as running make distcheck, and putting some files in EXTRA_DIST or prefixing Automake variables with the dist modifier.

It is more complicated with CMake. CPack can be used, but it is far from automatic. When reading the CPack documentation, I changed my mind and wrote a shell script instead.

Learning the Autotools

The Autotools are not as Autopain as people generally say. The learning curve is maybe steeper, but with a good book, there is no reasons to be afraid.

That said, there are certainly problems in LaTeXila, so some tests before the stable release would be more than welcome 😉

LaTeXila: some principles for the user experience

Writing a LaTeX document can be done in different ways. Some people prefer an application like LyX, which hides the LaTeX code and uses sophisticated UIs.

Other people prefer to work directly on the LaTeX code. LaTeXila has chosen this direction. In this context, let’s see, with two examples, some of the principles behind LaTeXila to offer a good user experience.

Inserting a figure

To insert a figure, an application like LibreOffice uses a wizard, so the user can choose an image, its size, the caption, etc.

For a LaTeX application, we could imagine that the corresponding LaTeX code is generated and inserted in the .tex file. Nice, isn’t it?

There is a little problem though: if the user doesn’t understand the code, how does he modify it afterwards to change an option? A good reaction is to look at the documentation to understand what happens. But a quicker solution is perhaps to re-run the wizard and refill the pieces of information and modify the option.

So, to force users to learn LaTeX, LaTeXila avoids wizards!<Esc>dd

A wizard is not a perfect solution. The root of the problem is that looking at the LaTeX documentation can take some time.

A better solution:

  • Good completion of LaTeX commands and their arguments.
  • A way to add easily the required commands for doing common actions like inserting a figure.

The completion works well in LaTeXila, but can be improved. Also, when we are in a command argument, if no completion is available, a calltip is displayed with the prototype of the LaTeX tag:

Calltip showing the prototype of a LaTeX tag

As for the second point, there is a toolbar and menus for common actions. An interesting feature, that doesn’t exist yet in LaTeXila, is the snippets plugin of gedit.

Creating a new document

Creating a new document can also be made via a wizard. We choose:

  • the document type (an article, a report, slides, …)
  • the title
  • the author(s)

But there is the same problem as for figures’ insertion.

In LaTeXila, creating a new document is done via a template. There are some default basic templates, and personal templates can be created.

The user can for example create a big personal template with all the stuff that he could possibly use in a new document. And then, when he creates a new document, he removes or comments what he doesn’t need.

The UI to create a new document has been improved recently ((The window style is different from the GNOME 3 style because I use Xfce, gnome-shell is not supported on my graphics card, and the fallback mode is a bit buggy.)):

New document
Create a new document from a template

To summarize, the idea of LaTeXila is to always deal directly with the LaTeX code, while simplifying as most as possible the writing of this LaTeX code. The users don’t need to be LaTeX gurus, but they should understand what happens.

About code quality and maintainability

It can be difficult to write clean code, that is easy to understand, split in nice and well-defined functions that do one thing but do it well, with good variables names, and so on. For the maintainability, it is really important.

In fact, a code is read far more often than it is written. For fixing a bug, adding a feature, or simply see how it is implemented.

General Advices

There are some general advices, for example:

  • A function’s name should be sufficient to know all what the function really does.
  • Hide implementation details, and use the domain-specific vocabulary, no technical words, if possible. An extreme example: get_last_document() is better than get_top_stack().
  • Avoid focusing on performance from the beginning. About 10% of the code is responsible of 90% of the execution time. An optimized code is more difficult to understand, so it is better to optimize only the 10%.

Every Details Matters

Small details can also improve the code readability. Take for example this line:

g_return_if_fail (foo >= min_value && foo <= max_value);

And compare it with this one:

g_return_if_fail (min_value <= foo && foo <= max_value);

Which one do you prefer? In the second sample, we can visually see the foo variable between the minimum and maximum values.

Many such small improvements, taken together, make the code more enjoyable to read.

Code Complete

We can learn these and other advices by reading some (good) existent code, by working with more experienced developers, AND by sitting in a comfortable sofa with a cup of coffee or tea while reading a book.

I personally have read Code Complete last year. It seems the reference on the subject. But there are other similar books, for instance The Pragmatic Programmer.

Although the editor of Code Complete is Microsoft Press, the book is not related to Microsoft or Windows. The author explains sometimes stuff related to open source, UNIX and Linux, but one can regret the total absence of the mention “free software” and all the benefits of freedom: be able to learn by reading other’s code, etc. But if you are here, you already know all of this, because you are on the good side 😉