HTML or PDF?

[kpreid]

I'm planning to write a short introduction/quick reference to LaTeX (with a particular emphasis on “what corresponds to this HTML element?”, and actually explaining the core syntax rather than just examples of particular cases), as another page on my web site. Should I write it as HTML or LaTeX (rendered to PDF)? Using LaTeX means I can embed rendered examples without each one being an image (which I don't really want to deal with), but the result being a PDF rather than HTML means that the document would have a fixed line width, and possibly require download/be unviewable depending on the particular browser/platform/installed plugins. (It could still have hyperlinks.)

(In case you're wondering, there are several LaTeX-to-HTML conversion tools, and the last time I looked they all either didn't run, accepted a far-too-small subset of LaTeX, or produced too-low-quality or obviously broken output. I used one of them for this post and had to hand-edit black bars out of every image and trim the margins, and the antialiasing is poor.)

What would you prefer?

Comments

[atheorist.livejournal.com]

Why not write in a third format, generate HTML and (via LaTeX) PDFs from that? There are probably lots of examples (I vaguely recall a POD format from the Perl ecosystem).

Googling quickly I found this example of the genre: http://www.fourmilab.ch/etexts/etset/

[antifuchs.livejournal.com]

While I appreciate the neatness of writing your tutorial in the markup language you're tutorial-ing for, the accessibility features of HTML (can be converted to ebook reader formats easily, for one) have made me detest PDF for longer reading. Unless you intend your readers to print out your documents, I would say go for HTML.

If you are on a mac, you can use LaTeXiT to quickly produce pictures from your examples, by the way (http://www.apple.com/downloads/macosx/math_science/latexit.html). Of course, if you wanted something makefile-compatible, I suppose you can use a pdf-to-image converter to generate includable pictures.

Go for PDF

[michael snoyman (from livejournal.com)]

Sounds like a PDF will be the easiest for you to make and be the easiest to read. I'd personally have no problem downloading/reading it. Also, I look forward to seeing this, I haven't yet gotten around to properly learning LaTeX.

[(Anonymous)]

Is this too long?

http://tobi.oetiker.ch/lshort/lshort.pdf

I've found it extremely useful despite its not-so-shortness.

[(Anonymous)]

+1 for any kind of markup (btw, pandoc could really help here). I bet people will keep your tutorial open while making their way through it. And it's definitely way more convenient to have it open in a browser tab.

markdown + pandoc

[(Anonymous)]

Use pandoc and markdown+LaTeX, it will do what you need.
Expose the mardown as a versioned document, in a repo on github or bitbucket so that readers can track changes. Provide all the scripts and LaTeX classes / CSS needed for the export along with the markdown document.

-- Paul

Re: markdown + pandoc

[(Anonymous)]

I second the use of markdown and latex that pandoc supports. It's a very powerful combination that will let you produce various formats. If you haven't tried it yet it's high time.

[winterkoninkje.livejournal.com]

While I'm not the target audience, I'd greatly prefer PDF. As you say, the HTML would require generating all renderings as pictures, which is a hassle to maintain and (often) to use. PDF is pretty well supported across all platforms these days; especially the well-behaved PDF that pdflatex etc generates.