octave: Publish Octave Script Files
11.10.1 Publish Octave Script Files
-----------------------------------
The function ‘publish’ provides a dynamic possibility to document your
script file. Unlike static documentation, ‘publish’ runs the script
file, saves any figures and output while running the script, and
presents them alongside static documentation in a desired output format.
The static documentation can make use of 
Publishing Markup to
enhance and customize the output.
-- : publish (FILENAME)
-- : publish (FILENAME, OUTPUT_FORMAT)
-- : publish (FILENAME, OPTION1, VALUE1, ...)
-- : publish (FILENAME, OPTIONS)
-- : OUTPUT_FILE = publish (FILENAME, ...)
Generate reports from Octave script files in several output
formats.
The generated reports consider Publishing Markup in comments, which
is explained in detail in the GNU Octave manual. Assume the
following example, using some Publishing Markup, to be the content
of a script file named ‘example.m’:
%% Headline title
%
% Some *bold*, _italic_, or |monospaced| Text with
% a <http://www.octave.org link to *GNU Octave*>.
%%
# "Real" Octave commands to be evaluated
sombrero ()
## Octave comment style supported as well
#
# * Bulleted list item 1
# * Bulleted list item 2
#
# # Numbered list item 1
# # Numbered list item 2
To publish this script file, type ‘publish ("example.m")’.
With only FILENAME given, a HTML report is generated in a
subdirectory ‘html’ relative to the current working directory. The
Octave commands are evaluated in a separate context and any figures
created while executing the script file are included in the report.
All formatting syntax of FILENAME is treated according to the
specified output format and included in the report.
Using ‘publish (FILENAME, OUTPUT_FORMAT)’ is equivalent to the
function call using a structure
OPTIONS.format = OUTPUT_FORMAT;
publish (FILENAME, OPTIONS)
which is described below. The same holds for using
option-value-pairs
OPTIONS.OPTION1 = VALUE1;
publish (FILENAME, OPTIONS)
The structure OPTIONS can have the following field names. If a
field name is not specified, the default value is considered:
• ‘format’ — Output format of the published script file, one of
‘html’ (default), ‘doc’, ‘latex’, ‘ppt’, ‘xml’, or ‘pdf’.
The output formats ‘doc’, ‘ppt’, and ‘xml’ are currently not
supported. To generate a ‘doc’ report, open a generated
‘html’ report with your office suite.
• ‘outputDir’ — Full path string of a directory, where the
generated report will be located. If no directory is given,
the report is generated in a subdirectory ‘html’ relative to
the current working directory.
• ‘stylesheet’ — Not supported, only for MATLAB compatibility.
• ‘createThumbnail’ — Not supported, only for MATLAB
compatibility.
• ‘figureSnapMethod’ — Not supported, only for MATLAB
compatibility.
• ‘imageFormat’ — Desired format for images produced, while
evaluating the code. The allowed image formats depend on the
output format:
• ‘html’ and ‘xml’ — ‘png’ (default), any other image
format supported by Octave
• ‘latex’ — ‘epsc2’ (default), any other image format
supported by Octave
• ‘pdf’ — ‘jpg’ (default) or ‘bmp’, note MATLAB uses ‘bmp’
as default
• ‘doc’ or ‘ppt’ — ‘png’ (default), ‘jpg’, ‘bmp’, or ‘tiff’
• ‘maxHeight’ and ‘maxWidth’ — Maximum height (width) of the
produced images in pixels. An empty value means no
restriction. Both values have to be set, to work properly.
‘[]’ (default), integer value ≥ 0
• ‘useNewFigure’ — Use a new figure window for figures created
by the evaluated code. This avoids side effects with already
opened figure windows.
‘true’ (default) or ‘false’
• ‘evalCode’ — Evaluate code of the Octave source file
‘true’ (default) or ‘false’
• ‘catchError’ — Catch errors while code evaluation and continue
‘true’ (default) or ‘false’
• ‘codeToEvaluate’ — Octave commands that should be evaluated
prior to publishing the script file. These Octave commands do
not appear in the generated report.
• ‘maxOutputLines’ — Maximum number of shown output lines of the
code evaluation
‘Inf’ (default) or integer value > 0
• ‘showCode’ — Show the evaluated Octave commands in the
generated report
‘true’ (default) or ‘false’
The returned OUTPUT_FILE is a string with the path and file name of
the generated report.
See also: grabcode XREFgrabcode.
The counterpart to ‘publish’ is ‘grabcode’:
-- : grabcode (URL)
-- : CODE_STR = grabcode (URL)
Grab by the ‘publish’ function generated HTML reports from Octave
script files.
The input parameter URL must point to a local or remote HTML file
with extension ‘.htm’ or ‘.html’ which was generated by the
‘publish’ function. With any other HTML file this will not work!
If no return value is given, the grabbed code is saved to a
temporary file and opened in the default editor.
NOTE: You have to save the file at another location with arbitrary
name, otherwise any grabbed code will be lost!
With a return value given, the grabbed code will be returned as
string CODE_STR.
An example:
publish ("my_script.m");
grabcode ("html/my_script.html");
The example above publishes ‘my_script.m’ by default to
‘html/my_script.html’. Afterwards this published Octave script is
grabbed to edit its content in a new temporary file.
See also: publish XREFpublish.
Info Catalog
octave: Script Files
octave: Publishing Markup