[ADMB Users] ADMB reference and help system?

[Arni Magnusson]

The current development plan is to continue improving the User Guides and 
to add Doxygen comments for the most common user classes and functions.

Once the Doxygen comments have reached that point, I think we could look 
into producing a human-readable booklet with succinct documentation for 
the basic classes and functions. In other words, we could compile with 
Doxygen and then copy and paste the essential parts of the Doxygen output 
into a nicely formatted PDF document. Although not as exhaustive as the 
Doxygen website, we could call the document the ADMB Reference Manual.

But here's the really cool thing. If we use Texinfo for the layout of the 
reference manual, it can not only compile a PDF document (see the GCC 
manual, R manuals, etc.), but an entire Info help system with separate 
help pages. The Info help system is accessible both from a Linux/Mac shell 
and also from within ADMB-IDE. To get acquainted with the Info help 
system, try this:

In Linux/Mac, open a terminal and type:
   info woman <return>

In Windows/Linux/Mac, open Emacs/ADMB-IDE and type:
   Alt-x info <return>
   m woman <return>

The help pages have hyperlinks to navigate between related help pages, and 
are colorful and clickable in Emacs/ADMB-IDE. Type ? to learn more about 
the Info viewer.

---

What this means is that the ADMB-IDE user would have a help system within 
the programming environment, similar to R.

In R, you type
   help(data.frame)
   ?data.frame

to open help pages.

In ADMB-IDE, you would type
   [f1] init_matrix
   [f1] mfexp
   [f1] mceval_phase

where the [f1] key is configured to access the ADMB help system.

People using other editors can access the help pages via the shell command 
"info", which even comes with a --vi-keys option.

---

I think this would be worth trying. Texinfo can also produce a bundle of 
linked HTML help pages, not unlike those seen in R.

The thought of an integrated ADMB help system should be added motivation 
to contribute Doxygen comments: simple user-level help for the essiential 
classes and functions. Yep, we have to create the help before the system. 
See http://admb-project.org/developers/contribute-documentation for 
details.

Arni