= 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 [[http://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html|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}}}.