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:

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):

The following categories are used for variables (these are the first argument of the @defvr keyword):

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:

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.

DynareWiki: ReferenceManual (last edited 2011-04-20 12:25:10 by SébastienVillemot)