Documentation Tips And Tricks

DocumentationTipsAndTricks

This page contains some tips and tricks on writing documentation with MuPAD Help style files.

Including code excerpts and examples

\eng{Here is how to compute 2:}
  \begin{Mexin}
1 + 1
  \end{Mexin}
  \begin{Mexout}
                               2
  \end{Mexout}

The examples can be checked automatically by MuPAD. For example, to check the examples in the combinat library, you can do:

        cd doc/dvi
        make combinat.res

The comparison is done by comparing the output character by character, so things like centering and MuPAD version do have an influence.

Some conventions

• The output must be centered with TEXTWIDTH set to 63
• If the output depends on the MuPAD version, the output corresponding to the development version of MuPAD (3.0.0 as of 08/04/2004) must be used
• The input must be raged left, without any spacing in front
• Their are some rules for spacing the input nicely (1 + 2) instead of 1+2. When the tests are run in doc/dvi, a file checkinput.log is created which suggests proper formating

A very practical way to create new examples is to use prog::makeExample interactively, and to copy paste the result (after double checking it!) into the documentation file (say lib/COMBINAT/DOC/words.tex). For example:

>> prog::makeExample(combinat::partitions::count(4),
                     combinat::partitions::list(3)):
  \begin{Mexin}
combinat::partitions::count(4);
combinat::partitions::list(3)
  \end{Mexin}
  \begin{Mexout}
                              5

                 [[3], [2, 1], [1, 1, 1]]
  \end{Mexout}

Advanced tips

In some cases, one need to customize the default behavior of Mexin and Mexout. This can be done by calling directly the underlying LaTeX environments Mvin and Mvout which can take extra options. Beware that this is not really documented nor supported by Christopher; use at your own risk.

Examples

• Hiding the environment in the generated documentation:

  \begin{Mvin}{hide=true}
bla
  \end{Mvin}

Typical application: an empty Mexout environment produces ugly extra vertical spacing. But removing this environment is not an option, because we want to test that the output is empty. A reasonable option is to use:

  \begin{Mvout}{hide=true}
  \end{Mvout}

This is better

• Disabling the automatic testing (typically useful when the result is unpredictable by nature):

  \begin{Mexin}
combinat::permutations::random(3)
  \end{Mexin}
  \begin{Mexout}
  \begin{Mvout}{test=false}
                           [2, 3, 1]
  \end{Mvout}

• Writing some long sample of MuPAD code that is not intended to be executed as is (kind of displaywise \Mex):

\begin{Mvin}{click=false,prompt=}
This is a long example of MuPAD
code that would not work as is
\end{Mvin}

The sources of Mhelp.sty tell that the following options also exists, with the following default values. If you ( = Christopher :-)) know

precisely what they mean please edit this page

• color: true
• collect: true
• postskip: \parskip
• preskip: 0pt
• contprompt: (not implemented)
• firstinseries: true
• inputfile
• samepage: true
• notebook
• plot:
• TeX: true