How to use TeX for user manuals.

Question

We are in the final preparations for releasing a product and we have to touch up the user guide.

The current one we have is an amalgamation of some MS Word and some OpenOffice.org documents. While it's sufficient, we going to massively re-do it after the release in readiness for the following release.

We haven't really been happy with either of these solutions (Word or OpenOffice) since they both impose their own limitations. Management have tasked us to identify the use of a markup language and part of that is looking into TeX.

Basically, we want plain text documents (since we can write shell scripts to change them a lot easier than VBA or OpenOffice macros) which will be turned into PDFs. We need support for TOC, index and glossary as well as being able to embed images and have global styles, easily changeable.

For example, say we have a list of commands:

+----------------------------+
| cmd1 <param1> <parameter2> |
+----------------------------+
    This command blah blah ...

    Param1     : hsdfhdfjhs
    Parameter2 : fsfsfsfsd

    Full description ...

and the top section is in a nice background-filled-in box.

We may have 100 different pages of that format and we'd like to be able to change the format of all of them with a simple change up the front of the file somewhere. Ideally, we like to be able to just mark some text with something like {command-header} or {command-params} and have a set of styles automatically applied.

Question 1: What is the software we need to install to make this task as easy as possible? Obviously TeX itself but should we be using something else as well?

Question 2: How do you do TOC, glossary and index entries?

Question 3: Can we somehow integrate the build of this PDF into the Visual Studio 2008 build process?

Question 4: How easy is it to generate PDFs from the TeX source file (and how do we do it)?

Answer 1

A1 -- you're probably better off starting with an installation of LaTeX (which includes TeX) than just plain ol' TeX. On MS Windows I've used MikTeX happily for several years, other installations are available.

A2 -- very easily once you have a document set up. A table of contents is included with the macro \tableofcontents, indices and glossaries need you to tag the entries, then their production is nearly as straightforward.

A3 -- don't know. If you get a good answer I'll be interested in experimenting with this. I run LaTeX from Emacs, but I work on Linux and Windows.

A4 -- very easy, the MikTeX installation includes a program (possibly called pdflatex) to emit PDF rather than the standard DVI.

Hope that gets you started. Head over to CTAN for all your (La)TeX needs, google around for The Not So Short Introduction to LaTeX.

Answer 2

1) You don't strictly speaking need any software other than a (La)TeX distribution, but a dedicated TeX editor might help, especially if you're not too used to working with this. In that case, you'll probably also find the LaTeX Wikibook helpful.

I would suggest you use LaTeX instead of plain TeX, because there's little point in not doing so. For a good distribution, I personally use the cross-platform TeX Live with a complete install, but there are others, like MiKTeX, which will download packages as you need them.

2) The way you would want to do this is by defining one or more commands which takes the actual text as a bunch of arguments and knows how to convert them to the desired layout. If you want to change the format of these, then you just change the command definition.

As part of the command, you can have this do the other things: the header for each command might just be a \section or \subsection header which you apply some style to. Index entries use the \index command, so you can work that in as well.

For a glossary, I think you need to maintain that part separately from the rest, but it might be possible to work that in as well - it wouldn't surpise me if there was a package for that as well.

3) Yes, this shouldn't be a problem - simply make this a post-build event in the project settings.

4) Quite easy. Executing this set of commands should do everything (assuming file.tex is the "main" TeX file):

pdflatex file
bibtex file
makeindex file
pdflatex file
pdflatex file

If you don't have a bibliography, leave out the bibtex line. You need to run pdflatex a couple of times to get references right.

By default, the build stops in case of an error to let you determine what should happen next. You can change this behavior by using the -interaction parameter with pdflatex - see pdflatex -help for the possible options.