Peruse 2.0 Beta 1 "The Long Awaited Beta"

A fair while ago, in the before times of late 2016, a release was made of a piece of software known as Peruse. Since then, it spent some time getting work done on it on and off, until sometime last year when we decided that it really was time to stop the thing just floundering in some free software equivalence of development hell, and actually get it ready for its next release.

Peruse?

First things first. For those of you who are new, Peruse is KDE's comic book reader project, which consists of the reader application, Peruse Reader, and the comic book creation tool called Peruse Creator.

The project's releases further include a library by the name of libacbf, which allows applications to use Advanced Comic Book Format (ACBF) metadata without doing manual parsing or generation of the xml data. If this doesn't mean anything to you, don't worry, as a reader or maker of comic books, what that really means is that you get rich comic books that are not simply a collection of images in a specific order.

What's New?

Since that most recent release, a fair lot of stuff has happened, including a great deal of polish and fixing in various places throughout the project. In the following, i am going to try and highlight the more impactful ones, in a rough order of coderiness.

Frame Based Navigation

One frame of a much larger page, so you can see all the gorgeous details

From the very start of Peruse, one of the goals was to eventually be able to read comics not only on a page-by-page basis, but more akin to what you might do if you get really deeply into something on paper and focus hard on each panel, except in a guided manner. This is one of the things that ACBF allows the authors of comic books (using an application like Peruse Creator) to do, by letting them mark out areas on a page, and assign them an order, which then lets applications like Peruse Reader know precisely what to show and in what order. Not only is this useful in a way that makes comic books more engrossing to read, but it also makes it much easier to do so on a smaller, hand held device like a phone.

Translated Comics

Translations - because language shouldn't be a barrier to enjoying a good comic book

One of the powerful features of ACBF is the concept of TextLayers. What those are, in essence, is translations for comic books - a way of putting formatted text on top of an image, for speech bubbles and the like. Peruse now has support for this, and if you would like, there's a blog entry right over here talking about that more deeply.

Better Navigation in Books

The sidebar pulled out, with page thumbnails

 Another feature in ACBF is the ability to link between various parts of a book to another. It seems simple enough on the surface, but this allows for some really nifty stuff. On a basic level, you can create a table of contents and jump from there to other places, but you can also create things akin to a choose your own adventure book using this method. There is plenty more to say about this, which is why there is a whole blog entry over here talking about that specifically.

Greatly Expanded Creator

Editing a text-area with a link in

 

The version of Peruse Creator shipped with Peruse 1.2 was an extremely simple tool, designed primarily to just create a simple comic book archive and fill it with pictures, and annotate it with some basic metadata. In Peruse 2.0, while it is not yet able to do everything that ACBF will do, a great deal of it is (such as, but not limited to, references, embedded files, as well as the three types of page areas: frames, jumps, and text areas). In short, Peruse Creator is starting to become a tool that is actually, genuinely good for creating comic book archives and annotating them with ACBF metadata.

Collection Cache

Previously, Peruse would scan the system on startup every time, and build a full database of all the books. This, as you might expect, was an extraordinarily heavy operation, and with any more than a few tens of books, it effectively made it impossible to use Peruse in the casual and immersive fashion the rest of the application intends.

Graduating from Playground

A more organisational thing that happened was that Peruse has graduated from being a Playground project (KDE's experimental section for projects that are not considered quite full featured yet), and is now a proper, full member of KDE. For most people this is a small detail, but one of the larger effects of this is that it means that KDE considers it a "real" project, and it gets attention for things like translations.

ACBF Library

The details of a book

 

Another kind of user we envision for Peruse is other people also working on software which handles comic books, and particularly ACBF enhanced ones. Peruse's ACBF support was always intended to be usable by others (it was built specifically to only require QtCore, but annotated with enough bits to also use it from QML), and as of Peruse 2.0 we are releasing the library versioned according to the Peruse release. It was also expanded greatly, and now supports almost the entirety of the ACBF specification. Round-tripping documents is still a work in progress, but it's already pretty solid.

More on this in a later blog post, but for now, the cmake module is called AdvancedComicBookFormat, and your starting point is AdvancedComicBookFormat::Document in the AcbfDocument.h header.

Kirigami 2

The original release of Peruse was built on top of Kirigami 1, during the early days of the development towards what would eventually become Plasma Mobile. One of the first things to happen after the release of version 1.2 was to port Peruse to Kirigami 2, and the result for the user is partly just more modern and stable code, but also much more easily navigable using a keyboard. Since then, the Peruse team has been working to bring more of the features of Kirigami' which didn't exist in the first version into Peruse, such as the way the search field works, the way scrolling pages are handled, page row layers, action handling, and a whole bunch more.

Gentler, Safer Threading

The way images are served into QML is something called an Image Provider. The old method used by Peruse was a set of simple image providers, which attempted to throttle their own behaviour somewhat, but in reality tended to block operations fairly badly, and also caused severe threading overload on slower systems (such as, for example, on a PinePhone). The end result of that was that you would regularly end up not being given an image when you loaded a book, or your thumbnails would take forever to load.

The new code has been refactored heavily, and now uses what is called an asynchronous image provider, and also makes sure to not ever launch more threads than are actually available on the system it's running on. To you as a user, what this means is not only a more reliable image generation, but often also faster, and safer to boot (which is not really a result of this change to a new kind of image provider, so much as the old code just not being very stable).

No More Submodules

The thing in this list which will be least relevant to someone who just wishes to learn about what Peruse does for reading comic books, this one is for the packagers and self-builders: Peruse previously used an external bit of code to read rar based comic book archives (the ones with the file suffix cbr, and seemingly the most common out in the wild). This turned out to cause endless headaches for packagers, and the decision was made to import that code fully into Peruse.

Gimme!

Before we get to the downloads: This is a beta version, and you should expect it to behave like one of those: Things may well be a bit broken or unpolished, and we will be very happy to see reports any bugs you run into over on the Peruse product category on bugs.kde.org. With that out of the way, head over to peruse.kde.org to grab yourself a shiny new copy of Peruse :)

