Bug in manual.ts

#1

Bug report: manual style prints literal <prefix> in big-figure captions

Environment

  • TeXmacs 2.1.5
  • macOS 14.8.4 (Apple Silicon)

Problem

Using the legacy manual document style, big-figure captions contain the
literal string

<prefix>

instead of the expected section number.

For example, instead of

Figure 2.3.

the document displays

Figure <prefix>3.

Location

The relevant code is in

TeXmacs/styles/documentation/manual.ts

around lines 62–64:

<assign|big-figure|<macro|fig|cap|
...
<assign|the-label|<prefix><figure-nr>>
...
<with|font-size|0.84|
  <surround|
    <with|font-series|bold|
      <localize|Figure>
      <prefix><figure-nr>. >
    ||
    <arg|cap>>>

Investigation

I traced the history of this code with Git.

manual.ts has contained these lines since commit

4b7f7b62
2004-03-23

and they have remained essentially unchanged ever since.

I then searched both the historical repository and the current TeXmacs source
tree for a definition of prefix.

Historical search

git grep '<assign|prefix|'

No definition exists in the 2004 tree where manual.ts introduced
<prefix>.

Current source tree

Searching the TeXmacs 2.1.5 installation likewise finds no numbering-related
definition of prefix.

A documentation package (tmdoc-keyboard) later introduced a macro also named
prefix, but it is used only for rendering keyboard shortcuts (Ctrl, Meta,
etc.) and is unrelated to document numbering.

Therefore the manual style appears to reference a macro that is no longer
defined (or perhaps never was).

Local workaround

Replacing

<assign|the-label|<prefix><figure-nr>>

by

<assign|the-label|<section-nr>.<figure-nr>>

and replacing

<prefix><figure-nr>. >

by

<value|the-label>. >

restores the expected captions.

For example, the following sections and figures produce

Figure 1.1
Figure 1.2
Figure 2.3
Figure 2.4
Figure 5.5

The workaround preserves the existing global figure-nr counter while
restoring the section prefix.

Question

Is the use of

<prefix>

inside manual.ts a long-standing typo or obsolete leftover from an older
numbering mechanism?

Would replacing it with an explicit construction of the-label be an
acceptable upstream fix, or is there a preferred modern implementation for
big-figure in the legacy manual style?

Maybe @mgubi, @darcy, or @jeroen would know.

Cheers, Tilda

#2

Correction to the proposed workaround

Further testing in a numbered subsection showed that my original workaround

<section-nr>.<figure-nr>

uses the wrong structural prefix.

For example, in Section 1.2 it produces

Figure 2.3.

whereas the native small-figure environment produces

Figure 1.4.

The figure counter itself is correct and shared by the native small and big
figure environments. Only the prefix used by the patched big-figure macro was
wrong.

Because the manual style is based on the book style, the correct label
construction is chapter-based:

<assign|the-label|<the-chapter>.<figure-nr>>

The caption should then reuse that value:

<value|the-label>. >

With this correction, the sequence becomes

Figure 1.3.
Figure 1.4.
Figure 1.5.

for alternating big and small figures in Section 1.2.

Using the-chapter rather than the raw chapter-nr should also preserve the
number representation selected by the active numbering style.