Inline text and roles

This page collects everything that happens inside a paragraph: text-level emphasis, literals, inline math, and the inline :role: family.

Emphasis and strong

One asterisk is emphasis (rendered as italic), two asterisks are strong (rendered as bold). They can sit next to each other — this is emphasised and this is strong — within ordinary running text.

Inline literals

Double backticks produce an inline literal: papyri gen, --no-api, ~/.papyri/data/. Literals are not parsed for further markup, so *not emphasised* stays verbatim with its asterisks intact.

Inline math

The :math: role typesets a short expression inline with the surrounding prose: the area of a circle is $A=\pi r^2$, and Euler's identity $e^{i\pi }+1=0$ reads naturally mid-sentence. Display (block) math lives on the tables and math page.

Formatting-only roles

A family of roles exists purely to mark what kind of thing a span of text is. papyri does not cross-link these — they render as inline code — but they keep the source semantic and round-trip cleanly:

• ~/.papyri/config.toml — a filesystem path (:file:).

• Ctrl+C — a keystroke (:kbd:).

• papyri upload — a shell command (:command:).

• papyri — a program name (:program:).

• gen {config}.toml — a literal with a placeholder (:samp:).

• Esc then :wq — keystrokes chained in prose.

C-domain roles such as :c:func: and :c:type: also render as inline code, since papyri does not index C symbols: PyList_Append and PyObject appear verbatim.

GitHub and PEP roles

When the project config sets [meta].github_slug, the IPython-style GitHub roles become links: pull request #42 and issue #7 link into the configured repository. Without a slug they degrade gracefully to plain #N text.

The :pep: role links to python.org: Pep 8 (style), Pep 257 (docstrings), and Pep 440 (version identifiers).

Cross-reference roles such as :func:, :class:, and :ref: are covered on the cross-references page.

Not supported

• Substitutions (|name| with a .. |name| replace:: definition): replace:: text substitutions are resolved at gen time; image and unicode substitutions are warned and dropped. The IR never carries a substitution node.

• There is no inline role for arbitrary HTML or raw output — the raw directive is dropped for security, and there is no inline equivalent.

• Subscript / superscript (:sub: / :sup:): accepted without error but rendered as verbatim inline code, not raised/lowered text. There is no true sub/superscript node, so H\ :sub:`2`\ O reads as H 2 O in monospace rather than H₂O.