Metadata Comments¶

Sometimes you want to tell CalcpadCE something about your document without that note showing up in the printed report — what a function's inputs mean, that a section is a work-in-progress the linter should leave alone, or that a block of scratch work shouldn't appear in the PDF.

A metadata comment does exactly that. It looks like an ordinary comment, so it never clutters your output, but CalcpadCE reads the extra information inside it. You don't have to write these by hand: the Metadata tab in the CalcpadCE panel fills them in for you.

The Metadata tab¶

Open the CalcpadCE panel and switch to the Metadata tab. Then click a line in your document, and the tab shows a small form for that line:

On a definition (a variable, function, macro, or custom unit) you can add a description, and for functions and macros, a type and description for each parameter and the return type. The parameter rows are filled in to match the definition automatically.
On any other line you get the document-wide options: settings overrides, lint-ignore regions, and no-print regions.

Fill in what you want and click Apply. If the line doesn't have a metadata comment yet, one is created for you; if it does, it's updated in place. Reset throws away your edits and reloads what's currently there. Only the fields that make sense for the line are shown — use Add field if you want one that's hidden.

What they look like¶

A metadata comment is a normal CalcpadCE comment (it starts with ' or ") with an HTML comment storing a JSON string :

'<!--{"desc": "Cross-sectional area"}-->
A(b; h) = b·h

Because it's an HTML comment, none of it appears in the HTML output.

A few things to know:

Notes about a definition go on the line directly above it.
The whole comment has to stay on one line unless you use _ line separators.
If the text inside gets garbled, CalcpadCE just ignores it and the linter points it out.
Toggling line wrapping with Alt+Z can make these easier to read fully or take up less space.

Documenting a definition¶

Put this on the line above a variable, function, macro, or custom unit:

Field	What it's for
Description	A sentence explaining what the definition is.
Parameter types	The kind of value each input expects. Functions take `value`, `vector`, `matrix`, or `any`; macros use CalcpadCE's token names.
Parameter descriptions	A short note for each input, in order.
Return type	What a function gives back: `value`, `vector`, `matrix`, or `any`.

'<!--{"desc": "Second moment of area of a rectangle", "paramTypes": ["value", "value"], "paramDesc": ["width", "height"], "returnType": "value"}-->
I(b; h) = b·h³/12

Filling in parameter and return types also helps the linter catch places where the function is called with the wrong kind of value.

Per-file settings¶

You can pin settings — decimals, angle units, and so on — to a document so it always renders the same way, no matter how the app is configured. Put a settings comment near the top of the file:

'<!--{"settings": {"decimals": 2, "degrees": 1, "units": "cm"}}-->

If more than one appears, the first one wins, so keep it at the top. The settings you can set here are the same ones on the Settings tab:

Setting	Values
`decimals`	0–15 decimal places
`degrees`	`0` radians · `1` degrees · `2` gradians
`complex`	`true` / `false` — complex-number mode
`substitute`	`true` / `false` — substitute variable values into the output
`formatEquations`	`true` / `false` — stacked math form
`zeroSmallMatrixElements`	`true` / `false` — show tiny values as `0`
`maxOutputCount`	5–100 rows shown for big matrices/vectors
`units`	unit system, e.g. `m`, `cm`, `mm`
`vectorGraphics`	`true` / `false` — SVG plots instead of images
`colorScale`	plot palette (see below)
`smoothScale`	`true` / `false` — smooth the color scale
`shadows`	`true` / `false` — shadows on 3-D surfaces
`adaptivePlot`	`true` / `false` — adaptive plot sampling

colorScale can be None, Gray, Rainbow, Terrain, VioletToYellow, GreenToYellow, Blues, BlueToYellow, BlueToRed, or PurpleToYellow. Anything the app doesn't recognize is ignored.

Quieting the linter¶

If the linter flags something that isn't actually a problem, you can silence it for a stretch of the document. Wrap those lines between a LintIgnore and an EndLintIgnore marker, listing the warning codes to hide (or leave the list empty to hide/unhide everything):

'<!--{"LintIgnore": ["CPD-3301"]}-->
prototype_var = 5
'<!--{"EndLintIgnore": []}-->

The Metadata tab has a picker for the codes, so you don't have to memorize them. See Suppressing diagnostics for the details.

Leaving sections out of the PDF¶

To keep something on screen but off the printed page — debug numbers, notes to yourself — wrap it between NoPrintStart and NoPrintEnd markers:

'<!--{"NoPrintStart": true}-->
debug_x = 5
'<!--{"NoPrintEnd": true}-->

The section still shows in the preview but is dropped from the PDF. See Excluding sections from the PDF for more detail.