Good article on O’Reilly Radar: Why an ebook still needs an index

Read this excellent post, Why an ebook still needs an index on O’Reilly Radar.

We learn why full text search won’t replace a good old-fashioned book index. We also learn that most ebooks don’t have one, because it’s horribly difficult to create a useful semantic index.

Yes, there are plans to include book index into Novelang.


iA Writer

iA Writer is the most clever text editor I’ve ever seen. Serious. Just watch its 1-minute presentation. It’s a lot of fun. I watched it three times already. They say:

iA Writer for Mac is a digital writing tool that makes sure that all your thoughts go into the text instead of the program.
That’s a lot of shared mindset with Novelang. While both tools leverage on a Wiki syntax, iA Writer tackles the problem with a dedicated graphical interface. It’s a minimalistic text editor that dynamically adjusts its display according to a Wiki syntax ( Markdown ). It has no menus, no preferences, and, well… almost no features. You pay for getting rid of the crap. It’s a paying application, only available on Mac and iPad, through the AppStore. Yes, it screws GPL lovers, but that’s not a reason to not look closely at what it does.


iA Writer relies on the Markdown syntax. I don’t like Markdown syntax , for various reasons.

But Markdown is simple enough to be extremely fast to learn (especially with HTML left out). By sticking to this minimalistic level, iA Writer becomes easy to learn and keeps focused on the text being written.

I should have invented it first!

During a presentation of Novelang for corporate use, a guy asked me: “Do you plan some graphical editor for Novelang?” I answered: “Never, it would lose the purpose of the tool. Maybe I’ll package some syntax highlighting configuration for text editors one day but nothing more.”

This was a decent answer, but iA Writer is more clever. I didn’t envisage dynamic formatting, just because it seems hard to program. One author if IntelliJ IDEA explained that they fully rewrote a Java parser by hand to be fault-tolerant. The rule about parsers is: don’t write them by hand because you’re not clever enough for that. And Novelang syntax is more complex than Java.

I didn’t play with iA Writer so I’ve no hint on how its parser works. Probably the display asks for a best effort given a paragraph, and when the parsing fails there is just no styling. Because of the interactive nature of the application, the user quickly learns how to fix broken text.

Novelang’s strict parser offers strong guarantees about correctness, and that’s a strong point when it comes to generate the final document. But this all-or-nothing approach greatly reduces interactivity. (Interactivity happens later in the Web browser, with some JavaScript to show metadata.)

iA Writer found a new path to the ultimate ease-of-use, while still relying on the Wiki syntax that’s at the heart of Novelang philosophy. I’m just disappointed I didn’t think first about an “augmented” text editor for aiding input of a Wiki text. On the other hand, this wouldn’t have helped me to keep focused on a restrained feature set.

Outsmarting iA Writer?

Spending hundreds of hours of effort to mimick iA Writer sounds like a waste. On the other hand, iA Writer only runs on the Mac/iOS platform and doesn’t offer more than a text editor when inserted in a publication chain. By now, a simple mix of Notepad++ , Novelang and git already offers a complete collaborative solution.

But iA Writer is not the end of the story. By now it works with a full-size keyboard, or with iPad’s keyboard emulation – not the most comfortable thing you can dream about. There are things to invent for a post-iPad world, when handheld devices will have something like a decent virtual keyboard . Starting experiments on a graphical interface with a dedicated parser could be a step in the future.


By now, Novelang is good at what it does, but lacks a few features: intralinks, embeddability, ePub, and desktop integration . It’s important to finish that first.

Novelang could support Markdown as optional syntax. This would make iA Writer the editor of choice and keep Novelang project focused on document agregation and rendering. Two different syntaxes trigger the “double feature alarm”. The source parser could become a pluggable thing, letting other people implement Markdown support. By now, the very few users of Novelang are happy with the out-of-the-box experience and didn’t ask for such geeky features.

Hacking a special text editor component that behaves like iA Writer’s one could be a nice experiment, but it shouldn’t be part of Novelang’s core before years.



AsciiFlow is a drawing tool for producing ASCII art. Currently supports lines and boxes, plus an eraser tool. Looks like the ultimate tool for UML diagrams – no kidding.

Thanks to Julien Kirch who reported this to me first.


Jekyll: a static website generator

Quoting its presentation, "Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server."

Jekyll is It’s github's Wiki engine. This is a clever integration: the VCS tracks Wiki page changes, which means the project hosted by github has a wiki and versioned documentation along with sourcecode.

Jekyll is a batch-only generator, so no interactive preview. Markdown and Textile are also more lenient about grammar validation. But Jekyll is probably much lighter than Novelang, which makes it a better choice for github.


Novelang-0.56.0 released!

Just released Novelang-0.56.0!

Summary of changes:

  • Added Romanian characters, as listed on Wikipedia. This includes diacritics made obsolete by the spelling reform of 1904, minus the d/D letter with a comma below, for which Unicode offers no precomposed characters.

Download it from here.




This is the result of a conversation with another Novelang user, coming with ideas for a better integration with the desktop environment.

