Next: , Up: Script Files   [Contents][Index]


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:

The returned output_file is a string with the path and file name of the generated report.

See also: grabcode.

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.


Next: , Up: Script Files   [Contents][Index]