Best tool for writing a Programming Book?

Question

Well, this is not directly programming related! But a friend of mine wants to write a book about programming. Now he asked me if I knew a good software for this, because Word crashes 10 times a day on his machine, and OpenOffice is just very chunky and slow. Also none of them seem to have any useful support for including Code Listings (examples) with useful syntax highlighting or at least some sort of support for inserting code (i.e. indicating line breaks with arrows that turn around, line numbers, etc). Latex is out of question since it's incredible hard to use and has no really useful feature for including tables. It's a mess.

Maybe some IT authors are here who can give some hints what tools they use. That would be great!

Answer 1

I think it is related to programming! The tools that come to mind are LaTeX and DocBook. If your friend finds LaTeX hard to use for writing a book about programming then s/he will need to stick at it until it becomes easier.

LaTeX provides excellent support for tables and code. It will certainly be more productive than trying to use OpenOffice or Word (I say that even though I work with Word in my own area).

Answer 2

Actually, LaTeX is not hard to use. It is hard to learn however. Having learned it, LaTeX (together with Emacs) is a joy to use. It did take a while to learn though.

Hard to learn. Hard to use. Different things.

Anyway, DocBook is probably what you want.

Answer 3

I think you've been misinformed about TeX, and suggest your friend give it another look. (I'm only suggesting this because your reasons for disallowing it sound completely untrue.)

First, TeX isn't harder to use than HTML, and if you're writing source code for a computer book, then you can certainly handle HTML. If you can say:

<i>this</i>

then you can say:

{\it this}

Both are even easier to use than a typical 1980's word processor (alt-F-what makes it italic?), and non-programmers I worked with had little trouble learning them.

Second, I have no idea what you mean by "has no really useful feature for including tables". TeX makes the best printed tables I've ever seen. Pull your copy of Knuth off the shelf and thumb through it, and you'll see quite a few tables.

As an example of why you want TeX, you mention that the tools you've looked at lack a feature for including code listings with line numbers. 10 seconds in google turned up the Listings package which does exactly that:

\usepackage{listings}
...
\lstset{numbers=left, language=Java}
\lstinputlisting{filename.java}

If you want to write a programming book and can't bother learning a little TeX, then write in plain text and hire somebody to do the TeX part for you, because it really is the best option by far.

Answer 4

Well, this is not directly programming related! But a friend of mine wants to write a book about programming. Now he asked me if I knew a good software for this, because Word crashes 10 times a day on his machine, and OpenOffice is just very chunky and slow.

I'm not gonna say Word is the best option, far from it, but he should reinstall his machine. It really isn't that bad, and normally it doesn't crash (up to, I don't know, 500 pg documents). I can't remember the last time it died on me.

Also none of them seem to have any useful support for including Code Listings (examples) with useful syntax highlighting or at least some sort of support for inserting code (i.e. indicating line breaks with arrows that turn around, line numbers, etc).

I don't think you'll find a word processor with syntax highlighting capabilities. What you can do, is use an editor with syn. highlighting and export his printout to a compromise format (pdf ?), then try to import it into a word processor.

Latex is out of question since it's incredible hard to use and has no really useful feature for including tables. It's a mess.

Oh, it's not so bad, but I still wouldn't recommend it, expecially if you're not familiar enough with it. When it comes to larger documents with lots of page formatting, tables and pictures of various kinds, it can get ... uhmm, messy.

Maybe some IT authors are here who can give some hints what tools they use. That would be great!

Anyways, apart from Word, and OpenOffice, he can use GoogleDocs (really nice sometimes).

But maybe the better variant would be if he used some kind of HTML editor, and tried to split the chapters into pages. Several programming editors have options to export their ... into html.

Answer 5

Adobe Framemaker

It's expensive, but not bad if you're using it for paid work. I've used it for three books and would be happy to use it again.

If you want to see the end results, see the "Look Inside" on these books:

http://www.amazon.com/Effective-Tcl-Tk-Programming-Programs/dp/0201634740 http://www.amazon.com/TCL-TK-Tools-Mark-Harrison/dp/1565922182

And a full text example here:

http://markharrison.net/usenet/usenet.pdf

Answer 6

All the Big Names™ in Open Source software with their own Web/PDF/Latex manuals do their stuff in DocBook.

DocBook is an XML standard for writing documentation, and there are toolchains available for processing it and generating various kinds of output from it.

I had some trouble finding a decent tool to input the text with; I used Lyx for a while, then started doing XML by hand. You may find better solutions, though. It wasn't sufficiently important for me at the time to pursue with great vigor.

Answer 7

I would simply suggest Microsoft Word and get your friend to find out what is wrong with it - it sounds like he could have some sort of bad addon. I would advise uninstalling all of them or running Word in safe mode... Hold Ctrl after clicking the icon.

Out of the box, Microsoft Word is extremely stable, and I suggest that you open another question if the above doesn't help so he can fix his problems.

Answer 8

You could use MediaWiki - Gina Trapani and Adam Pash used it to make their complete Wave Guide. There's a related Lifehacker article on how they did it.

Answer 9

I'm sorry to disapoint you, but LaTeX is THE tool when it comes to writing digital e-books. There's simply no other way.

It's not hard to use either. You just need to familiarize yourself with a few commands you use most of the time, and presto, you're done.

Especially for code listing and code syntax highlighting LaTeX is the tool to go. If you really do plan to say NO to LaTeX then you're in for a big dissapointment the long road down.

There are a few alternatives (names don't come to mind right now, sorry :( ), but in the long run they are, regarding efficiency, worse than LaTeX.

Answer 10

Perhaps you can start the document off in LyX and then transition to raw LaTeX when you're ready.

Answer 11

How about Adobe FrameMaker? It's insanely expensive. And they say it's for technical docs. Is that really a good tool?

Answer 12

If LaTeX is out of the question, you will probably find DocBook is worse, if you want any control over what the output looks like. (Does the DocBook-to-print tool chain still go through TeX?)

The only real alternative to Word is Framemaker, which has a bit of a learning curve itself. On the other hand, unlike Word, it is capable of producing acceptable output.

Answer 13

Alternately, you could do like these fine folks and make your own DTD for publishing a book. They explain it in the Sept. and Oct. issues if I remember right.

Answer 14

I've been working on a small project that enables using wiki-syntax in a number of situations, also non-wiki-related or even non-web-related: WikiEngine. Compared to HTML and other layout-encoding-syntaxes, wiki-syntax has a great way of add layout to text, and keep the text readable.

I've been using mostly the 'wikiparsexml' that mimics PmWiki (into HTML), but with a bit of work you can assemble 'wikiparsexml' to mimic any wiki-syntax or invent a layout-syntax of your own, exporting HTML or any other layout code. The WikiEdit application is a handy tool to preview the conversion from wiki-syntax into HTML.