First, as strange as it seems, Novelang is a desktop application. While it embeds a Web server it’s not meant to serve content to remote clients. The support of a Web client is just the fastest approach to give quick preview of files edited in a desktop-integrated text editor. (For serving Novelang documents on the World Wide Web, it’s much faster to generate them as static files first.)

By now the desktop integration relies on a java -jar Novelang-...jar typed in a command-line console. That’s a bit harsh.

The yet-to-develop Novelang-desktop project would be fancier. Novelang-desktop is a graphical application where user sets content roots and associated TCP ports. With this, editing or viewing Novelang documents from multiple content directories doesn’t require to start several JVMs anymore.

Here is a skeletal view of the main window of Novelang-desktop:

|  __________________________               |
| | C:\projects\docs  | 8081 |  [ Add...  ] |
| | I:\shared\foo     | 8082 |  [ Edit... ] |
| |___________________|______|  [ Remove  ] |
|                                           |
| [?]                      [ Configure... ] |

Double-clicking on a table line opens a Web browser with the directory listing of the content root.

The directory listing comes with great improvements. It shows every files, and each Novelang source file has several associated links:

  • Open in current Web browser (one link per rendition MIME type, like PDF, HTML, FO, XML).
  • Open in default editor.
  • Batch generation.

For the last two there is a trick: the link loops back to a special service of Novelang-desktop, which has all the powers to execute arbitrary code and scan local filesystem.

  • For editor opening it executes a pre-configured command with the file path as an argument.
  • For batch generation first it opens a dialog requesting target directory.

Novelang-desktop’s configuration goes in user’s home directory by default.


Novelang-0.55.0 released!

Just released Novelang-0.55.0!

Summary of changes:

  • New --temporary-dir option. For better error messages, Novelang now buffers the whole document before sending it to the HTTP client. When the document is too big Novelang buffers it into a temporary file under this directory. If an error occurs then its not too late to send an HTTP redirection.
  • Fixed SVG embedding for PDF. Now the image appears as true vector image inside the PDF. Correct reference to the SVG resource implied adding a $content-directory parameter passed to XSL stylesheets.
  • Fixed loss of request parameters when issuing error page.
  • Less verbose logging of Logback configuration at startup.
  • Fixed various cases of bad problem reporting, where location in origin file was missing.
  • Plenty of other small fixes.

Download it from here.



Secrets for embedding SVG images in PDF documents

Nhovestone reports don’t look good when zooming, because the charts are bitmap images. While trying to render them as vector images, a few interesting things did appear.

(Most of them relate to FOP-1.0 and Batik-1.7 which are the latest versions at this time.)

There was a bug (fixed in HEAD) preventing from embedding SVG images in PDF documents. Novelang resolves the image path (in n:vector-image/n:resource-location) as relative to the content directory. But most of times the stylesheet doesn’t reside right under the content root, so FOP (the PDF renderer) couldn’t find the SVG file. Now XSL stylesheets receive a $content-directory parameter to solve this.

There are several manners to embed an SVG file into a PDF. In order to keep the vector graphics (means: avoiding an ugly conversion to a bitmap) FOP needs a rather twisted declaration of the form:

  <svg:svg width="123px" height="456px" >
    <svg:image width="123px" height="456px" xlink:href="file:/my/image.svg" />

The documentation explains that width and the height must appear two times, with exactly the same values.

It’s important to note that an SVG image must always have width and height. Moreover, they must be in pixel unit. Pixel unit is bad, as it introduces a dependency to document’s resolution. But units other than pixel don’t work.

Knowing this, the graphs started to look really good. Unfortunately, the grid becomes bigger when zooming in. In theory, the solution is to set line with to a zoom-independant value with vector-effect="non-scaling-stroke" property (thanks to StackOverflow for that hint). Unfortunately, this is SVG 1.2. Batik doesn’t support this yet and some archived mails show this is somewhat tricky to implement.

Conclusion: while SVG embedding in PDF is far from perfect, it’s much better than rasterized images that seemed to be FOP’s approach. In order to get best vector images we'll have to wait for non-scaling stroke feature in Batik, and maybe some FOP upgrade in order to propagate this feature to generated PDF.


Aggregated javadoc with Maven

This generates a javadoc covering every subproject. From Novelang root project:

mvn -Dnovelang.javadoc.skip=false javadoc:aggregate

Generated HTML goes in target/site/apidocs.


Nhovestone report for Novelang-0.54.0

The Nhovestone report shows that Novelang-0.54.0 is as at least as fast as previous versions. Good news!


Novelang-0.54.0 released!

Just released Novelang-0.54.0!

Summary of changes:

  • Because of some cleanup, n:relative-identifier becomes illegal in stylesheets (wasn’t generated since a few versions). This might break a few existing stylesheets.
  • Better logging of accessed resources.
  • Documentation enhancements.

Download it from here.



Novelang-0.53.6 released!

Just released Novelang-0.53.6!

Summary of changes:

  • Fixed resource loading bug appeared in 0.53.5, that caused to ignore overriden resources (like stylesheets).

Download it from here.



Novelang-0.53.5 released!

Just released Novelang-0.53.5!

Summary of changes:

  • Various logging enhancements.
  • Various enhancements to the documentation.
  • Disabled full parsing and validation for SVG files.

Download it from here.