Okular: improved PDF annotation tool

Okular, KDE’s document viewer has very good support for annotating/reviewing/commenting documents. Okular supports a wide variety of annotation tools out-of-the-box (enable the ‘Review’ tool [F6] and see for yourself) and even more can be configured (such as the ‘Strikeout’ tool) — right click on the annotation tool bar and click ‘Configure Annotations’.

One of the annotation tools me and my colleagues frequently wanted to use is a line with arrow to mark an indent. Many PDF annotating software have this tool, but Okular was lacking it.

So a couple of weeks ago I started looking into the source code of okular and poppler (which is the PDF library used by Okular) and noticed that both of them already has support for the ‘Line Ending Style’ for the ‘Straight Line’ annotation tool (internally called the TermStyle). Skimming through the source code for a few hours and adding a few hooks in the code, I could add an option to configure the line ending style for ‘Straight Line’ annotation tool. Many line end styles are provided out of the box, such as open and closed arrows, circle, diamond etc.

An option to the ‘Straight Line’ tool configuration is added to choose the line ending style:

New ‘Line Ending Style’ for the ‘Straight Line’ annotation tool.

Here’s the review tool with ‘Open Arrow’ ending in action:

‘Arrow’ annotation tool in action.

Once happy with the outcome, I’ve created a review request to upstream the improvement. A number of helpful people reviewed and commented. One of the suggestions was to add icon/shape of the line ending style in the configuration options so that users can quickly preview what the shape will look like without having to try each one. The first attempt to implement this feature was by adding Unicode symbols (instead of a SVG or internally drawn graphics) and it looked okay. Here’s a screen shot:

‘Line End’ with symbols preview.

But it had various issues — some symbols are not available in Unicode and the localization of these strings without some context would be difficult. So, for now it is decided to drop the symbols.

For now, this feature works only on PDF documents. The patch is committed today and will be available in the next version of Okular.


22 responses to “Okular: improved PDF annotation tool”

  1. Thanks for those features! Could you also consider making Okular respect different settings for each opened file, e.g. View Mode > Single Page or Facing Pages etc.?

  2. I think the symbols really make it easier and faster to understand what is meant, and I think they would actually help translators translate those strings correctly. Words like “Diamond” or “Butt” could easily be mistranslated without the symbol that shows what is really meant. And what you mean by “Right Open Arrow” and “Right Closed Arrow” is also unclear without a symbol.

    For some of the symbols, it may be worth prepending a U+2500 BOX DRAWINGS LIGHT HORIZONTAL character? E.g. I guess “Right Closed Arrow” means something like “─◃”? And wouldn’t the “Right Open Arrow” be more consistently represented by the opposite character than the one you used, i.e., by U+2919 LEFTWARDS ARROW-TAIL “⤙”?

  3. Poppler isn’t as good as MuPDF for rendering but excepted SumatraPDF, there aren’t a lot of PDF viewers using it.

  4. Kevin,

    Symbols indeed help, but it is argued that better to use a proper icon or internally drawn shape. Hopefully that can be implemented, but I don’t know yet.

  5. du,

    This already works (I can open a PDF in ‘single page’ mode, then open another file and change to ‘facing pages’ mode). It seems that the setting persists, so if I open a new file now by default it will be shown in ‘facing pages’ mode. If you think this could be improved, please report a bug at https://bugs.kde.org/ under component ‘okular’.

  6. Thanks for your interest. Does it work if “Open new files in tabs” is on?

  7. du,

    Yes, I just tested and it works with tabs (although with some rough edges — if I hide the menu with `Crtl+m`, the view mode seems to reset, but if I enable it again the correct view is on different tabs).

  8. Now, I see that I wasn’t clear enough. Sorry. What I have in mind is not just re-using the most recent settings for new files but rather respecting different settings for different files open in different tabs. So you could for example view, at the same time:

    file A (one tab)
    – in a ‘Single Page’ mode,
    – rotated left,
    – zoomed in to 200%

    file B (another tab)
    – in ‘Facing Pages’ mode
    – rotated right,
    – zoomed out to 50%,

    It’s not possible currently, as far as I know.

  9. Very nice! I was thinking about the lack of this feature just today.

    BTW I am redesigning the annotation toolbar, have a look at this task: https://phabricator.kde.org/T8076, maybe we can discuss also with you how to integrate this new feature in the design of the new toolbar.

  10. du,

    I just tried these exact steps (Okular from KDE Apps 19.04) and it works as expected. What happens when you try this?

  11. simgunz,

    Excellent! I was indeed inspired by Adobe Reader, Foxit Reader and macOS Preview applications; and had the exact title (“Modernize the annotation tool bar”) in mind :-).

  12. It seems that everything works as expected until you browse (scroll) through one of the files. Then the most recent settings are applied to it even if they are opposite (e.g. facing pages) to what was inteded (e.g. single page). I can’t have these two modes (single page / facing pages) applied at the same to different files.

  13. Could you check if browsing through documents doesn’t change their view mode to the most recent one? In my case the most recent settings are applied while browsing (scrolling through) files regardless of the visibility of menu. Thanks.

  14. Indeed, the view mode is reset to latest chosen style once you scroll past a page. But, if I select the preferred view mode for that tab again, scroll, go to next tab (with a different view mode set), it works correctly (i.e., 2 tabs with 2 different view modes).

    Nevertheless, it is a bug which should be ideally fixed, so please open a bug request and someone hopefully attend.

  15. Thanks for checking out this issue! I hope someone will take it further from here.

  16. Hi ! Thank you so much ! My wife was complaining yesterday about the missing “arrow” shape 😉

    BTW, do you know who I could get in touch with to give examples of documents that take a lot of time to display with Okular / libpoppler (but not neceassarily as slow with EVince / libpoppler) ? I have some quite complex docs that take several seconds to refresh each time I make an annotation…

    Cheers !

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: