lardbucket: blog

11/30/2014

2012 Book Archive: Now With PDFs

Filed under: General — Andy @ 10:58 am

Almost two years ago, I launched (what became) my 2012 book archive. There’s a bit of background on that project on that page. While there have been a few minor developments since then, none of them have been noteworthy enough to document here. Recently, however, I decided that I would try to make PDF copies of the books. I wanted these to be good-quality PDFs, as although a number of PDFs of the books had circulated from other groups in the past, they weren’t particularly visually appealing: they were essentially what you would get by quickly printing each of the HTML files from the publisher.

My guess was that a simple HTML file with all of the book content could be combined with a quick print CSS style and get good-quality output without too much effort. I figured that with a decent number of iterations on the book CSS and test runs, the project might take a week or so. Over two months later, I’m finally set to release the PDFs. I’ve made a few notes of the things that I did along the way, in case anybody finds them useful in the future.

If you just want the PDFs, you can visit the 2012 book archive and download them there. There are a few ways to download each book: you can download a whole-book PDF file, or a PDF for each chapter. Both are accessible from a book’s table of contents, and the whole-book PDFs can be downloaded from the archive’s book list as well.

Getting a PDF

It’s worth noting that the content I have from the books is already in an HTML format, not necessarily the raw input to a book creator. I decided early on to try to work with HTML and CSS, because although the HTML I have is structured and could probably be parsed into a different format, doing that correctly for over a hundred books would be iffy. With that said, the HTML was well-structured, and lent itself to easy use of CSS to style specific things.

If you’ve been following CSS development, there are a lot of features in CSS that are supposed to allow styling of printed content. Unfortunately, support for some of these in browsers is spotty, and they don’t necessarily provide all of the features that you’d like when styling a book. (In particular, footnotes, page-relative positioning, page numbering, and PDF bookmarks are all difficult. There are likely other features I’ve forgotten about as well.)

At first, I was hoping to be able to use something like wkhtmltopdf, which wraps WebKit and converts an input file to a PDF. This gave me a number of problems, and didn’t seem to support the concept of pages as natively as would be desirable. (It’s still impressive that they managed to get the project to work as well as it does, but it doesn’t produce nice-looking books yet.) After that, I decided that perhaps Firefox’s support for printing would work for me: it works pretty well with many of the CSS printing features, and I can probably script Firefox to output PDFs if I want. Unfortunately, I again ran in to bugs with the rendering. I don’t recall the details at the moment, but I believe that content had a tendency to not wrap between pages in the right spots. Either way, this sent me in search of a high-quality PDF rendering solution.

If you look online for advice about generating PDFs from HTML, you will inevitably run upon many people suggesting PrinceXML (or, as it seems to be rebranding itself, Prince). They’re probably right. It is a commercial piece of software in a case where I had hoped to use free software, but it is still the best solution I have found by far, both in ease of use and functionality.

Princely Things

Prince itself is not cheap. A personal license is $495 at the time of writing, and even that may not cover what I intend to do in terms of converting books automatically. (To be clear, it might be covered, but only just barely if it is. I haven’t asked, for reasons I’ll explain shortly) If you are doing anything serious with Prince, you’re probably looking at a $3800 license per server generating PDFs, or a $1900 one if you’re only doing academic things. Upgrades are available for an additional annual cost. To be clear, if you’re generating revenue from the PDFs (or even just saving yourself loads of time), Prince is almost certainly worth every penny, but it’s prohibitive for side projects.

For non-commercial projects, Prince offers a free version with the requirement that you allow it to add a logo and link to the corner of your document’s first page, link to their website wherever you have Prince PDFs for download, and link to their website on a sponsors/partners page. This is mostly unintrusive (although a tad confusing at first: I’ve considered trying to style in a little “Made with” above the logo to explain why it’s there), and very nice of Prince to allow. (To get the “Non-commercial” license, just download the software: you don’t need a special license key or anything.)

In fact, I had a question about their licensing (“The books are licensed under a Creative Commons license that doesn’t allow me to add restrictions to them, so is it required for people who receive the PDFs from me to keep the Prince logo on them? If so, I can’t use the noncommercial license.”), emailed them, and got an email back quite quickly from Håkon Wium Lie, Prince’s Director (not to mention CTO at Opera and founding member of the Pirate Party of Norway). He’s definitely on top of things, and was quite happy to help. (The answer is no, other people can do whatever they want to the PDFs. In my case, they’re still subject to the Creative Commons license they always were, but that’s not because of Prince.) Later, I had a question about how to get something to render correctly (a somewhat minor, obscure layout bug), and quickly received a comment from Mike Day, the CEO, noting that they were looking into the issue. When I followed up, the bug hadn’t yet been fixed (it undoubtedly has tricky interactions with their page layout code), but I quickly received an alternative suggestion complete with example code. Definitely a pleasant experience all the way around.

If you’re looking for a cheaper option to start with, you’ll probably run into DocRaptor as well. DocRaptor started out as Prince-as-a-service, providing an API to allow people to generate PDFs using Prince. It now appears to support Excel files, although I haven’t looked in to those features. For many people, the benefits of being able to rely on DocRaptor to scale up as your workloads do (they claim “thousands of documents a second”) and the lower initial costs are probably a great benefit. They also provide well-supported libraries for a number of languages, where Prince usage is largely done by command line (although Prince has a PHP API as well). Overall, DocRaptor almost certainly provides benefits for many people. However, their plans aren’t super cheap either, and they’re targeted at recurring use, not one-shot uses like mine. I generated over 2500 PDFs in my final output (one per book, plus one per chapter), which would probably have cost me $149 in a month, assuming I didn’t want to tweak them later. Still far cheaper than the cheapest Prince license, but pricey for a personal side project like mine.

DocRaptor does have a 7-day free trial, which probably would have allowed me to generate whatever I wanted during that time, but that’s not exactly ideal, either. (Nor do I mind paying something for the service, but over a hundred dollars a shot is high for my purposes.) I emailed the DocRaptor folks about a pay-as-you-go plan (so I wasn’t paying monthly fees when I wasn’t using the service), because I had found references to such a plan elsewhere. I got a very nice response from Matt Gordon, the “lead vocalist” for the group running DocRaptor. Unfortunately, they no longer offer that plan, because they found that disproportionately more of their support costs (and they do provide good support) were going to users who didn’t spend much on the service anyway. We had a nice conversation about the possibility of plans that might support alternative uses such as mine, but it doesn’t sound like there’s anything planned in the immediate future. (I can’t blame them, as they need to make money and do what makes sense for their business to continue existing.) They did make a very nice offer (I won’t disclose the details) that I turned down for unrelated reasons, but they’re definitely nice folks too.

My conclusion is that you pretty much can’t go wrong with Prince or DocRaptor. Both have very nice and responsive folks behind them, and seem to be quite well done.

Tables of Contents and Bookmarks

One of the things relatively unique to printed books is cross-references with page numbers. Most of the book content doesn’t include these. This is primarily because any existing cross references are links to a specific section, and I didn’t think it necessary to include a page number along with the section number. However, the table of contents for the book definitely benefits from page numbers. Pulling a table of contents together in Prince is relatively easy. It could possibly be done automatically with JavaScript, but I chose to create taables of contents in a Ruby preprocessor as I was assembling whole-book files anyway. Prince makes it easy to include page numbers for links to given anchors, so I only needed to pull out the anchor for each section. (Luckily for me, I already had the anchors in a database.)

Secondly, I wanted to make sure that chapters and sections were listed in the PDF list of bookmarks. This list is sometimes useful when navigating a book in a PDF viewer, although some viewers don’t show it. Prince again makes this quite easy, simply requiring a CSS annotation for the items you wish to be bookmark headings. (In fact, by default it uses h1-h6 tags, but I disabled that default because it picked up way too many bookmarks.)

Optimization

