Texinfo format
The reference manual is now in the Texinfo format, in the doc/dynare.texi file. Texinfo is a markup language, conceptually close to LaTeX. It is the documentation format internally used by Octave (headers of Octave functions contain Texinfo snippets, which when combined together form the Octave manual).
The documentation of this format can be found:
on the GNU Texinfo website
for Debian users, in the texinfo-doc-nonfree package
The package to be installed under Debian or Cygwin in order to transform Texinfo to other formats is texinfo. The command to be run for creating the HTML or PDF output is makeinfo (the Dynare build system does it for you when calling make html pdf).
For Emacs users
Emacs comes with a mode for editing Texinfo source. This mode is documented in the Texinfo documentation.
Particularly useful are the shortcuts for most useful tags, and the texinfo-all-menus-update command which updates all menus.
Note that AucTeX also comes with a Texinfo mode, which overrides the default Texinfo mode, and has different key bindings. This overriding can be disabled by customizing the TeX-modes variable.
Conventions used in the source file
Categorization of functions, commands, variables
The following categories are used for functions and commands (these are the first argument of the @deffn keyword):
MATLAB/Octave command: a command to be run directly from within MATLAB
Command: a Dynare command in the MOD-file (excluding blocks)
Block: a Dynare block in the MOD-file
Function: a function to be used in expressions of the MOD-file (defined by the shortcut @defun)
Constant: a constant to be used in expressions of the MOD-file
Operator: an operator to be used in expressions of the MOD-file
Macro directive: a directive of the macro-processing language
Configuration block: a block in the configuration file
The following categories are used for variables (these are the first argument of the @defvr keyword):
MATLAB/Octave variable: variables of the MATLAB workspace
Special variable: for the obsolete Sigma_e command
Sectioning of command descriptions
Commands defined with @deffn, and whose description is not too short, should use Texinfo macros defined at the beginning of the source file for creating small headers which section the description.
Those macros are:
@descriptionhead
@optionshead
@outputhead
@examplehead
@customhead (accepts an argument, to be used as the title of the section)
Creating nice HTML output for math formulas
In Texinfo, it is possible to enter LaTeX formulas within @math tags.
When converted to PDF, these formulas look the way we expect.
When converted to HTML, these formulas are by default not transformed: they look like TeX input, which is unfriendly.
The solution is to use texi2html and latex2html instead of makeinfo --html to create the output: the formulas will appear as images, as under PDF output. This is done automatically by make html provided that you have installed these two programs before running the configure script.
Under current version of Debian, there are two bugs which make the output of formulas not perfect (black lines sometimes appear under formulas, and some characters may be missing). The solution is to create a file called $HOME/.latex2html-init with the following content:
$DVIPSOPT = ' -E'; $PSTOIMG = '/home/user/pstoimg'; 1;
and to create /home/user/pstoimg by copying /usr/bin/pstoimg, and removing from it all occurences of the following keyword: -floyd.