Tuesday, May 11, 2010

0.2.0 FINAL

And here it finally is. After months and months and months of finger-breaking[1] work, it’s finally done. Changelog is minimal going from RC4:

  • added new entries to the help menu for the online manual and the FAQ

Now cue tens of thousands of 0.1.9 users screaming “WHY DO I ONLY SEE JUST THE FIRST PAGE??!!”. See the FAQ.

Footnotes

[1] Like back-breaking, only for programmers.

Sunday, May 9, 2010

Manually, but for the web

When I decided I wanted to write the manual for Sigil, the first thing that came to mind was putting it online as some sort of website. A web version can be always up to date, you can put a link to it in the Help menu of your application and you don’t have to blow up the download size by including it in the installers.

But that was wishful thinking; Sigil is hosted at Google Code, and it doesn’t offer a way to host custom HTML pages, and I’m not buying a domain and webhosting just for a damn manual. So sadly, that couldn’t work.

The second idea was writing the manual in pure LaTeX, since if I’m going to write an “offline” version of the manual, I’m going to typographically do the best job I can. Epub can be used for technical manuals, but some of the nice typesetting tricks I hand in mind couldn’t be done in it.

Then it occurred to me that having a PDF-only version of the manual for an epub editor was… not the best political decision. I wanted to find a way to eat my cake and have it too: to offer both a nice PDF and a nice epub. I was willing to sacrifice some of the things I could do with custom LaTeX if the resulting PDF was “good enough”.

reStructuredText and Sphinx came into the picture. As I mentioned in a previous post, the PDF version of the manual sucks. Links don’t go where they’re supposed to, the layout is shoddy and in general, it just looks bad (to me at least). Sphinx was primarily designed for creating HTML documentation, and the LaTeX generator suffers because of it. I decided to upload what I had now, gather some feedback on the content and then rewrite the thing in custom LaTeX.

Then came the expected politics

While I’m convinced that I’m right[1], I wanted to talk to a few friends who lead or are members of other open source projects (some hosted on GC too) what their thoughts were on the subject. I got universal agreement that a LaTeX PDF was the way to go, but one of them pointed out that GC indeed does provide a way of hosting sites, just… unofficially. The Google guys apparently have no problems with people hosting their site inside their source code repositories. This could of course only work if your site serves only static content, which a manual would certainly be. They’ve even improved the SVN backend for direct web content serving, so they certainly approve of the practice.

Sigil uses Mercurial, and Google provides every mercurial-based project with many repositories. So I used Sphinx to generate the HTML, committed it all to a new “web” repo and voilà! An online manual.

Sphinx produces wonderful HTML, and I’m willing to sacrifice some typesetting beauty for online accessibility. It’s also much easier to customize the HTML output by injecting new CSS. Tweaking the LaTeX output was a nightmare.

There won’t be an offline epub version since there’s no point anymore and I want people to see the code samples and images on a large screen. But if someone wants one, they can easily download the manual sources and build one with Sphinx.

I think everyone should be satisfied now.

Footnotes

[1] Big surprise there.

Saturday, May 8, 2010

0.2.0RC4

