Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm looking for a toolkit in the form of one or a couple of applications that can be used to write long technical texts (such as an introduction to a programming language).

  • What applications (or combination of) are suitable for this?
  • How should said applications be setup (for example how would one setup MS Word to best fit writing a technical text)?
  • How do you deal with source code, syntax coloring and formatting?
  • In the case of it being several applications, how do you interact between them?
share|improve this question
    
What does "best" mean to you in this context? –  user1249 Feb 15 '11 at 8:43

7 Answers 7

up vote 15 down vote accepted

LaTeX is what you need.

MiKTeX - for Windows.

Text Editors
Kile - for Linux.
TeXnicCenter for Windows.

Documentation
Free LaTeX documentation.

Complexity comparison

enter image description here

share|improve this answer
    
Thank you, MiKTeX seems awesome! –  thr Feb 13 '11 at 14:01
    
The list of things that are added in each step is slightly misleading, though. All of those are trivial in Word. And things you have most headaches with are plenty of figures, for example and that holds for both Word and LaTeX. –  Joey Feb 13 '11 at 22:16
1  
@Joey, on the contrary. LaTeX handles the "plenty of figures" case very well (esp. wrt. cross-referencing, captions etc.), whereas it is a real challenge with Word (having to deal with page breaks, wrapping, figures not being where you want them, etc.). –  Gilead Feb 14 '11 at 6:48
    
Gilead: Had to resort to workarounds and headaches in both so far in such cases. LaTeX's automagic algorithms may be good but they still fail occasionally. And then it's quite hard to figure out how to do things manually. –  Joey Feb 14 '11 at 8:05
1  
@Joey: The breaking point for me is that I can never remember the exact incantation of mouse clicks and menu options in Word that finally got the page numbers/table of contents/whatever to behave. With LaTeX the exact steps are recorded in the last report I wrote, in black in white. In general, you only go through the pain of learning how to do something in LaTeX once. With word you go through it with each new version and, if you are forgetful, with each new document. –  Sharpie Feb 15 '11 at 10:14

I like LaTeX myself. It isn't fancy WYSIWYG stuff, but for me that is more or less an advantage as it lets you focus on the content instead of the design. It is also a lot easier to create consistent documents using LatTeX than by using some kind of traditional word processor.

share|improve this answer
    
LaTeX used to be the standard that technical publishers would accept and I'm sure that some still do. –  Arcege Feb 13 '11 at 15:06
    
@Arcege: If I remember correctly, most O'Reilly and Apress books mention somewhere in the beginning that they are generated using LaTeX –  Anto Feb 13 '11 at 16:00
    
Mostly I just remember trying to compile it, the pseudo pascal and the core dump that was then spliced with an executable header (before ELF before a defacto standard) to generate the Tex executable. Most of my own docs were in troff. I haven't touched TeX in more than twenty years. –  Arcege Feb 13 '11 at 23:29
    
@Anto, not quite. Most O'Reilly books in the past were formatted with troff. LaTeX is however the gold standard in publications where there's a lot of math--and that includes theoretical computer science. –  Gilead Feb 14 '11 at 6:50
    
@Gilead, I believe O'Reilly books are submitted in DocBook. They then have various backends depending on the output media - paper books are to my knowledge set with troff. –  user1249 Feb 15 '11 at 8:44

LaTex is most suitable for writing technical documents. It is a high-quality typesetting system; it includes features specifically designed for the production of technical and scientific documentation.

You will find everything related setting up LaTeX and using it on the homepage. Also, you will easily find a lot of tutorials on using LaTeX online.

share|improve this answer

LaTeX can be good, you might also want to check out DocBook. I am working on a book right now and its being done in DocBook and I quite like it for technical documentation.

share|improve this answer
    
DocBook has many backends making it suitable for targeting many devices, where LaTeX is more paper oriented. –  user1249 Feb 13 '11 at 14:36

LaTeX is definitely a great tool and worth looking into for anyone writing a book or manual.

That being said, I would like to throw a hook out for Sphinx.

Originally designed to create the documentation for Python, Sphinx is language agnostic and pretty flexible. It provides great support for source by using Pygments. The matplotlib team has put together a nice Sphinx example that showcases some of what it can do.

Sphinx uses restructured text as input which is not quite as syntax-heavy as LaTeX as it is similar to the Markdown used to style posts on this site. Sphinx can also generate a wide range of output. Some examples are: HTML Webpages, epub books or even PDF files generated using LaTeX.

On the other hand, by using just LaTeX you have access to a large ecosystem of extension packages that can pull off some pretty impressive feats. The price is that PDF is pretty much your only choice of an output format.

share|improve this answer

The most productive combination is a powerful text editor, like Emacs, and an inline markup language like LaTeX. Learning to use Emacs well takes a little time, but nothing else is as efficient over the long run.

share|improve this answer

I realise this topic has been marked as answered but figured I'd add my $0.02:

I haven't tried the LaTex tools, and personally find Word is a PITA - at least, if someone who thinks they know formatting has had a hand in creating the document.

I'd recommend you give TiddlyWiki a try:

http://www.tiddlywiki.com/

It's super-easy to get started and the markup is really simple to learn thanks to this page:

http://tiddlywiki.org/wiki/TiddlyWiki_Markup

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.