3. Publishing a script
rise.publish turns a runnable MATLAB script into a typeset PDF. The
script stays a script: it runs in the editor exactly as before, and the
only convention is on comments, the one the editor’s cell mode already
uses.
rise.publish('rbc_walkthrough.m')
rise.publish('rbc_walkthrough.m', 'Title', 'A first walkthrough')
Each %% title becomes a numbered section. The comment block under it
becomes prose. The code becomes a syntax-highlighted listing. Whatever the
code printed appears underneath it, and every figure it drew is placed
where it was drawn.
The point is that the document and the code are one file. Nothing is written twice, so nothing can drift out of agreement with the code that produced it, and the numbers in the document are the ones that run produced on the day it was made.
3.1. The markup
Block markup, written in comments:
Written |
Becomes |
|---|---|
|
a numbered section, with an optional label |
|
a subsection |
|
a subsubsection |
|
continues the current section, no new heading |
|
prose, if it comes before the first line of code |
|
a blank line in the prose |
|
a bullet |
|
a numbered item |
|
a row of a table |
|
display mathematics |
|
a block of prose |
|
raw LaTeX, passed through untouched |
Inline, prose recognises ` `code` `, $math$, **bold**,
*italic* and _italic_.
3.1.1. Tables
A table is written as pipe-delimited rows. A row of dashes marks the header and is not itself printed; it may be omitted, in which case the first row is the header.
% | Parameter | Value | What it governs |
% |---|---|---|
% | beta | 0.99 | the discount factor |
% | alpha | 0.45 | the weight on capital |
Cells are plain text. Emphasis inside a cell is not offered, rather than offered and silently broken.
3.1.2. Emphasis
A marker counts only where it is being used as a marker. A span has to open at a word boundary and close at one, so
_this_ and *that* are emphasis
simul_historical_data is a name, left alone
2*x*3 is arithmetic, left alone
which is what lets the underscore be used at all in a toolbox whose option names are full of them.
3.1.3. Where prose stops and code begins
Within a section the first run of full-line comments is prose. Every comment after the first line of code belongs to the listing.
That is the rule cell mode follows, and it is worth following: the alternative surprises people, because a comment written to explain the next three lines of code would silently leave the listing and reappear as a paragraph somewhere above it.
3.2. Cross references
A heading or a display equation can carry a label, and anything else in the document can point at it:
%% What the steady state says {#steady}
% Capital per unit of labour follows from the discount factor:
%
% $$ \frac{Y}{K} = \left( \frac{1/\beta - 1 + \delta}{\alpha}
% \right)^{\frac{1}{1-\psi}} $$ {#capital}
and later, anywhere:
% The levels asked for are deviations from the steady state of
% [#steady], the one that [#capital] pins down.
which comes out as “deviations from the steady state of section 4, the one that Equation 1 pins down”, with both as clickable links.
References are coloured, in a restrained blue, because one set in the
same black as the sentence around it reads as ordinary text and nobody
tries it. ColorLinks set to false turns the colour off for a document
going to a monochrome printer; the links still work. LinkColor takes
any xcolor name.
The author never writes the number. Insert a section above and every reference to what follows renumbers itself, which is the whole reason for labelling rather than typing “see section 4”.
A labelled equation is numbered. A reference to an unnumbered equation has nothing to point at, so labelling one numbers it.
The reference names the kind of thing as well as its number, so you write
[#steady] and not “section [#steady]”.
To show the syntax rather than use it, put it in backticks:
` `[#name]` ` is printed as an example and not resolved.
3.3. Margin bookmarks
Every listing carries a note in the margin giving the span of the source file it came from:
lines 24--36
The document and the script are the same file, and the bookmark is what
makes that usable: read a paragraph, look at the margin, open the editor
at that line. Numbering the listing lines against the source, which
NumberLines does, gives the same link inside the listing; the
bookmark gives it at a glance without reading the listing at all.
Turn it off with MarginLines set to false. It is on by default and it
widens the right margin to make room, because a note squeezed into a
narrow margin wraps and looks like damage.
3.4. Figures
Every figure a block creates is placed where it was created, in creation order. A figure the block merely updated is left alone, because it was already shown where it was first drawn.
A figure is captioned with its own title:
figure;
plot(t, y);
title('An unanticipated ten percent fall in efficiency');
An author who wrote title has already said what the figure is, and
being asked to say it again in separate markup would be being asked twice
for the same sentence.
A figure with several axes is a panel, so the first title would describe
only one piece of it and no caption is invented. The figure’s Name is
the fallback.
3.5. Options
3.5.1. Execution
Option |
Default |
Meaning |
|---|---|---|
|
|
run the code and capture what it produced |
|
|
|
|
|
include the listings |
|
|
include what the code printed |
|
|
longer output is cut, and the cut is stated rather than hidden |
|
|
number listings against the source file’s own line numbers |
|
|
a margin bookmark beside each listing giving its span in the source file |
3.5.2. Content
Option |
Default |
Meaning |
|---|---|---|
|
from the script |
taken from the first section when not given |
|
|
a table of contents |
|
|
with |
|
|
record RISE version, MATLAB version, date and run time |
TitlePage is what a note, a memo, or a piece destined for a larger
document wants. The title is still used for the running head and the
file name, the abstract still appears, and the first section stays in the
body rather than being consumed as the document title.
3.5.3. The page
Option |
Default |
Meaning |
|---|---|---|
|
|
also |
|
|
|
|
|
also |
|
|
also |
|
see below |
struct with |
Margins default to 2, 3.5, 2 and 2 centimetres, with the right margin
widened to 3.6 when margin bookmarks are on. Setting Margins
overrides that, bookmarks or not, so leave it alone unless you mean it.
rise.publish('wide_report.m', 'Orientation', "landscape", ...
'PaperSize', "a4paper")
3.5.4. Output
Option |
Default |
Meaning |
|---|---|---|
|
the script’s name |
output file name |
|
|
|
|
|
as a fraction of the text width |
|
|
dots per inch, for |
|
|
keep the working directory, including the generated LaTeX |
3.6. What it guarantees
The source file is never modified. Everything happens in a temporary working directory.
The script runs with the working directory set to its own folder, so a relative load behaves exactly as it does when the file is run by hand.
All the code blocks share one workspace, so a variable assigned in one block is available in the next, exactly as in the editor.
A failing block does not lose the document. Under the default,
OnError of "report", the failure is typeset where it happened and
the rest of the script still runs. Use "stop" when a failure should be
treated as a broken build.
The document says how it was made. The stamp records the RISE version, the MATLAB version, the date and the total run time, so two documents can be compared knowing whether they were produced the same way.
3.7. Publishing without running
rise.publish('walkthrough.m', 'EvalCode', false)
The script is typeset but not executed. Useful for a document whose code is slow, needs data that is not present, or is deliberately illustrative.
3.8. A worked example
rise-modern-tutorials/Reporting/mfile_publisher builds a small real
business cycle model, solves it, runs a deterministic experiment and
publishes the result twice, once with a title page and once without.
See also