In creating the full-book files, I noticed that some books created particularly large files. In general, this appeared to be because they embedded the full source images, rather than resampling them. While an option to resample the images inside Prince would be great, it doesn’t exist at this time. Some of the source images were quite large, and clearly intended to be printed at >= 300 dpi, while most users of the PDFs wouldn’t benefit from such images. My first attempt at reducing file size was to use Ghostscript to resample the images. Ghostscript has some features that work similarly to the now-unavailable Acrobat Distiller, and seemed likely to do the job. Unfortunately, after getting Ghostscript working (Ubuntu 14.04′s version appears to crash on larger documents, but 14.10′s works), I found that it removed page numbering information and bookmarks. The next step was to try to export this metadata using PDFtk before using Ghostscript, and then import it again afterward. Unfortunately, while PDFtk will output page numbering details, it won’t import them into a PDF, and there doesn’t appear to be any easily-available way to do so.

So, I temporarily abandoned the option to resample the images using Ghostscript. (It also may or may not have been worth it in the first place: some Ghostscript-generated files were larger than the Prince originals, so I had to handle both cases.) It may be worth patching Ghostscript in the future to keep the metadata around, but that seems likely to be quite involved. In many cases, you may get some benefit out of using Ghostscript with appropriate options (“gs -q -sDEVICE=pdfwrite -dPDFSETTINGS=/printer -dBATCH -dNOPAUSE -sOutputFile=[outfile] [inputfile]” seems to work well besides the additional metadata), but it was unfortunately unsuitable for my purposes at this time.

Chapter Files

Following up on the “whole book PDFs can be pretty big” issue, and after trying to open some such books and experiencing slow loading times, I decided that it may be appropriate to create one PDF per chapter as well as the whole-book PDF. My first pass at creating these PDFs was to use PDFtk to pull out just the pages from a given chapter. This posed a few problems: first, I had to figure out which pages belonged to which chapter. Luckily, the bookmarks inserted by Prince, combined with PDFtk’s metadata output, gave me the starting page for each chapter (although for a few minor reasons, this link was a bit iffy: the generated bookmark title did not always match the section name I had in my database), and I could assume that a chapter ended just before the next one began. Unfortunately, this ran into the same problem I had before: I would lose the page numbering and bookmarks. (Not to mention the fact that I would need to separately render a new first page to describe the licensing and get the Prince logo back on the first page.) Finally, I decided to simply depend on Prince once again.

I got Prince to log the page number and ID for each chapter heading by using a ::before psuedo-class with a content property of “prince-script(log, counter(page), attr(id))”, and a small “log” function in the JavaScript on each page. This allowed me to use the IDs to match up with my database, and easily identify where each chapter started. Because I already had whole-chapter HTML files, I could then use those HTML files to render the chapter in Prince, and everything would still be in sync, without having to try to render and merge together separate front pages for each chapter. (I still needed to get the page numbers to Prince for rendering purposes, but for this, I simply placed the page number in a CSS block in the HTML file.)

This solution appears to have worked surprisingly well, with the page numbers matching up where expected. Because the files were rendered separately, there is the possibility of some unforeseen issue (I certainly didn’t inspect the thousands of files by hand), but it seems unlikely.

Math

Finally, when reviewing one of the math textbooks in the collection, I noticed that Prince’s MathML rendering wasn’t particularly great. It is definitely better than nothing, but the rendering quality did leave something to be desired. Unfortunately, the most common web-based solution here, MathJax, doesn’t work very well with Prince. (This is a noted todo item on Prince’s release notes, but it’s not available yet.) After stumbling through a number of other options to try, I ended up using PhantomJS together with MathJax to prerender the math to MathJax’s “HTML-CSS” output (the SVG output didn’t look very good and produced a very large PDF file after the required fixes to make Prince display the SVG output). I forced MathJax to use the STIX fonts (which I installed on my computer), and after the math was rendered, I output the document’s HTML form again (after removing the MathJax wrapper divs). This produced files with reasonably good-looking math, the way they were intended to look. The prerendering code hasn’t been published yet because I haven’t taken the time to clean it up, but if someone is interested, I can definitely post it.

