6

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?
thr
  • 177
  • 5

8 Answers8

18

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

Sorantis
  • 2,720
  • 17
  • 24
  • 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 06:48
  • 1
    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 08: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 have worked both with LaTex and Word extensively over several years, and from my experience I can tell you it is not that black-and-white. LaTex is far better when texts contains lots of mathematical formulas. Word works IMHO better when you have lots of tables, pictures, drawings to integrate, or when you need visualize changes from different authors directly in one document. And for both programs there exist add-ons or additional tools to mitigate the drawbacks. – Doc Brown Mar 09 '19 at 08:02
4

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.

Anto
  • 11,157
  • 13
  • 67
  • 103
  • 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 06: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. –  Feb 15 '11 at 08:44
  • @Thorbjørn, the earlier paper books were written directly in troff. Docbook makes a whole of sense though, especially if one needs a diversity of backends. – Gilead Feb 15 '11 at 17:05
  • @Gilead, the troff input these days are generated from DocBook. I believe though that the exact templates are kept internally to O'Reilly. –  Feb 15 '11 at 18:09
3

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.

Keval
  • 31
  • 1
2

Asciidoc (especially the Asciidoctor implementation) is a very attractive option if you would like the robustness of DocBook, while wanting to avoid XML and other markup languages.

Tim McNamara
  • 121
  • 3
2

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.

Zachary K
  • 10,433
  • 2
  • 37
  • 55
  • DocBook has many backends making it suitable for targeting many devices, where LaTeX is more paper oriented. –  Feb 13 '11 at 14:36
2

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.

Sharpie
  • 912
  • 6
  • 9
1

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.

kevin cline
  • 33,608
  • 3
  • 71
  • 142
0

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

AlexFielder
  • 29
  • 5