21

Latex-to-html converters I've seen in the past have been pretty awful. Editing raw html is no fun and doesn't seem to translate well to the printed page. How do others solve this problem? Links to examples (both pdf and html) would be great.

Added: Another similar question was just asked:

What formatting language should I use for project documentation

Community
  • 1
  • 1
dreeves
  • 26,430
  • 45
  • 154
  • 229

16 Answers16

12

For documenting code, I also recommend Sphinx. ReStructured Text is nice because it is readable and somewhat marked up in plaintext, and can do a nice job converting to html and to pdf. I still like LaTeX for certain things. My wife and I use LaTeX to write our christmas letter, which we mail out via snail mail. The pdf version is pretty fancy, with two columns, and headers and footers. The html version is simpler. I convert with plastex. Examples here: http://fedibblety.com/annualReports

I don't think any binary format is a good choice (Word) for any sort of document that you might like to read 10 years from now. That is one of the nice things about LaTeX.

5

Yes, LaTeX-to-HTML converters used to suck (you've probably tried LaTeX2HTML), but of late they've got better. Tex4ht is highly configurable, and produces nice XHTML+CSS. See also other converters.

You can also use Docbook, if you can bear to write in it. There are converters from DocBook to both HTML and LaTeX (or to PDF directly); an example of the latter is dblatex.

See this post: LaTeX vs Docbook.

ShreevatsaR
  • 38,402
  • 17
  • 102
  • 126
  • tex4ht is no picknick either, and neither is Hevea. Somehow they all suck. Debugging latex2html (0.96) was the worst experience of my entire programming career. An over 1MB perl script tex4ht sometimes screws links totally, and there are some unfriendly beginner gotcha's (e.g. ligatures) – Marco van de Voort Jun 03 '09 at 22:02
  • They all suck, but some suck less than others. :-) (Have you tried plasTeX, BTW? http://plastex.sourceforge.net/ ) – ShreevatsaR Jun 03 '09 at 23:22
  • No, I'll have a look, but seeing it is in Python doesn't make me happy – Marco van de Voort Jul 09 '09 at 20:11
5

After many years of anguish and several false starts, I'm about to revisit this, and I'm going to give Sphinx a try. It can generate HTML or LaTeX from ReStructured Text.

I'm hoping it will be a much "lighter" option than full DocBook, but with many of the advantages.

Brent.Longborough
  • 9,567
  • 10
  • 42
  • 62
  • This is exactly my experience. Our manual was writte in docbook, but it was cumbersome to edit and so we never worked on the manual (and it was pretty ugly anyway). reST and Sphinx are much easier to use (and are much much prettier). – Paul Biggar Jul 29 '09 at 16:54
4

You could take a step back and use something like DocBook and render to PDF via LaTeX and HTML straight from the DocBook files. Alternatively, Adobe Technical Communication Suite (Framemaker) will let you single-source a document to PDF and HTML. See this posting for a rundown on various technical documentation systems.

Community
  • 1
  • 1
ConcernedOfTunbridgeWells
  • 64,444
  • 15
  • 143
  • 197
  • +1 - you can also go straight from docbook to pdf and html (and some other formats like helpfiles) without LaTeX in between using docbook-xsl – frankodwyer Jan 03 '09 at 21:25
  • I bet the typesetting to PDF isn't as good when you bypass LaTeX, though :) Unless there have been big changes I haven't heard about... – Will Robertson Mar 03 '09 at 02:15
2

This is a personal choice but Latex in theory is perfect however in practice it's pain-in-the-arse. I'm using VS.NET HTML editor + raw HTML edit when I need it.

So I think using an WSIWYG HTML editor is best choice. You can always use a simple tool to convert it to PDF, and you can always edit HTML when you need something advanced. Also it's easier to put online when you need.

That's how I'm managing my software documentations and works fine for me.

dr. evil
  • 26,944
  • 33
  • 131
  • 201
1

Since the answer mentioning Asciidoc was somewhat short on examples, here are some of the things your are looking for:

  • A pdf generated with Asciidoc
  • A cheatsheet with a side by side of the Asciidoc markup and the html result.
  • A list of publications done using Asciidoc, including O'Reilly books and the git documentation (to see both ends of the user scale).
DavidGamba
  • 3,503
  • 2
  • 30
  • 46
1

PlasTeX looks like a nice latex-to-html converter, though I haven't tried it myself.

My friend Rob Felty wrote a blog post extolling its virtues: http://blog.robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter/

dreeves
  • 26,430
  • 45
  • 154
  • 229
1

AsciiDoc looks like an interesting possibility.

dreeves
  • 26,430
  • 45
  • 154
  • 229
1

Read about EPUB format. Its e-book format. http://en.wikipedia.org/wiki/EPUB

Kamil
  • 13,363
  • 24
  • 88
  • 183
0

We were facing this problem in an academic project that involved Eclipse software, and we used plastex to convert Latex to HTML and Eclipse Help. Getting it to work was quite difficult, but the end result looks really nice. You can see all three versions here:

http://handbook.event-b.org/

Further, as this is an open project, the code (build scripts) are available. We have a continuous build system (Jenkins) that rebuilds everything when new Latex is checked in. This is particularly nice, as contributors don't need to install the toolchain on their systems. They just check in the new Latex and check on the server whether the HTML was produced correctly. Sources:

http://sourceforge.net/p/rodin-b-sharp/svn/HEAD/tree/trunk/Handbook/org.rodinp.handbook.feature/

Best, Michael

jastram
  • 733
  • 7
  • 19
0

I don't have enough points to comment, but to bolster the plastex answer, here is the updated plastex example link:

http://robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter

David B
  • 7
  • 1
    Note that [link-only answers](http://meta.stackoverflow.com/tags/link-only-answers/info) are discouraged, SO answers should be the end-point of a search for a solution (vs. yet another stopover of references, which tend to get stale over time). Please consider adding a stand-alone synopsis here, keeping the link as a reference. – kleopatra Jan 28 '14 at 12:17
  • @kleopatra This is a really useful information that I hope other people stumble across before they are about to make a comment. You explained why this is a poor answer without tossing insults. Wish I could give you another +1. Sorry it took 3 years to stumble across. – HowYaDoing Jun 26 '17 at 17:22
0

I'm not sure that latex is really the best tool for this. The trouble you're having with the usual latex to html converter is indicative of the problem: html is simple not as expressive as latex.

If you insist on latex to html, take care to use a limited subset that can convert reasonably.

dmckee --- ex-moderator kitten
  • 98,632
  • 24
  • 142
  • 234
0

I've used TeXinfo in the past and it does a good job. Here's an example: http://yootles.com/api. I'd prefer to stick with LaTeX though instead of use another language.

dreeves
  • 26,430
  • 45
  • 154
  • 229
0

If everything else fails you could grab an LaTeX to XML converter and write a simple XSLT stylesheet to convert it to HTML, or create a CSS style sheet and attach it to the XML file directly.

Jasper Bekkers
  • 6,711
  • 32
  • 46
0

We've been using WebWorks ePublisher (www.webworks.com) which offers both multiple single-source formats (we are using Word) and the ability to output to many output formats (we output to Adobe PDF and Online Help (.CHM).

-16

LaTeX? Seriously? I wasn't aware anyone outside academia still used it. I'd go with HTML, which you can save as PDF from the web browser. If you really must have some advanced typographic stuff, go with Word instead - it has a way to save to HTML (probably not as clean as one would like), and you can save as PDF with a free plug-in (downloadable separately).

Oh, and I wouldn't bother using things like InDesign - they are overkill. Also, don't bother paying for Acrobat Professional - there is a zillion free solutions available.

Dmitri Nesteruk
  • 23,067
  • 22
  • 97
  • 166
  • 1
    Dare I presume that the question was downvoted by LaTeX fans? – Dmitri Nesteruk Jan 03 '09 at 22:02
  • 1
    It wasn't me, but suggesting that Word is an adequate replacement for latex looks very hard to defend to me... I generally suggest Word with style sheets to my less technically inclined friends, but they are not the same thing. – dmckee --- ex-moderator kitten Jan 03 '09 at 22:09
  • Wasn't me either, but the question says "(ideally in LaTeX)" and "html is no fun and doesn't seem to translate well to the printed page", and this answer recommends the exact opposite of what is wanted. Plus yeah, I guess "some advanced typographic stuff, go with Word" must have sounded crazy :-) – ShreevatsaR Jan 03 '09 at 22:30
  • Many hackers *are* in academia, and in fact there are good reasons academics prefer it. Eg, if you use much math in your documentation, nothing else really compares, in my opinion. I think it's great to have contrary opinions though. (The downvotes might just for the incredulous tone.) – dreeves Mar 03 '09 at 00:15
  • Well, if you look at what format science journals and book publishers use nowadays, it's Word, not LaTeX. – Dmitri Nesteruk Mar 04 '09 at 06:26
  • Downvoted because of the implication that Word can typeset documents. – Arafangion Jun 05 '09 at 06:00
  • "what format science journals and book publishers use nowadays, it's Word, not LaTeX. " false ... How can you use Word for mathematicals Symbols ? – Nadir SOUALEM Oct 28 '09 at 14:20
  • "Well, if you look at what format science journals and book publishers use nowadays, it's Word, not LaTeX. " No in my field. It's a 70% LateX - 30% Word in Signal Processing. – fulmicoton Jan 18 '10 at 12:26
  • There is a reason for things like this: http://www.apeth.net/matt/iosbooktoolchain.html ... and simply giving LaTeX the finger. (I have written literally tons of LaTeX myself, more than the average academic person.) – sjas Feb 24 '13 at 17:39