Prerendering with MathJax is a step that seems to have very poor asymptotic time complexity. I haven’t formally benchmarked it, but a chapter’s sections took about two minutes to prerender in total, while the whole chapter itself took roughly twelve minutes to prerender. The whole book took roughly four days to prerender. It’s not clear why this occurred, but the prerendering did eventually succeed. It’s also not clear if this is a bug in MathJax, or simply some inefficiency in PhantomJS, so I have yet to report it as a bug to either project (and may never report it – it’s unlikely to come up in common use).

Fin

So, to summarize, getting PDFs of a quality I’m comfortable with took quite a bit of effort. In the end, Prince does most of the work, and I rarely had problems with Prince itself. I think it was worth the effort, at least for a personal learning experience. Hopefully the books will be useful to other people as well. Once again, they’re all available at http://2012books.lardbucket.org. Please feel free to copy or redistribute them as you see fit, pursuant to the terms of the associated Creative Commons by-nc-sa license.

Andy Schmitz

P.S. If you’re interested in any of the print-specific (or Prince-specific) things I did to make the books look decent when printed, it’s all left in the book’s CSS file toward the bottom, under the “prince” @media type. Feel free to reuse any of that styling for any purpose you see fit, in any situation. I do not believe it is covered under the Creative Commons license: you may consider it to be public domain.

3/3/2013

Calcsy – See your calculator on your computer

Filed under: Education, Math, Programming, School, Technology — Andy @ 9:17 pm

Calcsy LogoCalcsy is a tool you can download and use on your computer to show (and save) the screen of your TI-84+ or TI-89 Titanium calculator.

It’s useful for projecting the screen large enough for other people to see, or for taking a screenshot to use in instructions. For example, I’ve used it in teaching how to graph functions on a calculator, and I suspect it will be similarly useful to other people.

I first wrote Calcsy almost two years ago, and have been (very) slowly making it better since then. It’s now to a state where I think it’s reasonable to release. At the moment, it’s only available for Mac OS X, although it should be possible to port to Windows if there’s enough demand. Hopefully it’s pretty self-explanatory, but feel free to let me know if you have any questions.

All you need is a TI-84+ (or TI-84+ Silver Edition) or TI-89 Titanium and a USB cable to plug it in to your computer. The program is free, and you don’t need any special software on your calculator. (You also don’t need one of the special “Presentation Link” adapters – your computer and a normal USB cable works just fine.)

Other details of note: I suspect it won’t work with the very new TI-84+ Color calculators, but I’m happy to try to make it work if someone wants to send me one. Also, the logo was made by David Felice, so thanks are due to him.

Anyway, it’s free, go check it out. Let me know if you have any questions/comments/problems/etc.

Andy Schmitz

1/16/2013

Flat World Knowledge

Filed under: Education, School — Andy @ 10:00 am

Over the past few years, a publishing company called Flat World Knowledge has been publishing a number of textbooks in several subject areas, from history to psychology to math. One of the features they have advertised is their “open” books, meaning in part that their books are available for free online to everyone. Until recently, this was nearly unheard of: students can now legally get their textbooks for free (while paying for extra features if they want them). While I had not heard about their books until recently (likely because they have few math books), this is definitely something I like, at least in the abstract.

Unfortunately, Flat World Knowledge has recently decided that the “open” model will not work for their publishing, because not enough people were buying their books. As much as I would like to argue that such a model should work, I’m sure they have more data than I do, and have undoubtedly done their analysis and decided that such a business model is unsustainable for them at this time. While I hope that they are able to offer their books in an open manner again in the future, they have at this point decided to restrict the way in which their books are available on their website, starting on January 1, 2013. (They have already started implementing this change, as well.)

The good news is that they previously published their books online under a Creative Commons license, a common license which allows redistribution (in particular, the attribution, share-alike, non-commercial license, version 3.0). This means that people have the right to continue to redistribute copies of the books, if they happen to have them.

I am still a bit disappointed: I would have liked Flat World Knowledge to succeed in their open publishing experiment. I would have liked more books to be available, and I would have liked even more companies to follow in their footsteps. Unfortunately, it appears as though that area may remain the realm of private or government financing for the moment.

