writingDemos

1. summary Things to keep in mind when writing PMTK3 demos

Table of Contents Writing Demos for Publishing Title Sections Figures Tags Additional Formatting Options Example Preview your Demo Things to Avoid

Writing Demos for Publishing

Demos in PMTK3 are automatically published to html using the publishDemos() function. To ensure that these demos look as you expect, please format the comments as follows:

Title

Every demo should have a title. This will appear in two places, the list of demos by chapter, and at the top of the demo itself.

  * The title must be a single line, and the very first line of the file, above even the    function header. 
  * The title line must begin with two % signs followed by a single space, as in {{{%% Demo Title Here}}}.
  * Additional comments that pertain to the whole demo should immediately follow the title  without any blank lines and with each line beginning with a single % sign followed by a space. 
  * This comment block, even if empty, must end with two %% signs before the first line of Matlab code. 

Sections

Break the demo into logical sections using two %% signs. The comment text on this line is used as the section title and appears in the demos 'table' of contents.

Figures

Publishing automatically embeds any generated figures into the html document. You can control where these are placed in two ways: using %% double percent signs or by using the command. However, as Matlab simply executes the snapnow command when it sees %%, the latter is preferable.

Whenever publish encounters either of these, it immediately inserts any open figures, that have not already been inserted.

If you do not want the %% symbol to generate a subheading, do not include any text with it.

Tags

We generate a number of [contributingAuthors] automatically using various 'tags'. These are comment strings that begin with PMTK as in . You should include these tags in the comments as in the following:

Include the PMTKslow tag if the demo takes more than 30 seconds to run. This just excludes it from the debugDemos report. If the demo takes more than 30 minutes to run, add the PMTKreallySlow tag, which tells publishDemos() not to actually run the code, publishing only the text.

Place tags in their own comment block section, just after the title block section.

Additional Formatting Options

There are a few other formatting options. Select the cell menu --> insert text markup for details:

Example

The published version looks like this.

Preview your Demo

Once you're finished writing your demo, preview what the published version will look like using the previewPublish() function.

You can create a Matlab shortcut to preview the currently open document using this code:

Things to Avoid

A few commands can interfere with publishing. In particular the command sequence

 can cause problems. This is because Matlab publish uses

figure(1) itself. Its much better to create the figures explicitly and save the dynamically generate handles, as in

The use of should also be avoided.

Finally, do not include %% double percent signs within loops that will be executed many times. This significantly slows down publishing, as JIT compiling is turned off.