Differences between revisions 5 and 6
Revision 5 as of 2011-04-20 12:24:06
Size: 3958
Comment:
Revision 6 as of 2011-04-20 12:25:10
Size: 3972
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
The reference manual is now in the Texinfo format, in {{{doc/dynare.texi}}}. It is a markup language, The reference manual is now in the Texinfo format, in the {{{doc/dynare.texi}}} file. Texinfo is a markup language,

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.

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