Comment commands

A comment that starts with hc: is a command: it changes how lines are rendered and is not shown itself. Commands work in every interface and every built-in renderer.

x = a / b  # hc: -f .2f        <- applies to this line only
# hc: -f .3g                   <- applies to every following line

The commands

Command	Long form	Effect
-f CODE	--format-code CODE	Number format code, e.g. .2f, .3e, .4g. See Formatting numbers.
-m	--multiline	Break a calculation over several lines, aligned on =, for long equations.
-p	--param-line	Show only target = result, hiding the symbolic and substituted steps.
-h	--params	Start a parameter grid of the following assignments, keeping their comments.
-c N	--param-cols N	Number of columns in parameter grids (default 3).
-b	--line-break	Insert vertical space here.
	--check	On a comparison, show ✓ or ✗ instead of True/False. See Checks.
	--pagebreak (--page-break)	Start a new page: before the next line when on its own line, after the line when inline.
-i	--ignore	Run the line but leave it out of the output.

Flags can be combined: # hc: -m -f .2f.

-w (--if-winner-only) is accepted but has no effect yet.

Scope

Where you put a command decides how long it lasts:

• At the end of a line (x = a / b  # hc: -f .2f), it applies to that line only. A line can carry a command or a normal comment, not both.

• On its own line (# hc: -f .2f), it applies to every following line until another command changes it. The exceptions are -b, which inserts space once, and -h, which applies to the grid directly below it.

a = 2
b = 3
x = a / b  # hc: -f .2f
y = a / b
# hc: -f .1f
z = a / b
w = b / a

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} a &= 2 \\ b &= 3 \\ x &= \frac{a}{b} = \frac{2.00}{3.00} = 0.67 \\ y &= \frac{a}{b} = \frac{2}{3} = 0.66667 \end{aligned}\]

\[\begin{aligned} z &= \frac{a}{b} = \frac{2.0}{3.0} = 0.7 \\ w &= \frac{b}{a} = \frac{3.0}{2.0} = 1.5 \end{aligned}\]

Markdown output

$$\begin{aligned} a &= 2 \\ b &= 3 \\ x &= \frac{a}{b} = \frac{2.00}{3.00} = 0.67 \\ y &= \frac{a}{b} = \frac{2}{3} = 0.66667 \end{aligned}$$

$$\begin{aligned} z &= \frac{a}{b} = \frac{2.0}{3.0} = 0.7 \\ w &= \frac{b}{a} = \frac{3.0}{2.0} = 1.5 \end{aligned}$$

Warning

A standalone # hc: -i hides everything after it. To hide a single line, put # hc: -i at the end of that line.

Turning a setting off again

The flags can only switch a setting on. To switch one back off, or to set a value, use the assignment form described next: # hc: multiline = False, # hc: param_line = False, # hc: format_code = ".5g".

The assignment form

Instead of flags, a command can be one or more Python assignments:

# hc: format_code = ".2f"
# hc: param_cols = 2
x = a / b  # hc: multiline = True

Each assignment sets a field on the render context, the settings object the renderer reads. The flags are shorthands for these fields:

Flag	Context field
-f	format_code
-m	multiline
-p	param_line
-c	param_cols
-i	ignore
--check	check

Any other name is allowed too, and is passed to the renderer. A customized or custom renderer can read its own fields this way, for example # hc: highlight = True.

Note

The assignment form is executed as Python, so only use it in code you trust (which is already true of any code you render, because handcalcs runs it).

Choosing which steps appear: mode

The mode field picks the steps of a calculation that are shown. The default, "full", shows them all. Otherwise give a string containing any of:

Word	Step
ass	the assignment target (c)
sym	the symbolic formula (2 a + b/3)
num	the formula with values substituted
res	the result

For example, to show formulas only (symbolically, as v1’s symbolic override did):

a = 2
b = 3
# hc: mode = "ass sym"
c = 2*a + b/3
d = a**2 + b**2

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} a &= 2 \\ b &= 3 \end{aligned}\]

\[\begin{aligned} c &= 2 \cdot a + \frac{b}{3} \\ d &= a^{2} + b^{2} \end{aligned}\]

Markdown output

$$\begin{aligned} a &= 2 \\ b &= 3 \end{aligned}$$

$$\begin{aligned} c &= 2 \cdot a + \frac{b}{3} \\ d &= a^{2} + b^{2} \end{aligned}$$

Examples

A long equation

omega_2 = 1.0; L = 6000; E = 200000; I_y = 160e6; G = 77e3; J = 133e3; C_w = 200e9
M_u = omega_2 * pi / L * sqrt(E * I_y * G * J + (pi * E / L)**2 * I_y * C_w)  # hc: -m

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} \omega_{2} &= 1 \; &L &= 6000 \; &E &= 200000 \; \\ I_{y} &= 1.6 \times 10^{8} \; &G &= 77000 \; &J &= 1.33 \times 10^{5} \; \\ C_{w} &= 2 \times 10^{11} \; \end{aligned}\]

