# Best tool for writing a Programming Book? [closed]

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!

-
Incredeble. The question says "Latex is out of question" and 4/5 answers list it ... have people lost their reading abilities ? –  ldigas Nov 27 '09 at 16:37
Idigas: The usual thing: Read the title and the first line and start typing your answer :-) –  Joey Nov 27 '09 at 16:45
The only reason TeX was conceived was to write a programming book. "The Art of Computer Programming" has more than 1000 pages. If (La)TeX is not suitable to write a programming book I wonder what else is:-) –  Ludwig Weinzierl Nov 27 '09 at 20:51
@Idigas: I think it is more because the question is like: Best Tool for hammering a nail into the wall - my screwdriver breaks 10 times a day and a hammer is out of question. –  Ludwig Weinzierl Nov 27 '09 at 21:00
I'm going to make a flat-out statement here. Anybody who considers LaTeX incredibly hard to use is not competent to write a book about programming. –  David Thornley Nov 28 '09 at 16:32

## migration rejected from stackoverflow.comFeb 12 at 3:05

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

## closed as off-topic by Olli, Tog, random♦Feb 12 at 3:05

This question appears to be off-topic. The users who voted to close gave this specific reason:

• "Questions seeking product, service, or learning material recommendations are off-topic because they become outdated quickly and attract opinion-based answers. Instead, describe your situation and the specific problem you're trying to solve. Share your research. Here are a few suggestions on how to properly ask this type of question." – Olli, Tog, random
If this question can be reworded to fit the rules in the help center, please edit the question.

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).

-
Excellent support ... if you happen to use the right one of the approximately two dozen table packages from the start. And listings is broken for some niceties such as floating-point literals: 1.23e-5 gets highlighted wrongly and as far as I have seen this can't be fixed in the document. –  Joey Nov 27 '09 at 16:01

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.

-
I honestly didn't find latex that hard to learn. –  Jason Baker Nov 27 '09 at 16:48
It's hard to learn how to use all of it. It's pretty easy to learn to write a book with, if you just go with standard styles. –  David Thornley Nov 28 '09 at 16:32
It's incredibly easy to learn if you have someone who knows the basics sit down with you for 10 minutes. –  Wilduck Nov 29 '09 at 22:27

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.

-

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.

-

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:

And a full text example here:

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

-

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.

-

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.

-

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.

-

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.

-
That's a bit of an overstatement. Latex is used, but it isn't an only tool in the market. –  ldigas Nov 27 '09 at 16:45
I didn't say it's the only. I said its THE one.. –  Don Salva Nov 27 '09 at 17:30
Your commend only shows that you did understand what I was trying to say. –  ldigas Nov 27 '09 at 22:41

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

-

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

-
This updated comment would be easier to find if you edited your question to include it, or clicked the "add comment" on your own post. It's okay to answer your own question, but I don't think that's what you're doing here. –  Miss Cellanie Nov 27 '09 at 19:12
You'll need to associate your accounts to re-take ownership of this question. If that doesn't work, ask in Meta for someone on the team to look into it and they'll fix it. –  AnonJr Nov 29 '09 at 15:53

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.

-