Introduction
In early 2024, the last steps in the integration of the McCarl GAMS User Guide with the GAMS documentation will be completed. The McCarl Guide will no longer be pointed to or available from the GAMS docs, although it is available on Bruce McCarl’s web site or the GAMSWORLD forum (see links below). While these last steps may go unnoticed by many GAMS users, the integration process has resulted in a much better documentation that all have benefited from. Reaching this milestone provides us a good opportunity to look back at the history of the McCarl Guide. In this article, we consider the original purpose of the Guide, the positive impact it has had during the many years of its use, and the reasons for its retirement.
Origins of the McCarl Guide
The GAMS User’s Guide was originally published in book form in 1988. As such, it was organized linearly (chapters, sections, etc.), had a fairly consistent style (a User’s Guide is neither a reference manual nor a tutorial, but perhaps a compromise between the two), and was formatted to fit on a printed page. The primary search mechanism was the index, which was based on the page numbers used in the book. It even came with a copy of GAMS on a 5.25 inch floppy disk! An updated version of the User’s Guide was published in 1992 in order to keep up with additions, extensions, and changes to GAMS, but updating a published User’s Guide to keep pace with a growing and evolving software product was a losing battle. GAMS eventually shifted to PDF documentation that could be continuously updated, printed and shipped to users, and made available in electronic form via GAMS release and the web.
During this time, Bruce had been developing teaching material for use in his GAMS courses, so he was well-positioned to notice that the GAMS User’s Guide was not keeping pace with all the new features in GAMS and that important new capabilities were not included. Additionally, the PDF format it used didn’t make use of active links and otherwise take advantage of publication via the Web, and Bruce had a more tutorial style in mind. So with encouragement and support from GAMS, Bruce developed the McCarl GAMS User Guide, aka the McCarl Guide: a more complete and up-to-date user’s guide, more tutorial in flavor, that was linked, cross-referenced, searchable, and indexed. Originally developed in Word and made available in 2002, it was redone in the more convenient and powerful CHM format and released in 2006 as the Expanded GAMS Guide (McCarl). The guide was expanded and revised as new GAMS versions were released. With its improved content, organization, and navigability, Bruce’s new guide was a boon to all GAMS users, not just those taking his courses. We owe a debt of gratitude to Bruce for this and many other contributions.
Fig 1. Covers of GAMS User’s Guide and Solver Manual
Integration / Unification
While the User’s Guide to the GAMS language was and is the flagship of the line, many other documents existed or were introduced (e.g. solver or tool manuals, API docs). GAMS continued to update and produce these docs and also the original User’s Guide and make them (along with the McCarl Guide) available on the Web. The existence of two Guides was a source of confusion to some users and imposed the burden of keeping not one but two Guides up to date. The difficulties only increased as time went on and differences, inconsistencies and contradictions between the two became more frequent. Finally, GAMS made the decision to move all its documentation to a doxygen-based process that has a unified look and feel, makes extensive use of links, is searchable, is based on text files (and hence git-friendly and uniformly easy to edit), and is targeted solely for Web deployment. As part of this process, the two User’s Guides were merged into one that (we hope) maintains the best qualities of each. Much of the content of the current guide was drawn from the McCarl guide, along with some of the tutorial flavor, although the combined guide is generally more concise and less tutorial than the McCarl guide.
Final Thanks
The PDF for the McCarl Guide is no longer on the GAMS web site, but the content is not really gone. All of us who use the current User’s Guide benefit from Bruce’s work and the McCarl Guide he produced, and those who knew it well will see evidence of it in the content, organization, and style of the current documentation.
Thank you, Bruce!
Links:
- A history of the documentation effort
- Bruce McCarl’s Documentation Collection and Tools (including the McCarl Guide in PDF, CHM, and source form, along with other resources)
- Bruce’s web site
- GAMS content on Bruce’s web site