||[Wednesday 21st November 2012 at 11:22 pm]
|||||Newgrange ~ Clannad/The Best of Clannad: In a Lifetime||]|
Why is it that in this day and age the most common format for documentation is a PDF? Generally I don't want to print out umpteen pages when I'm poring over some documentation - I want to be able to browse through it on-screen, using a documentation program that has useful things (like an index, search engine, table of contents that's synchronised to what I'm viewing). And when there's a cross-reference I want to be able to go straight to it, *and* go back once I'm done with it.
To be slightly fair, PDF can do those. When the author has bothered to add them. But it still suffers from the other problem, which is that since it's a document format it's based around a concept of pages (as in sheets of paper). But when I'm reading something on-screen there's no need for this. Especially when the PDF author has chosen a 2-inch margin around everything (which, by the way, looks just as ridiculous printed as it did on-screen).
Windows HTML help is perfect for this. It has a left-hand pane which shows your table of contents (linked to what you're viewing), index, and full-text search, and a main pane that has the actual documentation you're reading. Which, being HTML, can have whatever fancy formatting you want *and* can contain hyperlinks (something else that's also usually lacking in PDFs). Except it's a Windows thing, and so any non-Windows projects (and an awful lot of cross-platform ones, for that matter) refuse to touch it with the proverbial bargepole. Some get close and use HTML, but that suffers from treating the index and the contents as being just another page. Surely Linux has some sort of usable HTML-help equivalent?
I suppose Linux does have info, but using that requires knowing the emacs keyboard commands off by heart. Now, if there was a graphical info viewer then it would be useful, but that also would require everyone to create their documentation in it as well.
This rant brought to you by the aforementioned 124-page PDF with 2-inch margins and no table of contents or internal links.