I would like to remark for the inevitable debates to ensue in unseen boardrooms in the future that the Creative Commons license likely allowed Flat World Knowledge to have so many books. In nearly every foreword I had read, the authors extolled the open license of the book as a primary reason for publishing with FWK. Were it not for this license, it is entirely probable that FWK would not be in such a favorable position. The ability of others to share your books should be regarded as the feature so many authors see it as, rather than a liability.

12/25/2012

Merry Christmas, Again

Filed under: General — Andy @ 12:00 am

Another year has passed, and with just one [other] published post here. I’m slowly starting to have more discretionary time, and to get some projects closer to completion. Barring any major surprises, I should have at least one or two things to release next year. (The problem, of course, with long-running projects is that there are few of them, and if I should decide for whatever reason to not release them, they tend to disappear entirely.)

In the arbitrary milestones department, GraphSketch passed 1.5 million graphs delivered a while back, and I should really pay attention for the 2 million milestone that’ll be coming up sooner or later. I’ve also obtained a full-time job, which surprisingly seems to take less time than school did at times. It seems to be pretty nice, although, as with many things, I haven’t yet taken the time to step back and thoroughly examine how it’s going. There will probably be more comments on the job in the future, but for the moment, allow me to disclaim everything posted here and say that unless an exception is clearly noted in a post, the posts on this blog represent only my own views (if that), and have never been, and will never be intended to represent the opinions of my employer, school, friends, colleagues, or anyone else.

So, this makes for a particularly lackluster sometimes-annual update, but it’s about everything I have to say. Have a Merry Christmas if that’s your thing, and have a great new year when that rolls around. With any luck, I’ll have something new to post in January.

Until then,
Andy Schmitz

9/1/2012

Getting Complicated, Embedded YouTube Videos

Filed under: Hacks, School, Technology — Andy @ 3:29 pm

So, earlier today, Karl Fisch asked for a copy of an Olympics video from NBC’s website to use in his school. A number of the “standard” ways of getting the video didn’t seem to work, so I figured I’d pitch in. By the way, the first thing to try (if whatever addons you might have to download YouTube videos don’t work – although I don’t use any myself, I’m told they didn’t work in this case) is to click the YouTube button.

The YouTube button will usually open the video up into YouTube’s website, where most addons for downloading a video will work better, and there are plenty of other websites happy to help you.

In this case, clicking the button only got to the NBC Olympics home on YouTube. A quick search of the channel showed that the video I was looking for wasn’t on the NBC Olympics channel, and I’d have to find another way to download it.

(more…)

4/4/2011

Portrait: Linux System Management Tool

Filed under: General — Andy @ 3:13 pm

So, over the past year or so, I’ve been working on a project I’m calling Portrait. It’s [going to be] a piece of open-source software system administrators can use to manage Linux computers. Unfortunately, there’s still a fair amount of work to be done on Portrait, because my free time is pretty sparse. I’d also like to launch a hosted version of Portrait, which people can use if they don’t want to deal with setting up and maintaining a copy of the software. To help get both of those things moving, I’ve set up a Kickstarter project, titled simply Portrait: Linux System Management Tool to raise funds to let me work on Portrait over the summer and set up a hosted version that people can use.

Most of my readers won’t personally have any use for a Linux system management tool, but if you happen to know anyone you think might find it useful, I’ll ask you to please pass the Kickstarter project along to them. If you’re interested yourself, please head on over to the Kickstarter project page, where I’ve put much more information on exactly what Portrait will do.

Andy Schmitz

2/27/2011

FABridgeC: A smaller FABridge

Filed under: Open Source, Programming — Andy @ 12:31 pm

I was working with some JavaScript libraries this week, and happened to have a use for Adobe’s Flex Ajax Bridge (also known as FABridge). However, I’m trying to work with Closure, and the most common FABridge.js is a rather large 18 KiB that doesn’t really work very well with Closure’s compiler.