\[\begin{aligned} M_{u} &= \frac{\omega_{2} \cdot \pi}{L} \cdot \sqrt{E \cdot I_{y} \cdot G \cdot J + \left(\frac{\pi \cdot E}{L}\right)^{2} \cdot I_{y} \cdot C_{w}} = \frac{1 \cdot 3.1416}{6000} \cdot \sqrt{200000 \cdot 1.6 \times 10^{8} \cdot 77000 \cdot 1.33 \times 10^{5} + \left(\frac{3.1416 \cdot 200000}{6000}\right)^{2} \cdot 1.6 \times 10^{8} \cdot 2 \times 10^{11}} = 4.3134 \times 10^{8} \end{aligned}\]

Markdown output

$$\begin{aligned} \omega_{2} &= 1 \; &L &= 6000 \; &E &= 200000 \; \\ I_{y} &= 1.6 \times 10^{8} \; &G &= 77000 \; &J &= 1.33 \times 10^{5} \; \\ C_{w} &= 2 \times 10^{11} \; \end{aligned}$$

$$\begin{aligned} M_{u} &= \frac{\omega_{2} \cdot \pi}{L} \cdot \sqrt{E \cdot I_{y} \cdot G \cdot J + \left(\frac{\pi \cdot E}{L}\right)^{2} \cdot I_{y} \cdot C_{w}} = \frac{1 \cdot 3.1416}{6000} \cdot \sqrt{200000 \cdot 1.6 \times 10^{8} \cdot 77000 \cdot 1.33 \times 10^{5} + \left(\frac{3.1416 \cdot 200000}{6000}\right)^{2} \cdot 1.6 \times 10^{8} \cdot 2 \times 10^{11}} = 4.3134 \times 10^{8} \end{aligned}$$

Results only

a = 2
b = 3
c = a**2 + b**2  # hc: -p

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} a &= 2 \\ b &= 3 \\ c &= 13 \end{aligned}\]

Markdown output

$$\begin{aligned} a &= 2 \\ b &= 3 \\ c &= 13 \end{aligned}$$

A parameter grid, two columns wide

# hc: -h -c 2
f_c = 30     # Concrete strength, MPa
f_y = 400    # Rebar yield, MPa
b = 300      # Width, mm
d = 540      # Effective depth, mm

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} f_{c} &= 30 \; \text{(Concrete strength, MPa)} \qquad &f_{y} &= 400 \; \text{(Rebar yield, MPa)} \\ b &= 300 \; \text{(Width, mm)} \qquad &d &= 540 \; \text{(Effective depth, mm)} \end{aligned}\]

Markdown output

$$\begin{aligned} f_{c} &= 30 \; \text{(Concrete strength, MPa)} \qquad &f_{y} &= 400 \; \text{(Rebar yield, MPa)} \\ b &= 300 \; \text{(Width, mm)} \qquad &d &= 540 \; \text{(Effective depth, mm)} \end{aligned}$$

Hide working lines

L_mm = 6000
L = L_mm / 1000  # hc: -i
w = 5
M = w * L**2 / 8

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} L_{\mathrm{mm}} &= 6000 \\ w &= 5 \\ M &= \frac{w \cdot L^{2}}{8} = \frac{5 \cdot 6^{2}}{8} = 22.5 \end{aligned}\]

Markdown output

$$\begin{aligned} L_{\mathrm{mm}} &= 6000 \\ w &= 5 \\ M &= \frac{w \cdot L^{2}}{8} = \frac{5 \cdot 6^{2}}{8} = 22.5 \end{aligned}$$

A pass/fail check

M_f = 180
M_r = 240
M_f <= M_r  # hc: --check

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} M_{f} &= 180 \\ M_{r} &= 240 \\ M_{f} \le M_{r} &= 180 \le 240\quad{\color{green}\checkmark} \end{aligned}\]

Markdown output

$$\begin{aligned} M_{f} &= 180 \\ M_{r} &= 240 \\ M_{f} \le M_{r} &= 180 \le 240\quad{\color{green}\checkmark} \end{aligned}$$

Several settings at once

a = 2.0
b = 7.0
# hc: format_code = ".3f"; mode = "ass sym res"
c = (a + b) / 3
d = c**2

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} a &= 2 \\ b &= 7 \end{aligned}\]

\[\begin{aligned} c &= \frac{a + b}{3} = 3.000 \\ d &= c^{2} = 9.000 \end{aligned}\]

Markdown output

$$\begin{aligned} a &= 2 \\ b &= 7 \end{aligned}$$

$$\begin{aligned} c &= \frac{a + b}{3} = 3.000 \\ d &= c^{2} = 9.000 \end{aligned}$$

The cookbook has many more. See the comment command reference for a compact table.