According to the manual

:: Special Commands
These commands all start with "\^" and take between none and 2 parameters (P0, P1)

   s set tab stop width to P0 pixels (used by "\t")

However, it appears to me that it isn't in pixels, but rather by characters.

This code snippet

?"1234567890"
?"----------"
for i = 1,9 do
?"\^s"..tostr(i).."1\t2\t3\t4\t5"
end

yields this output

Additionally, if \t is the first character in the string, it seems to be ignored.

?"\t1234567890"

outputs exactly as if no tab were included.

Agreed, seems like a documentation error.

Good catch on the leading-tab bug too.

Actually, it seems like tabs simply don't work at ANY tab stops.

Also, they default to 4 spaces, which is surprising. I would have expected 2 at most, given typical indenting in programs on PICO-8.

@Felice
My original post noted the "don't work at ANY tab stops"
but then I thought about it more and I realized that the length of the string breaks relative to the tab stop is important.

Consider the 1234\t5678
The tab stop is at 4 spaces, and the string has been broken up into 4-character chunks. So the first 4 characters are then instructed to go to the next tab stop which is... right where the cursor is already... so it appears nothing is broken up by a tab insertion. This is... counterintuitive maybe? but I can't say if it is wrong or right; but it was surprising to me. My expectation would be, "move the cursor to the next tab stop after the current position."

The same thing happens if you do
?"\^s3123\t456"

In fact, the behavior at first looks odd if you do

?"1234567890"
?"----------"
for i = 1,9 do
?"\^s"..tostr(i).."123\t456\t789"
end

Visually, the result is not my expectation, though this is mostly because I keep forgetting that it is moving to a tab STOP, and is not "a tab is like a multi-character space"

EDIT
Actually, considering how \^s2 behaves, the behavior of \^s3 in the above example looks wrong.

EDIT
I just realized this is exactly what Felice was saying above, but my stupid brain keeps getting "tab" and "tab stop" confused.

If the insertion point is already at a tab stop, the standard rule is that it moves to the next one.

Basically, the tab character is defined as "go to the next tab stop", so if you're already at one, the next one is the one ahead of you.

That makes the most sense to me, which is not happening consistently. In fact, maybe that explains the ignored "string starts with \t" bug? Is it seeing the first character as the "first tab stop" and refusing to move to the next one? Hmm...

Yup, that's exactly what's happening.

I think @zep is doing something like this:

column = ceil(column / tab_size) * tab_size

And he should be doing this:

column = flr(column / tab_size) * tab_size + tab_size