Code covered by the BSD License

# publish2latex

09 Apr 2013 (Updated )

Using full Latex markup in m-files to generate high quality documentation. Version 1.3

Introduction.m
%% Header to define the Title and authors.
% \documentclass[12pt]{article}
%
% \title{A Tool to Support \LaTeX~Markup in MATLAB\\
% \textbf{publish2latex}\\Version 1.1}
%
% \author{Matthew Harker and Paul O'Leary\\
% Institute for Automation\\
% University of Leoben\\
% A-8700 Leoben,
% Austria\\
% URL: automation.unileoben.ac.at\\
% \\
% Original: January 9, 2013\\
% $\copyright$ 2013\\
% \\
%
%% From here on all latex commands can be used
% \begin{abstract}
%  This tool extends the concept of publishing MATLAB code by enabling the
% full functionallity of \LaTeX. Presently the tool is no compatible with
% the \lstinline{publish} tool in MATLAN, it is an independent
% toolbox. The \lstinline{m} code
% is execued, the figures and the MATLAB screen outputs are captured. The
% MATLAB code is placed as a \textit{listing}, the screen output is then
% as a \textit{verbatim} and the figures are implemented as eps files.
% environments are available, including references to Bibtex etc.
% This document has been produced using this tool.
% \end{abstract}
%%
% \section{Introduction}
%
% This tool extends the concept of publishing MATLAB code by enabling the
% full functionallity of \LaTeX. Presently the tool is no compatible with
% the \lstinline{publish} tool in MATLAN, it is an independent
% toolbox\footnote{We are presently working on a converter from MATLAB
% publish to publish2latex}.
%
% The concept is you use \LaTeX markup in comment lines, whereby the full
% functionality of \LaTeX is available.
%
% We take advantage of the cell structure provided by MATLAB. Each file is
% segmented into the individual cells. The first cell mus be the file
% header. Between the file header and the second cell we automatically
% insert the file \textit{LatexDefinitions.tex}, which is contained in the
% library. This enables the definition of addition macros and packages you
% might wish to use.
%
% Before starting the MATLAB run we set default values for fonts and figur
% sizes. This ensures tha the formating of the text in the figures and the
% size of the figures is consistent.
%
% This tool has been used to generate the documentation for the discrete
% orthogonal polynomial toolbox DOPbox and the ordinary differential
% equation toolbox ODEbox which are available at MATLAB Central
%
% \begin{verbatim}
%   http://www.mathworks.com/matlabcentral/fileexchange/41250
%   http://www.mathworks.de/matlabcentral/fileexchange/41354
% \end{verbatim}
%
% You may find a collection of m-code examples and resulting PDF
% documentation in that library.
%%
% \section{Basic Structure}
%
% \subsection{Cell 1}
%
% The first cell in the m-file must contain the Latex document header
% containing the fololowing information. The present document provided an
% example.
%
% \begin{verbatim}
% \documentclass[12pt]{article}
%
% \title{.....}
%
% \author{.....}
% \end{verbatim}
%
% An empty template for \lstinline{publish2latex} can be found in the
% directory where this tool resides, it has the file
% name \lstinline{publishTemplate.m}.
%
% \subsection{Intermediate cells}
%
% Each cell in the m-file is considered to consist of three parts:
% \begin{enumerate}
%   \item Pre-m-code lines: these are interpreted as being LATEX commands.
%   \item m-code: Each cell contains only one code block and it starts
%   with the first non-comment line in the cell. All the comments in the
%   m-code part are dealt with as m-code comments and not interpreted as
%   Latex commands.
%   \item post-m-code: the last comment lines in a cell may be used to a
%   caption to the preceeding graphics figures. No other Latex code should
%   be used in this section.
% \end{enumerate}
%  The lines between the end of the code and
% the start of the next cell can be used to define a caption (no other \LaTeX
% code should be added here) for the
% figures produced by the code.
%
% Lines which start with \lstinline{% %} will be passed to \LaTeX as a
% comment line.
%
% \subsection{Last cell}
% The last cell in the m-file defines the bibliography style and bibtex
% files, e.g.
%
% \begin{verbatim}
% \bibliographystyle{IEEETran}
% \bibliography{myBibliography}
% \end{verbatim}
%
%%
% \section{Calling \lstinline{publish2Latex}}
%
% After installation of the package the tool is simply activated using
% the command \lstinline{publish2Latex}. This starts a simple pupup menu
% which is self explanatory.
%
% The tool requires no external programs to generate a \LaTeX file.
% Consequently, this section of code should also function on Apple 8hoever
% has not bee tested).
%
% The following programs must be installed if the tool is to automatically
% generate PDF documents:
%
% \begin{description}
%     \item[latex] To compile the .tex file to a .dvi file
%     \item[bibtex] Generates the necessary bibtex temporary files
%     \item[dvips] To convert .dvi to .ps
%     \item[ps2pdf14] to convert .ps to .pdf
% \end{description}
%
% We have chosen to generate postscript and them PDF because we feel this
% is the most advantageous way in the long run. You may choose to generate
% postscript and thes distill with other settings.
%
%%
% \section{Listings Package}
% %
% This tool uses the \textit{listings} package, consequently all the
% standard listings environments are available. You may need to install the
% listings package, see:
% \begin{verbatim}
%  ftp://ftp.tex.ac.uk/tex-archive/macros/latex/.../listings/listings.pdf
% \end{verbatim}
% for details.
%
% Complete MATLAB files can be included in the final documentation if
% desired using the listings package, for example,
%
% \begin{verbatim}
%      \lstinputlisting[caption=test]{Listings/fitLine.m}
% \end{verbatim}
% Code inserted in this manner is not executed by this tool.
%
% Inline code can be implemented using,
% \begin{verbatim}
%      \lstinline{for k=1:n}
% \end{verbatim}
% to generate \lstinline{for k=1:n}
%
%%
% \section{Getting started}
% Preparing the MATLAB environment.
clear all;
close all;
publishFigureFormat;
%%
%\subsection{Latex Equations}
%
% The following equations are just to test the possability of havig both
%  latex,
% $$% b = a^2 %$$
% and matlab equations. Note that line $7$ in the code has no semicolon
% and produces output to the screen, which is captured in
% this documentation.
a=1:10;
b = a.^2;
for k = 1:5
c(k) = a(k) * b(k)
end;
%%
%
% \subsection{Generating Figures and Captions}
% Each call of the \lstinline{figure} command generated a figure in the
% output, and after the figure a caption can be added.
h = figure;
plot( a,b,'k');
% \caption{testCaption}
%
%%
% \section{A Figure Without a Caption}
% Why? just for fun.
%
figure
plot(a,b,'h');
xlabel('Hier');
ylabel('there');
%%
close;
%%
% \section{Recalling a Graphic and Bibliography Citation}
% The command \lstinline{figure(h)} with a handel recalls a figure and
% generates a new outpur figure. The figures are sequentially numbered and
% can be referenced by the label, e.g. \lstinline{Figure 1}.
%
figure(h);
hold on;
plot( a,2*b,'r');
%%
%
% Test a reference to a bibliography~\cite{oleary2011}.
%
%%
% and now do a loop with figure calls to a handle this should only
for k=1:2
figure(h);
plot( a, 5 * k * b, 'k');
end;
%\caption{Figure with handel}
%%
%
% and now do a loop with figure withpout a handle this should
for k=1:2
figure;
plot( a, 5 * k * b, 'k');
end;
%\caption{Loop of figures}
%%
% \section{Files You May Wish to Modify}
%
% There are two files in the library you may wish to modify:
%
% \begin{enumerate}
%   \item \textit{LatexDefinitions.tex} This file may be used ot define
%   additional macros or include packages you may wish to use.
%   \item \textit{publishFigureFormat.m} This file defines the fonts to be
%   used in figures, sets the default interpreter in MATLAB to \LaTeX and
%   defines a default figure size.
% \end{enumerate}
%%
% \section{Finding Errors}
%
% Finding errors in your \LaTeX which is automatically generated can be
% cumbersome. Our recommendation is to generate the .TEX file and then
% compile this independently in your \LaTeX environment. This will enable
% you to more quickly find your error.
%
%% Define the Bibliography
%
% \bibliographystyle{plain}
% \bibliography{myBibliography}