The MATLAB editor automatically highlights all content after %% comments, and text after %% in the same line are turned bold. But what's the essential difference here? Why do people sometimes use %% instead of %?
From a syntax point of view, they are both comments.
In the Matlab editor, Matlab parses %% delimited blocks as "sections" which you can run as a unit independent of running the whole script.
One percent sign (%) is used for commenting lines.
Two percent signs (%%) have a different purpose: they are used for dividing your code into sections, which can be run independently. This allows easier debugging.
I really like the double percent sign (%%) and use as far as possible for the following reasons:
Creates a cell block which could be run separately from the whole code (Ctrl + Enter).
As mentioned in sections, it improves the readability of the file and appears as a heading if you publish your code. It increases concentration by creating a yellow background and you can focus more on the part that you are working on.
You can fold the code in cell blocks. (First you should enable code folding of cell blocks in Preferences >> Editor/Debugger >> Code Folding >> Sections). This is useful specially in large mfiles.
If you care about keeping a clean Command History running the codes in cell blocks (Ctrl + Enter) does not leave any trace in Command History , unlike the Evaluate Selection (F9) which evaluates the selected (highlighted) code and holds the executed code in Command History.
Hope it helps.
Related
Background
Matlab has a publish function which outputs a, say, .html file based on the syntax of the comments. Sections which contain example code are indicated by a '%' followed by three spaces. An example function can be seen below, and the .html file generated by the publish function can be seen here.
function randomImage = GenerateRandomImage(n)
%% TestFunction
% generates a random image
%
% randomImage = GenerateRandomImage(n) returns an nxn array of random pixels
%
%% Example
% randomImage = GenerateRandomImage(10);
% figure; imagesc(abs(randomImage));
randomImage = rand(n);
end
Matlab will not automatically evaluate the example code, unless I create a separate script with the example code explicitly uncommitted. An example script is seen below. This time, it automatically includes the outputs of that script, such as the image produced by the example script shown here here.
%% TestFunction
% generates a random image
%
% randomImage = GenerateRandomImage(n) returns an nxn array of random pixels
%
%% Example
randomImage = GenerateRandomImage(10);
figure; imagesc(abs(randomImage));
The Question
Is it possible for the publish function to automatically evaluate the code snippits in the comments of a function and include those outputs in the html file?
The matlab publisher is explicitly meant to be performed on scripts, not function files, since its purpose is to produce a report, where individual sections (marked with %%) become headings, and lines beginning with % immediately under the %% become the description text for that section. Anything that follows after that, both code and comment lines, will be presented by the publisher in a nice little box as the code that was run for that section, and then the results of that code will be shown below that box, but contained within their section.
Putting code in the description text for that section, expecting it to be run is counter-intuitive. In fact, the only reason you might want to put a code snippet in the description is if you wanted to mention some code without running it.
For this reason the publisher provides special syntax (indent by 2 spaces for monotyped text, 3 spaces to add syntax-highlighting to your code).
Publisher is a nice tool, but unfortunately it's fairly limited. The main limitation for me is that you cannot choose which code sections to show results for and which ones not to; it's all or nothing. Therefore I usually resort to a "latex + saved matlab figures + makefile" approach instead for flexible reports. But publisher is nice if you want something quick and dirty; e.g. it's good for keeping a logbook / diary of your work.
Anyway, to answer your question, no, you can't put code in the description and expect it to run. Nor are you expected to 'publish' functions; the fact that a function file responds at all to publishing in the first place is probably more of a side-effect of how publisher gets called more than anything.
I would like certain sections (rows) in my Matlab script to be foldable as a section code (cell). These rows do not necessarily always have an "end" keyword terminating them, and so I'd like to define myself where a code section begins and ends.
However, it seems that Matlab only understands the beginnings (marked with %%), and not the endings, of such code sections. Matlab seems to look for various other clues (such as code keywords like 'case') as the end of a code section, and ignores % or %% symbols, which I inserted in order to tell Matlab this is where I'd like the cell to end.
Under Preferences > Editor/Debugger > Code Folding there is a tick box for sections. If you tick this then you can use the %% to fold sections.
However, you should note that the sections (i.e. %%) have a use to the editor which is to allow you to easily run only the code in that section and not the entire script. So if you use %% liberally around your code just for code folding (and also it won't be nestable), then you might loose this capability.
Is there an option in matlab or a plugin/app or a trick such that if you are in an interactive command session, every time it would print out a matrix way too big for a human to look through, it redacts the output to either a warning of how big the matrix is or a summary (only a few rows and columns) of the matrix?
There are many times where I want to examine a matrix in the command window, but I didn't realize how big it was, so I accidentally printed the whole thing out. Or some place inside a function I did not code myself, someone missed a semicolon and I handed it a big matrix, and it dumps the whole thing in my command window.
It make sense that in 99.99% of the time, people do not intend to print a million row matrix in their interactive command window, right? It completely spams their scroll buffer and removes all useful information that you had on screen before.
So it makes much more sense for matlab to automatically assume that the user in interactive sessions want to output a summary of a big matrix, instead of dumping the whole thing into the command window. There should at least be such an option in the settings.
One possibility is to overload the display function, which is called automatically when you enter an expression that is not terminated by ;. For example, if you put the following function in a folder called "#double" anywhere on your MATLAB path, the default display behavior will be overridden for double arrays (this is based on Mohsen Nosratinia's display.m for displaying matrix dimensions):
% #double/display.m
function display(v)
% DISPLAY Display a variable, limiting the number of elements shown.
name = inputname(1);
if isempty(name)
name = 'ans';
end
maxElementsShown = 500;
newlines = repmat('\n',1,~strcmp(get(0,'FormatSpacing'),'compact'));
if numel(v)>maxElementsShown,
warning('display:varTooLong','Data not displayed because of length.');
% OR show the first N=maxElementsShown elements
% builtin('disp', v(1:maxElementsShown));
elseif numel(v)>0,
fprintf([newlines '%s = \n' newlines], name);
builtin('disp', v);
end
end
For example,
>> xx=1:10
xx =
1 2 3 4 5 6 7 8 9 10
>> xx=1:1e4
Warning: Data not displayed because of length.
> In double.display at 17
EDIT: Updated to respect 'compact' and 'loose' output format preference.
EDIT 2: Prevent displaying an empty array. This makes whos and other commands avoid an unnecessary display.
I'm writing MATLAB code in order to publish it later. By publishing, I mean the built-in MATLAB publish tool that allows the programmer to make a full report generated from their MATLAB code. There's an option to include the code with this report, section by section, preceding the results of this code. Is there a way to tell MATLAB to include some of this code in the report but not all of it? I know there are quite a few markup code tags, but I wasn't able to find anything on this topic.
Edit: Just to clarify, I want all results to be published, but only some of the code. So simply removing this code is not an option.
Cheers! = )
Hide your code that you don't want people to see in a script. For example, in the "sine_wave" example from the publish documentation page, I added a single line:
junk
Here's the content of junk:
figure()
plot(0:0.01:6,sin(0:0.01:6))
Now run your main script, and the published result has "junk" in the listing, but the contents of junk are not included, and you get the nice version of a sine wave, instead of the crappy one included in their example.
The only way I know of to do this is to remove the code that you don't want to appear in the output. If you just want to display the code and not the output, then you can just set the evalCode property to false in your call to publish.
If you do want the code to be evaluated, and the output to be published as well, then it's just slightly more complicated. You can manually execute the parts of the script that you don't want to publish, then publish the code that you care about (by putting it in it's own .m file). It shouldn't matter if the published code depends on any variables that are initialized in the omitted code, since those variables were added to your workspace when you manually executed the omitted code fragments.
Edit:
Since you've clarified your question to state that you're interested in publishing some of the code, but all of the output, I would think that your best bet is to just modify the "temporary" script (which contains the partial set of code that you wish to publish) to include any fprintf, disp, etc. function calls that you want to have appear in the output.
It's a bit hack-ish, but like I said, I'm not aware of any way to get that kind of fine granularity with "annotations" or using the publish command.
Hope that helps!
Here's a sample script that you can save and publish which will illustrate one workaround. You first have to set the Include code option to false, which stops all evaluated code from appearing, but you can still display code using a syntax highlighted code sample:
%% Controlling what code gets published
% Here's how you can do it...
%% Showing results without code
% If you set the
% <https://www.mathworks.com/help/matlab/matlab_prog/specifying-output-preferences-for-publishing.html#bthbe__-3
% *Include code* option> to |false|, you will see the plot but not the code
% that made it:
surf(peaks); % I'm John Cena!
%% But what if you want some of the code to show?
% The *Include code* setting affects the whole document, so all evaluated
% code will be hidden. If you want some code to show, you can use
% <https://www.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html#bs_uwzr
% syntax highlighted sample code>. This does mean you have to have duplicate
% sections of code (one is evaluated, one is displayed), but it's the best
% option thus far:
%%
%
% surf(peaks);
%
surf(peaks); % You can't see me, but you see the above!
And here's the published output:
I change the Matlab expression in the publishing options to
myFunction('PUBLISHING');
And the first lines of the function code to check for that input, so I can modify my code to only do certain things when publishing, usually displaying figures etc., but not during normal operation. Or vice versa :)
function [outputs] = myFunction(input1, input2)
isPublishing = (nargin == 1) && strcmp(input1, 'PUBLISHING');
if (nargin == 0) || isPublishing
% Set up default values
input1 = 'Hello';
input2 = 'World';
end
...
end
I could not find what formatting available to write help for your own MATLAB function. Very little information is available in official documentation.
Do you know about any other formatting that can be visible with Help Browser (not with help function)? As it is for built-in functions. How to format headings (like Syntax, Description, Examples)? Are bullets, tables possible? Or may be it should be a separate file?
I've tried text markup as used for PUBLISH and HTML, didn't work.
I found only one interesting thing. If your function contains mixed case, like testHelpFunction, its name will be highlighted:
No highlighting if it's just testhelpfunction.
Any other thoughts?
UPDATE
Here is extensive documentation I found on creating your own help files:
Providing Your Own Help and Demos
(Dead link replaced with web archive link)
(Dead link removed)
Updated again:
Add Help for Your Program
Display Custom Documentation
Try this other section in the official documentation. It's more thorough. MATLAB > User's Guide > Desktop Tools and Development Environment > Customizing Help and Demos > Providing Your Own Help and Demos. This describes both simple helptext and generating separate HTML help files.
Here's the helptext formatting I've picked up on and found useful.
function foo(x,y,z)
%FOO One-line description goes here
%
% foo(x,y,z)
%
% Multi-line paragraphs of descriptive text go here. It's fine for them to
% span lines. It's treated as preformatted text; help() and doc() will not
% re-wrap lines. In the editor, you can highlight paragraphs, right-click,
% and choose "Wrap selected comments" to re-flow the text.
%
% More detailed help is in the extended help.
% It's broken out like this so you can keep the main "help foo" text on
% a single screen, and then break out obscure parts to separate sections.
%
% Examples:
% foo(1,2,3)
%
% See also:
% BAR
% SOMECLASS/SOMEMETHOD
disp(x+y+z);
function extended_help
%EXTENDED_HELP Some additional technical details and examples
%
% Here is where you would put additional examples, technical discussions,
% documentation on obscure features and options, and so on.
error('This is a placeholder function just for helptext');
The first line after the function signature is called the "H1 line". It needs to be just one line so it is properly picked up by contentsrpt(), which can autogenerate a Contents.m file from the helptext in your functions
The function name in the H1 line is all caps, regardless of actual capitalization of the function name in the signature
Case matters for the "See also". I'm not sure which all cases work; this one does for sure.
Function names after "See also:" are all caps. Method names are qualified; I think names of methods in the same class as the current method can be unqualified.
Everything between the H1 line and "Examples:" is just a conventional formatting that I find readable; help() doesn't treat it specially.
You can use a limited form of hyperlinks in help. In particular, you can use hyperlinks to invoke arbitrary Matlab commands, and point to other sections of helptext by having it invoke help(). You can use this to point to any function; "function>subfunction" is just the syntax for addressing subfunctions in help() calls. Unfortunately, since you need to put either "help" or "doc" in those hyperlinks, it only works in one or the other presentation form. It would be nicer if there were a direct helptext hyperlink form.
I think the most important aspect in help formatting is that there is a help at all, and that your formatting is consistent, so that you (and people working with you) don't waste time finding out how to look for the information. Note that for OOP, it is useful to have a superclass with a 'help'-method that calls doc(class(obj)), since you cannot easily access the help from an instantiation of your class
To help me be consistent (and to make sure I don't forget stuff), I have created an automatic function template on the file exchange.
Here's the minimal header
function testhelp
%TESTHELP is an example (this is the H1 line)
%
% SYNOPSIS: a=testhelp(b,c)
%
% INPUT b: some input parameter
% c: (opt) some optional input parameter. Default: []
%
% OUTPUT a: some output parameter
%
% REMARKS This is just an example, it won't run
%
% SEE ALSO testHelpFunction
%
% created with MATLAB ver.: 7.11.0.584 (R2010b) on Mac OS X Version: 10.6.4 Build: 10F569
%
% created by: Jonas
% DATE: 01-Oct-2010
%
I figure there is some (see example), but I've never found the appropriate documentation. I often have such blocks:
% ...
%
% See also:
% this_other_function()
%
% <author>
And the See also part is formatted as a title, but if you replace See also by something else, it doesn't work. If anyone finds the list of such supported titles, please link to it here!
EDIT:
I've recently come to learn about matlab's built-in publishing system. It seems MATLAB comments support some form of markup not so far from Markdown's syntax (as used on SO itself), with support for LaTeX equations and all.
There's a post by "Loren on the art of MATLAB" with a short introduction on publishing and markup. For a full reference, see Making Up MATLAB Comments for Publishing on the Mathworks website.
When your code is ready, you can export the result to HTML/PDF/XML, etc. using the publish() function. I use the following snippet to export my files:
% Other formats are supported, refer to documentation.
options.format = 'html';
% I don't evaluate the code, especially for functions that require arguments.
% However, if providing a demo, turning this on is a fantastic way to embed
% figures in the resulting document.
options.evalCode = false;
% You can run this in a loop over files in the currrent directory if desired.
publish('script.m', options);