Another minor update:

  • fixed a regression that broke FindNext opening new tabs when searching across HTML files (issue #384)
  • fixed an issue with autocompletion in Find dialog ignoring the case of search terms (issue #385)

I’ll be doing these until the explosions stop.

Manually

I’ve just uploaded the manual for Sigil. You can get it from the downloads section.

The manual was written in reStructuredText (RST) and then processed with Sphinx. Honestly, I’m not too happy with the layout of final file compiled from the Sphinx-generated LaTeX. Some of the hyperlinks don’t lead to where they’re supposed to (bug in Sphinx I guess), and typographically in general… well I don’t like it.

Initially, I wanted to write the manual in straight hand-coded LaTeX. I decided against that because that would mean the manual would only be available in PDF form.

Now, I’m the kind of person who always tries to use the right tool for the job. I love epub and absolutely abhor the PDF “ebook” novels. PDF for novels just doesn’t work, and if you’re producing them… don’t. Make epubs. But for technical manuals with complex layouts, code listing, figures, diagrams, sidebars and the like, PDF is the right choice IMO. Epub is just not the right call for these kinds of books.

Sure, you could make epub versions of technical manuals, but you’d have to sacrifice some of your layout.

Then there’s politics. An epub editor with a manual in PDF form only? That just looks bad. That’s kind of like Microsoft employees using Linux.

I was pondering this until someone told me that the next version of Sphinx will have an epub generator. You would give it RST and it would spit out a nice epub file from the same source it would generate LaTeX markup. That sounded like an amazing deal, so I went with that.

I loved RST until I started using it. I don’t love it anymore. It has a weird syntax and to get anything above the barebones, you have to do all these strange contortions etc. Add to this that the resulting LaTeX markup produces a PDF that I dislike. I tried to tweak it here and there, and I’ve improved the output considerably over the last few days, but still… Having an epub file to silence the naysayers is good, but not at the expense of quality.

I’m pretty sure I’ll be rewriting the manual in pure LaTeX when I get the time (a few weeks from now, probably). Until then, enjoy the current version.

And if someone feels that the new PDF-only manual shows Sigil in a bad light, I say screw ‘em.

Thursday, May 6, 2010

0.2.0 RC3

Ok, RC3 is now up on the site. Download it here.

Changelog:

  • fixed a regression that messed up the tab order of the controls in the Find dialog (issue #380)
  • fixed an issue with cross-file FindNext causing a hang when the search term is not in the book and "Direction: All" is used (issue #378)
  • the Text folder in the Book Browser is now expanded by default after loading

This is also the first release that was completely built and uploaded by an automatic process composed of several Python scripts. Since it’s brand new, it could have introduced some problems. The whole point of this automated build system is to eliminate those nasty situations where I would upload the wrong file, forget to include some critical libraries into the installers or something else.

Once the system has been set up to produce correct builds, it should stay that way.

If anyone’s wondering when 0.2.0 final will be released, my rule of thumb is three days without any showstopper bugs reported. In RC2, the showstopper was the FindNext hang that has now been fixed.

Tuesday, May 4, 2010

0.2.0RC2

The second release candidate is now available. Changelog follows:

  • fixed an issue with ReplaceAll across files not using correct replacement lengths
  • fixed an issue with code in Code View not being pretty-printed
  • fixed an issue with the ReplaceAll across files not informing the opened tabs of the change

Small but important. I consider all of these to be showstoppers. Hopefully these are all there is.

If anyone finds any other bugs, please report them on the tracker. If this release stays showstopper-free, it will be promoted to a full release later this week.

Monday, May 3, 2010

0.2.0RC1

The first Release Candidate is here and you can get it from the downloads section. Between now and final 0.2.0, I’m fixing only showstopper bugs and maybe a few of the trivial ones. If all goes according to plan[1], there won’t be any need for further changes before the final release and thus you’ll see it a few days from now. This is not called a Release Candidate for nothing.

So hammer this version hard, especially the Find & Replace functionality.

Here’s the changelog. It’s by far the largest batch of changes to Sigil for one release (disregarding the first 0.2.0 beta, of course). Also, some very important bugs were finally fixed plus lots of new features, so this really is a big release. Some highlights have been… highlighted:

  • changes in the Book Browser now update the modified state of the main window (issue #331)
  • the Book Browser can now be opened/closed from the View menu (issue #335)
  • all the toolbars now have UI-facing names
  • by injecting a custom XML reader into QDom, the following issues were fixed:
    • Book View search sometimes skipping over instances (issue #253)
    • Book View ReplaceAll causing Sigil to hang on rare occasions (issue #293)
    • spaces disappearing from some HTML constructs (issue #352)
  • implemented component-wide search&replace for Code View searches (issue #372)
  • the Find&Replace dialog now remembers up to 20 previously used search and replace strings (issue #369)
  • fixed an issue with positive regex lookaheads in normal Replace (not ReplaceAll) (issue #261)
  • fixed a rare off-by-one error in Book View searching when the caret was at the start of the matched string; this made the search skip that instance of the match (issue #280)
  • fixed an issue with the Find Dialog not correctly scrolling to the found text in Book View (issue #195)
  • fixed an issue with Tidy not fixing free ampersands into "&", even when configured to do so (issue #365)
  • fixed an issue with the current tab unnecessarily reloading after book saves (issue #354)
  • fixed issues with filename basenames being read only until the first dot; was causing problems with OPF manifest ID generation (issue #351)
  • hitting the keyboard shortcut for the Find&Replace window while the window is open now switches focus to that window (issue #362)
  • fixed an issue with the applied headings not "sticking" and not showing up in the TOC editor (issue #300)
  • the special iPad- and Calibre-friendly cover meta tag information is now preserved after loading
  • added a new "Cover Image" entry for image resource in the "Add Semantics" Book Browser menu
  • if an image is not set as a cover image manually, Sigil now uses heuristics on save to determine if the epub has a cover image
  • if an epub has an image set as a cover image, Sigil will now write a special meta tag that identifies this image in the OPF; this tag is then used by the iPad (and Calibre) for the book cover, for instance
  • all OPF <guide> element information when loading epubs is now preserved
  • added a new "Add Semantics" menu for XHTML documents; it can be used to mark XHTMLs as "Dedication", "Colophon", "Glossary" etc. for the <guide> element of the OPF
  • the status bar now shows a message after chapter split operations
  • fixed an issue with filenames with characters that should not appear in valid XML IDs having those characters added anyway (issue #344)
  • fixed an issue with files with uppercase extensions not having a mimetype set in the OPF (issue #349)
  • fixed an issue with Sigil rewriting headings when the TOC was opened and no heading was edited (issue #327)
  • fixed an issue where adding an existing HTML file through the Book Browser would clear the current metadata in the book (issue #329)
  • added a check that prevents Sigil from loading the same resource multiple times in invalid epubs (issue #339)
  • fixed a bug that made the direct XHTML references in the NCX file less likely (issue #333)
  • fixed an issue with Sigil crashing when trying to save a loaded epub that had some badly formed metadata elements (issue #325)

It’s pretty damn huge.

Book-wide search

For now, you have to perform your book-wide searches in Code View. I know, I know. It’s not everything you wanted. But technical restrictions are causing problems[2]. I’ll try to write a post about it tomorrow explaining the issue, I’m too tired to go into it now. Just learn to live with only Code View searching until I work around this[3]. It should cover 95% of all your needs.

I’m making it up with the new remember-20-last-used-search-strings feature. The input fields also provide automatic text completion for previous searches. All of this was scheduled for 0.2.1, but hey.

Footnotes 

[1] Do I even need to chuckle at that?

[2] Cookies to the first person that points out the framework giving me grief.

[3] Something like 0.2.2, maybe sooner.