---

The word of the day is: Polish. Because that's something to be done when you've got a beta out of the door ;)

Advanced Comic Book Linking

In my previous post about Peruse's support for ACBF Textareas, i talked about how the formatting system there allowed for all manner of niftiness with languages, and rotating text, and making it coloured, and styled, and all of that visual fanciness. In this one, i'm going to talk a bit more in depth about a quite powerful feature the Textareas have that i kind of glossed over in that one: Hyperlinks.

Yes, hyperlinks. Links, like the one you just clicked on above to work out what that last post actually said about textareas (thanks for reading! :) ). Except that these links are inside any of the things in an ACBF document which can hold paragraphs of text, being primarily Textareas, References, and Annotations. The reason this is a separate post (apart from the fact the other one had a different focus) is that ACBF recently gained the ability to add a resource target (that is to say, a href property) to the Jump element.

Linking to some URL, and protecting people

For a simple starter, the most usual suspects for hyperlinks work for this: Websites (http(s)://) and email links (mailto:), primarily. If you click on one of those in Peruse, don't worry, we're not going to send you anywhere without making sure you want to actually go there. On the web, you usually would be expected to trust whatever you're clicking on, but inside a book, you'd reasonably expect to be constrained, so before sending you anywhere that isn't inside the book, you get a cute little popup that shows you the address of the link you clicked on, and asks if you really do want to follow it.

Additionally, and very possibly more interesting when creating a book: Internal links work as well. If an object in the book has been given an ID (which is now also more widely possible), you can link to it by prepending it with a # and using that as your link target (which is similar to how you might link to a named anchor in a simple html document). In its simplest form, this allows you to jump from page to page (which also is what the Jump element was originally designed to do), but with this system, much more power is added, by being able to link to not only pages, but also individual frames, and the reference and binary objects.

Linking to a page or a frame will make Peruse navigate to that location in the book, as you would expect (the way Jumps previously would link directly to a page). The idea there is to allow you to create branching narratives and other interactions of that type, like those you would find in a Choose Your Own Adventure book. Of course, ACBF is not a scripting system, and Peruse doesn't have one either; this is "just" markup, so it's not like you can create a full blown game here, in the modern sense, but even then, engaging narratives do not require score keeping for their interest :D

Say you've got a lovely CC-BY banner, and want to show the license? Pop the text in a Reference, and Jump away!

Linking to a reference or a binary object will make Peruse display that object in a popup or a page. An author can use this to create a glossary of terms, for example, or character reference art, a location map, or a world encyclopedia built right into the book itself. As someone who does writing and world building in their spare time, this in itself is something that i'm hoping to expand on greatly (how does having a pile of world-building focused templates for references sound to you? Sounds kind of neat to me, and i'd really like to see that happen :) ).

Something else Peruse does is keep track of all these internal links. Or, rather, the libacbf code does - we built that library as a non-gui Qt style library to be consumable without being bound to Peruse, but more on that at some later date (Tier 1 ACBF KDE Framework anybody? ;) ). What that means is that if you are at a location in a book which is linked to by something else, Peruse knows about it.

Right now, that information isn't used, but we might imagine things like building two-way navigation in the book (say you click a link, and you want to go back to where you came from; well with this we can make sure that happens), or even building entire navigation maps for a book (technically this tracking system for the internal links constitutes a directional graph, where each node is a location in the book, and the edges are the links). How such a thing would be presented visually, i'm frankly unsure, but as a basic idea it feels like it could be fun!

If this sounds like something you'd like to work with, get in touch - either here, or anywhere else you find me - i'm leinir basically everywhere, and we've got our own little corner over on Matrix as well. In short, get in touch, we'd love to hear from you! :)

---

The word of the day is: Emergent. Because that's the kind of behaviour these bits of functionality promises