OFT Specifications as PDF

PDFs are a fixed size document format, which means that they made more sense in days when PCs all had about the same video resolutions and screen geometries. But even then they were never perfect for displaying them on a screen because most are in portrait mode and monitors very seldom were. Nowadays displays especially in mobile devices come in all shapes and sizes, so fixed size formats are even more obsolete.

What PDFs excel at to the present day is a universal document exchange format for read-only documents — especially if you plan on printing them.

While specifications seldom get printed these days, they still tend to get archived  (especially PDF-A) and a universally accepted format helps. That being said, we plan to make converting OFT-native (aka. “requirement-enhanced Markdown”) easy.

The requirements are:

  • Creates PDFs
  • Is platform-independent
  • Separates content from layout
  • Customizable style (so that projects or companies can apply their corporate design)
  • Based on free software

While there is nothing wrong with users replacing parts of the tool chain with proprietary choices, our reference implementation is going to be free-software only.

These are the options we are discussing so far:

HTML + CSS + HTML2PDF Renderer

This is a variant where we let a Markdown renderer Create HTML for us and use printer-centric CSS as style and layout customization method. The benefits are that you have a broad base of developers these days who know how to tweak CSS, so it is easy for them to tweak the CSS stylesheet however they need. The downside is that the quality depends mostly on how good the PDF converter is.

LaTeX 2 PDF

LaTeX makes absolutely beautiful and professional documents. There is no doubt about that. The ability to customize via macros it is only limited by the user’s imagination.

On the other hand outside of the academic world there are not so many people who have previous experience with LaTeX. Also there are a lot of dependencies involved and they differ depending on the platform.

DocBook

DocBook shares the basic concept of separation of content and style with TeX. DocBook layouts are customizable through XSLT stylesheets. The DocBook documents are XML files that have a strictly defined schema, so the content structure is not customizable like in TeX. Depending on your perspective this is either a weakness or a strength (since it enforces a uniform document format).

DocBook is also known for producing quality PDFs. And the dependencies are should be pretty homogeneous between platforms.

Popularity Contest

I tried to find numbers about the popularity of LaTeX vs. DocBook. Since non popped up right away, I went for a different approach: comparing search term popularity.

I know that the results need to be treated with a healthy dose of skepticism, since more searches could simply mean one of the two is harder to use. Also while there is only one DocBook, there is a whole bunch of TeX variants out there.

If the search term popularity is any indicating LaTeX wins this contest with flying colors.

What’s your opinion? Any arguments I missed?

And this is why we can’t have nice things

The option to allow anyone to register to your WordPress blog is basically useless and should be removed. The reason why I am saying this is that once the automated spam bots find your blog, they start registering users in the hopes of using your blog as a spam distribution platform.

You can use CAPTCHAs as a gate keeper to your registration dialogs. But the fact alone that this is necessary angers me. Just because a bunch of rightfully underpaid software engineering dropouts thinks it is a good idea to support the spam industry, the rest of us have a harder and harder time using the Internet for something useful.

I hope that later generations will look back at this advertise-any-crap-anywhere madness with mild amusement telling themselves that we were a bunch of brainwashed consumers who just didn’t know better.

You there, spam bot programmer you proved that you at least know the basics of software development, make something useful out of that and improve your karma.

Releasing to Maven Central

While we already published releases on JCenter, we are now in the process of getting OpenFastTrace published on Maven Central. The goal is of course to make using OFT as convenient as possible for everyone.

I am happy to see that the people from Maven Central take security seriously and do not just let anyone publish modules under any package name. They asked us to prove that we own the domain “itsallcode.org”, so that gave me the necessary kick in the butt to speed up my plan to set up a web presence for OFT outside of Github on our domain. This blog is the first part.

Samsung Printer “security”

Not much time today, so just a list of “features” I’ve discovered on my shiny new Samsung M2825 printer:

  1.  HTTP but no HTTPS (admittedly most devices do that since there is the problem of how to start the certificate chain)
  2. Default user / password: “admin” / “sec00000”
  3. No mention of open HTTP server in installation manual
  4. No mention in handbook
  5. Shipped with firmware from 2015
  6. Firmware update dialog does not indicate that new firmware is available
  7. Firmware update via file upload from PC – not convenient
  8. Ton of protocols switched on by default
  9. HTML Handbook broken (text only) after unpacking
  10. Firmware well-hidden on the support page (unfold and scroll down): http://www.samsung.com/de/support/model/SL-M2825ND/SEE (edit 2018-07-01: this link not available anymore)
  11. Password cut after 18 characters (no indication when entering new password)
  12. Offers to select source IP for login (probably intended to improve “security”)

tl;dr:

Another example that “S” stands for security in IOT.

Intrusive Sharing

Good software tries not to surprise the user. Today I was surprised that four of the integration tests in OpenFastTrace (OFT) failed although I did not touch the code.

The failure reason given was a character encoding problem. Since I was quite sure that the problem did not occur last time I ran the test and I did not touch the code since, I knew the reason was not in our code.

I suspected that the test did not (or not only) use the test data in the resource directory, so I manually ran the test and explicityly pointed OFT to the resources. This time the test passed.

Then it started to dawn to me: the strange .AppleDouble directories that seemed to appear out of nowhere in my home directory might be the culprit.

A quick Internet search later I realized that they were a result of sharing my home directory over my LAN with another machine. Surely enough they contained the same filenames and that OFT mistook them for input files. Since the content of those files looks binary, OFT could not read them.

I stopped sharing and search-deleted all those directories. After that everything was back to normal.

Coming back to my original point: the appearance of .AppleDouble directories just because I shared a directory via Samba from my Linux box came as a complete surprise to me. I am grinding my teeth already because they will also be in all backups. Luckily I spotted them before I did any git commits.

Bottomline: don’t suprise your users – do exactly what they expect.

Test coverage pitfalls

When did I test enough?

While code coverage is a good indicator, you still have to know how code coverage works. Today I was hunting a bug in a Markdown importer I wrote for OpenFastTrace. The class where the bug sits had a whooping 93.1% code coverage and part of that missing coverage was owed to the fact that the JaCoCo coverage tracer can’t mark code that throws exceptions as covered – even though there is a test case for it.

So I wrote a new issue ticket, created a fix branch and wrote a three line test case that reproduced the problem. While the test now failed as expected, the code coverage didn’t go up.

I used the Mockito mocking framework to verify that an interaction with a mocked observer happended or in my case due to the bug didn’t.

The error was hiding in a regular expression which read

"Needs:\\s*(\\w+(?:,\\s*\\w+)+)"

instead of

"Needs:\\s*(\\w+(?:,\\s*\\w+)*)"

Notice the asterisk in the end.

So while there are a lot test cases waiting to be written for this regular expression, code coverage won’t tell you.

You get what you measure, so be sure you understand what it is you are measuring.