So, I took a few hours to go through and make it work with Closure, and then to make it work compiled outside of Closure in case anyone else wants a smaller version of FABridge. I’m calling the result FABridgeC, and you can read more about it on the project’s GitHub page. For most users, this is a minified FABridge.js (or if you prefer Closure’s terminology, a compiled FABridge.js) in just 5.4 KiB that can be dropped in instead of FABridge.js, and should work in exactly the same manner as the original for almost everyone. (There are a few minor caveats explained on the project page.) If you’re using FABridge at the moment, try dropping it in place of your existing FABridge.js, and let me know how it goes!

Feel free to send me a message via GitHub (I’m aschmitz, the repository’s owner) or leave a comment here with any questions, problems, or other comments.

Andy Schmitz

2/11/2011

Testing Help?

Filed under: General — Andy @ 11:30 am

I’m working on a program that will let users of TI-84+ or TI-89 Titanium calculators see their calculators on the computer screen, and take screenshots. (If you have a TI calculator that has a USB port and  isn’t an Nspire, you’ve probably got one of these.)

Right now, it runs on the Mac only (although that will hopefully change in a while). It works on my Mac, and at least one other, but I’m looking for one or two more test cases. If you have a TI-84+ or TI-89 Titanium, a USB cable that will plug into it and your computer, and one of the following computer setups, please give me an email at andy.schmitz@gmail.com so I can send you a copy and see if it works. The whole process of testing it out should only take a minute or so.

I’m looking for:

  • Mac OS X 10.5 (Leopard) on a PowerPC processor

If you’re not sure what operating system or processor you have, just click on the Apple menu in the upper-right corner of your screen, and click “About This Mac.” Your version of OS X will be displayed (I’m looking for anything that begins with 10.5), and your processor will be shown as well. Please let me know which version and processor you have when you email me, so I know which one you’re testing.

Thanks!

Andy Schmitz

10/11/2010

Announcing scavhunt

Filed under: Open Source, Programming, School, Technology — Andy @ 5:48 pm

Since the end of Dan Meyer’s SLV SCAV, it’s been in the back of my mind to get the source code available to more people, and there was at least some interest from others about running their own copies.

As a result, I took the time to go through the code, remove any references to the school, students, or teachers that I could find, and generally cleaned the code up for release. I changed the name to “scavhunt,” and made a working version that I can release. I’m happy to say that the code is now available as open source (AGPL v3), from GitHub as scavhunt.

Unfortunately, I haven’t yet had the time to properly document things. As it is, if you pull the code down (either use git if you’re comfortable with it, or download a tarball/zipball with the “Downloads” button in the upper-right corner of the GitHub page), it should be a working scavenger hunt, although a bit sparse. There are a number of files you should modify, and some directories that need to be writable by the web server, but those are all documented on the README.md file (and also on the GitHub page for the project). It comes with two example questions as a basis for writing your own, although additional question types exist in the code as well.

So, the code is now available for your use, however you see fit (as long as it complies with the AGPL v3, which is pretty relaxed in terms of usage). If anyone has any questions, feel free to contact me at andy [dot] schmitz [at] gmail [dot] com, or potentially file an issue on GitHub (although I’m new to GitHub, so it may take me a while to figure out how to respond). Unfortunately, at the moment, I don’t have enough time to necessarily improve the code in the ways I would like to, but I can certainly answer questions and respond to pull requests from those who would like to improve it on their own. Contributing your improvements back would be greatly appreciated. And hey, if you use it, I’d appreciate an email or tweet (@aschmitz) to see where it’s in use.

Andy Schmitz

P.S. This is indeed where the scoreboard movement tracking code came from, so that section is rather well-commented. Unfortunately, the rest is less documented, but hopefully understandable.

6/29/2010

Leaderboard with Movement Tracking

Filed under: Hacks, Programming — Andy @ 9:00 pm

In putting together SLV Scav with Dan Meyer, I ended up writing a (relatively) simple script for generating a scoreboard with rankings, as well as the amount the rankings had changed. It looks something like this: (picture from Dan Meyer, names blurred to protect the innocent)

Dylan Faullin asked for more information, so I’m posting most of the relevant code here.

(more…)

Next Page »
My Stuff
Blog Stuff
Categories
Archives