Metadata Comments¶

Part of Calcpad.Web. The Properties tab described here currently appears in the VS Code extension. The comments it writes are understood everywhere — the linter, the preview, and PDF export — no matter which editor created them.

Sometimes you want to tell Calcpad 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 Calcpad reads the extra information inside it. You don't have to write these by hand: the Properties tab in the CalcPad panel fills them in for you.

The Properties tab¶

Open the CalcPad panel and switch to the Properties 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.
Document settings are always available. Editing them writes a #settings directive at the top of the file — not a metadata comment — so they take effect during calculation.
On any other line you also get the 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.

Document 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. Use the #settings directive with a JSON object:

#settings {"decimals": 2, "degrees": 1, "units": "cm"}

Unlike the other properties on this tab, #settings is a real Calcpad directive, not a metadata comment — the engine reads it while calculating. It applies to every line after it, so you can change settings partway through a document by adding another #settings directive. If you keep one near the top, it configures the whole file; the Properties tab writes it there for you. The settings you can set 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 Properties 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.