[Developers] ADMB Manual Class

[Arni Magnusson]

Hi John,

The admbmanual.cls looks promising, but I'm experiencing some hiccups:

1. On my Windows machine, the makefile generates a broken admb-sample.ind, 
where

   \\begin{theindex}\n\\thispagestyle{fancy}\n

should be

   \begin{theindex}
   \thispagestyle{fancy}

Everything looked fine after I fixed this manually. I have a bunch of 
LaTeX packages installed, but I needed to install four additional packages 
for admbmanual.cls:

   anyfontsize
   chappg
   smallcap
   tocbibind

It was easy to install those packages in Windows, so the only problem when 
creating the manual in Windows was caused by extra backslashes in the 
makefile.

2. On both of my Linux machines (one Kubuntu 8.04 and another Fedora 11), 
the make process halted because the 'anyfontsize' package is missing. This 
relatively new package is not available from the package managers; it 
seems to be available for the newest Kubuntu 9.10, but not for the newest 
Fedora 12. When I installed 'anyfontsize' manually, the make process 
halted with these last words:

   Making admb-sample
   pdflatex --interaction batchmode admb-sample
   This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
    %&-line parsing enabled.
   entering extended mode
   #pdflatex admb-sample
   cp admb-sample.log admb-sample.1.log
   bibtex admb-sample
   This is BibTeX, Version 0.99c (Web2C 7.5.6)
   The top-level auxiliary file: admb-sample.aux
   The style file: plain.bst
   I couldn't open database file admb-sample.bib
   ---line 29 of file admb-sample.aux
    : \bibdata{admb-sample
    :                     }
   I'm skipping whatever remains of this command
   I found no database files---while reading file admb-sample.aux
   (There were 2 error messages)
   make: *** [all] Error 2

In Windows, everything seemed to work fine without an admb-sample.bib 
file, so I'm not sure what the problem is. One symptom is that the 
half-baked manual is missing the "Index" entry from the table of contents.

---

These issues are probably not very hard to fix and get all the buildbot 
machines to generate the new manuals. The issues also remind us that 
future modifications will be necessary. Is the idea to have the copyright 
holder (Dangerous Curve, Los Angeles) maintain admbmanual.cls, or will we 
do it ourselves? We may e.g. be interested in adding some automatic 
formatting of ADMB code, like boldface SECTIONs and FUNCTIONs.

Updating the manuals is a major improvement that has ranked high on my 
list of ADMB priorities. The addition of Getting Started, the Reference 
Card, the upcoming FAQ, the proofreading of old manuals, and the fancy new 
style, it all helps. It sounds like the initial plan is to maintain four 
"official" ADMB manuals (Getting Started, AUTODIF, ADMB, ADMB-RE) plus the 
reference card.

With time, we may decide to merge the Getting Started manual into the ADMB 
manual. We could also create a garden for user-contributed documentation, 
similar to http://cran.r-project.org/other-docs.html. It won't be long 
until we see ADMB tutorials in non-English languages, for example.

Arni



On Fri, 2 Apr 2010, John Sibert wrote:

> Thanks for participating in a productive meeting. I had a bit of time in 
> SFO airport yesterday, so I worked on the reformatted and proofed 
> manuals. I hope to make them generally available next week. Ultimately 
> they will be inserted into the buildbot (in place of the current 
> versions).
>
> The attached archive contains all you should need to process a LaTeX 
> document with the new document class. I tested it on the new "getting 
> started" guide and it works OK (there were some issues with the guide 
> itself, such as case errors in file names). I thought you guys might be 
> interested in testing the new class before it is posted on the website. 
> The package expects to have the logo and license files somewhere that 
> LaTeX can find them. For testing purposes, I suggest putting your 
> document in the ADMBManualClass directory created when the archive 
> uzips. There are a couple of PDFs in the archive that should help your 
> get started.
>
> Enjoy,
>
> John
>