| MATLAB® | |
Once you have formatted an M-file for publishing, as described in Formatting M-File Comments for Publishing and Formatting M-File Code for Publishing you are ready to publish it. The easiest method for publishing an M-file is to use factory defaults. This method is appropriate if your M-file requires no input arguments and you want to publish to HTML. However, if your M-file requires input arguments, or you want to specify preferences for publishing, such as the output directory, output format, image format, and so on, you need to specify custom property settings.
To publish a script M-file, or a function M-file that requires no input arguments:
Open the file in the Editor.
Click the Publish button
on the Editor toolbar.
By default, the Editor publishes the file using factory default settings. Factory default settings specify that the output file format is HTML, that the M-code is evaluated and included in the published output file, and so on.
If the file is neither in a directory on the search path, nor in the current directory, a dialog box opens and presents you with options that allow you to publish the file. You can either change the current directory to the directory containing the file, or you can add the directory containing the file to the MATLAB® search path.
If the file has unsaved changes, publishing it from the Editor automatically saves the changes before publishing.
Using a publish configuration, you can specify custom settings, including input arguments for a function M-file in the Editor. You can associate multiple publish configurations with an M-file for different publish settings, input arguments, or both. MATLAB saves the configuration between sessions.
For example, the function collatzplot_new.m, which computes and plots the Collatz sequence for any given positive integer, requires you to specify the integer as an input value. You cannot simply publish collatplot_new.m because the input value is not defined. A publish configuration enables you to publish collatzplot_new(specific value).
You can also use publish configurations to provide preparatory or setup information prior to publishing an M-file, whether it takes input arguments or not.
Note M-file publish configurations use the base MATLAB workspace. Therefore, a value that you assign to a variable in an M-file publish configuration overwrites the value for that variable (assuming it currently exists) in the base workspace. |
From the Command Window, execute the publish function to run the M-file and publish the results. See the publish function reference page for options you can set.
Follow these steps to create a publish configuration for an M-file in the Editor. The example in this section shows how to create and use a publish configuration to specify input arguments to a function M-file.
These steps specify Editor toolbar buttons, but you can also use equivalent items in the File menu.
Open the file that you want to publish in the Editor. This example uses the code that follows. This code is similar to the sine_wave.m file, after it has been formatted as described in Formatting M-File Comments for Publishing, but it is slightly altered to make it a function M-file. Save the code as sine_wave_f.m
%% Plot Sine Wave
% Calculate and plot a sine wave.
%% Calculate and Plot Sine Wave
% Calculate and plot |y = sin(x)|.
function sine_wave_f(x)
y = sin(x);
plot(x,y)
%% Modify Plot Properties
title('Sine Wave', 'FontWeight','bold')
xlabel('x')
ylabel('sin(x)')
set(gca, 'Color', 'w')
set(gcf, 'MenuBar', 'none') Click the down arrow next to the Publish button
on the Editor toolbar, and click Edit Publish Configuration for file name, where file name in this example is sine_wave_f.m.
The Edit M-File Configurations dialog box opens, with the default publish configuration template for sine_wave_f.m, as shown in the following figure.
In the Publish configuration name field, type a name for the publish configuration, or accept the default name.
If you expect to create multiple configurations for an M-file, assign each a name that helps you identify the configuration. In this figure, the default name of the configuration is sine_wave_f.
In the MATLAB expression field, type the expression that you want the Editor to evaluate when it publishes the M-file. In this example, delete the commented statements and replace them as shown in the following figure.
You can modify the statements in the MATLAB expression area of the dialog box, and then click Publish to see the results of the changes. If you clear the MATLAB expression area, MATLAB publishes the M-file without evaluating any code. This is equivalent to setting the Evaluate code property in the Publish settings properties table to false.
In the Publish settings properties table, change the property values if you do not want to use the current settings.
You can modify the property settings, and then click Publish to see the results of the changes.
See Specify and Save Publish Configuration Settings for details.
Do one of the following:
To publish the file using the settings and MATLAB expression that you have specified, click Publish.
For this example MATLAB creates the following files in I:\my_matlab_files\my_mfiles\html, which is a subdirectory in the directory where sine_wave_f.m is located:
A published document file, sine_wave_f.html
A thumbnail file for the last image generated by the M-file code, sine_wave_f.png
Image files created by the executable M-file code, sine_wave_f_##.png
To create another publish configuration for the same
M-file, click the plus button
, and then select Publish
Configuration.
See Create and Run Multiple Publish Configurations for an M-File for details.
To close the Edit M-File Configurations dialog box, click Close. MATLAB saves the configuration and its association with the M-file.
After creating a configuration, you can view the MATLAB expression and use the configuration to publish the M-file without opening the Edit M-File Configurations dialog box. See Run an Existing Publish Configuration for details.
This section describes how to specify new publish settings for a configuration. Publish settings enable you to specify the directory to which a published file is saved, how images generated by the M-code are captured and included in the published document, and so on.
If the Edit M-File Configurations dialog box is not
already open, click the down arrow on the Publish button
and then click the configuration that
you want to change.
This example uses the sine_wave_f publish configuration as described in Creating a Publish Configuration for an M-File.
View the properties table below the Publish settings field to see the current publish property values.
For information about a property, click the property name. A brief description of that property displays below the publish settings property table. For example, if you click Catch error, the dialog box appears as shown in the following image.
Optionally, you can change publish setting values by clicking in the column to the right of the property name and then entering or selecting a property value. This example changes Max image width and Max image height to 400.
The Editor marks each property that you change with a dot (
) and adds the string, (modified), next
to User Default in the Publish settings field.
See Specify Values for the Publish Settings Property Table for information about the various properties you can set.
Click Publish to preview the publication of the M-file that is open in the Editor using the new settings.
When you are satisfied with the results, click Save As.
The Save Publish Options dialog box opens and displays the names of all the currently defined publish settings. By default the following publish settings are installed with MATLAB:
Factory Default
The MathWorks installs this named set of publishing properties for you to get started with publishing documents. It enables you to quickly publish an M-file to HTML and view the results. You can use it to test the effect of changing settings on the published output. If you determine that the test settings produce undesirable results, you can restore the Factory Default publish settings by selecting it from the Publish settings drop down list.
User Default
The MathWorks™ installs this named set of publishing properties in anticipation that you will have a set of publish properties that are common to most or all of your publishing configurations. Initially, User Default settings are identical to those in the Factory Default. See Creating a Template for Typical Publish Settings for an example of changing the User Default settings to best suit your publishing needs.
In the Settings Name field, enter a meaningful name for the settings. For example, reduce_image. Then click Save.
You can now use the reduce_image publish settings with other publish configurations.
You can also overwrite the publishing properties saved in an existing publish settings name by selecting it from the Publish settings drop-down list, and then clicking Overwrite. However, you cannot overwrite the Factory Default publish settings.
In the Edit M-File Configurations dialog box, do one of the following:
Click Publish to publish the M-file that is open in the Editor using the new settings.
Click Close to close the dialog box.
The sections that follow describe each of the publish settings properties that you can adjust to fit your needs when you create or update a publish configuration. To access a publish configuration open the M-file for which you want create or update a publish configuration, and then select File > Publish Configuration for file name > Edit Publish Configurations for file name.
You can set or adjust values for the following properties:
Select one of the choices from the drop-down list to publish the document to one of the following file formats:
html — Publishes an HTML document.
xml — Publishes an XML document.
latex — Publishes a LaTeX document, which you can use to create a PDF document, if you want.
doc — Publishes a Microsoft® Word document, if your system is a PC.
ppt — Publishes a Microsoft® PowerPoint® document, if your system is a PC.
MATLAB names the published file with the same name as the publish configuration that produced it and stores it, along with images that MATLAB generates from M-file code, in the directory specified with the Output folder property.
Type the full path of the directory to which you want MATLAB to publish the output document and its associated image files. For example, if your M-file is in I:\my_matlab_files\my_mfiles, you might specify I:\my_matlab_files\my_word_files if you are creating a publish configuration for documents that you publish to Word.
Type the full path of the cascading style sheet (CSS), also referred to as an Extensible Stylesheet Language (XSL) style sheet, that you want to use when you specify the Output file format as HTML, XML, or LaTeX. If you leave this field blank, MATLAB uses a default stylesheet installed with the MATLAB software.
To create the images produced when publishing M-files, select one of the following options:
getframe — MATLAB uses the getframe function to capture figures for inclusion in the published document. Any published image identically matches the image you see on the screen. However, if another open application window is partially on top of the image, MATLAB includes that second image in the capture.
print — MATLAB uses the print function to capture figures for inclusion in the published document. The published image never includes portions of another window, but in some cases, the published image does not exactly match what appears on the screen. For example, if the EraseMode plot property is set to none, an image published with the figure capture method set to print does not exactly match the screen image.
Select the file type for images produced when publishing M-files. The image file types available in the drop-down list depend on the Figure capture method you specify.
Set to true if you want MATLAB to create a new Figure window with a white background and at the default size before publishing if the M-file code generates a figure. After publishing finishes, MATLAB closes the Figure window.
To use a figure with different properties for publishing, set this property to false. Then open a Figure window, change the size and background color, for example, and then publish. Figures in your published document use the characteristics of the figure you opened before publishing.
Note This preference applies to executable M-file code that generates a figure. It does not apply to figures included in a published document using the Cell > Insert Text Markup > Image menu option. |
The following example demonstrates how to specify new Figure window properties for published images by setting the Use new figure publish settings property to false:
Create sine_wave_f.m, as described in Creating a Publish Configuration for an M-File.
Create a Figure window by saving the following code in an M-file and then running it:
function createfigure
%CREATEFIGURE
% Create figure
figure1 = figure('Name','purple_background',...
'Color',[0.4784 0.06275 0.8941]);
colormap('hsv');
% Create subplot
subplot(1,1,1,'Parent',figure1);
box('on');
% Create xlabel
xlabel({''});
% Create title
title({''});
The following figure appears.
Reduce the size of the figure by dragging and dropping the edges. For example:
Do not close the window.
Make sine_wave_f.m the active file in the Editor, and then select File > Publish Configurations for sine_wave_f.m > Edit Publish Configurations for sine_wave_f.m.
In the Publish settings drop-down list, select Factory Default.
If you have previously set Publish settings for sine_wave_f.m, the Change Publish Settings dialog box opens. Click Change to Factory Default..
In the Publish settings properties table, set Use new figure to false.
Click Publish. MATLAB publishes sine_wave_f.m as shown in the following figure.
Overwrite the current value to restrict the width of images in the published output. Note the following about this property:
It applies only to images that the M-code generates. It does not apply to images you include using the method described in Specifying Graphics in M-Files for Publishing.
It applies when you select an Image Format property setting that is a bitmap, such as .png or .jpg.
It does not apply when the Image Format property setting is a vector format, such as .eps.
The image's aspect ratio is maintained. If you restrict both height and width using Max image width and Max image height properties to resize the image, then MATLAB maintains the aspect ratio by using the maximum you specified for one dimension and something less than the maximum for the other dimension.
Overwrite the current value to restrict the height of images in the published output. Note the following about this property:
It applies only to images that the M-code generates. It does not apply to images you include using the method described in Specifying Graphics in M-Files for Publishing.
It applies when you select an Image Format property setting that is a bitmap, such as .png or .jpg.
It does not apply when the Image Format property setting is a vector format, such as .eps.
The image's aspect ratio is maintained. If you restrict both width and height using Max image width and Max image height properties to resize the image, then MATLAB maintains the aspect ratio by using the maximum you specified for one dimension and something less than the maximum for the other dimension.
Set to true to direct MATLAB to create a thumbnail image if the Image Format preference is a bitmap, such as .png or .jpg. For example, you can use this thumbnail to represent your M-file in HTML pages. If you create your own demos and include them in the Help browser Demos pane via a demos.xml file, MATLAB automatically creates a list of your demos that includes the thumbnail for each.
Set to false to direct MATLAB to not create a thumbnail image.
Set to true to have MATLAB include the M-file code in the published document. Set to false to the have MATLAB exclude the code from all output types except HTML. When the output type is HTML, MATLAB inserts the M-file code in the output file as an HTML comment. Therefore, when viewed in a Web browser, for example, the M-file code is not displayed.
Use the MATLAB grabcode function if you want to extract the M-file code from the published HTML file.
For example, suppose you publish I:/my_matlabfiles/my_mfiles/sine_wave_f.m to HTML using a publish configuration with the Include code property set to false. If you share the published document with colleagues, they can view the published document in a Web browser. If your colleagues want to see the M-file code that generated the published document, they can issue the following command from the directory containing sine_wave_f.html:
grabcode('sine_wave_f.html')MATLAB opens the M-file code that created sine_wave_f.html in the Editor.
See Creating a Publish Configuration for an M-File for the sine_wave_f.m code.
Set to true to direct MATLAB to evaluate the M-file code while publishing the results and include the results in the output document.
Set to false, to direct MATLAB to not evaluate the code nor include code results when publishing an M-file.
Because MATLAB does not evaluate the code, there might be invalid code in the M-file. Therefore, you might not want to set this property to false without first running the M-file.
For example, suppose you include comment text, Label the plot, in an M-file, but forget to preface it with the comment character. If you publish the document to HTML, and set Evaluate code to true, the published document includes the error, such as shown in the following figure.
Use this property with the Max # of output lines property to specify the maximum number of lines you want to include in the output. This property is helpful when you have code that produces a lot of output and you only want to include a sample of it in the published document.
Set to true to direct MATLAB to publish and include the error message text in the published document if an error occurs when it evaluates the code.
Set to false to direct MATLAB to terminate the publish operation if an error occurs when it evaluates the code.
This property has no effect if you set the Evaluate code property to false.
Type a value to specify the maximum number of output lines that you want to include after each cell break in the published document.
For example, suppose your M-file code includes a loop, such as the following:
for n = 1:100 disp(x) end;
If you publish the document, then by default, all 100 lines of the output generated by the preceding code is included in the published document. If you want to include a smaller representative sample of the output, set Max # of output lines to a small value, such as 10.
Use the User Default publish settings installed with MATLAB to create a template for all or most of your publish configurations.
Initially, the User Default publish setting has the same property values as Factory Default publish settings. Update and save your most commonly used property settings to avoid having to reset the same settings each time you create a new publish configuration.
For example, suppose that you frequently publish your M-files using the factory installed User Default settings, with a few exceptions. You want to change the factory installed User Default settings to:
Save the published document files to I:\my_matlab_files\my_published_mfiles
Use the getframe figure capture method
Terminate publishing if an error occurs while the M-file code is being evaluated
Update the User Default publish settings, as follows:
If the Edit M-File Configurations dialog box is not
already open, click the down arrow on the Publish button
, and then click the configuration for
which you want to set the properties as described in the preceding
list.
From the Publish settings drop-down list, select User Default.
If the Change Publish Settings dialog box opens, click Change to User Default.
Adjust the values in the publish settings properties table, so that the Publish settings appear as shown in the following figure.
Click Save As.
The Save Publish Settings dialog box opens.
In the Publish settings drop-down list, select User Default, and then click Overwrite.
The User Default publish settings are now saved with the specified property values.
Now, suppose you want to create a publish configuration using all the same settings, except you want to publish your M-file to a Microsoft Word document. Follow these steps:
In the Editor, open the M-file that you want to publish to a Word document.
Click the down arrow next to the Publish button
on the Editor toolbar and click Edit Publish Configuration for file name, where the file name is the name of the file that
you want to publish to a Word document.
The Edit M-File Configurations dialog box opens.
If you want, adjust the MATLAB expression.
Notice that the Publish settings are set to User Default and the publish settings properties table contains the values you set in the preceding list of steps.
Change the Output file format from html to doc.
Click Save As.
The Save Publish Settings dialog box opens.
In the Settings name box, type a name for the new group of publish settings. For example, WordDefault.
Click Save.
Now you can use any one of the following as the publish settings, or the basis for new publish settings, for the next publish configuration you create:
Factory Default
Your customized User Default
Word Default
Any other publish settings that you create and save with a unique name
After creating a publish configuration, you can run the configuration without opening the Edit M-File Configurations dialog box, as follows:
In the Editor toolbar, click the down arrow on the
Publish button
, and position the pointer on a publish
configuration name. MATLAB displays a ToolTip showing the publish
configuration's MATLAB expression so you can see what will be
evaluated when you publish the M-file using the named configuration.
To use the publish configuration, select a configuration name. MATLAB publishes the M-file using the MATLAB expression you specified in the publish configuration. For example, if you select sine_wave_f, MATLAB sets the value of the input argument, x, to 0:1:6*pi and passes it to the M-file function before evaluating and publishing it. (To see how to set the MATLAB expression, see Creating a Publish Configuration for an M-File.)
You can create multiple publish configurations for a given M-file. You might do this to publish the M-file with different values for input arguments, with different publish setting property values, or both. Create a named configuration for each purpose, all associated with the same M-file. Then, any time you publish the M-file, you can chose and run whichever particular publish configuration that you want. For example, for sine_wave_f(x) you might use different values for x and adjust publishing properties for these purposes:
For reviewing with colleagues, publish the document to Word. Use publish settings to adjust the size of images generated by the code so they are not cropped in the document. Evaluate and include the code, as well as any errors generated by the code in the Word document.
For inclusion in a blog, publish the document to HTML. Use publish settings to specify an argument value and set publishing properties to evaluate and include the code, but exclude errors generated by the code from the output published to HTML.
For presentation at a meeting, use the same settings as used for publishing to the blog, but publish to Microsoft PowerPoint.
The following sections provide instructions for creating multiple configurations for sine_wave_f.m. Each set of steps assumes you have completed the previous set of steps. When you complete all three you will have three publish configurations, one for each output format described in the previous list.
The following steps provide an example of settings you might use when you want to publish an M-file to Word. This example uses the sine_wave_f.m file, the code for which is presented in Creating a Publish Configuration for an M-File.
In the Editor, open sine_wave_f.m.
Select File > Publish Configuration for sine_wave_f.m > Edit Publish Configurations for sine_wave.m.
Select sine_wave_f in the list
of M-files and configurations, click the Add button
, and then select Publish Configuration.
MATLAB creates a new publish configuration, sine_wave_f_2.
Rename sine_wave_f_2 to sine_wave_word, and replace the default template expression with the following code:
x = 0:1:rand*pi; sine_wave_f(x)
Change the values for Publish settings, as follows so that the M-file is published to a Word document, including the code, its output and any errors the code may generate. The maximum values for the image height and width are set so that the images are not cropped in the Word document:
For Output file format, select doc from the drop-down list.
For Image format, select jpeg from the drop-down list.
For Max image width, type 400.
For Max image height, type 400.
Click Publish to test how the settings affect the Word document.
You can continue to test and change publish settings until you achieve the results that you want.
Click Save As. In the Save Publish Settings dialog box, in the Settings name field, type word_settings, and then click Save.
These steps provide an example of creating a configuration for sine_wave_f.m, that publishes the M-file to HTML. You might do this to publish output for inclusion in a blog, for example.
If it is not currently open, open the Edit M-File Configurations dialog box.
Select sine_wave_word in the list of M-files and configurations on the left side of the dialog box, click the + button, and then select Publish Configurations.
In the Publish configuration name field, replace sine_wave_f_2 with sine_wave_html.
In the MATLAB expression field, replace the default expression with the following:
x = 0:1:rand*pi; sine_wave_f(x)
Tip To get a quick view of the expression used in a different configuration, position the pointer on the name of a different publish configuration without selecting it. In the following figure, sine_wave_html is selected, but the pointer is positioned on sine_wave_f. You can see the MATLAB expression specified for the sine_wave_f configuration in the ToolTip. |
From the Publish settings drop-down list, select word_settings.
This example uses the word_settings configuration as a starting point for adjusting the publish settings. In step 8, it will be saved using a different Publish settings name.
Change the Output file format to html.
Click Publish to test how the HTML output appears.
Click Save As. In the Save Publish Settings dialog box, in the Settings name field, type html_settings, and then click Save.
These steps provide an example of creating a configuration for sine_wave_f.m, that publishes the M-file to Microsoft PowerPoint. You might do this to publish output for presentation in a meeting, for example.
If it is not currently open, open the Edit M-File Configurations dialog box.
Select sine_wave_word in the list of M-files and configurations on the left side of the dialog box, click the + button, and then select Publish Configurations.
In the Publish configuration name field, replace sine_wave_f_2 with sine_wave_ppt.
In the MATLAB expression field, replace the default expression with the following:
x = 0:1:6*pi; sine_wave_f(x)
From the Publish settings drop-down list, select word_settings.
This example uses the word_settings configuration as a starting point for adjusting the publish settings. In step 8, it will be saved using a different Publish settings name.
Assume for the purposes of a PowerPoint® presentation, you do not want to include the code.
Change the Output file format to ppt and Include code to false.
Click Publish to test how the PowerPoint output appears.
Click Save As. In the Save Publish Settings dialog box, in the Settings name field, type ppt_settings, and then click Save.
When you create one or more publish configurations using the Edit M-File Configurations dialog box, the Editor updates the publish_configurations.m file in your preferences directory. (This is the directory that MATLAB returns when you run the MATLAB prefdir function.)
Although you can port this file from the preferences directory on one system to another, there can only be one publish_configurations.m file on a system. Therefore, you should only do this if you have not already created configurations on the second system. In addition, because this file may contain references to file paths, you need to be sure the specified M-files and paths exist on the second system.
The MathWorks recommends that you not update publish_configurations.m in the MATLAB Editor or a text editor. Changes that you make using tools other than the Edit M-File Configurations dialog box may be overwritten later. Each time you save a configuration using the Edit M-File Configurations dialog box, MATLAB updates the publish_configurations.m file, as well as the run_configurations.m file. See About the run_configurations.m File for more information about that file.
The method you use to find publish configurations is the same as the one you use to find run configurations. See Find Configurations for details.
If you no longer need a publish configuration because you do not use it or because you deleted the M-file with which it is associated, it is a good practice to delete the publish configuration. The method you use to delete publish configurations is the same as the one you use to delete run configurations. See Remove Configurations for details.
Each publish configuration is associated with a specific M-file. If you move or rename the M-file, you need to redefine the association. If you delete an M-file, you might want to delete the associated configurations, or associate them with a different M-file. You might also need to modify the statements in the configurations so they will run. The method you use to reassociate and rename publish configurations is the same as the one you use to reassociate and rename run configurations. See Reassociate and Rename Configurations for details.
| Formatting M-File Code for Publishing | Using Notebook to Publish to Microsoft® Word | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |