I guess properly structured and styled HTML goes a long way, but I'm impressed -- the default PDF creation with Prince works nearly perfectly so far. My first PDFs already included a nice navigation/toc tree like this out of the box:
+(Document title)
├Chapter 1 title
│...
└Chapter n title

After that I fiddled a bit with bookmark levels and labels to automatically generate the exact TOC I wanted, and everything worked good as well. However, I've hit my first bump. In some of my documents, chapter titles have a <br> line break in them so they look like

First chapter
Something with a long name

and I would really like to have these included in the PDF bookmarks toc with the line break.

This is trivial to do with GhostScript and pdfmarks using \n like this:

[/Page 10 /Title (Chapter two\nA somewhat long title) /OUT pdfmark

but of course creating the pdfmarks by hand and merging the files with GhostScript is a real nag.

My problem is Prince includes the above in the TOC replacing the <br> line break with a big nothing so the chapter labels and titles are concatenated as in "Chapter NumberChapter Title".

Is there a way to make Prince insert a newline, or any other separator (an em dash, or even a space) character to replace those <br>s?

JavaScript to the rescue! The attached example document finds h1 elements and gives them a title attribute that is the concatenation of their text with br elements replaced with hyphens, then uses that attribute for the bookmark label.

1. bookmark.html‎ 0.7 kB

As I said, a hyphen --anything-- is better than literal nothing in this case, so thanks for the idea!
However, real line breaks are still not preserved like that -- if anyone really wants them instead of some inline character it's back to pdfmarks drudgery, I guess.

I am not a javascript man either, but this is not bad at all -- so maybe we can add a few more comments for completeness' sake and the benefit of those who are into it, and/or keep on exploring the capabilities of Prince.

Regarding your code, I am also a bit more events- and separate files- school anyway, so I'd put a slightly modified version of the above in a standalone .js file like the one I'm attaching -- with the .addListenerEvent thingy more events can be added to the final document rendering as necessary, instead of reworking window.onload everytime. But that's a matter of taste.

Now the really cool thing is that no modifications to your HTML files are necessary at all like this. Sure, it's necessary to add "bookmark-label: attr(title)" to your CSS to override the default, but that should be a no-brainer were you using separate, globally linked CSS files as you should. Prince will very nicely run the script against your HTML with the --script switch in the command line, thus entirely avoiding the need to link this "fix" from within your documents:

prince --script=h2fix.js MyDoc.htm -o MyFile.pdf

One final word on copying the H2 contents to a title attribute. The long <h2> tags I mentioned also differentiate between label and content to put one of them in cursive like this: <h2>Chapter number<br><span class="content">Blah blah blah</span></h2>, and the code attached won't deal with the text wrapped in the span. For the moment, writing an enhanced version will be left up to the interested reader

1. h2fix.js‎ 0.7 kB ‎
   Copies H2s'contents to a title attribute