Next: Publishing Markup, Up: Script Files [Contents][Index]
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.
Generate a report from the Octave script file file in one of several output formats.
The generated reports interpret Publishing Markup in section comments, which is explained in detail in the GNU Octave manual. Section comments are comment blocks that start with a line with double comment character.
Assume the following example, using some Publishing Markup, to be the contents of the script file pub_example.m:
## Headline title # # Some *bold*, _italic_, or |monospaced| Text with # a <https://www.octave.org link to *GNU Octave*>. ## # "Real" Octave commands to be evaluated sombrero () %% MATLAB comment style ('%') is 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 ("pub_example.m")
.
When called with one input argument, a HTML report is generated in a subdirectory html relative to the current working directory. Any Octave commands in pub_example.m are evaluated in a separate context and any figures created while executing the script file are included in the report.
Using publish (file, output_format)
is equivalent to the
function call using a structure
options.format = output_format; publish (file, options)
which is described below. The same holds for using option/value pairs
options.option1 = value1; publish (file, options)
The structure options can have the following field names. If a field name is not specified, the default value is used:
‘html’ (default), ‘doc’, ‘latex’, ‘ppt’, ‘pdf’, or ‘xml’.
The output formats ‘doc’, ‘ppt’, and ‘xml’ are not currently supported. To generate a ‘doc’ report, open a generated ‘html’ report with your office suite.
In Octave custom formats are supported by implementing all callback subfunctions in a function file named ‘__publish_<custom format>_output__.m’. To obtain a template for the HTML format type:
edit (fullfile (fileparts (which ("publish")), ... "private", "__publish_html_output__.m"))
‘[]’ (default), integer value ≥ 0
‘true’ (default) or ‘false’
‘true’ (default) or ‘false’
‘true’ (default) or ‘false’
‘Inf’ (default) or integer value > 0
‘true’ (default) or ‘false’
The option output output_file is a string with path and file name of the generated report.
See also: grabcode.
The counterpart to publish
is grabcode
:
Grab the code from a report created by the publish
function.
The grabbed code inside the published report must be enclosed by the
strings ‘##### SOURCE BEGIN #####’ and ‘##### SOURCE END #####’.
The publish
function creates this format automatically.
If no return value is requested the code is saved to a temporary file and opened in the default editor. NOTE: The temporary file must be saved under a new or the code will be lost.
If an output is requested the grabbed code will be returned as string code_str.
Example:
publish ("my_script.m"); grabcode ("html/my_script.html");
The example above publishes my_script.m to the default location html/my_script.html. Next, the published Octave script is grabbed to edit its content in a new temporary file.
See also: publish.
Next: Publishing Markup, Up: Script Files [Contents][Index]