Creating LaTeX and PDF output

You create a LaTeX file from the help set by simply selecting the appropriate menu entry:

Menu entry for exporting to LaTeX

HelpSetMaker creates a file doc.tex in the latex/ directory below the project root. If the project contains any pictures, they are also copied in a latex/pics/ directory. doc.tex is generated in a way that it correctly references those pictures. As with all exports, the latex/ directory is completely self-contained.

After having created the LaTeX source text, it has to be run through the TeX interpreter. This can be done from directly within the HelpSetMaker by selecting the “Create target → Run LaTeX processor” menu item.

Menu item to run the LaTeX processor

HelpSetMaker opens an additional dialog and starts executing pdfLaTeX in the background.

LaTeX execution dialog

The output of the LaTeX program is written into the dialog. Additionally, HelpSetMaker parses and gives indication how far the document creation has come.

By its internal structure and mode of operation, LaTeX processing can be a multipass process: The document contains references to itself and these can change or even only be revealed while the document is created. HelpSetMaker scans the LaTeX protocol output for indications whether a further pass is needed and restarts the LaTeX processor automatically if this is needed. Depending on the picture placement, the amount of changes since the last LaTeX processing and the general complexity of the document, up to three passes can be needed until the document is finished.

Success message after document creation.

Manual PDF creation

If for any reason the automatic invocation of the LaTeX processor does not work or is not wanted, manual handling of the created TeX files is also possible. Do something like this on the command line:

/home/dh/helpsets/hsm/latex > pdflatex doc

The TeX interpreter will run through the created file. If everything works as expected, it will not print out any error messages, but run through the document and produce a file “doc.pdf” in the very same directory.

If TeX finds any errors, it will interrupt and show an error message. If you are a TeX expert, feel free to dig into this. Otherwise, try hitting the “Return” key to continue. If more errors are presented, continue hitting “Return” or press

• “Q” to enter the “Quiet” or “Batch” mode, in which TeX will continue producing output. As there have been errors, the result can be more or less discouraging, however. Or press

• “X” to stop evaluation. the PDF file is created nevertheless, but it will most certainly not contain the complete document.

If everything ran smoothly, issue the pdflatex doc command once again. TeX gathers some information during the first run through a document which it uses in the second run. An example is the table of contents which will be inserted only after the second pass. If it needs more than one page, you will even have to run the TeX interpreter a third time, as the page numbers in the references will have changed.

Note that TeX tells you at the end of each run whether it wants to run again or not.