MatlabAutoDoc

From NA-Wiki

Jump to: navigation, search

MatDocTex is a tool Dag wrote that can assemble comments from a Matlab m-file into a nicely formatted latex source. Download it: MatDocTex.tar].

The tarball contains the actual script, matdoctex.pl and an example of how it may be used. Check out the result here.

Contents

Running it

Usage of the script is simple:

$ ./matdoctex.pl *.m 

parses all comments (see below) from all m-files in the current directory, formats them and assembles them into a single tex-file which is printed to STDOUT. Note that one must set run permissions on the script iteslf.

Building the example

In the MatAutodocTex dirctory, run the script

$ ./matdoctex.pl *.m > doc.tex

Then run latex on doc.tex twice (since it has contents). You may also use the makefile supplied.

Comment formatting

MatdocTex will search for specific comment strings that let it format the tex file. Here is an example

function y = dummy_func(x)
%% Function Title - What the function does
%
% Descriptive comment about the function, 
% that may include a
%$ \sin(x)^2 + \cos(x)^2 = 1
% mathematical expression
%
%* Dag Lindbo
%%%

Note the following:

  • If the function line is not present, the m-file is formated as a script
  • The title comment is preceded by %%
  • The the " - " marks the end of the function title and the beginnig of a one-line description of what the function is
  • Any line that starts with % (note the space) will be parsed as part of the function description
  • Any line that starts with %$ is assumed to contain a mathematical expression that will be inserted into a displaymath enviroment block in TeX.
  • %* marks the author
  • %%% stops the parsing
  • if the tile comment is not present, the file name will be taken as the title.

Other features/bugs

  • Certain characters are forbidden by LaTex in ordinary text mode. This means that if a comment line contains _ \ etc then LaTex will fail. It is, however, simple to put $x_i$ instead of x_i in a comment (and that will make the output even neater).
  • To get inline verbatim formatting there is an additional formatting rule: ""[x y] = func(t)" will be parsed into \verb|[x y] = func(t)|.
Personal tools