Building the User Guide

Owned by Deepa Chavali
Last updated: Mar 31, 2014 by Joel Parker

This page describes how to build the GMAT User Guide and Training Manual from sources. The User Guide and Training Manual are both configurations of the same set of source documents.

Check out the sources

Check out the documentation sources from the GMAT SourceForge repository. The Subversion URL for the documentation is:

http://svn.code.sf.net/p/gmat/code/trunk/doc/help/

Or, you can check out the entire trunk. The documentation is stored in the doc/help directory.

Internal users will need to check out the internal gmat.git repository. Again, look in the doc/help directory.

Get the prerequisites

You'll need the following prerequisites to build the User Guide:

Java

Download the Java SE JRE or JDK from Oracle, if you don't already have it installed. Both versions 6 and 7 should work. I haven't tested earlier versions. You'll need to add the main javaexecutable to your system path.

MSYS (Windows only)

Download the MinGW installer from SourceForge. The installer will ask if you want to install MSYS; make sure you select this option. You can install the other components if you wish, but MSYS is the only required component.

HTML Help Workshop (optional, Windows only)

Download htmlhelp.exe from Microsoft and install it. You'll need to add the path to hhc.exe to your Pathenvironment variable. This is only needed for CHM format output.

Build the User Guide
  • Add java to your path: You should be able to open a shell (cmd.exe or the MinGW Shell on Windows) and type "java" to run the Java command-line application. If you get "'java' is not recognized as an internal or external command, operable program or batch file.", then follow these steps:
    • Windows 7:
      • Navigate to Control Panel > User Accounts > User Accounts.
      • On the left, click Change my environment variables.
      • Under User variables for user name, add or edit a variable named Path.
      • Set the variable value to the path to java.exe on your system. For me, this path is C:\Program Files\Java\jre7\bin. If there is already an existing value for Path, add the new path to the end, separated from the existing value by a semicolon.
      • Confirm all prompts to exit the Environment Variables window.
      • Restart any command-line shells so they use the new path information.
  • Start MSYS (Windows only): On my system, it is installed to All Programs > MinGW > MinGW Shell. On other platforms, start a normal shell.
  • Navigate to doc/help: In the shell, navigate to the help directory of the GMAT repository you checked out earlier. If you checked out the full trunk, the path is doc/help.
  • Run make: The documentation will be built in all formats: PDF, HTML, CHM. All files are placed directly in the help directory.
Advanced usage

The documentation Makefilesupports the following main targets:

  • all (default): build both the User Guide and the Training Manual in all formats
  • clean: delete all compiled files
  • help: build User Guide in all formats
  • training: build Training Manual in all formats
  • html: build the User Guide in HTML single-page and multi-page formats
  • pdf: build the both User Guide and the Training Manual in PDF format (both letter and A4 sizes)
  • help-chm
  • help-html
  • help-html-single
  • help-html-multiple
  • help-pdf
  • help-pdf-letter
  • help-pdf-a4
  • training-pdf
  • training-pdf-letter
  • training-pdf-a4