publish - Generate view of MATLAB file in specified format - MATLAB (original) (raw)
Generate view of MATLAB file in specified format
Syntax
Description
publish([file](#d126e1422112)) generates a view of the specified MATLAB® code file and output in an HTML format that can be used for sharing. publish saves the HTML file and a file for each graphic that the code creates in a subfolder named html. The location of the html subfolder is relative to the location offile.
For example, publish('C:\myMATLABfiles\myfile.m') runs the code in myfile.m using the base workspace, and then saves the formatted code and results inC:\myMATLABfiles\html\myfile.html.
publish([file](#d126e1422112),[format](#d126e1422154)) generates a view of the specified MATLAB file in the specified file format. All file formats save to thehtml subfolder.
publish([file](#d126e1422112),[Name,Value](#namevaluepairarguments)) generates a view of the specified MATLAB file with options specified by one or morename,value pair arguments.
publish([file](#d126e1422112),[options](#d126e1422276)) uses the options structure to generate the view of the specified MATLAB file. Using a structure to specify options is useful when you want to preconfigure and save your options for repeated use. The fields and values of the options structure correspond to names and values of name-value pair arguments.
my_doc = publish([file](#d126e1422112),___) generates a view of the specified MATLAB file and returns the path of the resulting output file. You can use this syntax with any of the input argument combinations in the previous syntaxes.
Examples
Create an HTML view of a MATLAB example script including the code, results, and comments. Use theweb function to view the resulting file.
publish("fourier_demo2.m"); web("html/fourier_demo2.html")
Create a Microsoft® Word view of a MATLAB example script including the code, results, and comments. Save the path of the published file to a variable. Use the winopen function to view the resulting file.
mydoc = publish("fourier_demo2.m","doc"); winopen(mydoc)
Use name-value arguments to change the appearance of published figure windows in the HTML view of a MATLAB example script.
Use the figureSnapMethod name-value argument with the value entireFigureWindow to include window decorations and to match the figure background color to the screen color for figures. Then, use the web function to view the resulting file.
publish("fourier_demo2.m","figureSnapMethod","entireFigureWindow"); web("html/fourier_demo2.html")
Use a structure to create a Microsoft Word view of a MATLAB example script that does not show the code from the script. Specifying options as a structure is useful when you want to preconfigure and save your options for repeated use.
Create a structure options that specifies theformat and showcode options.
options.format = "doc"; options.showCode = false;
Create a Microsoft Word view of the example using the options specified in_options_. Use the winopen function to view the resulting file.
publish("fourier_demo2.m",options); winopen("html/fourier_demo2.doc")
Generate an HTML view of a MATLAB function that requires input arguments.
Create and save the function fact.m.
%% FACT compute the factorial of a number % FACT(N) computes the factorial of the number N and returns the results function f = fact(n) f = prod(1:n); end
Use the publish function to generate an HTML view of the function. Set the value of the input argument n by using the codeToEvaluate name-value argument. Then, use the web function to view the resulting file.
publish("fact.m","codeToEvaluate","fact(5);"); web("html/fact.html")
Input Arguments
MATLAB file name, specified as a character vector or string.file can include a full or partial path.
Note
When MATLAB publishes a file, it can overwrite existing files from the output folder that start with the same name asfile.
Example: publish('myfile.m')
Example: publish('C:\myMATLABfiles\myfile.m')
Output format of published file, specified as one of the values listed in the table.
| Value | Output Format |
|---|---|
| 'html' (default) | Hypertext Markup Language |
| 'doc' | Microsoft Word |
| 'latex' | LaTeX |
| 'ppt' | Microsoft PowerPoint® |
| 'xml' | Extensible Markup Language |
| 'pdf' | Portable Document Format (PDF) |
The Microsoft Word and Microsoft PowerPoint formats are only available on Windows® platforms.
MATLAB does not preserve syntax highlighting when you specify the output format as Microsoft PowerPoint or LaTeX.
Example: publish('myfile.m','ppt');
Options for published output, specified as a structure. Use theoptions structure instead of name-value pair arguments when you want to reuse the same configuration for publishing multiple MATLAB files.
The fields and values of the options structure correspond to names and values of the name-value pair arguments.
For example, this command creates the structureoptions, and specifies the PDF output format and the output folderC:\myPublishedOutput.
options = struct('format','pdf','outputDir','C:\myPublishedOutput')
Name-Value Arguments
Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose Name in quotes.
Example: 'format','pdf','showCode',false specifies the PDF output file format and excludes the code from the output.
Output Options
Output format of published file, specified as one of the values listed in the table.
| Value | Output Format |
|---|---|
| 'html' (default) | Hypertext Markup Language (HTML) |
| 'doc' | Microsoft Word |
| 'latex' | LaTeX |
| 'ppt' | Microsoft PowerPoint |
| 'xml' | Extensible Markup Language |
| 'pdf' | Portable Document Format (PDF) |
The Microsoft Word and Microsoft PowerPoint formats are only available on Windows platforms.
MATLAB does not preserve syntax highlighting when you specify the output format as Microsoft PowerPoint or LaTeX.
Example: publish('myfile.m','format','pdf')
Output folder to which the published document is saved, specified as a character vector. Specify the full path of the folder.
Example: publish('myfile.m','outputDir','C:\myPublishedOutput')
Extensible Stylesheet Language (XSL) file to use when publishing a MATLAB file to HTML, XML, or LaTeX format, specified as a character vector. Specify the full path of the XSL file.
Example: publish('myfile.m','stylesheet','C:\myStylesheet\stylesheet.xsl')
Figure Options
Whether to create a thumbnail image for the published document, specified as true or false. You can use the generated thumbnail to display a small representation of your file on HTML pages.
Figure window appearance for the published document, specified as one of the values listed in the table. Figure window appearance includes the background color of the plot and whether it includes window decorations (title bar, toolbar, menu bar, and window border).
This option is not available in MATLAB Online™.
| Value | Window Decorations | Background Color | ||
|---|---|---|---|---|
| GUIs | Figures | GUIs | Figures | |
| 'entireGUIWindow' (default) | Included | Excluded | Matches screen | White |
| 'print' | Excluded | Excluded | White | White |
| 'getframe' | Excluded | Excluded | Matches screen | Matches screen |
Image file format for the images in the published document, specified as one of the values listed in the table. The list of valid image formats depends on the specified output format.
| Output Format | Valid Image Formats | Default Image Format |
|---|---|---|
| Microsoft Word | Any image format that your installed version of Microsoft Office can import, including'png' ,'jpg','bmp', and'tiff'. If the'figureSnapMethod' option is set to 'print', then you also can specify 'eps','epsc','eps2','ill','meta', and'pdf'. | 'png' |
| Hypertext Markup Language (HTML) | All image formats.Ensure that the tools you use to view and process the output files can display the output format you specify. | 'png' |
| LaTeX | All image formats.Ensure that the tools you use to view and process the output files can display the output format you specify. | 'epsc2'The default changes to 'png' in these cases: figureSnapMethod is'getframe'.figureSnapMethod is'entireGUIWindow' and the snapped window is a GUI window. |
| Portable Document Format (PDF) | 'png' and'jpg'. | 'png' |
| Microsoft PowerPoint | Any format that your installed version of Microsoft Office can import, including'png','jpg', 'bmp', and 'tiff'. | 'png' |
| Extensible Markup Language (XML) | All image formats. Ensure that the tools you use to view and process the output files can display the image format you specify. | 'png' |
Maximum image height of the published images, specified as one of these values:
[](default) — Unrestricted height. This value is always used when the output format is PDF.- Positive integer — Height in pixels.
Maximum image width of the published images, specified as one of these values:
[](default) — Unrestricted width. This value is always used when the output format is PDF.- Positive integer — Width in pixels.
Whether to create new figure, specified as true orfalse. If true and the code generates a figure, then MATLAB creates a new figure window in the default size with a white background before publishing. If false, MATLAB does not create a figure window.
Specifying a value of false is useful if you want to use a figure with different properties for publishing. For example, you can open a figure window, change the size and background color, and then publish your code. Figures in your published document use the characteristics of the figure you opened before publishing.
Code Options
Whether to run the code and include the MATLAB output in the published view, specified astrue or false.
Whether to catch errors during publishing, specified astrue or false. Iftrue and an error occurs, MATLAB continues publishing and includes the error in the published file. If false and an error occurs, MATLAB displays the error at the command line and does not produce a published file.
Additional code to run during publishing, specified as a character vector. Use this option to run code that is not included in the MATLAB file. For example, when publishing a function, you can set the value of input arguments.
If this option is unspecified, MATLAB only runs the code in the MATLAB file you are publishing.
Example: publish('myfunction.m','codeToEvaluate','myfunction(1,10)')
Maximum number of lines of output to be included in the published document, specified as one of these values:
Inf(default) — MATLAB includes all output in the published document.- Nonnegative integer — MATLAB only includes the specified number of lines in the published document. Setting this option is useful if a smaller, representative sample of the output suffices.
Whether to include code in published file, specified astrue or false.
If the output format is HTML, MATLAB includes the code at the end of the published HTML file as comments, even when you set the 'showCode' option tofalse. Including the code as comments enables thegrabcode function to extract the MATLAB code from an HTML file, even when the file does not display the code. The code does not display in a Web browser because MATLAB includes the code as comments.
Limitations
- Publishing live scripts or functions is not supported. To convert live scripts or functions to other formats, use the export function instead.
- Publishing a MATLAB code file (
.m) by calling thepublishfunction from a live script or function (.mlx) is not supported. - The
publishfunction does not support theinputfunction. Publishing a MATLAB code file (.m) that contains a call to theinputfunction results in an error.
Tips
- To enhance the readability of the published document and include additional image snapshots, external file content, and external images, see Publishing Markup.
- To avoid duplicate snapshots when publishing MATLAB code files, make sure that your cursor is not positioned over any figures before calling the
publishfunction. Having the cursor on a figure can cause the figure to update and thepublishfunction to generate duplicate snapshots.
Version History
Introduced before R2006a
Specifying the figureSnapMethod name-value argument as"entireFigureWindow" is no longer supported. Use the"entireGUIWindow", "print", or"getframe" values instead.
Specifying the imageFormat name-value argument as"bmp" is no longer supported when the value of theformat name-value argument is "pdf". With this change, you can instead specify imageFormat as either"png" or "jpg" for PDFs, with"png" being the default value. Specifying theimageFormat name-value argument as "bmp" is also no longer supported when the value of thefigureSnapMethod name-value argument is"print".
By default, figures created when publishing a document appear larger than in previous releases. In addition, these figures appear as tabs in a figure container.
To publish documents using the previous default figure size, set thePosition property of each figure using a position vector of the form [left bottom width height]. Setting thePosition property undocks the figure from the figure container.
f = figure(Position=[100 100 560 420]);
To use the previous default initial figure size for all figures, set the default figure position of the graphics root object.
set(groot,DefaultFigurePosition=[100 100 560 420])
For more information, see Figure.
The 'entireFigureWindow' value for thefigureSnapMethod option will not be supported in a future release. Use the 'entireGUIWindow', 'print', or 'getframe' values instead.