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 😉